Skip to content

feat(ledger): validate src per kind and name the crew contracts - #11307

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:feat/ledger-kind-layering
Sep 16, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:feat/ledger-kind-layering

Conversation

@chenmingwei23

Copy link
Copy Markdown
Contributor

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.

src was one list for both kinds. require_src accepted any fixed source for any kind
(schema.py), so patrol was accepted as the writer of an entry inside a single
session's turn history, and acp as the writer of a crew activity entry. src is what a
reader 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>/dispatch and crew:<child>/report, so the writer's identity was inside
the 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 patrol from landing in one session's own history. A type carrying the
writer'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_LEDGER is default-off and no user data exists
on disk, so this is the point at which the shape can still be fixed.

What changed (motivation -> approach -> change)

src is validated per kind. KIND_FIXED_SOURCES and KIND_SOURCE_PREFIXES replace
the single FIXED_SOURCES list as the rule: a session ledger accepts gateway and acp,
a crew ledger accepts gateway, dashboard, patrol, crew:<name> and app:<name>.
require_src(src, *, kind) takes the kind as a required keyword argument, because the kind
selects the rule and a caller that omits it must fail loudly rather than have its src
measured against some default kind's list. FIXED_SOURCES stays exported as the derived
union of the two lists, so it cannot drift from what is enforced. session:<id> is
accepted 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_emit passes only acp and
gateway, and the repair closers in store.py pass gateway.

Authorization hangs off src. A crew:<name> emitter writes the crew kind's built-in
domains and its name in src is the signature, so the RFC's signed family becomes one type
each, crew/dispatch and crew/report, already owned by the crew domain the registry
lists. crew:<name>/<action> is refused as a malformed type (bad_type), since the only
guest TYPE namespace left is app:<name>/, for a fact no built-in domain covers. An
app:<name> emitter is still confined to its own prefix (namespace_violation). Codes are
additive: no code is renamed and none is added, because every new refusal reuses the
existing bad_src, bad_type or namespace_violation.

This layer still checks no relationship. It has no crew tree, so it cannot ask whether
crew:qa is really a child of the crew whose file it writes into, and a check with nothing
behind it only looks like a boundary -- the same reason resolve has no forbidden status
yet. 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/dispatch data is
{item, target: {kind: "session", slot} | {kind: "crew", name}, brief?} with target
required; crew/report data is {item, status: done|blocked|failed|progress, credits?, summary?} with a required ref into the child's ledger segment, and thread set to the
dispatch's seq when it answers one. Both are per-type data requirements, which belong in
the type registry next to each type's own data shape rather than as a branch per type
inside 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 the
registry.

Docs. docs/system-specs/modules/ledger-core.md section 4 splits into "4. Envelope"
(the kind-independent fields, the bounds, ref versus thread, and the two deliberate
overlaps: the message domain in both kinds, and ref crossing kinds), "4a. Session
ledger" (allowed src, thread unset, the header's thread {crew, seq} back-pointer, a
pointer to the section 5 tables) and "4b. Crew ledger" (allowed src, the families, the two
contracts, the one cross-kind bridge a writer takes). Section 6 states the per-kind src
rule, the src-based guest rule, and what the layer does not check. Section 5's rows are
untouched. The RFC keeps its body and gains an "Amendment 2026-09-16" section recording the
three corrections.

Tests

test/test_ledger_kinds.py is new and holds the layering: the per-kind src matrix as a
parametrized 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 (patrol into a session
ledger, acp into a crew ledger), the guest rules, and the crew contracts' envelope half.
test/test_ledger_core.py keeps 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 144
across the eight test_ledger_edge_* / test_ledger_real_crash / test_ledger_sweep /
test_session_ledger_order files.

Nine mutations, nine killed, one per new rule: adding patrol to the session source list;
adding crew: to the session guest prefixes; giving require_src's kind a default;
moving require_kind after the source-list lookup; widening the type-domain shape so any
colon-bearing domain parses (which reinstates crew:<name>/<action>); barring a crew guest
from the kind's own domains; dropping the app-guest confinement; adding crew to the
session ownership registry; and hardcoding FIXED_SOURCES instead 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 env
var 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.md and schema.py alongside 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.py alone, 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 "per
kind" and the fix is not a second function but making kind un-omittable, so the gap
cannot 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_SOURCES is kept
for 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) list dashboard, patrol and session:<id>
in the session envelope's src row. They are out of scope for this PR and need
regenerating against 4a.

thread staying unset on session entries is stated in 4a as the writer's discipline and is
not 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

  • Tests added or updated
  • Docs updated
  • Gates run locally

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.
@chenmingwei23
chenmingwei23 requested review from a team and krishdhasmana September 16, 2026 13:32
@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

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

FINDING -- src/kiro_crew/ledger/schema.py:303 -- "src ... is settled first" contradicts split_type() running before require_src(), returning bad_type before bad_src -> Fix: move require_src() before split_type(). (origin: validation)
[GPT-REVIEWED] 596dd70

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 596dd702137c1213dbab73715f5791bb926a5571 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

Nothing to check.

[DESIGN-REVIEWED] 596dd70

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of 596dd702137c1213dbab73715f5791bb926a5571 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

  • Item 4 — premise risk: the base RFC (in-progress) pins the signed family as crew:<parent>/dispatch / crew:<child>/report (rfc-append-only-ledger.md:110); this PR refuses that spelling as bad_type and its only record is the "Amendment 2026-09-16" the diff itself adds ("The RFC keeps its body and gains an 'Amendment' section"). The fold/registry argument is from fundamentals and the flag is default-off with no crew writer, so this is not read as product shape — but the decision is proposed beside the change, not recorded before it.
    Clears when: the amendment lands on the base branch first (then push or rebase), or a maintainer pushes this branch to the repository and records /ai-review override first-principles 596dd702137c1213dbab73715f5791bb926a5571: <decision>.
  • Item 7 — zero consumers: KIND_FIXED_SOURCES / KIND_SOURCE_PREFIXES join kiro_crew.ledger.__all__; grep for the two names finds only schema.py internals and the new tests — the sole non-test importer of the package, session_ledger_emit.py, uses neither.
    Subtraction: drop both names from ledger/__init__.py / __all__; the schema-internal use stands.
    Clears when: the export is removed, or a non-test importer exists.

What this change ships

Inventory (9 items) — 6 justified

Intent: 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 src.

  1. A session ledger now refuses dashboard, patrol, crew:*, app:* as src — justified
  2. A crew ledger now refuses acp as src — justified
  3. session:<id> is refused as src by both kinds; its prefix and regex are deleted — justified
  4. crew:<name>/<action> types become malformed; the signed family is plain crew/dispatch / crew/report, crew guests write built-in domains, RFC amended in-PR — premise risk (decision proposed beside the change)
  5. crew/dispatch / crew/report contracts specified with required target / ref; enforcement deferred to a named module that does not exist yet — justified
  6. require_src now requires kind= (one caller on base, updated) — justified
  7. KIND_FIXED_SOURCES / KIND_SOURCE_PREFIXES exported from the package — zero consumers
  8. A refused src error now names the kind and its accepted list — rides along
  9. Spec section 4 split into envelope / 4a / 4b; section 6 restated per-kind — justified

[FIRST-PRINCIPLES-REVIEWED] 596dd70

@github-actions

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 596dd70

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 16, 2026
@iamwhatever
iamwhatever merged commit 1d80a8c into kirodotdev:main Sep 16, 2026
85 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
…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.
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