<?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-29-1-the-events-domain-and-its-java-services-live-in-spec-kitty-events/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-29-1-the-events-domain-and-its-java-services-live-in-spec-kitty-events/</id>
  <title>ADR: the events domain and its Java services live in spec-kitty-events; core consumes a released, pinned service</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-29-1-the-events-domain-and-its-java-services-live-in-spec-kitty-events/"/>
  <summary>The Java event services and contracts move to spec-kitty-events; core pins a service-v* release by tag and sha256, fetches it on first use, and fails closed.</summary>
  <content type="html">&lt;h2 id=&quot;the-events-domain-and-its-java-services-live-in-spec-kitty-events-core-consumes-a-released-pinned-service&quot;&gt;The events domain and its Java services live in spec-kitty-events; core consumes a released, pinned service&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted (2026-10-29). The decision was made by the operator with the Spec Kitty CEO on 2026-10-29; the operator signed off this record, its &lt;em&gt;(derived)&lt;/em&gt; clauses included, the same day.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;What was ruled and what is derived.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Ruled by the operator (2026-10-29):&lt;/strong&gt;
&lt;ul&gt;
&lt;li&gt;The Java read service (Mission Status Read API) and the Java write service (Mission Write API / event-log write core) leave core for &lt;code dir=&quot;auto&quot;&gt;spec-kitty/spec-kitty-events&lt;/code&gt;, which becomes the canonical owner of the events domain.&lt;/li&gt;
&lt;li&gt;The build is Gradle everywhere, and history is preserved in the move.&lt;/li&gt;
&lt;li&gt;spec-kitty-events gets a separate &lt;code dir=&quot;auto&quot;&gt;service-vX.Y.Z&lt;/code&gt; release line, and core pins a service tag plus a sha256 per OS binary.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;services/&lt;/code&gt; is frozen in core from the decision onward.&lt;/li&gt;
&lt;li&gt;Layout in spec-kitty-events: &lt;code dir=&quot;auto&quot;&gt;service/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The contract bundles ride on &lt;code dir=&quot;auto&quot;&gt;service-v*&lt;/code&gt;. Two release lines exist in total, PyPI &lt;code dir=&quot;auto&quot;&gt;v*&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;service-v*&lt;/code&gt;, and core’s &lt;code dir=&quot;auto&quot;&gt;contract-&amp;#x3C;module&gt;-v*&lt;/code&gt; line retires.&lt;/li&gt;
&lt;li&gt;Events CI pins a core SHA for the lock-interop peer, the corpus compare and golden regeneration.&lt;/li&gt;
&lt;li&gt;Users get the binary by a first-run, digest-verified fetch, and the wheel stays pure.&lt;/li&gt;
&lt;li&gt;The read service is pinned in core for CI conformance only.&lt;/li&gt;
&lt;li&gt;acceptance-jvm fetches its contract tools from the pinned release.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Derived:&lt;/strong&gt; every clause marked &lt;em&gt;(derived)&lt;/em&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;/blockquote&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-29&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator), with the Spec Kitty CEO.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Epic #6117 (Mission Write API) and epic #6608 (event-native core).&lt;/li&gt;
&lt;li&gt;#6676 (the fail-closed launcher), #6590 (bundle the charter backend service through CI, the way the packs are), and #6409, #957 and #5528 (read API).&lt;/li&gt;
&lt;li&gt;This record amends:
&lt;ul&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-7, D-9 to D-12);&lt;/li&gt;
&lt;li&gt;&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; (where the writer lives);&lt;/li&gt;
&lt;li&gt;&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-5);&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/4.x/2026-10-27-1-the-write-service-protocol-is-loopback-http-with-a-bearer-token/&quot;&gt;ADR 2026-10-27-1&lt;/a&gt; (the launcher’s binary source);&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-04-25-1-shared-package-boundary/&quot;&gt;ADR 2026-04-25-1&lt;/a&gt; (what &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; is to core).&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;It follows the charter precedent: &lt;a href=&quot;/adr/4.x/2026-10-12-2-charter-extraction-to-its-own-repository/&quot;&gt;ADR 2026-10-12-2&lt;/a&gt; (Superseded), &lt;a href=&quot;/adr/4.x/2026-10-16-1-extract-charter-offering-first-activation-rework-post-ga/&quot;&gt;ADR 2026-10-16-1&lt;/a&gt; (Amendment 2026-10-19) and &lt;a href=&quot;/adr/4.x/2026-10-03-1-charter-read-write-service-strangler/&quot;&gt;ADR 2026-10-03-1&lt;/a&gt;. It differs from that precedent: here the service code does move, while the Python client side stays in core.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer changing how core builds, pins, fetches or launches an events service, or deciding where a piece of events-domain work belongs.&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;Core holds three things that belong to the events domain:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;services/mission-status-api/&lt;/code&gt;, a Gradle build (Spring Boot 4, GraalVM 25) with the read service and the &lt;code dir=&quot;auto&quot;&gt;domain-model&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;event-log&lt;/code&gt; libraries the write service is built from (#6192, #6193);&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;contracts/mission-status&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;contracts/mission-write&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;the workflow &lt;code dir=&quot;auto&quot;&gt;mission-status-api.yml&lt;/code&gt;, which builds per-OS native binaries.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The Python package &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; already owns event envelopes, payload schemas, fixtures and the reducer the Java &lt;code dir=&quot;auto&quot;&gt;StatusReducer&lt;/code&gt; ports. The events domain is therefore split across two repositories. Every change to an event model means coordinated edits in both: the Python model in spec-kitty-events, then the Java port, contract and goldens in core.&lt;/p&gt;
&lt;p&gt;The CLI itself never ran either service. The wheel ships no server (2026-10-01-2 D-7), and the write-service launcher (#6676) is unbuilt. Moving the code costs core nothing at runtime, but it does change how core gets the write binary once #6195 binds the EventBridge to it.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Single canonical authority: one repository owns an event model, its Java port, its contract and its release.&lt;/li&gt;
&lt;li&gt;Core’s job is to consume, pin and launch the binary, not to build it.&lt;/li&gt;
&lt;li&gt;One pin-and-fetch mechanism for every backend service core consumes: the events write service, the charter service (#6590), and the read service for CI.&lt;/li&gt;
&lt;li&gt;Fail closed, with no Python fallback writer (2026-10-22-1 D-5).&lt;/li&gt;
&lt;li&gt;Keep the wheel pure, and keep CLI reads working with no binary present.&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;Keep the services in core and let spec-kitty-events stay Python-only.&lt;/li&gt;
&lt;li&gt;Move the services and contracts to spec-kitty-events; core pins a released build (chosen).&lt;/li&gt;
&lt;li&gt;Move them to a new dedicated service repository.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;Chosen option: &lt;strong&gt;2&lt;/strong&gt;.&lt;/p&gt;
&lt;h3 id=&quot;d-1-spec-kitty-events-owns-the-java-services-and-the-events-contracts&quot;&gt;D-1: spec-kitty-events owns the Java services and the events contracts&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The read service, the &lt;code dir=&quot;auto&quot;&gt;domain-model&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;event-log&lt;/code&gt; libraries, the future &lt;code dir=&quot;auto&quot;&gt;command-cli&lt;/code&gt; write deployable, and &lt;code dir=&quot;auto&quot;&gt;contracts/{mission-status,mission-write,_shared,tools,lint}&lt;/code&gt; live in spec-kitty-events (&lt;code dir=&quot;auto&quot;&gt;service/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt;). They are imported with their history.&lt;/li&gt;
&lt;li&gt;Core’s copies are removed at the cut-over. Core’s history is kept.&lt;/li&gt;
&lt;li&gt;Java work on these modules is filed and done in spec-kitty-events.&lt;/li&gt;
&lt;li&gt;The architecture page &lt;code dir=&quot;auto&quot;&gt;docs/architecture/event-ledger-writers-and-readers.md&lt;/code&gt; moves to spec-kitty-events with the domain. It stays frozen in core, and corrections to it are made there (operator ruling, 2026-10-29).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-2-the-service-v-release-line-is-cores-only-source-for-service-binaries&quot;&gt;D-2: the &lt;code dir=&quot;auto&quot;&gt;service-v*&lt;/code&gt; release line is core’s only source for service binaries&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Each &lt;code dir=&quot;auto&quot;&gt;service-vX.Y.Z&lt;/code&gt; release carries, per deployable:
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;deployable&gt;-&amp;#x3C;ver&gt;-&amp;#x3C;target&gt;[.exe]&lt;/code&gt; for linux-x64, linux-arm64, macos-arm64 and windows-x64, each with a &lt;code dir=&quot;auto&quot;&gt;.sha256&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;deployable&gt;-&amp;#x3C;ver&gt;.jar&lt;/code&gt; (the JVM fallback of 2026-10-22-1 D-5).&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Each release also carries &lt;code dir=&quot;auto&quot;&gt;contract-bundles-&amp;#x3C;ver&gt;.tar.gz&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;contract-tools-&amp;#x3C;ver&gt;.tar.gz&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;conformance-fixtures-&amp;#x3C;ver&gt;.tar.gz&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;SHA256SUMS&lt;/code&gt; and an SLSA attestation. Asset names are stable across releases; only &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;ver&gt;&lt;/code&gt; changes.&lt;/li&gt;
&lt;li&gt;Core’s &lt;code dir=&quot;auto&quot;&gt;contract-&amp;#x3C;module&gt;-v*&lt;/code&gt; line and &lt;code dir=&quot;auto&quot;&gt;contracts-release.yml&lt;/code&gt; retire.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-3-core-pins-a-release-by-tag-and-per-asset-sha256-derived-from-the-ruling&quot;&gt;D-3: core pins a release by tag and per-asset sha256 &lt;em&gt;(derived from the ruling)&lt;/em&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;One lockfile per service, &lt;code dir=&quot;auto&quot;&gt;pins/&amp;#x3C;service&gt;.source.yaml&lt;/code&gt;, shaped like &lt;code dir=&quot;auto&quot;&gt;packs/*.source.yaml&lt;/code&gt;. It records:
&lt;ul&gt;
&lt;li&gt;the repository, the tag, and the resolved commit;&lt;/li&gt;
&lt;li&gt;the protocol versions and &lt;code dir=&quot;auto&quot;&gt;requires_core&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;per target, the asset name and its sha256;&lt;/li&gt;
&lt;li&gt;the contract and fixture assets.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;The single bump path is &lt;code dir=&quot;auto&quot;&gt;spec-kitty service vendor --service &amp;#x3C;s&gt; --tag &amp;#x3C;t&gt;&lt;/code&gt;. A pin gate in CI catches drift.&lt;/li&gt;
&lt;li&gt;A binary is executed only when its bytes match a pinned sha256. A cached copy is re-hashed on every resolve, and a mismatch is deleted and fetched again.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-4-users-get-the-binary-by-a-first-run-digest-verified-fetch&quot;&gt;D-4: users get the binary by a first-run, digest-verified fetch&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The wheel stays &lt;code dir=&quot;auto&quot;&gt;py3-none-any&lt;/code&gt; and ships the pins, not the binaries.&lt;/li&gt;
&lt;li&gt;On first need, the launcher fetches the host target’s asset into &lt;code dir=&quot;auto&quot;&gt;${XDG_CACHE_HOME}/spec-kitty/services/&amp;#x3C;service&gt;/&amp;#x3C;tag&gt;/&lt;/code&gt; and verifies it.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty service fetch&lt;/code&gt; pre-fetches. &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SERVICE_ASSET_DIR&lt;/code&gt; serves an offline or air-gapped install from a local directory. Assets served that way are still digest-checked.&lt;/li&gt;
&lt;li&gt;An install-provided slot stays in the resolution order, so a companion platform wheel can be added later without changing the launcher.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-5-one-launcher-fail-closed-for-every-pinned-service-derived&quot;&gt;D-5: one launcher, fail-closed, for every pinned service &lt;em&gt;(derived)&lt;/em&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; owns one launcher with a per-service policy:
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Write service:&lt;/strong&gt; one per git common dir, launch-when-down, endpoint file per 2026-10-27-1.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Charter service:&lt;/strong&gt; one per worktree, token-gated, per 2026-10-03-1.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Read service:&lt;/strong&gt; never launched by the CLI (D-6).&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Resolution order:
&lt;ol&gt;
&lt;li&gt;an explicit binary path, still digest-checked;&lt;/li&gt;
&lt;li&gt;the install-provided slot;&lt;/li&gt;
&lt;li&gt;the cached native asset;&lt;/li&gt;
&lt;li&gt;the JVM jar on a local JDK 25;&lt;/li&gt;
&lt;li&gt;otherwise a refusal.&lt;/li&gt;
&lt;/ol&gt;
&lt;/li&gt;
&lt;li&gt;Dev-only digest bypass (operator ruling, 2026-10-29): an explicit binary path may skip the digest check only when the developer passes an opt-in flag (&lt;code dir=&quot;auto&quot;&gt;--unpinned-dev&lt;/code&gt;).
&lt;ul&gt;
&lt;li&gt;It is never the default.&lt;/li&gt;
&lt;li&gt;Every use prints a visible warning.&lt;/li&gt;
&lt;li&gt;CI and release paths never use it.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Refusals carry a named code and a remedy: &lt;code dir=&quot;auto&quot;&gt;SERVICE_BINARY_MISSING&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;SERVICE_BINARY_DIGEST_MISMATCH&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;SERVICE_UNSUPPORTED_PLATFORM&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;SERVICE_UNHEALTHY&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;SERVICE_VERSION_MISMATCH&lt;/code&gt;, plus the existing &lt;code dir=&quot;auto&quot;&gt;WRITE_SERVICE_ENDPOINT_*&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;There is no Python fallback writer. Reads keep working with no binary present.&lt;/li&gt;
&lt;li&gt;The launcher’s start, health and stop half of #6676 lives here. The native-image build half moves to spec-kitty-events.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-6-the-read-service-is-pinned-for-ci-conformance-only&quot;&gt;D-6: the read service is pinned for CI conformance only&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Core pins the read service to run the Python-oracle conformance and corpus comparisons against the released binary.&lt;/li&gt;
&lt;li&gt;The CLI never launches it. 2026-10-01-2 D-5 and D-7 hold.&lt;/li&gt;
&lt;li&gt;Consumers (mission-ui, the pack composer) fetch it from spec-kitty-events themselves.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-7-the-client-side-stays-in-core-derived&quot;&gt;D-7: the client side stays in core &lt;em&gt;(derived)&lt;/em&gt;&lt;/h3&gt;
&lt;p&gt;These stay in core:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the EventBridge port and &lt;code dir=&quot;auto&quot;&gt;bind_event_bridge&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;LocalFileEventBridge&lt;/code&gt;, until #6195;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;write_service_protocol.py&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;kernel.locks&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;kernel.event_log_append&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;the Python oracle tests and the CI scripts that drive a binary (&lt;code dir=&quot;auto&quot;&gt;mission_status_corpus_compare.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lock_interop_peer.py&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;spec-kitty-events CI checks out core at a pinned SHA to run them.&lt;/p&gt;
&lt;h3 id=&quot;d-8-one-owner-for-http-release-asset-downloads-derived&quot;&gt;D-8: one owner for HTTP release-asset downloads &lt;em&gt;(derived)&lt;/em&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Fetching a release asset is new remote contact.&lt;/li&gt;
&lt;li&gt;It gets one owner module in &lt;code dir=&quot;auto&quot;&gt;kernel&lt;/code&gt; and a sibling gate to &lt;code dir=&quot;auto&quot;&gt;test_remote_contact_owner.py&lt;/code&gt;, with an empty allowlist. It does not become a scattered HTTP call.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-9-freeze-until-removal&quot;&gt;D-9: freeze until removal&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;No change lands in core after 2026-10-29 under any of these frozen paths. Queued Java work moves to spec-kitty-events.
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;services/&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;contracts/mission-status&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;contracts/mission-write&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;contracts/_shared&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;contracts/tools&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;contracts/lint&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;contracts/gradle&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;contracts/README.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;contracts/build.gradle&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;contracts/settings.gradle&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/architecture/event-ledger-writers-and-readers.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;contracts/fixtures/&lt;/code&gt; stays in core and is not frozen.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;The architectural gate &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_events_import_frozen.py&lt;/code&gt; enforces the freeze (its &lt;code dir=&quot;auto&quot;&gt;_FROZEN_OBJECTS&lt;/code&gt; is the exact set above). It lands in the same PR as this record.&lt;/li&gt;
&lt;li&gt;Exception path: an operator-approved change to a frozen path may re-pin &lt;code dir=&quot;auto&quot;&gt;_FROZEN_OBJECTS&lt;/code&gt; in the same PR, and that change is ported to spec-kitty-events.&lt;/li&gt;
&lt;li&gt;Exit: the gate is removed together with &lt;code dir=&quot;auto&quot;&gt;services/&lt;/code&gt; at the cut-over. That exit is tracked by #6117, owner Stijn Dejongh.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Positive&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;One repository owns each event model end to end.&lt;/li&gt;
&lt;li&gt;The pin-and-fetch mechanism, the lockfile and the launcher serve the charter service too (#6590).&lt;/li&gt;
&lt;li&gt;Core CI no longer builds GraalVM binaries.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Negative&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Two repositories now pin each other: core pins a &lt;code dir=&quot;auto&quot;&gt;service-v*&lt;/code&gt; release, and events CI pins a core SHA for the interop peer and the corpus compare.&lt;/li&gt;
&lt;li&gt;A golden regeneration becomes a PR in events that records the core SHA.&lt;/li&gt;
&lt;li&gt;A first write on a fresh install needs network access, or a pre-fetched asset directory. Without either, the write refuses.&lt;/li&gt;
&lt;li&gt;A pin bump is a core PR.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Neutral&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The Shared Package Boundary now has two artifact kinds for &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;: the PyPI package (a SemVer range plus the lockfile) and the pinned service binaries (tag plus sha256).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;After the cut-over, &lt;code dir=&quot;auto&quot;&gt;services/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mission-status-api.yml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;contracts.yml&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;contracts-release.yml&lt;/code&gt; are absent from core.&lt;/li&gt;
&lt;li&gt;The pin gate and the release-asset owner gate are green, and the packaging guards pass with no binary in the wheel or sdist.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;test_shared_package_boundary.py&lt;/code&gt; accepts the pins.&lt;/li&gt;
&lt;li&gt;The conformance tests run against the pinned fixtures and the pinned binary.&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;keep-the-services-in-core&quot;&gt;Keep the services in core&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Good: there is no cross-repository pin.&lt;/li&gt;
&lt;li&gt;Bad: the events domain stays split, so every event-model change means two coordinated PRs, and core keeps a GraalVM build it does not run.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;move-them-to-spec-kitty-events-chosen&quot;&gt;Move them to spec-kitty-events (chosen)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Good: one owner; one release line per artifact kind; core only consumes.&lt;/li&gt;
&lt;li&gt;Bad: mutual pins; network on first write.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;move-them-to-a-new-service-repository&quot;&gt;Move them to a new service repository&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Good: a clean separation from the Python package.&lt;/li&gt;
&lt;li&gt;Bad: a third repository to coordinate, and the events domain would still be split between the Python models and the Java port.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Core-side plan, inventory and cut-over runbook: &lt;a href=&quot;/plans/events-domain-move/plan/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/plans/events-domain-move/plan.md&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Precedent for the pin and fetch: &lt;a href=&quot;/development/how-to/sync-packs/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/development/how-to/sync-packs.md&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-30-accepted-refusal-codes-and-pin-location&quot;&gt;Amendment 2026-10-30 (Accepted): refusal codes and pin location&lt;/h2&gt;
&lt;p&gt;The pre-PR review of the implementation (#6590) settled four points this record left implicit. The body above is unchanged.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Refusal codes.&lt;/strong&gt; Besides the D-5 codes, the launcher and the operator commands use:
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SERVICE_PIN_INVALID&lt;/code&gt;: no pin for the service in this core version, or a malformed or placeholder lockfile;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SERVICE_VENDOR_*&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;USAGE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;COMMIT_REQUIRED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;TAG_UNRESOLVED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;RELEASE_UNAVAILABLE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;RELEASE_INVALID&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;DIGEST_MISMATCH&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;REQUIRES_CORE&lt;/code&gt;): &lt;code dir=&quot;auto&quot;&gt;spec-kitty service vendor&lt;/code&gt; refused a bump or a check.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Pin location.&lt;/strong&gt; The CLI reads its own pin: the &lt;code dir=&quot;auto&quot;&gt;pins/&lt;/code&gt; directory of the spec-kitty source checkout the running package belongs to, or the &lt;code dir=&quot;auto&quot;&gt;specify_cli/_pins/&lt;/code&gt; resource of the installed wheel. It never reads a pin from the user’s project. &lt;code dir=&quot;auto&quot;&gt;spec-kitty service vendor&lt;/code&gt; writes only that source checkout’s &lt;code dir=&quot;auto&quot;&gt;pins/&lt;/code&gt;, and only when run inside it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The read service stays off user machines (D-6).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty service fetch --all&lt;/code&gt; covers only the services the CLI launches, and &lt;code dir=&quot;auto&quot;&gt;spec-kitty service status&lt;/code&gt; reports the write service unless another is named. The read service is fetched only when it is named explicitly (&lt;code dir=&quot;auto&quot;&gt;--service read-service&lt;/code&gt;), as CI does.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Stop outcomes.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty service stop&lt;/code&gt; has four outcomes: stopped, not running, forced, and unconfirmed. Unconfirmed means the published process is alive but could not be proven to be the instance, so it was not signalled. It exits 1 and names the pid and the log.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-31-accepted-the-optional-companion-services-wheel&quot;&gt;Amendment 2026-10-31 (Accepted): the optional companion services wheel&lt;/h2&gt;
&lt;p&gt;Operator ruling 2 of 2026-10-31 (#6117) fills the install-provided slot that D-4 reserved. Tracked by #6904; the research and the twelve recommendations the operator accepted are in &lt;a href=&quot;/plans/events-domain-move/companion-wheel-research/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/plans/events-domain-move/companion-wheel-research.md&lt;/code&gt;&lt;/a&gt;. The body above is unchanged; D-4’s first-run fetch stays the default for every install.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Name.&lt;/strong&gt; The companion is the distribution &lt;code dir=&quot;auto&quot;&gt;spec-kitty-services&lt;/code&gt; (import package &lt;code dir=&quot;auto&quot;&gt;spec_kitty_services&lt;/code&gt;). Its source lives in &lt;code dir=&quot;auto&quot;&gt;packages/spec-kitty-services/&lt;/code&gt;, outside &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;, and is excluded from the CLI sdist.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Install.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; gains the extra &lt;code dir=&quot;auto&quot;&gt;services&lt;/code&gt;, which requires &lt;code dir=&quot;auto&quot;&gt;spec-kitty-services==&amp;#x3C;cli version&gt;&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;pip install &quot;spec-kitty-cli[services]&quot;&lt;/code&gt; is the one-command offline-ready install; &lt;code dir=&quot;auto&quot;&gt;pip install spec-kitty-services==&amp;#x3C;cli version&gt;&lt;/code&gt; also works.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Version lock.&lt;/strong&gt; The companion’s version equals the CLI’s version, and so does the extra pin. A test and &lt;code dir=&quot;auto&quot;&gt;scripts/release/validate_release.py&lt;/code&gt; check all three. Each companion wheel is built from the same release commit’s &lt;code dir=&quot;auto&quot;&gt;pins/&lt;/code&gt; and embeds a &lt;code dir=&quot;auto&quot;&gt;spec_kitty_services/_manifest.json&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;{service, tag, asset, sha256}&lt;/code&gt; per binary.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Skew degrades, tampering refuses.&lt;/strong&gt; A provider offers nothing when the installed CLI version or the host target differs from its manifest, so resolution falls through to the cache and fetch. Whatever a provider does offer is still digest-checked against the CLI’s own pin, and a mismatch refuses with &lt;code dir=&quot;auto&quot;&gt;SERVICE_BINARY_DIGEST_MISMATCH&lt;/code&gt; (D-5 unchanged).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Contents.&lt;/strong&gt; Each platform wheel carries the native write-service and charter-service builds pinned for its own target, and nothing else: never the read service (D-6), no jar, no contract or fixture assets.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fallback wheel.&lt;/strong&gt; A binary-free &lt;code dir=&quot;auto&quot;&gt;py3-none-any&lt;/code&gt; wheel of the same version makes the extra installable on every host (Intel macOS, musl Linux, Linux below the glibc floor, Windows on ARM). Its providers offer nothing, so those hosts use the first-run fetch.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Platform tags.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;py3-none-manylinux_2_39_x86_64&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;py3-none-manylinux_2_39_aarch64&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;py3-none-macosx_11_0_arm64&lt;/code&gt; (the first Apple Silicon macOS) and &lt;code dir=&quot;auto&quot;&gt;py3-none-win_amd64&lt;/code&gt;. GraalVM links glibc dynamically, so the Linux floor is the glibc of the spec-kitty-events build hosts (2.39 on &lt;code dir=&quot;auto&quot;&gt;ubuntu-24.04&lt;/code&gt;); &lt;code dir=&quot;auto&quot;&gt;release.yml&lt;/code&gt; passes it to the builder explicitly (&lt;code dir=&quot;auto&quot;&gt;--glibc-floor 2_39&lt;/code&gt;) and must change together with those hosts. Neither floor is yet read from the binary itself (follow-up #6948). Lowering the Linux floor is spec-kitty-events work.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Amendment (#6948): floors are read from the binary.&lt;/strong&gt; The build reads each pinned binary’s own floor (the highest &lt;code dir=&quot;auto&quot;&gt;GLIBC_x.y&lt;/code&gt; need, or the Mach-O &lt;code dir=&quot;auto&quot;&gt;minos&lt;/code&gt;) and refuses a wheel whose tag would understate it, so the declared floors above stay the published tags and a binary that needs more is a build failure, not a quietly narrower install base. A macOS floor with a minor is refused from macOS 11 on, because pip generates only &lt;code dir=&quot;auto&quot;&gt;macosx_&amp;#x3C;major&gt;_0&lt;/code&gt; tags.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Built, never rebuilt.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;scripts/build_services_wheel.py&lt;/code&gt; fetches every asset through &lt;code dir=&quot;auto&quot;&gt;kernel.service_artifacts.fetch_asset&lt;/code&gt; (D-8’s owner; every byte is checked against the pinned sha256) and writes the wheels with the standard library, deterministically. A &lt;code dir=&quot;auto&quot;&gt;--verify&lt;/code&gt; pass proves each wheel holds exactly the pinned digests.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Size.&lt;/strong&gt; PyPI’s default per-file limit is 100 MB. The build fails above 95 MB per wheel and warns above 60 MB (the threshold of plan §3.4). No binary size has been measured yet; the estimate is 60–85 MB per platform wheel. Splitting the companion into one wheel per service needs its own amendment.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Release.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;release.yml&lt;/code&gt; gains &lt;code dir=&quot;auto&quot;&gt;build-companion-wheels&lt;/code&gt; (to &lt;code dir=&quot;auto&quot;&gt;dist-services/&lt;/code&gt;, never &lt;code dir=&quot;auto&quot;&gt;dist/&lt;/code&gt;) and &lt;code dir=&quot;auto&quot;&gt;publish-companion-pypi&lt;/code&gt; (environment &lt;code dir=&quot;auto&quot;&gt;pypi-services&lt;/code&gt;, Trusted Publishing). &lt;code dir=&quot;auto&quot;&gt;publish-pypi&lt;/code&gt; waits for the companion, so the CLI’s exact extra always resolves. With no pin, only the fallback wheel is built and published.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Resolution order is unchanged:&lt;/strong&gt; explicit path, the install slot, the cached native asset, the jar, then a refusal (D-5).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;uv workspace member.&lt;/strong&gt; The exact extra cannot lock from PyPI, because the companion of version X is published in the same release run as commit X. &lt;code dir=&quot;auto&quot;&gt;packages/spec-kitty-services&lt;/code&gt; is therefore a uv workspace member: &lt;code dir=&quot;auto&quot;&gt;[tool.uv.workspace] members = [&quot;packages/spec-kitty-services&quot;]&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;[tool.uv.sources] spec-kitty-services = { workspace = true }&lt;/code&gt; (operator ruling, 2026-10-31). It is a first-party member, not an override of an external package, so the Shared Package Boundary (ADR 2026-04-25-1) is unchanged. The companion carries a standard-library in-tree build backend, which builds the fallback wheel and shares its wheel writer with the release script.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Operator prerequisites before the first release that carries the extra:&lt;/strong&gt; claim the PyPI name &lt;code dir=&quot;auto&quot;&gt;spec-kitty-services&lt;/code&gt; (a pending Trusted Publisher does not reserve it; upload the binary-free fallback wheel once), bind its Trusted Publisher to this repository’s &lt;code dir=&quot;auto&quot;&gt;release.yml&lt;/code&gt; and the GitHub environment &lt;code dir=&quot;auto&quot;&gt;pypi-services&lt;/code&gt;, and create that environment. Until the name is claimed, anyone could register it, and the CLI’s published &lt;code dir=&quot;auto&quot;&gt;services&lt;/code&gt; extra would resolve to their package.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Emergency waiver &lt;code dir=&quot;auto&quot;&gt;skip_companion&lt;/code&gt;.&lt;/strong&gt; A manually dispatched &lt;code dir=&quot;auto&quot;&gt;release.yml&lt;/code&gt; run (never a tag push) can set &lt;code dir=&quot;auto&quot;&gt;skip_companion=true&lt;/code&gt;, shaped like &lt;code dir=&quot;auto&quot;&gt;skip_nightly&lt;/code&gt;: the companion build, verify and publish jobs are skipped and &lt;code dir=&quot;auto&quot;&gt;publish-pypi&lt;/code&gt; no longer waits for the companion. The run first refuses unless &lt;code dir=&quot;auto&quot;&gt;spec-kitty-services==&amp;#x3C;version&gt;&lt;/code&gt; already exists on PyPI, because the CLI’s &lt;code dir=&quot;auto&quot;&gt;services&lt;/code&gt; extra pins that exact version; the waiver therefore suits an orphan or hand-published companion, and does not let a CLI release ship an extra that cannot resolve. The release then lacks a freshly built and verified companion for this run. Use it only when a failed companion publish would otherwise block a CLI release.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;PyPI storage quota.&lt;/strong&gt; Each release uploads about four wheels of 60-85 MB for the companion against the 10 GB default project quota; prune release candidates or request a raise before the quota runs out.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Orphan companion version.&lt;/strong&gt; If the companion publishes and the CLI publish then fails, that companion version stays on PyPI and cannot be re-uploaded. This is tolerable: the CLI re-run reuses it through &lt;code dir=&quot;auto&quot;&gt;skip-existing&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
