docs: fix accuracy gaps — checksum format, time-window semantics, error catalog, UI filter scope, CHANGELOG/ROADMAP currency#34
Merged
Conversation
…or catalog, UI filter scope, CHANGELOG/ROADMAP currency - docs/http-api.md: document checksum as 64-char lowercase hex (no sha256: prefix); add half-open [since, until) time-window semantics to POST /v1/diff; document window format constraints (d/h/m only, positive integer required); add 'Invalid RunEvent:' prefix note for batch ingest 400 errors; document GET /v1/actions newest-first ordering and server-enforced limit range (1–500). - docs/operations-and-policy.md: expand common errors table with candidate/rollback variants that match actual OperationError strings in operations.py (Unknown candidate release, Missing pricing table for candidate/rollback target/promoted_baseline, Promoted baseline release is missing); document parse_window units and constraints inline in compute_diff steps; add section on diffs where one side has no run events (agent consistency check skipped, confidence implications). - docs/web-ui.md: add explicit note on DiffPage that tenant_id and task_id are not exposed in the UI form and link to CLI/API alternatives. - CHANGELOG.md: correct the 1.0.1 'slim distribution' entry which claimed this tree 'omits the full in-tree docs/ tree' — docs/ is present and maintained in this clone. - ROADMAP.md: mark v1.0.4 as shipped and update 'Next release' to describe v1.0.5 candidates. Co-authored-by: Gottam Sai Bharath <Gsbreddy@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation accuracy pass triggered by the v1.0.4 release. Fixes concrete gaps between source code behavior and the reference docs.
Why
After the v1.0.4 push, a review of source code against docs identified several accuracy issues:
sha256:...prefix (wrong — storage returns bare 64-char hex)[since, until)half-open interval)windowformat constraints (onlyd/h/m, positive integer) not stated explicitlycandidate/rollback/promoted_baselinepricing error variantsInvalid RunEvent:prefix in 400 batch ingest errors was undocumentedGET /v1/actionsnewest-first ordering and 1–500 limit range not documentedtenant_id/task_id— no note directing users to CLI/APICHANGELOG.md1.0.1 entry incorrectly claimed this tree "omits the full in-tree docs/ tree"ROADMAP.md"Next release" still described v1.0.4 as upcomingChanges
docs/http-api.md: checksum as 64-char hex;[since, until)time-window semantics;windowformat constraints;Invalid RunEvent:prefix in 400 errors;GET /v1/actionsordering and limit bounds.docs/operations-and-policy.md: expanded common errors table (candidate/rollback/promoted_baseline error strings fromoperations.py);parse_windowconstraints incompute_diffsteps; new section on diffs with one empty side.docs/web-ui.md: note thattenant_id/task_idare absent from DiffPage UI with links to CLI/API alternatives.CHANGELOG.md: correct the 1.0.1 slim-distribution bullet —docs/is present and maintained in this clone.ROADMAP.md: mark v1.0.4 as shipped; describe v1.0.5 candidates.Validation
uv sync --frozen --extra devuv run python -m ruff check src tests— all checks passeduv run python -m pytest— docs-only change, no model/code changesweb/changes —generate_schemas.pyandnpm run buildnot requiredSchema / Storage Impact
Risk
Docs-only. No code, schema, or
static/changes. Zero runtime risk.Notes
All changes were verified against the source code (
operations.py,storage.py,ledger.py,server/routes/ingest.py,bundle.py) before being written.