<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-10-13-2-the-event-ledger-is-the-publication-seam-default-on-with-local-retention/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-13-2-the-event-ledger-is-the-publication-seam-default-on-with-local-retention/</id>
  <title>ADR: the event ledger is the publication seam, on by default, with a versioned row contract and local-log retention</title>
  <updated>2026-10-22T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-10-13-2-the-event-ledger-is-the-publication-seam-default-on-with-local-retention/"/>
  <summary>Integrations read the committed ledger through a versioned row schema in spec-kitty-events; publication is on by default, apart from hosted drain; local logs get retention.</summary>
  <content type="html">&lt;h2 id=&quot;the-event-ledger-is-the-publication-seam-on-by-default-with-a-versioned-row-contract-and-local-log-retention&quot;&gt;The event ledger is the publication seam, on by default, with a versioned row contract and local-log retention&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted (2026-10-13). The operator gave the direction on 2026-10-13: a versioned row schema in spec-kitty-events, publication on by default, and a retention or cleanup policy; accepted when the operator merged this pull request into &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-13&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;This is the produce/drain decision that the &lt;a href=&quot;/plans/4-0-0-milestone-roadmap/&quot;&gt;4.0.0 milestone roadmap&lt;/a&gt; lists as a next step. It amends that roadmap’s item 3 (“each behind its own toggle”): this record rejects a publication toggle (see Considered Options).&lt;/li&gt;
