Repository navigation
docs(ledger): add an API-level reference for the ledger event contract - #11313
Conversation
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the field tables transcribed from unlanded #11185 (head 86a449f) when that PR merges — no test pins per-field payload shapes. Suggestions
[DESIGN-REVIEWED] 1117d11 |
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed |
|
Disposition of the three advisory findings on 1. The refusal table omits reachable codes (GPT 5.6, advisory -- Residual risk: a reader building error handling from those two rows handles fewer 2. Nothing forces the eight Residual risk: this one is about timeliness, not correctness. The follow-up that 3. The prose constants are ungated (Design Review, suggestion). Correct. 64 KiB, Residual risk: changing any of those four constants leaves eight prose sites stale Items 1 and 3 are queued for the follow-up that removes the |
9800c4a to
2048dda
Compare
|
Fixed in 1. Refusal table. 2. Pending marks vs the code. 3. Prose constants. 194 tests pass. Gates green: black, isort, flake8, scoped mypy, the black baseline |
The ledger's on-disk event contract is readable only by reading the emitter: which types exist, what each payload carries, which type closes which, and what a reader may assume are spread across session_ledger_emit.py and the store. Anything consuming a ledger has to guess field names and required-ness from the code that writes them. Adds docs/reference/ledger/ as five pages -- the concepts and guarantees (README), the shared envelope, the 26 session types on a fixed nine-part template, the crew types, and the read/write API with its error codes. docs/reference/ is a mirror directory that defaults to "do not author", so each page carries the named-exception mark and the index gains one marked row, following ledger-conductor-sequence.md. Field shapes come from session_ledger_emit.py as it stands on kirodotdev#11185. The summary table's Emitter column separates the 18 types an emitter writes today from the 8 whose emitter lands with that change. The crash-repair closer carries only turn and stop_reason, which is what store.py writes. tool/completed.status is an open set: the terminal frame passes the backend's own word through unmapped. Every entry point resolves the unit's path first, so exists, create and open all refuse bad_kind, invalid_id and bad_root before their own codes. test/test_docs_ledger_reference.py holds the pages to the code. Every documented type's domain is owned by the session kind in TYPE_OWNERSHIP; the summary table matches the subsections; every JSON example is one line, parses, names a documented type, names a session emitter, and survives the envelope reader. Two checks guard the parts a reader cannot verify by eye: a type marked as awaiting its emitter must have no caller in this build, so the mark cannot outlive the change that lands it, and a paragraph naming MAX_ENTRY_BYTES, MAX_REF_SPAN, MAX_PAGE_LIMIT or DEFAULT_PAGE_LIMIT must state that constant's current value.
2048dda to
1117d11
Compare
iamwhatever
left a comment
There was a problem hiding this comment.
Approved after a full read of the diff on the current head: the change matches the linked issue and body, every load-bearing claim was spot-checked against main, tests pin the behaviour, all review lanes are clean and nothing is left undisposed on this head.
kirodotdev#11313) The ledger's on-disk event contract is readable only by reading the emitter: which types exist, what each payload carries, which type closes which, and what a reader may assume are spread across session_ledger_emit.py and the store. Anything consuming a ledger has to guess field names and required-ness from the code that writes them. Adds docs/reference/ledger/ as five pages -- the concepts and guarantees (README), the shared envelope, the 26 session types on a fixed nine-part template, the crew types, and the read/write API with its error codes. docs/reference/ is a mirror directory that defaults to "do not author", so each page carries the named-exception mark and the index gains one marked row, following ledger-conductor-sequence.md. Field shapes come from session_ledger_emit.py as it stands on kirodotdev#11185. The summary table's Emitter column separates the 18 types an emitter writes today from the 8 whose emitter lands with that change. The crash-repair closer carries only turn and stop_reason, which is what store.py writes. tool/completed.status is an open set: the terminal frame passes the backend's own word through unmapped. Every entry point resolves the unit's path first, so exists, create and open all refuse bad_kind, invalid_id and bad_root before their own codes. test/test_docs_ledger_reference.py holds the pages to the code. Every documented type's domain is owned by the session kind in TYPE_OWNERSHIP; the summary table matches the subsections; every JSON example is one line, parses, names a documented type, names a session emitter, and survives the envelope reader. Two checks guard the parts a reader cannot verify by eye: a type marked as awaiting its emitter must have no caller in this build, so the mark cannot outlive the change that lands it, and a paragraph naming MAX_ENTRY_BYTES, MAX_REF_SPAN, MAX_PAGE_LIMIT or DEFAULT_PAGE_LIMIT must state that constant's current value.
Problem / Motivation
The ledger's on-disk event contract is readable only by reading the emitter. A
consumer asking which entry types exist, what each payload carries, which type
closes which, or what a reader may assume has to reconstruct all of it from
src/kiro_crew/ledger/session_ledger_emit.pyandsrc/kiro_crew/ledger/store.py.There is no reference page for the format, so the answer to "what is in a ledger"
lives in the writer's control flow.
Why it matters
Anything that consumes a ledger -- a dashboard panel, an analysis script, a future
crew-side emitter -- has to guess field names and required-ness from the code that
writes them. A guess that holds on one sample breaks on the next entry that omits
an optional field, and reading the emitter gives no signal about which fields are
guaranteed and which are incidental to one call site. A reference that is merely
written by hand has the opposite failure: it drifts from the schema silently, and
looks correct to the reader who trusts it.
What changed
Goal: one page per question a ledger consumer actually asks, held to the code by a
test instead of by a single review.
Approach: five pages under
docs/reference/ledger/, split by audience questionrather than by source file -- the concepts, terms and guarantees (
README.md); theshared envelope every entry carries (
envelope.md); the 26 live session types(
session-types.md); the crew types (crew-types.md); and the read/write API withits error codes (
reading-and-writing.md,errors.md). Each session type follows afixed nine-part template -- one-line purpose, kind and
src, when it is written,what it pairs with, a field table, invariants, a copyable example, a reader hint,
and the change that introduced it -- so a reader learns the shape once and applies
it 26 times.
The part that keeps it honest is
test/test_docs_ledger_reference.py: the pagesassert their own claims against
kiro_crew.ledger.schema, so a type renamed in theregistry or an example hand-edited into a shape the envelope refuses fails a test
rather than misleading a reader.
Field shapes are read from
session_ledger_emit.pyas it stands on #11185(feat/ledger-resolver, head 86a449f). Because that change is not yet on main, the
summary table's
Emittercolumn separates the 18 types an emitter writes today fromthe 8 whose emitter lands with it --
approval/requested,approval/decided,plan/updated,background/completedand the foursubagent/*-- and each of thosesubsections says the same thing in its
Sinceline. The read/write page marks thesame boundary for the
child_gonepredicate and the two repair closers that arrivewith it. A type this kind owns with no emitter in any open change stays in the
removed-types table, which is what separates it from an
#11185row:message/steeredsits there because its emitter function exists and nothing calls it, on main or on
#11185.
The retention and segment wording is written to hold whether or not #11193
(feat/ledger-retention) lands: segments are documented as read-supported, which is
what the resolver tree guarantees today. This implements merged RFC #10090 and
documents the event contract shipped by #10091 (merged as 69aeb28).
docs/reference/is a mirror directory whose convention is to not author localpages, so each page carries the named-exception mark in its body and the index
gains one marked row, following the precedent of
ledger-conductor-sequence.md.Tests
test/test_docs_ledger_reference.py-- 10 test functions, parametrized per type andper example for 187 cases. What each one locks in:
test_reference_page_exists-- the page the other tests read is present, so adeleted page fails loudly instead of collecting zero parametrized cases.
test_documented_type_count-- the live type count is pinned at 26 and no typehas two subsections, so adding a subsection without updating the page's opening
line fails here.
test_documented_type_domain_is_owned_by_the_session_kind-- every documentedtype's domain is owned by
KIND_SESSIONinTYPE_OWNERSHIP. Ownership is matchedper domain by prefix, so a new action needs no registry change while a renamed or
reassigned domain is caught.
test_summary_table_matches_the_subsections-- the page's index table and itssubsections name the same set, so the page cannot disagree with itself.
test_every_documented_type_has_an_example-- no type is documented without acopyable entry.
test_example_is_one_line_of_valid_json-- every example is a single line andparses to an object, which is the shape a ledger line has.
test_example_passes_the_envelope_reader-- the reader accepts every examplerather than discarding it.
test_example_would_be_accepted_as_a_session_entry-- each example clears thewriter's checks too: owned type, acceptable
src, serializabledata, and aserialized line inside the size ceiling.
test_example_type_is_documented_on_this_page,test_session_examples_carry_no_crew_only_envelope_fieldsandtest_session_examples_name_only_a_session_emitter-- an example belongs to atype the page documents, carries no crew-only field (
thread,ref), and namesone of the two emitters that write a session entry (
gateway,acp).test_summary_emitter_cell_agrees_with_the_subsection_since_line-- a row'sEmittercell and its subsection'sSinceline say the same thing about whetherthat emitter has landed. The two sit about 850 lines apart, so they drift silently,
and the drift has a direction that misleads: a row reading
livefor a type whoseemitter has not landed tells a consumer to handle entries nothing writes. Pinned in
both directions, because either half can be the stale one.
Scope is the live types only. The removed-types appendix stays a plain table with
no subsection and no example, so trimming those from the schema does not red this
test.
Mutation-verified 6 killed / 6 applied, each mutation aimed at one assertion:
retyping
tool/completedto a domain the session kind does not own reds theownership test; dropping
timefrom one example reds the envelope reader test;setting
srcto a non-session emitter reds the emitter test; deleting one summaryrow reds the table test; flipping one
#11185cell tolivewhile itsSincelinestays pending, and dropping the marker from one
Sinceline while its row keeps it,each red the agreement test from the opposite side. The harness refuses to score a
mutation whose literal does not apply exactly once, so a no-op edit fails loudly
instead of reading as an undetected mutant. The tree returns to 187 passed after
revert.
Manual verification
N/A -- the pages' claims are machine-checked rather than eyeballed, and the field
tables were built by reading the emitter call sites directly.
Gates run from the worktree root, all exit 0: the scoped test (186 passed); black
(via
scripts/check_black_formatting.pyand directly on the new file), isort,flake8, and mypy with
--follow-imports=silenton the changed test file;scripts/docs_lint.py --testandbash scripts/docs-lint.sh;scripts/check_lockdown_before_publish.py; and the seven base-scoped gates withtheir base set to
origin/main-- brand name, changelog history, comment history,feature map, focus cue, harness parity, and memory store seam.
Related Issues
No linked issue.
Pattern harvest
Rule candidate: review-prompt
Pattern: an API reference with no test drifts silently from the registry it
documents, and both failure directions look correct to a reader -- a renamed symbol
leaves the old spelling in prose, and a hand-edited example takes a shape the
writer would refuse. A reference page that names symbols from a registry can assert
that membership in the same repository that owns the registry.
Other suggestions on the work
#11185marker come out: the summarycolumn collapses back to one value, the read/write page drops its build-boundary
paragraph, and the removed-types table stops having to explain the difference
between a type with no writer and one with a writer on the way. Landing it first is
still correct -- the markers are accurate either way -- but the simpler page is
worth one follow-up once that change is in.
contracts are documented and not validator-enforced. The page says so plainly
rather than implying a live writer.
background/completed.kindis an unvalidated string: the values callers emit aredocumented as an open set, and the reader hint asks consumers to keep a bucket for
an unrecognized one. Closing it to an enum in the schema is a small follow-up that
would let the page drop that hint.
bash scripts/docs-lint.shreports 13 stale baseline entries in documents thischange does not touch, and names
--update-baselineas the way to prune them.That output is report-only and does not red CI, so it is left for a hygiene pass
rather than folded in here.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)