Repository navigation
feat(ledger): validate src per kind and name the crew contracts - #11307
Conversation
The ledger has one base envelope plus a session-only and a crew-only half, and three things did not follow that shape. `src` was one list for both kinds, so `patrol` was accepted inside a single session's turn history. It is now per kind: a session ledger takes `gateway` and `acp`, a crew ledger takes `gateway`, `dashboard`, `patrol` and the two guest forms. `require_src` takes `kind` as a required keyword argument, since it selects the rule. Authorization hangs off `src` rather than off the type prefix. A `crew:<name>` emitter writes the crew kind's built-in domains and its name in `src` is the signature, so the RFC's `crew:<parent>/dispatch` and `crew:<child>/report` are one type each -- `crew/dispatch` and `crew/report` -- and `crew:<name>/<action>` is a malformed type. `app:<name>/` stays the one guest type namespace. Both crew contracts are specified with their required fields: a dispatch needs `data.target`, a report needs a `ref` into the child's segment. Those are per-type `data` requirements, so they are declared in the type registry rather than branched on in the write path, and the spec carries them until that module lands. Spec section 4 splits into 4 Envelope, 4a Session ledger and 4b Crew ledger; section 6 states the src rule and what this layer deliberately does not check. The RFC keeps its body and gains an amendment section.
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsFINDING -- src/kiro_crew/ledger/schema.py:303 -- |
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. [DESIGN-REVIEWED] 596dd70 |
First Principles Review (Fable 5, fork) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The signed-family respelling reverses the design the base RFC records, and the amendment recording that reversal ships inside this same PR — a proposal, not a decision. Not justified as shipped
What this change shipsInventory (9 items) — 6 justifiedIntent: FIX — make ledger entries attributable and foldable before the format ships: each kind accepts only its real writers, and a dispatch/report is one type signed by
[FIRST-PRINCIPLES-REVIEWED] 596dd70 |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed |
…dotdev#11307) The ledger has one base envelope plus a session-only and a crew-only half, and three things did not follow that shape. `src` was one list for both kinds, so `patrol` was accepted inside a single session's turn history. It is now per kind: a session ledger takes `gateway` and `acp`, a crew ledger takes `gateway`, `dashboard`, `patrol` and the two guest forms. `require_src` takes `kind` as a required keyword argument, since it selects the rule. Authorization hangs off `src` rather than off the type prefix. A `crew:<name>` emitter writes the crew kind's built-in domains and its name in `src` is the signature, so the RFC's `crew:<parent>/dispatch` and `crew:<child>/report` are one type each -- `crew/dispatch` and `crew/report` -- and `crew:<name>/<action>` is a malformed type. `app:<name>/` stays the one guest type namespace. Both crew contracts are specified with their required fields: a dispatch needs `data.target`, a report needs a `ref` into the child's segment. Those are per-type `data` requirements, so they are declared in the type registry rather than branched on in the write path, and the spec carries them until that module lands. Spec section 4 splits into 4 Envelope, 4a Session ledger and 4b Crew ledger; section 6 states the src rule and what this layer deliberately does not check. The RFC keeps its body and gains an amendment section.
Problem / Motivation
The ledger is one base envelope plus a session-only half and a crew-only half. Three
places did not follow that shape.
srcwas one list for both kinds.require_srcaccepted any fixed source for any kind(
schema.py), sopatrolwas accepted as the writer of an entry inside a singlesession's turn history, and
acpas the writer of a crew activity entry.srcis what areader attributes an entry to, in a file nothing rewrites.
Authorization hung off the spelling of the TYPE. The merged RFC's "signed" family is
crew:<parent>/dispatchandcrew:<child>/report, so the writer's identity was insidethe type name and every child crew produced a different type for the same fact.
The two crew dispatch types had no contract. A dispatch with no target names nobody and a
report with no pointer to the work is an unfalsifiable claim, yet neither field was
required or specified.
Why it matters
A ledger entry is permanent and is what a conductor's board is folded from. A shared
source list is an authorization gap rather than a convenience: nothing stopped an entry
attributed to
patrolfrom landing in one session's own history. A type carrying thewriter's identity makes one fact N types, so a fold has to parse the type string to group
two children's reports on one item and the ownership registry grows an entry per crew. And
a half-addressed dispatch cannot be placed by the fold that reads it, permanently, because
no later line can complete a line already written.
The format is pre-release:
KIROCREW_SESSION_LEDGERis default-off and no user data existson disk, so this is the point at which the shape can still be fixed.
What changed (motivation -> approach -> change)
srcis validated per kind.KIND_FIXED_SOURCESandKIND_SOURCE_PREFIXESreplacethe single
FIXED_SOURCESlist as the rule: a session ledger acceptsgatewayandacp,a crew ledger accepts
gateway,dashboard,patrol,crew:<name>andapp:<name>.require_src(src, *, kind)takes the kind as a required keyword argument, because the kindselects the rule and a caller that omits it must fail loudly rather than have its
srcmeasured against some default kind's list.
FIXED_SOURCESstays exported as the derivedunion of the two lists, so it cannot drift from what is enforced.
session:<id>isaccepted by neither kind: no emitter in the tree writes it, and adding a source to a kind
is additive since no reader validates
src.The existing session writes are unchanged:
session_ledger_emitpasses onlyacpandgateway, and the repair closers instore.pypassgateway.Authorization hangs off
src. Acrew:<name>emitter writes the crew kind's built-indomains and its name in
srcis the signature, so the RFC's signed family becomes one typeeach,
crew/dispatchandcrew/report, already owned by thecrewdomain the registrylists.
crew:<name>/<action>is refused as a malformed type (bad_type), since the onlyguest TYPE namespace left is
app:<name>/, for a fact no built-in domain covers. Anapp:<name>emitter is still confined to its own prefix (namespace_violation). Codes areadditive: no code is renamed and none is added, because every new refusal reuses the
existing
bad_src,bad_typeornamespace_violation.This layer still checks no relationship. It has no crew tree, so it cannot ask whether
crew:qais really a child of the crew whose file it writes into, and a check with nothingbehind it only looks like a boundary -- the same reason
resolvehas noforbiddenstatusyet. Section 6 says so explicitly so a reader does not read more into the rule than it
enforces.
The two crew contracts are specified.
crew/dispatchdata is{item, target: {kind: "session", slot} | {kind: "crew", name}, brief?}withtargetrequired;
crew/reportdata is{item, status: done|blocked|failed|progress, credits?, summary?}with a requiredrefinto the child's ledger segment, andthreadset to thedispatch's seq when it answers one. Both are per-type
datarequirements, which belong inthe type registry next to each type's own
datashape rather than as a branch per typeinside the write path. That module is not on main, so the spec carries the contracts and
names the module in a TODO; the tests here assert the envelope half (the cross-kind
ref,the dispatch seq as the report's
thread) and say in the file docstring what waits on theregistry.
Docs.
docs/system-specs/modules/ledger-core.mdsection 4 splits into "4. Envelope"(the kind-independent fields, the bounds,
refversusthread, and the two deliberateoverlaps: the
messagedomain in both kinds, andrefcrossing kinds), "4a. Sessionledger" (allowed
src,threadunset, the header'sthread {crew, seq}back-pointer, apointer to the section 5 tables) and "4b. Crew ledger" (allowed
src, the families, the twocontracts, the one cross-kind bridge a writer takes). Section 6 states the per-kind
srcrule, the
src-based guest rule, and what the layer does not check. Section 5's rows areuntouched. The RFC keeps its body and gains an "Amendment 2026-09-16" section recording the
three corrections.
Tests
test/test_ledger_kinds.pyis new and holds the layering: the per-kindsrcmatrix as aparametrized table over both kinds (7 source spellings x 2 kinds), a guard that the matrix
covers every source the format knows, the two concrete holes (
patrolinto a sessionledger,
acpinto a crew ledger), the guest rules, and the crew contracts' envelope half.test/test_ledger_core.pykeeps one code-pinning test per refusal, updated to the new rule.218 tests pass across the two files. The related suites were run unchanged: 280 in
test_session_ledger_emit.py/test_session_ledger.py/test_ledger_lease.py, and 144across the eight
test_ledger_edge_*/test_ledger_real_crash/test_ledger_sweep/test_session_ledger_orderfiles.Nine mutations, nine killed, one per new rule: adding
patrolto the session source list;adding
crew:to the session guest prefixes; givingrequire_src'skinda default;moving
require_kindafter the source-list lookup; widening the type-domain shape so anycolon-bearing domain parses (which reinstates
crew:<name>/<action>); barring a crew guestfrom the kind's own domains; dropping the app-guest confinement; adding
crewto thesession ownership registry; and hardcoding
FIXED_SOURCESinstead of deriving it.Manual verification
Gates run from the worktree, all exit 0:
scripts/check_black_formatting.py(black 26.3.1,6 files in scope), isort, flake8,
mypy src/kiro_crew/(1552 files, no issues),scripts/docs_lint.py,scripts/docs-lint.sh,scripts/check_lockdown_before_publish.py, and the seven base-scoped gates with their envvar set to
origin/main: brand, changelog-history, comment-history, feature-map, focus-cue,harness-parity, memory-store-seam.
Diff is 45 KB, well under the 1 MB fork-review ceiling.
Related Issues
No linked issue. Implements the merged RFC #10090 (
docs/request-for-change/rfc-append-only-ledger.md),following #10091 (merged as 69aeb28) which landed the storage layer this amends. Touches
ledger-core.mdandschema.pyalongside open PRs #11185 (ledger-resolver) and #11193(ledger-retention); this branch edits sections 4, 4a, 4b, 6 and 9 and leaves section 5's
rows and
store.pyalone, so the overlap with both is small.Pattern harvest
A validator whose rule depends on a discriminator should take that discriminator as a
required argument rather than defaulting it.
require_src(src)could not express "perkind" and the fix is not a second function but making
kindun-omittable, so the gapcannot reappear by a caller forgetting to pass it.
Identity belongs in the field authorization reads, not in the name of the thing being
authorized. Encoding the writer into the type made the same fact a different type per
writer, which pushes string parsing into every fold and grows the registry per instance.
A constant that is not the rule should be derived from the rule.
FIXED_SOURCESis keptfor callers that want the vocabulary, computed as the union of the per-kind lists, so it
cannot drift from what is enforced -- and a mutation test pins that.
Other suggestions on the work
The generated reference drafts outside this repo
(
workspace/ledger-event-types.{en,zh}.md) listdashboard,patrolandsession:<id>in the session envelope's
srcrow. They are out of scope for this PR and needregenerating against 4a.
threadstaying unset on session entries is stated in 4a as the writer's discipline and isnot enforced by a refusal. Making it one is a behaviour change beyond this PR's surface, and
it would need a decision about
subagent/*threading first.Checklist