Skip to content

chore(ledger): trim unwritten types and retire kiro_crew.events - #11310

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:chore/ledger-schema-trim
Sep 17, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:chore/ledger-schema-trim

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

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. The digest
value of background/completed.kind is in the same position.

Alongside it sits a second structured stream, kiro_crew.events
(src/kiro_crew/events/), with zero emitters, zero readers, and no events/
directory on any host. Each of its seven kinds names a fact the ledger already
owns as a type.

ledger-core.md section 5 also calls the format "frozen" and
"additive-only from this commit". That is not the state it is in:
KIROCREW_SESSION_LEDGER is 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_VOCABULARY tuple, and
digest leaves the background/completed kind list. Three domains become
empty and leave schema.TYPE_OWNERSHIP[KIND_SESSION]: skill, summary and
remote. 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. message and session stay, since other types
in those domains remain. The remote envelope FIELD is untouched; only the
remote/* 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.events is retired: the package and the two test files that import
it 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:40 line-ref that points into the
deleted package; every other entry is left alone, so this PR's colour does not
depend on anyone else's baseline hygiene.
ledger-core.md section 2 becomes a short note in place of the
relationship 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 docstring
states 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 ignorable versus migrations, is
decided there. rfc-append-only-ledger.md carries the same correction as an
Amendment 2026-09-16 section rather than a body rewrite, so the RFC still
records 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 the
rows and domains being removed, so their cells survive a rebase.

Tests

test/test_ledger_core.py asserts the ownership registry is exactly the
documented partition, and a new test pins the removal itself:
test_a_type_the_vocabulary_dropped_is_refused_with_its_domain walks
skill/loaded, skill/searched, summary/written and remote/placed and
requires each to raise LedgerError with CODE_EVENT_TYPE_NOT_OWNED. A type
cannot creep back in on a prefix that was never removed.

SESSION_VOCABULARY shrinks to the 26 remaining types, and the two tests that
walk it (accept-every-type and reader-reconstructs-every-type) cover the new
set. The tests that monkeypatched the deleted on_message_steered emitter drop
it. Two test files go with the package: test_events_base.py and
test_events_backfill.py, which import kiro_crew.events.base and
kiro_crew.events.backfill.

test/test_events_forward.py stays. Its name matches the same
test_events_* prefix, but its subject is kiro_crew.slack.events, a live
module 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.py pins enum values and
source 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:

  • Re-adding the skill domain to TYPE_OWNERSHIP[KIND_SESSION] turns two
    tests red (test_a_type_the_vocabulary_dropped_is_refused_with_its_domain
    DID NOT RAISE, and the ownership-partition assertion). KILLED.
  • Re-adding session/seeded to SESSION_VOCABULARY leaves all 196 tests
    green. SURVIVED, and the reason is worth stating: the session domain stays
    owned, 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 are
    declaration-only here. The per-type registry in feat/ledger-type-schema
    is 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_LEDGER is
default-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 with
their base ref set to origin/main (brand, changelog history, comment
history, 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.py accepts 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

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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 pepmach September 16, 2026 14:19
@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

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

FINDING -- docs/system-specs/modules/ledger-core.md:145 -- "no ledger directory is created" contradicts eager creation by ensure_data_home() -> Fix: say no session ledger file is created.

FINDING -- test/test_ledger_core.py:435 -- "SESSION_VOCABULARY" drives both inputs and expectations, so restoring removed retained-domain types leaves the ratchet green -> Fix: explicitly assert those names are absent.

[GPT-REVIEWED] 249da5c

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 249da5c1a08d44a9ba93e83981cebda71ce4b152 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

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 — session_ledger_emit.py is inert unless KIROCREW_SESSION_LEDGER is truthy, so only opt-in experimental data can exist — the RFC carries a dated amendment instead of a body rewrite, the new freeze point (flag-default flip) is named, and test_a_type_the_vocabulary_dropped_is_refused_with_its_domain pins the removal as fail-closed rather than documentary. The kiro_crew.events deletion is clean: the only remaining events imports in src/ are kiro_crew.workflows.events and kiro_crew.metrics.events, different modules, and the deleted tripwire test itself mandated this deletion once the package's fate was settled. No user-visible surface changes, so no rendered evidence is required.

[DESIGN-REVIEWED] 249da5c

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

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

Premise-level review of 249da5c1a08d44a9ba93e83981cebda71ce4b152 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

session/seeded is cut as "no site can honestly produce it," but the base RFC §8 names its producer: the PR-2 seeding import.

Not justified as shipped

  • Item 2 — inherited (contradicted premise): the description groups session/seeded with types that "have no site that can honestly produce them," yet the base RFC's delivery plan says "the session/seeded import are migration steps and follow" — an identified writer, which is this PR's own criterion for keeping an unwritten type (approval/*, subagent/*, background/completed all stay on exactly that ground). The amendment removing it ships in this same PR, so the divergence from the in-progress RFC is proposed here, not yet recorded on base.
    Clears when: the session/seeded row is kept, or the amendment superseding §8's seeding step merges to the base branch and this branch is pushed or rebased onto it.

What this change ships

Inventory (10 items) — 8 justified

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

  1. Eight unwritten types and the digest kind value leave the session vocabulary — justified
  2. session/seeded leaves with them — inherited: base RFC §8 names its future writer, the seeding import
  3. skill, summary, remote domains leave TYPE_OWNERSHIP, so a dropped type now fails closed — justified
  4. kiro_crew.events package and its backfill CLI deleted, with baseline/sink cleanup (0 importers; grepped kiro_crew\.events and the relative form — both hits are workflows/events.py) — justified
  5. on_message_steered public emitter removed from __all__ (0 production callers) — justified
  6. Spec's "frozen / additive-only" rule becomes "pre-release until the flag-on release" — justified
  7. RFC gains Amendment 2026-09-16 recording the trim — justified
  8. Two sibling RFCs and the README index annotated that the events package is gone — rides along
  9. New test pins that dropped domains refuse with CODE_EVENT_TYPE_NOT_OWNED — justified
  10. Fixture test reads archived transcripts via the rotated-chain reader instead of backfill — justified

[FIRST-PRINCIPLES-REVIEWED] 249da5c

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 249da5c

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 16, 2026
@chenmingwei23
chenmingwei23 force-pushed the chore/ledger-schema-trim branch from fc6e4a2 to 7c4ffbc Compare September 16, 2026 14:53
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 16, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Blockers fixed at 7c4ffbce06

Design Review and First Principles are both right, and the framing they caught was
wrong in the description as well as in the diff.

test/test_events_forward.py is restored intact, all 758 lines, along with its
.github/black-baseline.txt entry. The file was matched by the test_events_*
filename prefix, not by content: its subject is kiro_crew.slack.events, a live
module this PR does not touch. Deleting it would have unpinned the only behavioral
coverage for that messaging boundary -- a raising composed gate failing CLOSED to
DROPPED with a SEL audit, a REDIRECTED decision deduping retries so one event mints
one challenge, and placeholder-text recovery through _route_message.
test_slack_message_gate_seams.py pins enum values and source order, not that
runtime behavior, so nothing else carried these.

The tripwire in the deleted test_events_backfill.py warned about exactly this
leaf-name collision, and it was used to rule the from .events import hits a false
positive without the same question being asked of the test filenames.

Two test files go with the package, test_events_base.py and
test_events_backfill.py, which import kiro_crew.events.base and
kiro_crew.events.backfill. The description said three and now says two.

Also fixed, from the GPT 5.6 lane: the docs-lint baseline was regenerated with
--update-baseline, which pruned 13 entries that have nothing to do with this
change (redirectUri, subprocess_exec, SessionStart, trust_env and others).
Both baselines are back to their base contents, and the docs-lint baseline now loses
exactly one line, the events/kinds.py:40 line-ref pointing into the deleted
package. scripts/docs_lint.py exits 0 with those 13 restored and reports them as
report-only: no longer fire, so pruning them was optional global tightening rather
than anything this gate required.

On the rename suggestion

Renaming to test_slack_forward.py is not done here. Restoring the file unchanged is
the smallest change that clears the blocker and is byte-verifiable against the base;
a move would edit two baseline files for a non-blocking reason on a PR whose point is
removal. Worth doing as a follow-up.

Verification at 7c4ffbce06

Rebased onto f4cbf1021e; main's two new commits touch none of this PR's files, and a
post-rebase sweep finds no new caller of kiro_crew.events or on_message_steered.

  • test/test_events_forward.py alone: 54 passed, exit 0.
  • Related set plus that file, -n 2: 754 passed.
  • All 14 local gates exit 0, including docs_lint.py, docs-lint.sh, the black
    baseline check, and the seven base-scoped gates against origin/main.
  • Diff is now 25 files, 242 insertions, 2280 deletions.

@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
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 16, 2026
@chenmingwei23
chenmingwei23 force-pushed the chore/ledger-schema-trim branch from 7c4ffbc to 76b4e4e Compare September 17, 2026 00:35
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 17, 2026
@chenmingwei23
chenmingwei23 force-pushed the chore/ledger-schema-trim branch from 76b4e4e to 100b98d Compare September 17, 2026 02:08
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 17, 2026
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Sep 17, 2026
@chenmingwei23
chenmingwei23 force-pushed the chore/ledger-schema-trim branch from 100b98d to 7e2b2d3 Compare September 17, 2026 05:53
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 17, 2026
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.
@chenmingwei23
chenmingwei23 force-pushed the chore/ledger-schema-trim branch from 7e2b2d3 to 249da5c Compare September 17, 2026 06:55
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 17, 2026
@iamwhatever
iamwhatever merged commit 5f31ae7 into kirodotdev:main Sep 17, 2026
86 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 17, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…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.
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