&lt;li&gt;It amends the hosted-posture contract of mission &lt;code dir=&quot;auto&quot;&gt;hosted-opt-in-drain-ledger-01M3FFEV&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;kitty-specs/hosted-opt-in-drain-ledger-01M3FFEV/contracts/hosted-posture.md&lt;/code&gt;), whose drain-off line says “fan-out, producers, live-work, the widen prereq probe return silently”. After this record the fan-out and the runtime moment producer no longer return on drain off; only the hosted handlers do.&lt;/li&gt;
&lt;li&gt;It amends &lt;a href=&quot;/adr/3.x/2026-09-26-3-hosted-interaction-opt-in/&quot;&gt;ADR 2026-09-26-3&lt;/a&gt;, D-1 and D-2.&lt;/li&gt;
&lt;li&gt;It builds on the 2026-10-12 amendments to &lt;a href=&quot;/adr/4.x/2026-10-01-2-mission-status-read-api-and-dashboard-extraction/&quot;&gt;ADR 2026-10-01-2&lt;/a&gt; and &lt;a href=&quot;/adr/4.x/2026-10-06-1-team-kitty-surfaces-are-hidden-unless-drain-is-on/&quot;&gt;ADR 2026-10-06-1&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;It retires, as follow-up debt, the &lt;code dir=&quot;auto&quot;&gt;canonical-producer-exempt&lt;/code&gt; markers that still cite the closed issues #1198 and #1248, and the eight &lt;code dir=&quot;auto&quot;&gt;#1200&lt;/code&gt; markers on the local glossary JSONL fallback (&lt;code dir=&quot;auto&quot;&gt;src/glossary/events.py&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer changing what the CLI writes to its event logs, how an integration reads them, or what the CLI may delete.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The CLI already keeps an event ledger. Every lane transition is appended to the Mission’s committed &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; by &lt;code dir=&quot;auto&quot;&gt;emit_status_transition&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/emit.py&lt;/code&gt;, then &lt;code dir=&quot;auto&quot;&gt;status/store.py::append_event_stream_atomic_verified&lt;/code&gt;). Lifecycle and decision rows join that file. Decision input events go to &lt;code dir=&quot;auto&quot;&gt;decisions.events.jsonl&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; writes its step events to a per-run journal, &lt;code dir=&quot;auto&quot;&gt;.kittify/runtime/runs/&amp;#x3C;run&gt;/run.events.jsonl&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/runtime/next/_internal_runtime/engine.py::_append_event&lt;/code&gt;). ADR 2026-09-26-3 (D-2, FR-010) makes these committed records a non-optional floor, and no setting stops them being written.&lt;/p&gt;
&lt;p&gt;The direction is now Pub, ledger, Sub:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Runtime transitions produce events.&lt;/li&gt;
&lt;li&gt;The ledger keeps them.&lt;/li&gt;
&lt;li&gt;Integrations consume them from a separate package (&lt;code dir=&quot;auto&quot;&gt;spec-kitty/event-router&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Producers and consumers know only the shared contracts in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;, not each other.&lt;/li&gt;
&lt;li&gt;The CLI is planned to offer services as integration points to the ledger (the Mission Status Read API of ADR 2026-10-01-2 is the first one). Traceability, dashboards and integrations all depend on the ledger being readable and published.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Three facts block that today:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;The ledger rows have no contract.&lt;/strong&gt;
&lt;ul&gt;
&lt;li&gt;The CLI writes them from its own &lt;code dir=&quot;auto&quot;&gt;StatusEvent&lt;/code&gt; dataclass (&lt;code dir=&quot;auto&quot;&gt;status/models.py&lt;/code&gt;) and from local envelopes. Lifecycle rows use &lt;code dir=&quot;auto&quot;&gt;schema_version &quot;5.0.0&quot;&lt;/code&gt; and carry an &lt;code dir=&quot;auto&quot;&gt;aggregate_type&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;status/lifecycle_events.py::_build_envelope&lt;/code&gt;). The run journal row has no &lt;code dir=&quot;auto&quot;&gt;event_id&lt;/code&gt; and no version.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; publishes the canonical &lt;code dir=&quot;auto&quot;&gt;Event&lt;/code&gt; envelope 3.0.0 and typed payload schemas, but the on-disk row exists there only as the &lt;code dir=&quot;auto&quot;&gt;diary.StatusEvent&lt;/code&gt; dataclass. That dataclass has no JSON schema and no row version, and it silently drops the CLI’s &lt;code dir=&quot;auto&quot;&gt;reason_source&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The package itself states that local rows are not canonical (&lt;code dir=&quot;auto&quot;&gt;contracts/versioning-and-compatibility.md&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;A consumer that reads the ledger therefore depends on CLI internals.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Publication is welded to hosted drain.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt; is a clean, transport-free callback seam. Its &lt;code dir=&quot;auto&quot;&gt;fire_*&lt;/code&gt; functions return early unless &lt;code dir=&quot;auto&quot;&gt;hosted_posture.drain_posture().enabled&lt;/code&gt;, so the gate sits on the &lt;strong&gt;seam&lt;/strong&gt;, not on the hosted handler. Drain is off by default and stays off: the hosted backend is frozen (ADR 2026-10-06-1). As long as the gate lives there, no integration can be told about an event without also turning on the hosted relay.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Nothing cleans up the local logs.&lt;/strong&gt; The per-run journals, &lt;code dir=&quot;auto&quot;&gt;.kittify/events/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.kittify/derived/&lt;/code&gt; and the &lt;code dir=&quot;auto&quot;&gt;kitty-ops/ops-index.jsonl&lt;/code&gt; cache grow without bound. There is no retention code for any of them.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;One contract for producers and consumers&lt;/strong&gt; (charter: single canonical authority; shared package boundary). A Java or other non-Python consumer must be able to implement it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Local-first and drain-independent.&lt;/strong&gt; Producing an event never depends on whether a hosted drain is on (ADR 2026-10-06-1, Amendment 2026-10-12).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The committed record is never lost.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; is the sole authority for lane state, and the floor of FR-010 holds.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Nothing hosted turns on by default.&lt;/strong&gt; Zeitgeist, auth and the SaaS surface stay frozen and opt-in.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Bounded local growth&lt;/strong&gt;, with no risk to an in-flight run.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;h3 id=&quot;the-row-contract&quot;&gt;The row contract&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;A versioned ledger-row schema in spec-kitty-events (chosen, operator ruling 2026-10-13).&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;Write canonical 3.0.0 &lt;code dir=&quot;auto&quot;&gt;Event&lt;/code&gt; envelopes into the ledger, replacing the flat rows.&lt;/li&gt;
&lt;li&gt;Keep the rows CLI-internal and expose only the read API.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;publication&quot;&gt;Publication&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;The ledger is the publication; subscribers read it by cursor. Publication is on by default, and the drain gate moves from the seam onto the hosted handlers (chosen).&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;Turn &lt;code dir=&quot;auto&quot;&gt;hosted.drain&lt;/code&gt; on by default.&lt;/li&gt;
&lt;li&gt;Keep publication behind drain and add a second toggle for local subscribers.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;retention&quot;&gt;Retention&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Two tiers: committed ledgers are never pruned; local logs get a policy (chosen).&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;One policy for every log.&lt;/li&gt;
&lt;li&gt;No retention.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;h3 id=&quot;d-1-the-ledger-row-is-a-versioned-contract-in-spec-kitty-events&quot;&gt;D-1: the ledger row is a versioned contract in spec-kitty-events&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; publishes a JSON Schema for each row kind the CLI persists, with a row-level version marker. Producers and consumers both build against those schemas:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the status transition row;&lt;/li&gt;
&lt;li&gt;the inner-state annotation row;&lt;/li&gt;
&lt;li&gt;the lifecycle row;&lt;/li&gt;
&lt;li&gt;the decision row in &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; and in &lt;code dir=&quot;auto&quot;&gt;decisions.events.jsonl&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;the run-journal row;&lt;/li&gt;
&lt;li&gt;the glossary event row in &lt;code dir=&quot;auto&quot;&gt;.kittify/events/glossary/&amp;#x3C;mission_id&gt;.events.jsonl&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/glossary/events.py&lt;/code&gt;), including the &lt;code dir=&quot;auto&quot;&gt;StepCheckpointed&lt;/code&gt; row a step resumes from.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The schemas follow the package’s existing versioning rules (&lt;code dir=&quot;auto&quot;&gt;contracts/versioning-and-compatibility.md&lt;/code&gt;): a new row kind or an optional field is a minor change, and a changed required field or a changed accept/reject behaviour is a major one. The package also documents the file-level rules a reader needs: which row kinds share a file, how a reader tells them apart, and that a reader ignores a kind it does not know. Today those rules exist only in Python docstrings (&lt;code dir=&quot;auto&quot;&gt;diary.py&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;The CLI then writes from the package’s models, not from its own &lt;code dir=&quot;auto&quot;&gt;StatusEvent&lt;/code&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;reason_source&lt;/code&gt; either joins the schema or is dropped;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Lane&lt;/code&gt; is defined once;&lt;/li&gt;
&lt;li&gt;the run journal gains an &lt;code dir=&quot;auto&quot;&gt;event_id&lt;/code&gt; and the row version.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;canonical-producer-exempt&lt;/code&gt; markers (#1198, #1248, #1200) are retired once every persisted line validates against its row schema, and a producer gate checks persisted lines, not only payloads.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Release order (shared-package boundary).&lt;/strong&gt; The row schemas ship in a &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; minor release first. The CLI then raises its floor (today &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&gt;=10.4.6,&amp;#x3C;11&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;) and extends &lt;code dir=&quot;auto&quot;&gt;tests/contract/spec_kitty_events_consumer/&lt;/code&gt; before any writer migrates. A row with no version marker reads as version 1 and is never rewritten, so committed history, and the archive freeze of &lt;a href=&quot;/adr/4.x/2026-10-11-1-archive-freeze-verifies-reducer-outcome-not-byte-identity/&quot;&gt;ADR 2026-10-11-1&lt;/a&gt;, stay valid.&lt;/p&gt;
&lt;p&gt;The canonical 3.0.0 &lt;code dir=&quot;auto&quot;&gt;Event&lt;/code&gt; envelope stays the wire contract for anything that leaves the machine. The row schema is the contract for anything that reads the ledger.&lt;/p&gt;
&lt;h3 id=&quot;d-2-the-ledger-is-the-publication-seam-and-publication-is-on-by-default&quot;&gt;D-2: the ledger is the publication seam, and publication is on by default&lt;/h3&gt;
&lt;p&gt;A subscriber learns about events by reading the ledger, never by being called by the CLI. The supported read paths are:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty events tail&lt;/code&gt;, with its cursor (&lt;code dir=&quot;auto&quot;&gt;status/tail_reader.py::TailCursor&lt;/code&gt;);&lt;/li&gt;
&lt;li&gt;the Mission Status Read API, with its overview cursor and the planned SSE change stream (ADR 2026-10-01-2).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Today &lt;code dir=&quot;auto&quot;&gt;events tail&lt;/code&gt; reads only the Mission’s &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;, and its &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; flag has no effect, because JSON is the only output mode (&lt;code dir=&quot;auto&quot;&gt;cli/commands/events.py&lt;/code&gt;). &lt;code dir=&quot;auto&quot;&gt;decisions.events.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.kittify/canonical-events.jsonl&lt;/code&gt; and the run journals have no tail path yet; adding one is follow-up work.&lt;/p&gt;
&lt;p&gt;These need no daemon in the CLI, and they need no knowledge of the subscriber. That is what makes “producers and consumers do not need to know about each other” true. &lt;code dir=&quot;auto&quot;&gt;spec-kitty/event-router&lt;/code&gt; is such a subscriber.&lt;/p&gt;
&lt;p&gt;The in-process fan-out seam in &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt; stays transport-free, but the drain gate moves off it:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;fire_*&lt;/code&gt; functions no longer read &lt;code dir=&quot;auto&quot;&gt;drain_posture()&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The runtime moment producer (&lt;code dir=&quot;auto&quot;&gt;events/runtime_moments.py&lt;/code&gt;) drops its own drain check and always calls the seam.&lt;/li&gt;
&lt;li&gt;Only the Zeitgeist handlers in &lt;code dir=&quot;auto&quot;&gt;status/zeitgeist_bridge.py&lt;/code&gt; check drain, before codec or credential work, and return when it is off.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_NO_MOMENT_HANDLERS&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SYNC_DISABLE&lt;/code&gt; registration gate keeps binding only those hosted handlers.&lt;/li&gt;
&lt;li&gt;Any local, in-process adapter registered on the seam therefore fires by default, and the hosted relay stays silent by default.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Publication on by default&lt;/strong&gt; therefore means two things:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the ledger and its read paths are always available, which they already are under FR-010;&lt;/li&gt;
&lt;li&gt;the seam fires for local adapters without an opt-in.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;hosted.drain&lt;/code&gt; stays off by default, is unchanged in meaning, and still gates every hosted edge.&lt;/strong&gt; No new toggle is added for publication.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;ledger.projection&lt;/code&gt; (default &lt;code dir=&quot;auto&quot;&gt;true&lt;/code&gt;) keeps its narrow meaning from ADR 2026-09-26-3, D-2: it gates only the derived, gitignored read model under &lt;code dir=&quot;auto&quot;&gt;.kittify/derived/&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;d-3-retention-has-two-tiers&quot;&gt;D-3: retention has two tiers&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Committed tier: never pruned by the CLI.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;These files are tracked by git: &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;decisions.events.jsonl&lt;/code&gt;, the Mission’s &lt;code dir=&quot;auto&quot;&gt;mission-events.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.kittify/canonical-events.jsonl&lt;/code&gt;, the decision ledger (&lt;code dir=&quot;auto&quot;&gt;decisions/&lt;/code&gt;) and committed Op records (&lt;code dir=&quot;auto&quot;&gt;kitty-ops/&amp;#x3C;id&gt;.jsonl&lt;/code&gt;). Their history is git’s to keep.&lt;/li&gt;
&lt;li&gt;A finished Mission is archived under the archive-freeze rule of &lt;a href=&quot;/adr/4.x/2026-10-11-1-archive-freeze-verifies-reducer-outcome-not-byte-identity/&quot;&gt;ADR 2026-10-11-1&lt;/a&gt;, not truncated.&lt;/li&gt;
&lt;li&gt;No retention setting may delete or rewrite a committed row.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Local tier: a retention policy, cleaned by an explicit command.&lt;/strong&gt; The gitignored local logs and caches are:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/runtime/runs/&amp;#x3C;run&gt;/&lt;/code&gt; (the run journal);&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/events/&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/derived/&lt;/code&gt; (always rebuildable);&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-ops/ops-index.jsonl&lt;/code&gt; (a cache of the durable Op records).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;These are kept under a policy read from &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;yaml&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;ledger&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;projection&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;true&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;          &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# unchanged (ADR 2026-09-26-3, D-2)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;retention&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;keep_runs&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;20&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;           &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# proposed default: keep at least the newest N runs&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;max_age_days&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;30&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;        &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# proposed default: and every run newer than this&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Eligibility applies alike to a run directory under &lt;code dir=&quot;auto&quot;&gt;.kittify/runtime/runs/&lt;/code&gt; and to a per-Mission log under &lt;code dir=&quot;auto&quot;&gt;.kittify/events/&lt;/code&gt; (for example &lt;code dir=&quot;auto&quot;&gt;.kittify/events/glossary/&amp;#x3C;mission_id&gt;.events.jsonl&lt;/code&gt;). An item is eligible for cleanup only when all of these hold:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;it is outside both limits;&lt;/li&gt;
&lt;li&gt;its Mission is not open;&lt;/li&gt;
&lt;li&gt;it holds no lock;&lt;/li&gt;
&lt;li&gt;for a &lt;code dir=&quot;auto&quot;&gt;.kittify/events/&lt;/code&gt; log, its Mission has no unfinished step. &lt;code dir=&quot;auto&quot;&gt;glossary/checkpoint.py::load_checkpoint&lt;/code&gt; reads the &lt;code dir=&quot;auto&quot;&gt;StepCheckpointed&lt;/code&gt; rows of every &lt;code dir=&quot;auto&quot;&gt;.kittify/events/glossary/*.events.jsonl&lt;/code&gt; to resume a step, so pruning that log would lose the resume point.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Deleting a run directory also removes its entry from &lt;code dir=&quot;auto&quot;&gt;.kittify/runtime/feature-runs.json&lt;/code&gt;, under that index’s own lock (&lt;code dir=&quot;auto&quot;&gt;runtime/next/run_index.py::index_lock&lt;/code&gt;), so the index never names a run that is gone.&lt;/p&gt;
&lt;p&gt;Durable Op records (&lt;code dir=&quot;auto&quot;&gt;kitty-ops/&amp;#x3C;op-id&gt;.jsonl&lt;/code&gt;) are tracked and never pruned; only the &lt;code dir=&quot;auto&quot;&gt;kitty-ops/ops-index.jsonl&lt;/code&gt; cache is in scope.&lt;/p&gt;
&lt;p&gt;Cleanup never touches the committed tier. It is done by an explicit, dry-run-first command in the &lt;code dir=&quot;auto&quot;&gt;doctor&lt;/code&gt; family, and automatically only where the operator has opted in. A rebuildable cache (&lt;code dir=&quot;auto&quot;&gt;.kittify/derived/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ops-index.jsonl&lt;/code&gt;) may be deleted at any time, because it is recomputed on the next read.&lt;/p&gt;
&lt;p&gt;The default numbers above are a proposal for the operator to confirm.&lt;/p&gt;
&lt;h3 id=&quot;follow-up-debt&quot;&gt;Follow-up debt&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The seam’s slots and registration functions are still named after the retired SaaS fan-out (&lt;code dir=&quot;auto&quot;&gt;register_saas_fanout_handler&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;register_lifecycle_saas_fanout_handler&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;fire_saas_fanout&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;fire_lifecycle_saas_fanout&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt;). Local adapters would register into slots called &lt;code dir=&quot;auto&quot;&gt;saas_fanout&lt;/code&gt;; renaming them to transport-neutral names is recorded here as follow-up debt.&lt;/li&gt;
&lt;li&gt;A tail path for &lt;code dir=&quot;auto&quot;&gt;decisions.events.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.kittify/canonical-events.jsonl&lt;/code&gt; and the run journals (D-2).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;An integration such as event-router can be built against a published, language-neutral contract and never reaches into CLI internals.&lt;/li&gt;
&lt;li&gt;Traceability, dashboards and integrations work on a default install, with nothing hosted switched on.&lt;/li&gt;
&lt;li&gt;The hosted relay keeps its two-scope opt-in. Moving the gate onto its handlers makes that opt-in more precise, not weaker.&lt;/li&gt;
&lt;li&gt;Local disk use is bounded, with no risk to the record of what happened.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; takes on schemas for rows that were CLI-internal, and the CLI must migrate its writers to the package models. That is the #1198 / #1248 debt, now scheduled.&lt;/li&gt;
&lt;li&gt;Moving the drain gate changes a guarantee callers may rely on (“an empty seam when drain is off”). Tests that pin the seam-level gate move to the handlers.&lt;/li&gt;
&lt;li&gt;A row-schema change becomes a cross-repository release, like any other contract change in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The read API (ADR 2026-10-01-2) is unchanged. It already reads the committed ledger and stays read-only and independent of drain.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;hosted.drain&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;[hosted] drain&lt;/code&gt; and the hidden hosted CLI entries are unchanged.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Every line the CLI persists, glossary event rows included, validates against its &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; row schema in a producer gate, and every &lt;code dir=&quot;auto&quot;&gt;canonical-producer-exempt&lt;/code&gt; marker (#1198, #1248, #1200) is gone.&lt;/li&gt;
&lt;li&gt;With drain off, a test adapter registered on &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt; is called on a lane transition, and the Zeitgeist handler makes no network call.&lt;/li&gt;
&lt;li&gt;With drain on (both scopes), the hosted handler fires as before.&lt;/li&gt;
&lt;li&gt;An architectural test pins that every handler registered by &lt;code dir=&quot;auto&quot;&gt;ensure_zeitgeist_moment_handlers&lt;/code&gt; checks drain first.&lt;/li&gt;
&lt;li&gt;The cleanup command, run against a fixture with open and closed Missions, deletes only eligible local runs and logs, removes their &lt;code dir=&quot;auto&quot;&gt;feature-runs.json&lt;/code&gt; entries, keeps every log of a Mission with an unfinished step, and never changes a tracked file.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;row-contract-canonical-300-envelopes-in-the-ledger&quot;&gt;Row contract: canonical 3.0.0 envelopes in the ledger&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; one shape on disk and on the wire. &lt;strong&gt;Cons:&lt;/strong&gt; it rewrites the authoritative file’s format. The reducers, migrations, archive freeze and every replay golden would move at once, and the envelope carries fields (build, node, Lamport) the local file has no use for. Rejected by the operator in favour of a row schema.&lt;/p&gt;
&lt;h3 id=&quot;row-contract-rows-stay-internal-read-api-only&quot;&gt;Row contract: rows stay internal, read API only&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; least work. &lt;strong&gt;Cons:&lt;/strong&gt; every consumer depends on CLI internals or on the CLI process. It contradicts “producers and consumers know only the shared contracts”.&lt;/p&gt;
&lt;h3 id=&quot;publication-hosteddrain-on-by-default&quot;&gt;Publication: &lt;code dir=&quot;auto&quot;&gt;hosted.drain&lt;/code&gt; on by default&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; no code change. &lt;strong&gt;Cons:&lt;/strong&gt; it turns the frozen hosted relay on for every install and reverses ADR 2026-09-26-3, which the operator does not want.&lt;/p&gt;
&lt;h3 id=&quot;publication-a-second-toggle-for-local-subscribers&quot;&gt;Publication: a second toggle for local subscribers&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; explicit. &lt;strong&gt;Cons:&lt;/strong&gt; it adds a setting for something that should simply work, and it leaves the drain gate on the seam, where it does not belong.&lt;/p&gt;
&lt;h3 id=&quot;retention-one-policy-for-every-log&quot;&gt;Retention: one policy for every log&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; simple. &lt;strong&gt;Cons:&lt;/strong&gt; a policy that can reach the committed ledger can destroy the sole authority for lane state.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-09-26-3-hosted-interaction-opt-in/&quot;&gt;ADR 2026-09-26-3&lt;/a&gt;, hosted interaction opt-in: D-1 unchanged in meaning (the gate moves from the seam to the hosted handlers); D-2 unchanged, now with a &lt;code dir=&quot;auto&quot;&gt;ledger.retention&lt;/code&gt; sibling.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/4.x/2026-10-01-2-mission-status-read-api-and-dashboard-extraction/&quot;&gt;ADR 2026-10-01-2&lt;/a&gt;, the producer read surface.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/4.x/2026-10-06-1-team-kitty-surfaces-are-hidden-unless-drain-is-on/&quot;&gt;ADR 2026-10-06-1&lt;/a&gt;, Amendment 2026-10-12, which unblocked the adapter seam.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/4.x/2026-10-11-1-archive-freeze-verifies-reducer-outcome-not-byte-identity/&quot;&gt;ADR 2026-10-11-1&lt;/a&gt;, the archive freeze for the committed tier.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;contracts/versioning-and-compatibility.md&lt;/code&gt; (the versioning rules the row schema follows) and &lt;code dir=&quot;auto&quot;&gt;diary.py&lt;/code&gt; (the current row model and reducer).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendments&quot;&gt;Amendments&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;2026-10-22, factual (#6607; Mission &lt;code dir=&quot;auto&quot;&gt;event-write-hygiene-01M5HS55&lt;/code&gt;):&lt;/strong&gt; the “Follow-up debt” bullet that records the &lt;code dir=&quot;auto&quot;&gt;saas_fanout&lt;/code&gt; slot names is discharged. The produce seam in &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt; is renamed with no alias for any old name: &lt;code dir=&quot;auto&quot;&gt;register_saas_fanout_handler&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;register_status_fanout_handler&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;register_lifecycle_saas_fanout_handler&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;register_lifecycle_fanout_handler&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;fire_saas_fanout&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;fire_status_fanout&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;fire_lifecycle_saas_fanout&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;fire_lifecycle_fanout&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;emit._saas_fan_out&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;emit._status_fan_out&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;queue_saas_emission&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;queue_fanout_emission&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;fanout_lifecycle_event_hosted&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;fanout_lifecycle_event&lt;/code&gt;, and the env var &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SAAS_FANOUT_TIMEOUT&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_STATUS_FANOUT_TIMEOUT&lt;/code&gt; (the old name is ignored, not read as a fallback). Open-core still registers no default handler, so every &lt;code dir=&quot;auto&quot;&gt;fire_*&lt;/code&gt; call is a no-op until a transport owner registers one; &lt;code dir=&quot;auto&quot;&gt;tests/status/test_adapters_contract.py&lt;/code&gt; pins this. The decisions in this ADR are unchanged.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;2026-10-22, by &lt;a href=&quot;/adr/4.x/2026-10-22-1-the-java-write-service-is-the-canonical-event-writer/&quot;&gt;ADR 2026-10-22-1&lt;/a&gt;:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Writer.&lt;/strong&gt; The rows D-1 lists are written by the Java write service (one per repository), not by a module inside the CLI.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Confirmation.&lt;/strong&gt; The &lt;em&gt;shape&lt;/em&gt; of the producer gate (one gate over many writers) is superseded by ADR 2026-10-14-1’s single-writer gate, which ADR 2026-10-22-1 extends to two languages. The row-schema validation that gate asked for still applies.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Unchanged.&lt;/strong&gt; D-2 (the committed ledger is the publication seam) and D-3 (retention).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Historical.&lt;/strong&gt; The “today &lt;code dir=&quot;auto&quot;&gt;&gt;=10.4.6,&amp;#x3C;11&lt;/code&gt;” floor in D-1’s release order: core consumes &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&gt;=11.0.0,&amp;#x3C;12&lt;/code&gt; since #6425.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;2026-10-18 (#6410):&lt;/strong&gt; an Op record’s auto-commit is now skipped where the record matches an ignore rule or the primary branch tracks no Op record (or cannot be shown to: the primary branch is unresolved, or a git probe failed). Such a record stays on disk, uncommitted. It belongs to neither tier: no retention policy prunes it and no cleanup command removes it, so it stays as durable as the working tree. D-3 is otherwise unchanged; it still governs committed Op records.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;2026-10-14:&lt;/strong&gt; the hosted surfaces this ADR fences were removed from open-core by #6164; the code is preserved in spec-kitty/event-router.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Amended by &lt;a href=&quot;/adr/4.x/2026-10-14-1-event-native-core-one-canonical-event-writer/&quot;&gt;ADR 2026-10-14-1&lt;/a&gt;&lt;/strong&gt; (an event-native core with one canonical event writer). D-1’s row list loses the lifecycle row: the internal lifecycle events are retired, and their facts are written as canonical &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; events. One module, the EventBridge, writes every row D-1 lists. D-1’s row schema is read as the persisted form of a canonical &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; event: the package’s row envelope, whose &lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt; is the row-level version marker, around the typed payload. It is not a second, CLI-owned schema, and it is not the 3.0.0 wire envelope (ADR 2026-10-14-1, D-3a). D-2 and D-3 are unchanged.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
