Skip to content

docs: align README and ledger schema with runtime behavior#44

Merged
WhatsYourWhy merged 1 commit into
mainfrom
codex/review-and-update-documentation-accuracy
Feb 22, 2026
Merged

docs: align README and ledger schema with runtime behavior#44
WhatsYourWhy merged 1 commit into
mainfrom
codex/review-and-update-documentation-accuracy

Conversation

@WhatsYourWhy

Copy link
Copy Markdown
Owner

Motivation

  • The README and ledger schema contained claims and examples that did not match the actual runtime output (ledger timestamps, state file naming, API shapes), which could mislead users or produce incorrect expectations.
  • Update docs to reflect the concrete, observed behavior of the code so users can follow and reproduce examples without guessing runtime internals.

Description

  • Updated README.md to clarify determinism: the runtime guarantees semantic replay (same graph/state/config/seed → same state/artifact hashes and step records) rather than byte-for-byte identical ledger files because ledger records include timestamps and incidental metadata. The README minimal example was replaced with a runnable, API-accurate snippet using Graph(graph_id, version, steps), StepResult, and StepEvent, and the import list was corrected. (files changed: README.md)
  • Fixed docs/LEDGER_SCHEMA.md examples to match the code: state files are emitted as 0000.json, 0001.json, etc.; RunConfig.output_dir is the configured output root; RUN_START.run contains only mode and seed (no CLI-only fields); STEP_START.step_version uses the src:<sha256(module_file_bytes)> format; graph_node_id values match n{index:04d}; terminal record statuses use COMPLETED. (file changed: docs/LEDGER_SCHEMA.md)
  • Adjusted wording to point to semantic/manifest comparisons rather than raw ledger bytes and added a short example showing how to inspect RunResult.status and RunResult.ledger_path after a run.

Testing

  • Ran the project test suite with python -m pytest -q, and all tests passed: 13 passed.
  • Verified that the README example matches the public API by referencing determinant.step.StepResult/StepEvent and determinant.run.run behavior observed during tests.
  • Verified ledger schema examples against the runtime writer behavior (timestamps in records, state and meta file paths, COMPLETED statuses) by inspecting determinant/run.py and determinant/ledger.py during the change.

Codex Task

@WhatsYourWhy WhatsYourWhy merged commit 9ac040f into main Feb 22, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant