Skip to content

docs(ledger): add an API-level reference for the ledger event contract - #11313

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:docs/ledger-reference
Sep 16, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:docs/ledger-reference

Conversation

@chenmingwei23

Copy link
Copy Markdown
Contributor

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.py and src/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 question
rather than by source file -- the concepts, terms and guarantees (README.md); the
shared 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 with
its error codes (reading-and-writing.md, errors.md). Each session type follows a
fixed 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 pages
assert their own claims against kiro_crew.ledger.schema, so a type renamed in the
registry 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.py as it stands on #11185
(feat/ledger-resolver, head 86a449f). Because that change is not yet on main, the
summary table's Emitter column separates the 18 types an emitter writes today from
the 8 whose emitter lands with it -- approval/requested, approval/decided,
plan/updated, background/completed and the four subagent/* -- and each of those
subsections says the same thing in its Since line. The read/write page marks the
same boundary for the child_gone predicate and the two repair closers that arrive
with 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 #11185 row: message/steered
sits 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 local
pages, 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 and
per example for 187 cases. What each one locks in:

  • test_reference_page_exists -- the page the other tests read is present, so a
    deleted page fails loudly instead of collecting zero parametrized cases.
  • test_documented_type_count -- the live type count is pinned at 26 and no type
    has 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 documented
    type's domain is owned by KIND_SESSION in TYPE_OWNERSHIP. Ownership is matched
    per 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 its
    subsections name the same set, so the page cannot disagree with itself.
  • test_every_documented_type_has_an_example -- no type is documented without a
    copyable entry.
  • test_example_is_one_line_of_valid_json -- every example is a single line and
    parses to an object, which is the shape a ledger line has.
  • test_example_passes_the_envelope_reader -- the reader accepts every example
    rather than discarding it.
  • test_example_would_be_accepted_as_a_session_entry -- each example clears the
    writer's checks too: owned type, acceptable src, serializable data, and a
    serialized line inside the size ceiling.
  • test_example_type_is_documented_on_this_page,
    test_session_examples_carry_no_crew_only_envelope_fields and
    test_session_examples_name_only_a_session_emitter -- an example belongs to a
    type the page documents, carries no crew-only field (thread, ref), and names
    one of the two emitters that write a session entry (gateway, acp).
  • test_summary_emitter_cell_agrees_with_the_subsection_since_line -- a row's
    Emitter cell and its subsection's Since line say the same thing about whether
    that 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 live for a type whose
    emitter 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/completed to a domain the session kind does not own reds the
ownership test; dropping time from one example reds the envelope reader test;
setting src to a non-session emitter reds the emitter test; deleting one summary
row reds the table test; flipping one #11185 cell to live while its Since line
stays pending, and dropping the marker from one Since line 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.py and directly on the new file), isort,
flake8, and mypy with --follow-imports=silent on the changed test file;
scripts/docs_lint.py --test and bash scripts/docs-lint.sh;
scripts/check_lockdown_before_publish.py; and the seven base-scoped gates with
their 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

  • Merging this after feat(ledger): resolve slot keys and wire eight session emitters #11185 would let every #11185 marker come out: the summary
    column 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.
  • The crew types are specified here but have no emitter in the tree, so their
    contracts are documented and not validator-enforced. The page says so plainly
    rather than implying a live writer.
  • background/completed.kind is an unvalidated string: the values callers emit are
    documented 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.sh reports 13 stale baseline entries in documents this
    change does not touch, and names --update-baseline as 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@chenmingwei23
chenmingwei23 requested review from a team and Zedmor September 16, 2026 14:37
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Sep 16, 2026
@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 1117d11faa5343910b9f971b21be58f5a4bdf37e via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 1117d11faa5343910b9f971b21be58f5a4bdf37e via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1117d11

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed 1117d11faa5343910b9f971b21be58f5a4bdf37e via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 1117d11

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition of the three advisory findings on 9800c4aa3b. All three are accepted as
real. None changes this head, so each one's residual risk is stated here rather than
left implicit.

1. The refusal table omits reachable codes (GPT 5.6, advisory --
docs/reference/ledger/reading-and-writing.md:22). Correct. Ledger.create can also
refuse bad_root, bad_data and entry_too_large, and Ledger.open can also refuse
bad_kind, invalid_id and bad_root. Both resolve a path through the helpers that
raise CODE_BAD_ROOT (store.py:203, :208, :221, :226) and CODE_INVALID_ID
(store.py:260), and create additionally serializes a header line through
serialize and require_entry_line. The exists row of that same table already
lists the three path codes, so the table disagrees with itself.

Residual risk: a reader building error handling from those two rows handles fewer
refusals than can occur. What limits it is that the table is a summary and not the
code reference -- errors.md documents each of these six codes in full, with the
fields it carries and what raises it -- so the omission costs a reader one hop rather
than the information.

2. Nothing forces the eight #11185 marks to flip when that change lands (Design
Review, CONCERNS). Correct, and the sharpest of the three.
test_summary_emitter_cell_agrees_with_the_subsection_since_line compares a summary
row's Emitter cell against its subsection's Since line -- the page against itself
-- and no assertion compares either against the emitter. The remedy named in the
review, that a type the emitter actually emits may not carry a pending #11185 cell,
would be self-clearing: it goes red the moment #11185 reaches main.

Residual risk: this one is about timeliness, not correctness. The follow-up that
removes every #11185 marker once #11185 merges is already recorded against this
branch and reaches the same end state the gate would force, so the exposure is the
window between that merge and that follow-up, during which the page understates eight
types. A CI assertion would close the window; a recorded follow-up narrows it.

3. The prose constants are ungated (Design Review, suggestion). Correct. 64 KiB,
the 500-line ref span, and the page limits 50 and 500 appear at eight sites across
five pages, with no assertion tying them to MAX_ENTRY_BYTES (schema.py:80),
MAX_REF_SPAN (schema.py:85), MAX_PAGE_LIMIT (store.py:140) and
DEFAULT_PAGE_LIMIT (store.py:141).

Residual risk: changing any of those four constants leaves eight prose sites stale
with no signal. What limits it is that every site names its constant in backticks
beside the number, so the constant name greps to all eight and a reader can check any
one of them against the code.

Items 1 and 3 are queued for the follow-up that removes the #11185 markers. Item 2's
remedy is superseded by that follow-up rather than carried into it, since the
assertion's purpose is to force the very edit the follow-up makes.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Fixed in 2048dda99d. All three are addressed in this head rather than deferred.

1. Refusal table. create and open now carry the path codes they resolve
through, and create carries the two its header serialization reaches. A sentence
under the table states why all three rows share bad_kind, invalid_id and
bad_root, so the common prefix reads as a fact about path resolution rather than as
duplication.

2. Pending marks vs the code.
test_a_pending_emitter_mark_is_not_contradicted_by_the_code asserts that a type
marked #11185 has no caller under src/kiro_crew outside the emitter module, which
is the property the mark claims: an emitter API with no caller writes nothing. It is
self-clearing, going red when that change lands and naming the calling file, so the
mark cannot outlive it. Mutation-verified by planting a file that calls
on_plan_updated, which reddens exactly that test.

3. Prose constants. test_a_documented_constant_carries_its_current_value asserts
that a paragraph naming MAX_ENTRY_BYTES, MAX_REF_SPAN, MAX_PAGE_LIMIT or
DEFAULT_PAGE_LIMIT states that constant's current value, rendering
MAX_ENTRY_BYTES as KiB the way the prose does. A mention that is only a signature
default (limit=DEFAULT_PAGE_LIMIT) asserts no value and is not treated as a claim.
Two doc sites changed to come under it: the paging paragraph now names both
page-limit constants beside their numbers, and the crew-types span cap now names
MAX_REF_SPAN. Mutation-verified on both a page that already carried its claim and
the page newly brought under the rule, since a rule that covers only what already
passed proves nothing.

194 tests pass. Gates green: black, isort, flake8, scoped mypy, the black baseline
gate, docs_lint.py --test, docs-lint.sh, the lockdown check, and the seven
base-scoped gates against origin/main.

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.
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 16, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@iamwhatever
iamwhatever merged commit 9d5133c into kirodotdev:main Sep 16, 2026
152 of 156 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 16, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants