<?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-14-1-event-native-core-one-canonical-event-writer/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-14-1-event-native-core-one-canonical-event-writer/</id>
  <title>ADR: an event-native core with one canonical event writer behind a domain port</title>
  <updated>2026-10-29T00: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-14-1-event-native-core-one-canonical-event-writer/"/>
  <summary>One EventBridge module writes only spec-kitty-events contract events; the run loop calls its port; git and filesystem effects become internal consumers.</summary>
  <content type="html">&lt;h2 id=&quot;an-event-native-core-with-one-canonical-event-writer-behind-a-domain-port&quot;&gt;An event-native core with one canonical event writer behind a domain port&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted (2026-10-14). Decided by the operator on 2026-10-14; this record writes the decision down. Amended 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; (D-1, D-2, D-5 and the Confirmation; see Amendments at the end). Amended by &lt;a href=&quot;/adr/4.x/2026-10-29-1-the-events-domain-and-its-java-services-live-in-spec-kitty-events/&quot;&gt;ADR 2026-10-29-1&lt;/a&gt; (the events services live in spec-kitty-events); see Amendment 2026-10-29.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-14&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;Operator ruling, 2026-10-14 (quoted under Context).&lt;/li&gt;
&lt;li&gt;It builds on &lt;a href=&quot;/adr/4.x/2026-10-13-2-the-event-ledger-is-the-publication-seam-default-on-with-local-retention/&quot;&gt;ADR 2026-10-13-2&lt;/a&gt; (pub, ledger, sub; a versioned row contract in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;). It amends that record’s D-1 row list: the lifecycle row kind is retired, not given its own schema (see the Amendments note added there). It also settles how D-1’s “versioned row schema” and the operator’s “canonical events only” fit: they are one contract, not two (D-3 below).&lt;/li&gt;
&lt;li&gt;It builds on the produce side of &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;, D-6: the read API stays a pull over the committed ledger, and this record names the one thing that writes that ledger.&lt;/li&gt;
&lt;li&gt;It keeps &lt;a href=&quot;/adr/2.x/2026-02-09-3-event-log-merge-semantics/&quot;&gt;ADR 2026-02-09-3&lt;/a&gt; (event-log merge semantics) unchanged. The writer changes, but the log keeps its merge and reduction rules.&lt;/li&gt;
&lt;li&gt;It keeps &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; unchanged. The hosted surfaces that record fenced were removed from open-core by #6164 (PR #6206); their code is preserved in &lt;code dir=&quot;auto&quot;&gt;spec-kitty/event-router&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer changing how the CLI or the runtime records what happened to a Mission or a work package, or adding a side effect that reacts to it.&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 operator’s decision, verbatim:&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;“The idea is to have a SINGLE canonical event writer module inside of the CLI. This writes `spec-kitty-events’ published contract compatible events only. The event schema MUST contain a ‘schemaVersion’ field, so consumers know which events they are receiving, and async backwards compatibility is facilitated. Consumers can still choose whether to support multiple versions, or a single version. The producer ( usually ) produces only the latest version. Cfr. &lt;a href=&quot;https://martinfowler.com/eaaDev/EventSourcing.html&quot;&gt;https://martinfowler.com/eaaDev/EventSourcing.html&lt;/a&gt;. Our runtime ( FSM ) core module sends these events as missions transition through their lifecycle. The internal ‘lifecycle events’ are to be removed and replaced by canonical events ONLY. We will use a ports-and-adaptors approach for the event creations: the core mission run loop needn’t know about the structure of the event writer or pub-ledger-sub approach. It only needs to know to call the eventbridge ssot entrypoints when transitioning WPs or advancing mission state. Allowing it to be pure domain code, and having the git / filesystem operations handled by internal consumers of the events. This effectively makes our core system event-native by design.”&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;The decisions of 2026-10-13 stand: runtime transitions create events; events flow pub, ledger, sub; producers and consumers (the consumers live in &lt;code dir=&quot;auto&quot;&gt;spec-kitty/event-router&lt;/code&gt;) share only &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; contracts; ledger rows get a versioned row schema in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;current-state-originmain-566b20b9&quot;&gt;Current state (&lt;code dir=&quot;auto&quot;&gt;origin/main&lt;/code&gt;, 566b20b9)&lt;/h3&gt;
&lt;p&gt;This survey predates #6164 (PR #6206), which removed the hosted surfaces from open-core: &lt;code dir=&quot;auto&quot;&gt;status/zeitgeist_bridge.py&lt;/code&gt;, the hidden hosted CLI entries and the drain gates in &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt; are gone. The citations below describe the tree at 566b20b9.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Many writers, several row shapes.&lt;/strong&gt; Counting each module that builds an event-like record and appends it to a log, there are twelve producers writing seven files:&lt;/p&gt;



















































































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;#&lt;/th&gt;&lt;th&gt;Producer&lt;/th&gt;&lt;th&gt;File&lt;/th&gt;&lt;th&gt;Row shape and version marker&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;Lane transitions: &lt;code dir=&quot;auto&quot;&gt;status/transition_pipeline.py::prepare_transition&lt;/code&gt; (:245) builds a &lt;code dir=&quot;auto&quot;&gt;StatusEvent&lt;/code&gt;, appended by &lt;code dir=&quot;auto&quot;&gt;status/emit.py::_persist_prepared&lt;/code&gt; (:831) or &lt;code dir=&quot;auto&quot;&gt;BookkeepingTransaction.append_events&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;coordination/transaction.py:985&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;StatusEvent.to_dict&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;status/models.py:470&lt;/code&gt;): flat row, &lt;strong&gt;no version&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;Inner-state annotations: &lt;code dir=&quot;auto&quot;&gt;status/emit.py::emit_inner_state_changed&lt;/code&gt; (:1212)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;InnerStateChanged.to_dict&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;status/models.py:793&lt;/code&gt;), no version&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;3&lt;/td&gt;&lt;td&gt;Internal lifecycle events: &lt;code dir=&quot;auto&quot;&gt;status/lifecycle_events.py::persist_lifecycle_event_local&lt;/code&gt; (:536), envelope from &lt;code dir=&quot;auto&quot;&gt;_build_envelope&lt;/code&gt; (:309)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/canonical-events.jsonl&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; (:10-18, :125-126)&lt;/td&gt;&lt;td&gt;local envelope, &lt;code dir=&quot;auto&quot;&gt;schema_version &quot;5.0.0&quot;&lt;/code&gt; (:317), marked &lt;code dir=&quot;auto&quot;&gt;canonical-producer-exempt: #1198&lt;/code&gt; (:308, :319)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;4&lt;/td&gt;&lt;td&gt;Decision points: &lt;code dir=&quot;auto&quot;&gt;decisions/emit.py::_append_raw_event&lt;/code&gt; (:117)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; (:65)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;DECISIONPOINT_SCHEMA_VERSION&lt;/code&gt; (:185)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;5&lt;/td&gt;&lt;td&gt;Retrospective lifecycle: &lt;code dir=&quot;auto&quot;&gt;retrospective/lifecycle_events.py&lt;/code&gt; (:320-331)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; (:55)&lt;/td&gt;&lt;td&gt;integer &lt;code dir=&quot;auto&quot;&gt;schema_version = 1&lt;/code&gt; (:146)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;6&lt;/td&gt;&lt;td&gt;Retrospective events, superseded entry: &lt;code dir=&quot;auto&quot;&gt;retrospective/events.py&lt;/code&gt; (:208-226)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;&lt;/td&gt;&lt;td&gt;own envelope&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;7&lt;/td&gt;&lt;td&gt;Backfill migration: &lt;code dir=&quot;auto&quot;&gt;migration/backfill_runtime_state.py&lt;/code&gt; (:1200, :1440)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;&lt;/td&gt;&lt;td&gt;synthesized &lt;code dir=&quot;auto&quot;&gt;StatusEvent&lt;/code&gt; rows&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;8&lt;/td&gt;&lt;td&gt;Run journal: &lt;code dir=&quot;auto&quot;&gt;runtime/next/_internal_runtime/engine.py::_append_event&lt;/code&gt; (:107-123)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/runtime/runs/&amp;#x3C;run&gt;/run.events.jsonl&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;{event_type, timestamp, payload}&lt;/code&gt;, no &lt;code dir=&quot;auto&quot;&gt;event_id&lt;/code&gt;, no version, &lt;code dir=&quot;auto&quot;&gt;canonical-producer-exempt: #1248&lt;/code&gt; (:109)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;9&lt;/td&gt;&lt;td&gt;Decision input log: &lt;code dir=&quot;auto&quot;&gt;events/decision_log.py::DecisionGitLog&lt;/code&gt; (:78, append at :252)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;decisions.events.jsonl&lt;/code&gt;&lt;/td&gt;&lt;td&gt;sanitized &lt;code dir=&quot;auto&quot;&gt;mission_next&lt;/code&gt; payloads&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;10&lt;/td&gt;&lt;td&gt;Mission v1 events: &lt;code dir=&quot;auto&quot;&gt;mission_v1/events.py::_write_event&lt;/code&gt; (:60-66)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission-events.jsonl&lt;/code&gt; (:23)&lt;/td&gt;&lt;td&gt;own dict&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;11&lt;/td&gt;&lt;td&gt;Glossary: &lt;code dir=&quot;auto&quot;&gt;glossary/events.py::_local_append_event&lt;/code&gt; (:162-173)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/events/glossary/&amp;#x3C;mission_id&gt;.events.jsonl&lt;/code&gt;&lt;/td&gt;&lt;td&gt;own dict (#1200 markers)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;12&lt;/td&gt;&lt;td&gt;Op records: &lt;code dir=&quot;auto&quot;&gt;invocation/writer.py&lt;/code&gt; (:194-205), &lt;code dir=&quot;auto&quot;&gt;invocation/lifecycle.py::append_lifecycle_record&lt;/code&gt; (:57)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-ops/&amp;#x3C;op&gt;.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;kitty-ops/lifecycle.jsonl&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Op record schema v2&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Rows 1 to 7 share &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; and two low-level append primitives in &lt;code dir=&quot;auto&quot;&gt;status/store.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;append_raw_rows_atomic&lt;/code&gt; :369, &lt;code dir=&quot;auto&quot;&gt;append_event_stream_atomic_verified&lt;/code&gt; :496). The file stays readable only because a hand-kept registry tells the lane reader which &lt;code dir=&quot;auto&quot;&gt;event_type&lt;/code&gt; rows to skip and keep (&lt;code dir=&quot;auto&quot;&gt;AUTHORITATIVE_NON_LANE_EVENT_TYPES&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status/lifecycle_events.py:166&lt;/code&gt;). A thirteenth shape exists only on the way out: &lt;code dir=&quot;auto&quot;&gt;build_saas_lifecycle_queue_event&lt;/code&gt; (:421) rewrites a lifecycle row into a 3.0.0 envelope (:462) for the hosted relay.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;There are two internal lifecycle-event writers, with many importers.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;git grep -l lifecycle_events origin/main -- src&lt;/code&gt; lists 23 files (&lt;code dir=&quot;auto&quot;&gt;status/lifecycle_events.py&lt;/code&gt; itself and 22 others), and they cover two modules:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status/lifecycle_events.py&lt;/code&gt; (producer 3) has 14 direct module importers, among them &lt;code dir=&quot;auto&quot;&gt;migration/mission_state.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status/doctor.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status/views.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status/zeitgeist_bridge.py&lt;/code&gt; and the upgrade migration &lt;code dir=&quot;auto&quot;&gt;m_3_2_9_migrate_lifecycle_envelope.py&lt;/code&gt;. More callers reach it through the &lt;code dir=&quot;auto&quot;&gt;specify_cli.status&lt;/code&gt; re-exports, for example &lt;code dir=&quot;auto&quot;&gt;core/mission_creation_events.py:76&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;MissionReopened&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;FollowUpRecorded&lt;/code&gt; stay local-only because the hosted strict path would reject them (:85-106).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;retrospective/lifecycle_events.py&lt;/code&gt; (producer 5) is imported by &lt;code dir=&quot;auto&quot;&gt;runtime/next/runtime_bridge_retrospective.py:227&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;cli/commands/agent_retrospect.py:36&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;post_merge/retrospective_terminus.py:128&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;retrospective/events.py:222&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Where transitions are triggered, and where side effects run inline.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The runtime run loop (&lt;code dir=&quot;auto&quot;&gt;runtime/next/&lt;/code&gt;) reads lane state (&lt;code dir=&quot;auto&quot;&gt;decision.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;discovery.py&lt;/code&gt;) but does not write it. Lane writes inside composed steps go through &lt;code dir=&quot;auto&quot;&gt;emit_status_transition&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;runtime_bridge_composition.py:93-95&lt;/code&gt;), and production callers use the transactional door &lt;code dir=&quot;auto&quot;&gt;emit_status_transition_transactional&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;coordination/status_transition.py:1598&lt;/code&gt;): CLI commands (&lt;code dir=&quot;auto&quot;&gt;agent/tasks_move_task_executor.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agent/tasks.py&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;orchestrator_api/wp_lifecycle.py:846&lt;/code&gt;, consolidation (&lt;code dir=&quot;auto&quot;&gt;done_bookkeeping.py&lt;/code&gt;, both attestations) and the &lt;code dir=&quot;auto&quot;&gt;MissionStatus&lt;/code&gt; facade (&lt;code dir=&quot;auto&quot;&gt;status/aggregate.py:168&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;The runtime already has the shape of a port: &lt;code dir=&quot;auto&quot;&gt;RuntimeEventEmitter&lt;/code&gt; is a &lt;code dir=&quot;auto&quot;&gt;Protocol&lt;/code&gt; over canonical &lt;code dir=&quot;auto&quot;&gt;mission_next&lt;/code&gt; payloads (&lt;code dir=&quot;auto&quot;&gt;runtime/next/_internal_runtime/events.py:76&lt;/code&gt;), with a reject-on-conflict factory registry (:240) and &lt;code dir=&quot;auto&quot;&gt;runtime_emitter_for_mission&lt;/code&gt; (:288). But the engine also writes its own journal and snapshot directly (&lt;code dir=&quot;auto&quot;&gt;engine.py:107&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:132&lt;/code&gt;), and the bridge wraps the emitter in &lt;code dir=&quot;auto&quot;&gt;DecisionGitLog&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;runtime_bridge.py:497-512&lt;/code&gt;), which calls &lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; inline on every answered decision and swallows a failed commit as a warning (&lt;code dir=&quot;auto&quot;&gt;events/decision_log.py:85-87&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:269-276&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;The validation step is already pure: &lt;code dir=&quot;auto&quot;&gt;prepare_transition&lt;/code&gt; has “zero writes, zero locks, zero git, zero fan-out” (&lt;code dir=&quot;auto&quot;&gt;status/transition_pipeline.py:27-35&lt;/code&gt;). Its git-derived &lt;code dir=&quot;auto&quot;&gt;lane_head&lt;/code&gt; stamp is injected as a probe (&lt;code dir=&quot;auto&quot;&gt;status/emit.py:996-1006&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;The shells around it do the git and filesystem work in line. &lt;code dir=&quot;auto&quot;&gt;BookkeepingTransaction&lt;/code&gt; appends to the worktree log, commits through &lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;coordination/transaction.py:1225-1266&lt;/code&gt;), cuts the appended rows on failure (&lt;code dir=&quot;auto&quot;&gt;_cut_event_log&lt;/code&gt;, :1350) and runs deferred outbound effects only after the commit (:952-962, :1431). The coordination fallback commits status artifacts itself (&lt;code dir=&quot;auto&quot;&gt;coordination/status_transition.py:362-395&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:487&lt;/code&gt;). Mission creation commits its creation events to the coordination branch (&lt;code dir=&quot;auto&quot;&gt;core/mission_creation_events.py:163&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Outbound notification is a third concern mixed into the same shells: the flat shell fans out after releasing its lock (&lt;code dir=&quot;auto&quot;&gt;status/emit.py:1026-1035&lt;/code&gt;), the lifecycle writer fans out after its append (&lt;code dir=&quot;auto&quot;&gt;status/lifecycle_events.py:646&lt;/code&gt;), and the seam &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;fire_saas_fanout&lt;/code&gt; :265, &lt;code dir=&quot;auto&quot;&gt;fire_lifecycle_saas_fanout&lt;/code&gt; :382) still gates on hosted drain (:295, :393) until ADR 2026-10-13-2 D-2 lands.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;What “schemaVersion” means against the published contract.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;origin/main&lt;/code&gt; 5599380, package 10.4.6; the CLI pins &lt;code dir=&quot;auto&quot;&gt;&gt;=10.4.4,&amp;#x3C;11&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pyproject.toml:80&lt;/code&gt;) already has:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;An &lt;strong&gt;envelope&lt;/strong&gt; version: &lt;code dir=&quot;auto&quot;&gt;Event.schema_version&lt;/code&gt;, snake_case on the wire, default and only accepted value &lt;code dir=&quot;auto&quot;&gt;&quot;3.0.0&quot;&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;models.py:141&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;strict.py:144&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:629&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;contracts/versioning-and-compatibility.md&lt;/code&gt;). The contract says producers keep emitting &lt;code dir=&quot;auto&quot;&gt;3.0.0&lt;/code&gt; whatever the package major.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Per-family payload versions&lt;/strong&gt; for five families: &lt;code dir=&quot;auto&quot;&gt;CONNECTOR_SCHEMA_VERSION&lt;/code&gt; 2.8.0, &lt;code dir=&quot;auto&quot;&gt;DECISIONPOINT_SCHEMA_VERSION&lt;/code&gt; 3.0.0, &lt;code dir=&quot;auto&quot;&gt;AUDIT_SCHEMA_VERSION&lt;/code&gt; 2.5.0, &lt;code dir=&quot;auto&quot;&gt;PROFILE_INVOCATION_SCHEMA_VERSION&lt;/code&gt; 3.1.0, &lt;code dir=&quot;auto&quot;&gt;RETROSPECTIVE_SCHEMA_VERSION&lt;/code&gt; 4.1.0.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;So the requirement is met at the envelope level for events that leave the machine. It is not met where the operator needs it:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The envelope version is pinned to one value, so it tells a consumer nothing about the &lt;strong&gt;payload&lt;/strong&gt; shape. The families a Mission run produces most (&lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; lane transitions, &lt;code dir=&quot;auto&quot;&gt;project_lifecycle&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mission_next&lt;/code&gt;) have no payload version at all.&lt;/li&gt;
&lt;li&gt;The &lt;strong&gt;ledger rows&lt;/strong&gt; carry no version (rows 1, 2, 8), a local one that contradicts the wire (row 3’s &lt;code dir=&quot;auto&quot;&gt;&quot;5.0.0&quot;&lt;/code&gt;), or a different type (row 5’s integer). The row schema of ADR 2026-10-13-2 D-1 does not exist yet.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Single canonical authority&lt;/strong&gt; (charter): one writer, one contract, one place to change.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Pure domain core&lt;/strong&gt; (charter: DDD and tiered rigour): the run loop and the lane state machine decide; they do not touch git, files or transports.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Consumers choose their versions&lt;/strong&gt;: every persisted or published event says which shape it is.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No lost history&lt;/strong&gt;: the committed logs stay readable and are never rewritten (ADR 2026-10-13-2 D-3; 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;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The consolidation gates keep their evidence&lt;/strong&gt; (status events with &lt;code dir=&quot;auto&quot;&gt;policy_metadata.lane_head&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;review_result&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;force&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;One canonical event writer, the EventBridge, behind a domain port; side effects move into internal consumers (chosen, operator ruling 2026-10-14).&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;Keep the twelve producers and enforce the contract with a producer gate on persisted lines only (ADR 2026-10-13-2’s Confirmation).&lt;/li&gt;
&lt;li&gt;Keep writing internal rows and canonicalize only at the outbound edge, as &lt;code dir=&quot;auto&quot;&gt;build_saas_lifecycle_queue_event&lt;/code&gt; does today.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “One canonical event writer behind a domain port”, because it is the only option that gives the ledger one authority and lets the core stay domain code. Option 2 checks shapes but leaves twelve writers and inline git. Option 3 keeps the ledger non-canonical, so every consumer still needs a CLI-side translation.&lt;/p&gt;
&lt;h3 id=&quot;d-1-one-canonical-event-writer-the-eventbridge&quot;&gt;D-1: one canonical event writer, the EventBridge&lt;/h3&gt;
&lt;p&gt;The CLI has exactly one module that creates and persists events: the EventBridge. It is the single source of truth for event creation. Every event-like record the CLI persists, today’s producers 1 to 12 included, is created through it. No other module appends to an event log. The low-level append primitives become private to it.&lt;/p&gt;
&lt;h3 id=&quot;d-2-the-domain-depends-on-a-port-not-on-the-writer&quot;&gt;D-2: the domain depends on a port, not on the writer&lt;/h3&gt;
&lt;p&gt;The run loop and the state machine see only an EventBridge &lt;strong&gt;port&lt;/strong&gt;: a small interface owned by the domain layer, in the direction the layer rules allow (&lt;code dir=&quot;auto&quot;&gt;kernel &amp;#x3C;- charter &amp;#x3C;- {runtime, mission_runtime} &amp;#x3C;- specify_cli&lt;/code&gt;). The port has SSOT entry points for the facts the domain decides:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;a work package transition (the event &lt;code dir=&quot;auto&quot;&gt;prepare_transition&lt;/code&gt; already builds);&lt;/li&gt;
&lt;li&gt;a Mission state advance (run started, step issued, step completed, decision requested and answered, run completed).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The domain calls an entry point and knows nothing else: not the row format, not the ledger file, not the pub, ledger, sub flow, not git. The writer is an &lt;strong&gt;adapter&lt;/strong&gt; in &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;, bound at the composition root. &lt;code dir=&quot;auto&quot;&gt;RuntimeEventEmitter&lt;/code&gt; and its factory registry are the existing seed of this port and are grown into it, not duplicated. Facts produced outside the run loop (decision points, retrospective, glossary, Op records) use family entry points on the same bridge.&lt;/p&gt;
&lt;h3 id=&quot;d-3-contract-events-only-latest-version-every-event-versioned&quot;&gt;D-3: contract events only, latest version, every event versioned&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The bridge writes only events that conform to a contract published by &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;: a typed payload from the package, carried in the ledger row schema of ADR 2026-10-13-2 D-1. The full 3.0.0 envelope remains the wire contract for events that leave the machine.&lt;/li&gt;
&lt;li&gt;It produces only the &lt;strong&gt;latest&lt;/strong&gt; version of each event type. It does not write older shapes and does not dual-write.&lt;/li&gt;
&lt;li&gt;Every event carries its schema version, so a consumer knows what it is reading. On the wire the field is &lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt;, the published contract’s name, and it stays that name unless &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; changes it. The operator’s “schemaVersion” names this requirement, not a new field name. Two versions are needed and both must be present:
&lt;ul&gt;
&lt;li&gt;the envelope or row version (D-1 of ADR 2026-10-13-2);&lt;/li&gt;
&lt;li&gt;a payload version per event type, for every family the bridge writes. &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;project_lifecycle&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;mission_next&lt;/code&gt; have none today. &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; adds them; their field placement and name are that package’s call.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Consumers decide whether to support one version or several. The producer makes no promise to emit an old version for a consumer that has not upgraded. Compatibility is carried by the version marker and the package’s versioning rules (&lt;code dir=&quot;auto&quot;&gt;contracts/versioning-and-compatibility.md&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-3a-the-ledger-row-is-the-canonical-event-in-its-persisted-form-so-there-is-no-second-row-schema&quot;&gt;D-3a: the ledger row is the canonical event in its persisted form, so there is no second row schema&lt;/h3&gt;
&lt;p&gt;ADR 2026-10-13-2 D-1 asks for a versioned schema for each ledger row kind, published in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;. The operator now says the writer writes canonical &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; events only. Both texts hold under one reading, and this record adopts it:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The row schema D-1 asks for is the persisted form of a canonical event, and &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; publishes it.&lt;/strong&gt; A ledger row is one canonical event: the package’s row envelope (&lt;code dir=&quot;auto&quot;&gt;event_id&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;event_type&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt;, timestamp and ordering fields, aggregate identity) around the package’s typed payload for that &lt;code dir=&quot;auto&quot;&gt;event_type&lt;/code&gt;. “One schema per row kind” therefore means one published schema per event type, owned by &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;, never a CLI-owned row shape beside it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The row’s &lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt; is D-1’s row-level version marker.&lt;/strong&gt; No separate &lt;code dir=&quot;auto&quot;&gt;row_version&lt;/code&gt; field is added. The payload version of D-3 travels with the payload.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The persisted row is not the full 3.0.0 wire envelope.&lt;/strong&gt; ADR 2026-10-13-2 rejected writing 3.0.0 envelopes into the ledger (its “canonical 3.0.0 envelopes in the ledger” option), and that rejection stands. The wire envelope adds required transport and causality fields (&lt;code dir=&quot;auto&quot;&gt;build_id&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;node_id&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lamport_clock&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;correlation_id&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;project_uuid&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;models.py:110-140&lt;/code&gt;) that the local rows do not carry today. Turning a row into a wire envelope is a mechanical mapping that &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; defines and ships, so the event is the same canonical event on disk and on the wire. The CLI-side canonicalizer goes away (D-4).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Open question, with a default.&lt;/strong&gt; Should &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; later make the row envelope and the wire envelope one schema? Default: no. Keep two envelopes over one set of typed payloads, both published by &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;, until a consumer needs the transport fields on disk.&lt;/p&gt;
&lt;h3 id=&quot;d-4-the-internal-lifecycle-events-are-retired&quot;&gt;D-4: the internal lifecycle events are retired&lt;/h3&gt;
&lt;p&gt;Both internal lifecycle-event modules go. &lt;code dir=&quot;auto&quot;&gt;status/lifecycle_events.py&lt;/code&gt; is removed with its &lt;code dir=&quot;auto&quot;&gt;&quot;5.0.0&quot;&lt;/code&gt; local envelope, its &lt;code dir=&quot;auto&quot;&gt;LIFECYCLE_EVENT_TYPES&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;LOCAL_ONLY_LIFECYCLE_EVENT_TYPES&lt;/code&gt; sets and the CLI-side envelope rewrite for the hosted relay. &lt;code dir=&quot;auto&quot;&gt;retrospective/lifecycle_events.py&lt;/code&gt; is removed with its integer-versioned rows; the retrospective facts are written as the canonical &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; retrospective events (&lt;code dir=&quot;auto&quot;&gt;RETROSPECTIVE_SCHEMA_VERSION&lt;/code&gt;). Each lifecycle fact (project initialized, Mission created, specify, plan and tasks started and completed, work package created, reviewer self-approval, Mission reopened, follow-up recorded) is written as the canonical &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; event for it. A fact with no canonical event yet gets one in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; first (a minor release under its rules) before the CLI writes it. No new internal event type is added in the meantime.&lt;/p&gt;
&lt;h3 id=&quot;d-5-git-and-filesystem-effects-are-internal-consumers&quot;&gt;D-5: git and filesystem effects are internal consumers&lt;/h3&gt;
&lt;p&gt;Status commits, artifact writes, coordination commits, worktree work, the lane-state mirror, the derived projection refresh and outbound publication stop being inline steps of the transition shells. Each becomes an &lt;strong&gt;internal consumer&lt;/strong&gt; (a subscriber in the CLI) of the events the bridge writes. Two kinds:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Synchronous consumers&lt;/strong&gt; run inside the bridge’s unit of work, after the append and before it returns. The status commit is one: today’s guarantee holds that an event is announced only after its commit succeeded (&lt;code dir=&quot;auto&quot;&gt;coordination/status_transition.py:26-29&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Asynchronous consumers&lt;/strong&gt; run after the unit of work. They include the derived projection, the outbound publication adapter and the in-process seam of &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt;. Their failure never undoes or blocks the event.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;External publication is not one of these. The bridge’s external publication adapter is &lt;code dir=&quot;auto&quot;&gt;spec-kitty/event-router&lt;/code&gt;’s concern; it reads the ledger as ADR 2026-10-13-2 D-2 describes. The Zeitgeist handlers are no longer in this repository (#6164).&lt;/p&gt;
&lt;p&gt;This follows Martin Fowler’s &lt;a href=&quot;https://martinfowler.com/eaaDev/EventSourcing.html&quot;&gt;Event Sourcing&lt;/a&gt;: every change of state is captured as an event, and the event log, not the side effects, is the record. Lane state already works this way: &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; is its sole authority. This decision makes the rest of the core work the same way.&lt;/p&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;One writer and one contract. A consumer, in this repository or in event-router, needs only &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The run loop and the state machine become testable without git or a filesystem; a test port records the calls.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;canonical-producer-exempt&lt;/code&gt; markers (#1198, #1248, #1200), the lifecycle envelope, the hosted canonicalizer and the non-lane registry’s lifecycle half go away.&lt;/li&gt;
&lt;li&gt;Adding a side effect means adding a consumer, not editing a transition shell.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;A large migration across the 22 files that use the two lifecycle modules, three transition shells and the consolidation code. It cannot ship as one change.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; takes on payload versions for &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;project_lifecycle&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;mission_next&lt;/code&gt;, and the lifecycle events that have no canonical form today. Each is a cross-repository release before the CLI can switch.&lt;/li&gt;
&lt;li&gt;Moving side effects out of the shells changes their failure handling and needs new tests for every consumer.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The Mission Status Read API (ADR 2026-10-01-2) is unchanged; it reads the committed ledger.&lt;/li&gt;
&lt;li&gt;The hosted surfaces (&lt;code dir=&quot;auto&quot;&gt;hosted.drain&lt;/code&gt;, the hidden hosted CLI entries) were removed by #6164 and are not reintroduced.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;what-must-stay-true-during-the-migration&quot;&gt;What must stay true during the migration&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;One contract, two envelopes.&lt;/strong&gt; Event-router and other consumers read ledger rows against the &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; row-envelope schema plus the payload schema for each event type (D-3a). They do not read against a CLI schema or the 3.0.0 wire envelope. A consumer that also takes events from the wire uses the package’s row-to-wire mapping.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Existing logs.&lt;/strong&gt; Committed &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; and &lt;code dir=&quot;auto&quot;&gt;.kittify/canonical-events.jsonl&lt;/code&gt; rows are never rewritten. Readers keep accepting every historical shape: unversioned rows read as version 1 (ADR 2026-10-13-2 D-1), and &lt;code dir=&quot;auto&quot;&gt;&quot;5.0.0&quot;&lt;/code&gt; lifecycle rows stay readable as legacy. Only new rows use the canonical shape, so a Mission’s log can hold both. The merge driver installed for these files keeps working on mixed logs. The archive freeze compares reducer outcomes, not bytes, so it still holds.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reducer duality.&lt;/strong&gt; The bridge changes who writes, not how logs are reduced. Two reducers still ship: the Lamport wrapper &lt;code dir=&quot;auto&quot;&gt;materialize_snapshot&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;status/reducer.py:373-377&lt;/code&gt;, ADR 2026-02-09-3) and the wall-clock &lt;code dir=&quot;auto&quot;&gt;reduce_parsed&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;status/reducer.py:17&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;:176-181&lt;/code&gt;). The consolidation gates keep reading through the Lamport wrapper (&lt;code dir=&quot;auto&quot;&gt;consolidation/reconciliation.py::build_approved_wp_set&lt;/code&gt;, :1442). #4941 stays open, and nothing here resolves it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Consolidation gates.&lt;/strong&gt; The approval-stamp bound, per-WP attribution, the reconciliation claim, the coordination status-surface guard and the origin-freshness gate read status events. They read &lt;code dir=&quot;auto&quot;&gt;policy_metadata.lane_head&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;review_result&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;force&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;evidence&lt;/code&gt; and actor provenance. The canonical status event carries each of these, so the gates’ verdicts do not change. If a field changes form, the gate migrates in the same change. The &lt;code dir=&quot;auto&quot;&gt;lane_head&lt;/code&gt; probe stays a port the adapter fills; the domain never runs git to stamp it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Ordering and atomicity.&lt;/strong&gt; The event is appended before any consumer runs. A synchronous consumer that fails rolls the append back and the call raises, as &lt;code dir=&quot;auto&quot;&gt;BookkeepingTransaction&lt;/code&gt; does today; no consumer runs for an event that was cut. An asynchronous consumer that fails leaves the event recorded and its own work pending. Because consumers are idempotent by &lt;code dir=&quot;auto&quot;&gt;event_id&lt;/code&gt;, it can be rerun. &lt;code dir=&quot;auto&quot;&gt;DecisionGitLog&lt;/code&gt;’s swallowed commit failure becomes a recorded, rerunnable consumer failure.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Hosted stays out.&lt;/strong&gt; Nothing in this decision reintroduces, extends or points at Zeitgeist, auth or the hosted backend, which #6164 removed from open-core.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;An architectural gate finds exactly one module that appends to any event log (&lt;code dir=&quot;auto&quot;&gt;*.events.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;canonical-events.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;run.events.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mission-events.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;kitty-ops/*.jsonl&lt;/code&gt;), with an empty allowlist.&lt;/li&gt;
&lt;li&gt;The layer rules show &lt;code dir=&quot;auto&quot;&gt;runtime&lt;/code&gt; and the transition pipeline import the EventBridge port and nothing that runs git or writes event files.&lt;/li&gt;
&lt;li&gt;Every row the bridge writes validates against its &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; row schema and carries both version markers; no &lt;code dir=&quot;auto&quot;&gt;canonical-producer-exempt&lt;/code&gt; marker remains.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status/lifecycle_events.py&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;retrospective/lifecycle_events.py&lt;/code&gt; are gone, and &lt;code dir=&quot;auto&quot;&gt;git grep lifecycle_events -- src&lt;/code&gt; finds no importer.&lt;/li&gt;
&lt;li&gt;The consolidation suites (&lt;code dir=&quot;auto&quot;&gt;tests/consolidation/&lt;/code&gt;) pass unchanged over logs that mix legacy and canonical rows.&lt;/li&gt;
&lt;li&gt;A failing synchronous consumer leaves the log byte-identical; a failing asynchronous consumer leaves the event recorded, and a rerun completes it.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;open-questions-each-with-a-default&quot;&gt;Open questions (each with a default)&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Where the port and the bridge live.&lt;/strong&gt; Default: the port in &lt;code dir=&quot;auto&quot;&gt;src/runtime/&lt;/code&gt; next to &lt;code dir=&quot;auto&quot;&gt;RuntimeEventEmitter&lt;/code&gt;; the bridge adapter in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/events/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Payload version placement and name.&lt;/strong&gt; Default: a version field on each typed payload, named and placed by &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;, snake_case like &lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt;. The row’s own &lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt; is the row-envelope version (D-3a).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Do the file layouts change?&lt;/strong&gt; Default: no. The bridge writes the same files (&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; per Mission, &lt;code dir=&quot;auto&quot;&gt;.kittify/canonical-events.jsonl&lt;/code&gt; for project facts, the run journal, &lt;code dir=&quot;auto&quot;&gt;decisions.events.jsonl&lt;/code&gt;); it does not merge them into one ledger file.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Is the Mission state a projection of events?&lt;/strong&gt; Default: the run snapshot (&lt;code dir=&quot;auto&quot;&gt;engine.py:132&lt;/code&gt;) and &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; become projections rebuilt by consumers from the ledger; &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; stays authored configuration.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Consumer failure reporting.&lt;/strong&gt; Default: a pending asynchronous consumer is reported by &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor&lt;/code&gt; and rerun by an explicit command, never silently retried in a loop.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Order of migration.&lt;/strong&gt; Default: the work package transition first (one bridge entry point behind the two existing doors), then the run loop, then the lifecycle facts, then the remaining families.&lt;/li&gt;
&lt;/ol&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;a-producer-gate-over-twelve-writers&quot;&gt;A producer gate over twelve writers&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; smallest change; ADR 2026-10-13-2 already plans the gate. &lt;strong&gt;Cons:&lt;/strong&gt; compliance without one authority. The side effects stay inline, so the domain still runs git, and each new writer has to be caught by the gate after the fact.&lt;/p&gt;
&lt;h3 id=&quot;canonicalize-only-at-the-outbound-edge&quot;&gt;Canonicalize only at the outbound edge&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; the ledger is untouched. &lt;strong&gt;Cons:&lt;/strong&gt; the ledger stays CLI-internal, which contradicts “producers and consumers share only the contracts”. It keeps today’s translation step, the one that made &lt;code dir=&quot;auto&quot;&gt;MissionReopened&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;FollowUpRecorded&lt;/code&gt; local-only.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Martin Fowler, &lt;a href=&quot;https://martinfowler.com/eaaDev/EventSourcing.html&quot;&gt;Event Sourcing&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/4.x/2026-10-13-2-the-event-ledger-is-the-publication-seam-default-on-with-local-retention/&quot;&gt;ADR 2026-10-13-2&lt;/a&gt;: row contract, publication seam, retention.&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;, D-6: the read side.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/2.x/2026-02-09-3-event-log-merge-semantics/&quot;&gt;ADR 2026-02-09-3&lt;/a&gt;: event-log merge semantics.&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;: hosted surfaces frozen.&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;, &lt;code dir=&quot;auto&quot;&gt;models.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;Event.schema_version&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;strict.py&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendments&quot;&gt;Amendments&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;2026-10-22, factual (#6614, #6607; Mission &lt;code dir=&quot;auto&quot;&gt;event-write-hygiene-01M5HS55&lt;/code&gt;):&lt;/strong&gt; the write doors and seam names this ADR cites have changed. D-1 to D-5 are unchanged.
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Doors deleted.&lt;/strong&gt; The flat &lt;code dir=&quot;auto&quot;&gt;store.append_event&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;append_event_verified&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;append_primary_checkout_event_verified&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;coordination.status_service.append_event_log&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;kernel.atomic.notify_file_written&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;invocations_cmd.append_to_index&lt;/code&gt; had no production caller and are gone. The “two low-level append primitives” paragraph below the writer table still describes the two primitives that remain in use (its line numbers have shifted). This is a step toward ADR 2026-10-22-1’s Confirmation (“a Python writes gate with no appender left”); no append path was added.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Hosted builder deleted.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;build_saas_lifecycle_queue_event&lt;/code&gt;, which the context section calls a thirteenth row shape and Option 3 cites as today’s outbound-edge canonicalization, was dead code and is deleted, with &lt;code dir=&quot;auto&quot;&gt;_canonical_lifecycle_payload_for_saas&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_validate_lifecycle_payload&lt;/code&gt; and the public &lt;code dir=&quot;auto&quot;&gt;repo_root_for_lifecycle_log&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Seam renamed.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;fire_saas_fanout&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;fire_lifecycle_saas_fanout&lt;/code&gt; are now &lt;code dir=&quot;auto&quot;&gt;fire_status_fanout&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;fire_lifecycle_fanout&lt;/code&gt;, with no alias. The claim that the seam “gates on hosted drain” is stale: the drain posture was removed in #6164, and the seam registers no default handler, so producing an event never depends on a drain.&lt;/li&gt;
&lt;li&gt;The gap table in &lt;a href=&quot;/architecture/event-ledger-writers-and-readers/&quot;&gt;Event ledger writers and readers&lt;/a&gt; records G-11, G-16 and G-18 as closed.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&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; (operator ruling 2026-10-22): the canonical writer is the Java write service.
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;D-1.&lt;/strong&gt; The one module that persists events is the Java write service’s &lt;code dir=&quot;auto&quot;&gt;event-log&lt;/code&gt; module: the command side of the Mission Write API (#6117), one resident service per repository, keyed on the git common dir &lt;em&gt;(derived; ADR 2026-10-22-1 D-2)&lt;/em&gt;. It is no longer a module inside the CLI. “No other module appends to an event log” still holds, now across both languages.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D-2.&lt;/strong&gt; The domain still depends only on the EventBridge port, which stays in Python. The adapter in &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; is a client of the write service, not the writer. The CLI decides when and what to write; the service decides how and where.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D-5.&lt;/strong&gt; The synchronous consumers move inside the service’s unit of work: the append, the status commit and the cut on failure. The asynchronous consumers, including the produce seam &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt;, stay in the CLI or read the committed ledger by cursor.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Confirmation.&lt;/strong&gt; The single-writer proof becomes two gates: a Python writes gate with no appender left, and an ArchUnit rule that only &lt;code dir=&quot;auto&quot;&gt;event-log&lt;/code&gt; opens a ledger for writing. Rows are checked byte for byte against the &lt;code dir=&quot;auto&quot;&gt;ledger_append&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;status_append&lt;/code&gt; fixtures.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;“What must stay true”, the consolidation gates bullet.&lt;/strong&gt; “The &lt;code dir=&quot;auto&quot;&gt;lane_head&lt;/code&gt; probe stays a port the adapter fills” no longer holds. The probe moves into the write service’s &lt;code dir=&quot;auto&quot;&gt;GitPort&lt;/code&gt;, and the CLI adapter no longer fills it. The gates’ evidence fields are unchanged.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Unchanged.&lt;/strong&gt; D-3, D-3a and D-4.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;2026-10-22, factual (#4941, #6604):&lt;/strong&gt; the “Reducer duality” bullet under “What must stay true during the migration” is wrong about the code.
&lt;ul&gt;
&lt;li&gt;Both &lt;code dir=&quot;auto&quot;&gt;status.reducer.reduce&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;materialize_snapshot&lt;/code&gt; reach the wall-clock &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.diary.reduce_parsed&lt;/code&gt;. That is one reducer with two parsers; neither path is a Lamport wrapper.&lt;/li&gt;
&lt;li&gt;#4941’s library fix (the approved-departure lift, &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; 10.5.1) has shipped. What remains is narrower: a non-approval transition minted on a clock behind the event it follows still sorts before it.&lt;/li&gt;
&lt;li&gt;The consolidation gates read through that same reducer.&lt;/li&gt;
&lt;li&gt;The Technical Story’s “keeps ADR 2026-02-09-3 unchanged” now holds only for its merge rules. Its ordering is amended to wall clock for 4.0.0 (ADR 2026-02-09-3, Amendment 2026-10-22), and Lamport-primary ordering is a post-GA direction (#6609).&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-29-accepted-the-events-services-live-in-spec-kitty-events&quot;&gt;Amendment 2026-10-29 (Accepted): the events services live in spec-kitty-events&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;/adr/4.x/2026-10-29-1-the-events-domain-and-its-java-services-live-in-spec-kitty-events/&quot;&gt;ADR 2026-10-29-1&lt;/a&gt; records the operator and CEO ruling of 2026-10-29 that the events domain’s Java services and contracts move to &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;, and that core consumes a released, pinned build.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Where the writer lives.&lt;/strong&gt; The Java write service that 2026-10-22-1 made the canonical writer is built and released by &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;. Core keeps the domain port, &lt;code dir=&quot;auto&quot;&gt;bind_event_bridge&lt;/code&gt; and the client adapter. D-1 to D-5 are otherwise unchanged.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Nothing else in this record changes.&lt;/p&gt;</content>
</entry>
