Repository navigation
chore(ledger): trim unwritten types and retire kiro_crew.events - #11310
Conversation
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsFINDING -- docs/system-specs/modules/ledger-core.md:145 -- FINDING -- test/test_ledger_core.py:435 -- [GPT-REVIEWED] 249da5c |
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Confirm the format owner signs off on reversing the "frozen from this commit" pin — this PR deliberately overturns a decision #10091 shipped, not a gap. That reversal is the only judgment call here, and it is done the right way: the premise ("no user data exists") checks out against the base — [DESIGN-REVIEWED] 249da5c |
First Principles Review (Fable 5, fork) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS
Not justified as shipped
What this change shipsInventory (10 items) — 8 justifiedIntent: make the flag-off session ledger's declared vocabulary match what is actually written, and delete the writer-less parallel event stream — a FIX (removal of unearned surface), not an addition.
[FIRST-PRINCIPLES-REVIEWED] 249da5c |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed |
fc6e4a2 to
7c4ffbc
Compare
Blockers fixed at
|
7c4ffbc to
76b4e4e
Compare
76b4e4e to
100b98d
Compare
100b98d to
7e2b2d3
Compare
The session vocabulary declares 26 types, down from 35. Nine types have no site that can honestly produce them, or would double-record a fact another entry already carries: session/seeded, message/steered, tool/searched, tool/loaded, skill/searched, skill/loaded, summary/written, remote/placed, remote/lost. The digest value of background/completed.kind goes with them. The skill, summary and remote domains become empty and leave TYPE_OWNERSHIP, so a dropped type fails closed on its own domain. They may return under the additive rule once a real source exists. kiro_crew.events is retired: the package had no emitter, no reader, and no events/ directory on any host, and each of its seven kinds names a fact the ledger already owns as a type. Two vocabularies for one fact is a choice every future emitter would have to make. A fact with no unit to belong to, such as a script cron or gateway lifecycle, gets a gateway-kind ledger when one is needed. The format is pre-release, not frozen. KIROCREW_SESSION_LEDGER is default-off and no user data exists on disk, so shapes may still change. The freeze point is the release that turns the flag on by default, and the compatibility strategy is decided there. ledger-core.md section 5 says this, and rfc-append-only-ledger.md carries it as an Amendment section rather than a body rewrite. Implements RFC kirodotdev#10090 and follows kirodotdev#10091.
7e2b2d3 to
249da5c
Compare
…dotdev#11310) The session vocabulary declares 26 types, down from 35. Nine types have no site that can honestly produce them, or would double-record a fact another entry already carries: session/seeded, message/steered, tool/searched, tool/loaded, skill/searched, skill/loaded, summary/written, remote/placed, remote/lost. The digest value of background/completed.kind goes with them. The skill, summary and remote domains become empty and leave TYPE_OWNERSHIP, so a dropped type fails closed on its own domain. They may return under the additive rule once a real source exists. kiro_crew.events is retired: the package had no emitter, no reader, and no events/ directory on any host, and each of its seven kinds names a fact the ledger already owns as a type. Two vocabularies for one fact is a choice every future emitter would have to make. A fact with no unit to belong to, such as a script cron or gateway lifecycle, gets a gateway-kind ledger when one is needed. The format is pre-release, not frozen. KIROCREW_SESSION_LEDGER is default-off and no user data exists on disk, so shapes may still change. The freeze point is the release that turns the flag on by default, and the compatibility strategy is decided there. ledger-core.md section 5 says this, and rfc-append-only-ledger.md carries it as an Amendment section rather than a body rewrite. Implements RFC kirodotdev#10090 and follows kirodotdev#10091.
Problem / Motivation
The session ledger's declared vocabulary is wider than anything that writes to
it. Nine of its 35 types have no site that can honestly produce them, or would
double-record a fact another entry already carries:
session/seeded,message/steered,tool/searched,tool/loaded,skill/searched,skill/loaded,summary/written,remote/placed,remote/lost. Thedigestvalue of
background/completed.kindis in the same position.Alongside it sits a second structured stream,
kiro_crew.events(
src/kiro_crew/events/), with zero emitters, zero readers, and noevents/directory on any host. Each of its seven kinds names a fact the ledger already
owns as a
type.ledger-core.mdsection 5 also calls the format "frozen" and"additive-only from this commit". That is not the state it is in:
KIROCREW_SESSION_LEDGERis default-off and no user data exists on disk.Why it matters
A vocabulary entry is a promise to a reader. A reader that folds the log has to
handle every declared type, so nine types nothing writes cost every future
consumer real work for facts that never arrive. Two parallel vocabularies for
one fact is worse: every future emitter has to choose between them, and the
answer is this format every time.
The "frozen" wording is the expensive part. Taken at face value it forces the
next shape correction through a migration for data that does not exist, and it
is the sentence a future contributor will cite to refuse a change that is
free today.
What changed
The removals come first, because they set the size of everything else. The
nine types leave the section 5 tables and the
SESSION_VOCABULARYtuple, anddigestleaves thebackground/completedkind list. Three domains becomeempty and leave
schema.TYPE_OWNERSHIP[KIND_SESSION]:skill,summaryandremote. That is what makes the removal enforceable rather than documentary,because a dropped type now fails closed on its own domain with
CODE_EVENT_TYPE_NOT_OWNED.messageandsessionstay, since other typesin those domains remain. The
remoteenvelope FIELD is untouched; only theremote/*type domain goes.They may return under the additive rule once a real source exists, and the
emitter spec says so in one sentence.
kiro_crew.eventsis retired: the package and the two test files that importit are deleted, and its references are cleaned out of the module index, the
docs-lint baseline and the security-posture sink list. The docs-lint baseline
loses exactly one line, the
events/kinds.py:40line-ref that points into thedeleted package; every other entry is left alone, so this PR's colour does not
depend on anyone else's baseline hygiene.
ledger-core.mdsection 2 becomes a short note in place of therelationship description: the parallel stream is retired, and a fact with no
unit to belong to, such as a script cron or gateway lifecycle, gets a
gateway-kind ledger when one is needed.schema.py's envelope docstringstates the envelope's own shape rather than pointing at
events/base.py.Section 5 says pre-release. Shapes may change while the flag is default-off;
the freeze point is the release that turns it on by default, and the
compatibility strategy, additive plus
ignorableversus migrations, isdecided there.
rfc-append-only-ledger.mdcarries the same correction as anAmendment 2026-09-16section rather than a body rewrite, so the RFC stillrecords what was decided when it was decided.
This implements merged RFC #10090 and follows #10091 (merged as 69aeb28).
It touches three files that PRs #11185 and #11193 also edit
(
docs/system-specs/modules/ledger-core.md,test/test_ledger_core.py,src/kiro_crew/session_ledger_emit.py); the edits here are confined to therows and domains being removed, so their cells survive a rebase.
Tests
test/test_ledger_core.pyasserts the ownership registry is exactly thedocumented partition, and a new test pins the removal itself:
test_a_type_the_vocabulary_dropped_is_refused_with_its_domainwalksskill/loaded,skill/searched,summary/writtenandremote/placedandrequires each to raise
LedgerErrorwithCODE_EVENT_TYPE_NOT_OWNED. A typecannot creep back in on a prefix that was never removed.
SESSION_VOCABULARYshrinks to the 26 remaining types, and the two tests thatwalk it (accept-every-type and reader-reconstructs-every-type) cover the new
set. The tests that monkeypatched the deleted
on_message_steeredemitter dropit. Two test files go with the package:
test_events_base.pyandtest_events_backfill.py, which importkiro_crew.events.baseandkiro_crew.events.backfill.test/test_events_forward.pystays. Its name matches the sametest_events_*prefix, but its subject iskiro_crew.slack.events, a livemodule this PR does not touch, and it holds the only behavioral pins for that
messaging boundary: a raising composed gate fails CLOSED to DROPPED with an
audit (CWE-1188, deny-by-default), a REDIRECTED decision dedups retries so one
event mints one challenge, and placeholder text is recovered through
_route_message.test_slack_message_gate_seams.pypins enum values andsource order, not that runtime behavior.
Related files,
-n 2:test_ledger_core.py,test_ledger_sweep.py,test_session_ledger_emit.py,test_session_ledger_order.py,test_session_control.py,test_steer_requeue.py,test_fixture_sessions_a_few.py. 700 passed.Mutation-verified, 1 of 2 killed:
skilldomain toTYPE_OWNERSHIP[KIND_SESSION]turns twotests red (
test_a_type_the_vocabulary_dropped_is_refused_with_its_domainDID NOT RAISE, and the ownership-partition assertion). KILLED.
session/seededtoSESSION_VOCABULARYleaves all 196 testsgreen. SURVIVED, and the reason is worth stating: the
sessiondomain staysowned, ownership is prefix-based, and the vocabulary tuple is the
declaration the tests read from, so mutating it moves the expectation with
it. Four of the nine removals sit in a domain that survives
(
session/seeded,message/steered,tool/searched,tool/loaded) and aredeclaration-only here. The per-type registry in
feat/ledger-type-schemais what makes them enforceable; adding validation in this PR would collide
with it.
Manual verification
N/A - no runtime behavior changes for a user.
KIROCREW_SESSION_LEDGERisdefault-off, the deleted package has no emitter or reader, and the removed
types have no writer, so there is no path to exercise by hand.
Gates, all exit 0: black baseline, isort, flake8, mypy on the changed
src/paths,docs_lint.py,docs-lint.sh,check_lockdown_before_publish.py, and the seven base-scoped gates withtheir base ref set to
origin/main(brand, changelog history, commenthistory, feature map, focus cue, harness parity, memory store seam).
Related Issues
No linked issue. Implements merged RFC #10090
(
docs/request-for-change/rfc-append-only-ledger.md).Pattern harvest
Pattern: a declared vocabulary that no emitter writes, kept because removing a
name feels riskier than keeping it. The generalizable check is the one this PR
applies: for each declared type, name the site that produces it, and where
none exists decide between building the emitter and deleting the declaration.
The enforceable half is that a removed name must fail closed rather than
merely leave a table.
Other suggestions on the work
The surviving mutation is the finding worth carrying forward. A vocabulary
tuple that the tests also read as their expectation cannot pin itself, so the
26 remaining types are pinned only where a whole domain went with them. The
per-type registry lands that pin; until then, adding a type is a
one-line diff no test objects to.
schema.pyaccepts a type on its domain PREFIX. That is the right check for"does this kind have such events" and the wrong one for "is this type in the
format", and the two are easy to confuse when reading the code. The registry
work is the place to make the second question answerable.
Checklist