<?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-27-1-the-write-service-protocol-is-loopback-http-with-a-bearer-token/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-27-1-the-write-service-protocol-is-loopback-http-with-a-bearer-token/</id>
  <title>ADR: the write-service protocol is loopback HTTP with a bearer token from the git common dir</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-27-1-the-write-service-protocol-is-loopback-http-with-a-bearer-token/"/>
  <summary>The CLI reaches its write service on 127.0.0.1 with a per-clone bearer token; the service is authoritative, refuses with the CLI&apos;s codes, and acks one synced append.</summary>
  <content type="html">&lt;h2 id=&quot;the-write-service-protocol-is-loopback-http-with-a-bearer-token-from-the-git-common-dir&quot;&gt;The write-service protocol is loopback HTTP with a bearer token from the git common dir&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted (2026-10-27). Operator rulings of 2026-10-25 (on #6675) and 2026-10-27 (the Decision Moments of Mission &lt;code dir=&quot;auto&quot;&gt;write-service-protocol-01M5Z6N5&lt;/code&gt;). 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;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-25):&lt;/strong&gt; loopback HTTP on &lt;code dir=&quot;auto&quot;&gt;127.0.0.1&lt;/code&gt; with a random port; the port and a random bearer token in a file in the git common dir, one writer per clone; the service is authoritative and refuses with structured codes that match the CLI’s; one &lt;code dir=&quot;auto&quot;&gt;O_APPEND&lt;/code&gt; write of a full JSON line, &lt;code dir=&quot;auto&quot;&gt;fsync&lt;/code&gt; before the ack, a batched &lt;code dir=&quot;auto&quot;&gt;fsync&lt;/code&gt; for multi-event operations; Windows semantics documented under the lock.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Ruled by the operator (2026-10-27):&lt;/strong&gt; the refusal &lt;code dir=&quot;auto&quot;&gt;code&lt;/code&gt; reuses the CLI’s codes verbatim and the guard reasons are minted as provisional URNs; the bearer scheme is declared natively in the contract (a narrow amendment of the contract layout check); protocol questions not yet ruled carry provisional defaults; the client side ships typed shapes and one binder with no transport; the shapes’ dead-code debt is priced with the #6195 exit (Decision Moments DM-01M5Z6TDWPD1RGWDNXQGQW27C9 and DM-01M5ZC1PYHBB6QB02YQ4H1V52P: 11 dead-symbol entries in &lt;code dir=&quot;auto&quot;&gt;category_c_write_service_client_6675&lt;/code&gt; and one dead-module entry).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Derived:&lt;/strong&gt; clauses marked &lt;em&gt;(derived)&lt;/em&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Open:&lt;/strong&gt; the open questions at the end carry defaults that hold until the operator rules otherwise.&lt;/li&gt;
&lt;/ul&gt;
&lt;/blockquote&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-27&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;#6675 (this protocol), in epic #6117 (Mission Write API).&lt;/li&gt;
&lt;li&gt;It amends &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;: open question 3 (transport and trust model) and D-7 (which append semantics are authoritative).&lt;/li&gt;
&lt;li&gt;Coordinated by reference, not changed: #6676 (the fail-closed launcher), #6193 (the lock-interop spike), #6195 (the lane-transition cut-over that binds the client), spec-kitty/spec-kitty-events#92 (the event envelope).&lt;/li&gt;
&lt;li&gt;The contract: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty-events/blob/main/contracts/mission-write/openapi.yaml&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;contracts/mission-write/openapi.yaml&lt;/code&gt;&lt;/a&gt; (in spec-kitty-events since #6915). The client shapes: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/write_service_protocol.py&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer building the write-service client behind the EventBridge port, or the Java write service, or its launcher.&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;ADR 2026-10-22-1 makes a resident Java service per repository the one event writer, reached through the CLI’s EventBridge port. It left the transport open, with a local socket as the default (open question 3), and left the append semantics open (D-7). Nothing defined what the CLI sends, what the service answers, how a client finds and trusts the running service, or how the two agree on a protocol version.&lt;/p&gt;
&lt;p&gt;The read service (&lt;code dir=&quot;auto&quot;&gt;services/mission-status-api&lt;/code&gt;) already sets a local precedent: it binds &lt;code dir=&quot;auto&quot;&gt;127.0.0.1&lt;/code&gt; only and refuses a foreign &lt;code dir=&quot;auto&quot;&gt;Host&lt;/code&gt;, a foreign &lt;code dir=&quot;auto&quot;&gt;Origin&lt;/code&gt; and a cross-site fetch. It has no token, because it only reads.&lt;/p&gt;
&lt;p&gt;The CLI refuses writes today with codes scattered over many modules, and the lane state machine’s guards raise free text with no code at all; only the &lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt; edge turns them into codes (&lt;code dir=&quot;auto&quot;&gt;TRANSITION_REJECTED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;WP_ALREADY_CLAIMED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;DEPENDENCIES_NOT_SATISFIED&lt;/code&gt;). Moving validation into the service must not change a code a user or a script sees.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;One writer per clone&lt;/strong&gt; (ADR 2026-10-22-1 D-2).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fail closed:&lt;/strong&gt; a stale endpoint, a recycled port, a foreign process or a version skew must refuse, never write to the wrong place.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No lost history:&lt;/strong&gt; a write is acknowledged only when it is durable.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Parity:&lt;/strong&gt; the service’s refusals carry the codes the CLI raises today.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Contract first:&lt;/strong&gt; the client and the service are built against one checked boundary.&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;A local socket, a named pipe on Windows&lt;/strong&gt; (ADR 2026-10-22-1’s default).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Loopback HTTP on &lt;code dir=&quot;auto&quot;&gt;127.0.0.1&lt;/code&gt; with a random port and a bearer token&lt;/strong&gt; (chosen, ruled).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Standard input and output of a process per write&lt;/strong&gt; (rejected by ADR 2026-10-22-1 D-2: a start per transition).&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; “Loopback HTTP on &lt;code dir=&quot;auto&quot;&gt;127.0.0.1&lt;/code&gt; with a random port and a bearer token”. It reuses the read service’s HTTP stack, guard and contract tooling, it is the same on every platform, and an OpenAPI contract describes it with the tools the repository already runs.&lt;/p&gt;
&lt;h3 id=&quot;d-1-transport&quot;&gt;D-1: transport&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The service binds &lt;code dir=&quot;auto&quot;&gt;127.0.0.1&lt;/code&gt; only, on a port the operating system picks (port 0), and never &lt;code dir=&quot;auto&quot;&gt;localhost&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;0.0.0.0&lt;/code&gt; or IPv6 &lt;em&gt;(derived from the read service’s BindGuard)&lt;/em&gt;.&lt;/li&gt;
&lt;li&gt;Every request passes the read service’s guard: &lt;code dir=&quot;auto&quot;&gt;Host&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;127.0.0.1:&amp;#x3C;port&gt;&lt;/code&gt;, an &lt;code dir=&quot;auto&quot;&gt;Origin&lt;/code&gt; (when present) names the same, and &lt;code dir=&quot;auto&quot;&gt;Sec-Fetch-Site: cross-site&lt;/code&gt; is refused. A refusal is &lt;code dir=&quot;auto&quot;&gt;403&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;REQUEST_REFUSED&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The contract is &lt;code dir=&quot;auto&quot;&gt;contracts/mission-write&lt;/code&gt;, served under &lt;code dir=&quot;auto&quot;&gt;/api/v1&lt;/code&gt;, version &lt;code dir=&quot;auto&quot;&gt;1.0.0-SNAPSHOT&lt;/code&gt; until its first release.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-2-the-endpoint-file-and-the-token&quot;&gt;D-2: the endpoint file and the token&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Location&lt;/strong&gt; &lt;em&gt;(ruled)&lt;/em&gt;: &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;git-common-dir&gt;/spec-kitty-write-service/endpoint.json&lt;/code&gt;. Every worktree of a clone resolves the same git common dir, so all reach one service; a separate clone has its own.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fields&lt;/strong&gt; &lt;em&gt;(derived)&lt;/em&gt;: &lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt; (1), &lt;code dir=&quot;auto&quot;&gt;host&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;127.0.0.1&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;port&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;token&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;instance_id&lt;/code&gt; (a ULID minted at each start), &lt;code dir=&quot;auto&quot;&gt;pid&lt;/code&gt; (diagnostics only), &lt;code dir=&quot;auto&quot;&gt;protocol_versions&lt;/code&gt; (informative: the handshake’s list is authoritative), &lt;code dir=&quot;auto&quot;&gt;started_at&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Token&lt;/strong&gt; &lt;em&gt;(ruled: random bearer token; derived: its form)&lt;/em&gt;: 32 random bytes, URL-safe base64 without padding (at least 43 characters), new on every start. It is sent as &lt;code dir=&quot;auto&quot;&gt;Authorization: Bearer &amp;#x3C;token&gt;&lt;/code&gt; on every request and is never logged, echoed in a body or written anywhere else.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Permissions&lt;/strong&gt; &lt;em&gt;(derived)&lt;/em&gt;: on POSIX the directory is &lt;code dir=&quot;auto&quot;&gt;0700&lt;/code&gt; and the file &lt;code dir=&quot;auto&quot;&gt;0600&lt;/code&gt;, both owned by the user. The client refuses a file or directory with any group or other permission bit, a symbolic link, a FIFO or any other non-regular file, another owner, or a host other than &lt;code dir=&quot;auto&quot;&gt;127.0.0.1&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;WRITE_SERVICE_ENDPOINT_EXPOSED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;..._NOT_LOOPBACK&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;..._MALFORMED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;..._MISSING&lt;/code&gt;). It judges the file on &lt;code dir=&quot;auto&quot;&gt;lstat&lt;/code&gt; before it opens it, opens it once without following a link and without blocking, and no refusal carries the token or an exception that holds the file text.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Windows&lt;/strong&gt; &lt;em&gt;(derived)&lt;/em&gt;: the directory and the file carry an ACL that grants access to the owner only; the service sets it. The client, which has no mode bits to read, still refuses a link or a non-regular file and checks the shape and the loopback host.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One service per clone&lt;/strong&gt; &lt;em&gt;(derived from ADR 2026-10-22-1 D-2)&lt;/em&gt;: before it publishes the file, the service takes an exclusive OS lock on &lt;code dir=&quot;auto&quot;&gt;spec-kitty-write-service/service.lock&lt;/code&gt; and holds it for its whole life; a second service that cannot take the lock exits without publishing. It publishes by writing a temporary file in the same directory and renaming it into place, so a reader never sees a partial file. At exit it deletes &lt;code dir=&quot;auto&quot;&gt;endpoint.json&lt;/code&gt; only while the file still names its own &lt;code dir=&quot;auto&quot;&gt;instance_id&lt;/code&gt;. Starting, health-checking and recovering a stale service is the launcher’s (#6676).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-3-the-service-is-authoritative&quot;&gt;D-3: the service is authoritative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The service validates every unit against the lane state machine, its guards and dependency gating, verifies the request’s write location against its own resolution, and refuses with a code. A CLI pre-check is advisory only: it may shape a message, never skip or replace the service’s check.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;During the strangler the request carries rows, not a command&lt;/strong&gt; &lt;em&gt;(derived from ADR 2026-10-22-1 open questions 1 and 2)&lt;/em&gt;. The client sends what the EventBridge port holds (&lt;code dir=&quot;auto&quot;&gt;WorkPackageTransition&lt;/code&gt;): the rows the CLI built, in order, and the request context (actor, the checkout that holds the Mission directory, relative to the repository root checkout, the Mission directory inside it, and the CLI’s write contract target as &lt;code dir=&quot;auto&quot;&gt;writeSurface&lt;/code&gt;). The command form of ADR 2026-10-22-1 D-3, in which the service also stamps git-derived evidence (&lt;code dir=&quot;auto&quot;&gt;policy_metadata.lane_head&lt;/code&gt;) itself, arrives with migration step 4; until then the service does not change a row’s content. Nothing a host path can leak through travels.&lt;/li&gt;
&lt;li&gt;Every row of a unit names the unit’s &lt;code dir=&quot;auto&quot;&gt;wpId&lt;/code&gt;, and a row that names a Mission names the path’s &lt;code dir=&quot;auto&quot;&gt;missionId&lt;/code&gt;; otherwise the request is &lt;code dir=&quot;auto&quot;&gt;REQUEST_MALFORMED&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;What the port does not hold yet&lt;/strong&gt; &lt;em&gt;(derived)&lt;/em&gt;: the destination branch (&lt;code dir=&quot;auto&quot;&gt;EventLogWriteContract&lt;/code&gt; has none, so &lt;code dir=&quot;auto&quot;&gt;destinationRef&lt;/code&gt; is null until placement moves into the service), the owned-checkout fact (the service resolves ownership itself and refuses with &lt;code dir=&quot;auto&quot;&gt;OWNED_MISSION_PATH_REFUSED&lt;/code&gt;), and the &lt;code dir=&quot;auto&quot;&gt;missionId&lt;/code&gt; of the path (the #6195 adapter reads it from the Mission’s &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; in the write location).&lt;/li&gt;
&lt;li&gt;Parity of validation will be proven by the #6194 conformance corpus.&lt;/li&gt;
&lt;li&gt;The port’s Mission-state-advance half (the run events of &lt;code dir=&quot;auto&quot;&gt;RuntimeEventEmitter&lt;/code&gt;) has no operation in protocol major 1; those events stay outside #6195.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-4-handshake-and-version-negotiation&quot;&gt;D-4: handshake and version negotiation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;GET /handshake&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;GET /health&lt;/code&gt; need the bearer token but no protocol header. The handshake returns the supported protocol majors, the service version, the &lt;code dir=&quot;auto&quot;&gt;instanceId&lt;/code&gt; and the &lt;code dir=&quot;auto&quot;&gt;repositoryId&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;repositoryId&lt;/code&gt; &lt;em&gt;(derived)&lt;/em&gt; is the lowercase hex SHA-256 of the UTF-8 bytes of the git common dir’s real path in forward-slash form (Python &lt;code dir=&quot;auto&quot;&gt;Path.resolve().as_posix()&lt;/code&gt;), with the case the file system reports. Java computes the same string from &lt;code dir=&quot;auto&quot;&gt;toRealPath()&lt;/code&gt; with separators replaced; a cross-language fixture lands with the Java client of #6192.&lt;/li&gt;
&lt;li&gt;The client requires &lt;code dir=&quot;auto&quot;&gt;instanceId&lt;/code&gt; to equal the endpoint file’s &lt;code dir=&quot;auto&quot;&gt;instance_id&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;repositoryId&lt;/code&gt; its own digest, or it refuses. It then sends the highest major both sides speak, on every other request, in &lt;code dir=&quot;auto&quot;&gt;Spec-Kitty-Write-Protocol&lt;/code&gt;. A missing header, a value that is not an integer, or an unsupported major is &lt;code dir=&quot;auto&quot;&gt;400 PROTOCOL_VERSION_UNSUPPORTED&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;A protocol major changes only with a breaking change of the contract; additive changes keep the major &lt;em&gt;(derived from the contracts versioning rule)&lt;/em&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-5-durability&quot;&gt;D-5: durability&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;A unit (one transition and its annotations) is appended in &lt;strong&gt;one &lt;code dir=&quot;auto&quot;&gt;O_APPEND&lt;/code&gt; write of full JSON lines&lt;/strong&gt; and synced with &lt;code dir=&quot;auto&quot;&gt;fsync&lt;/code&gt; before the &lt;code dir=&quot;auto&quot;&gt;201&lt;/code&gt;. A batch of units is &lt;strong&gt;one write and one &lt;code dir=&quot;auto&quot;&gt;fsync&lt;/code&gt;&lt;/strong&gt;, all or nothing. A refusal writes nothing.&lt;/li&gt;
&lt;li&gt;This rules ADR 2026-10-22-1 D-7’s open point: the single &lt;code dir=&quot;auto&quot;&gt;O_APPEND&lt;/code&gt; write is authoritative, not the CLI’s temporary-file-and-replace.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Encoding&lt;/strong&gt; &lt;em&gt;(derived from ADR 2026-10-22-1 D-7)&lt;/em&gt;: the service owns the row encoding and writes the bytes the CLI’s one encoder writes, &lt;code dir=&quot;auto&quot;&gt;store.serialize_event_line&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;sanitize_event_for_log&lt;/code&gt; first (it strips host and developer fields such as &lt;code dir=&quot;auto&quot;&gt;hostname&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;developer_email&lt;/code&gt;), then &lt;code dir=&quot;auto&quot;&gt;json.dumps(..., sort_keys=True)&lt;/code&gt;. It never writes the bytes as received, and it judges a retry by comparing sanitized rows as JSON values. The client sends rows unsanitized.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Windows:&lt;/strong&gt; there is no &lt;code dir=&quot;auto&quot;&gt;O_APPEND&lt;/code&gt; atomicity guarantee between processes; the service holds the repository’s write lock around the write, and the lock’s semantics on Windows are settled by the lock-interop spike (#6193). This record does not decide them.&lt;/li&gt;
&lt;li&gt;Where the topology commits status, the commit joins the unit at migration step 4 of ADR 2026-10-22-1; until then the acknowledgement’s &lt;code dir=&quot;auto&quot;&gt;statusCommit&lt;/code&gt; is null.&lt;/li&gt;
&lt;li&gt;A fully replayed batch writes nothing and acknowledges &lt;code dir=&quot;auto&quot;&gt;fsyncs: 0&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;fsynced: true&lt;/code&gt; means the rows are durable, synced now or when they were first written.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-6-refusals&quot;&gt;D-6: refusals&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Every refusal is the shared &lt;code dir=&quot;auto&quot;&gt;Problem&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;application/problem+json&lt;/code&gt;) with a &lt;code dir=&quot;auto&quot;&gt;code&lt;/code&gt; and the &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; that code fixes. The service checks a request in this order and answers the first refusal: the Host and Origin guard (403), the bearer token (401), the protocol header (400), the size cap (413), the body’s shape (400), then the domain (404, 409, 422).&lt;/li&gt;
&lt;li&gt;A code that names an existing CLI refusal is &lt;strong&gt;the CLI’s string, verbatim&lt;/strong&gt; (20 codes, from &lt;code dir=&quot;auto&quot;&gt;orchestrator_api/wp_lifecycle.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;coordination/*&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status/locking.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status/store.py&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;cli/selector_resolution.py&lt;/code&gt;). A wrapper the CLI raises around another code (&lt;code dir=&quot;auto&quot;&gt;BOOKKEEPING_POLICY_REFUSED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;BOOKKEEPING_LOCK_TIMEOUT&lt;/code&gt;) is never returned; the wrapped code is.&lt;/li&gt;
&lt;li&gt;The contract mints 9 &lt;strong&gt;protocol-only&lt;/strong&gt; codes with no CLI counterpart: &lt;code dir=&quot;auto&quot;&gt;REQUEST_MALFORMED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;PROTOCOL_VERSION_UNSUPPORTED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;WRITE_TOKEN_INVALID&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;REQUEST_REFUSED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;WRITE_LOCATION_UNVERIFIED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;EVENT_ID_CONFLICT&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;REQUEST_TOO_LARGE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;SERVICE_BUSY&lt;/code&gt; (retry the same service after &lt;code dir=&quot;auto&quot;&gt;Retry-After&lt;/code&gt;) and &lt;code dir=&quot;auto&quot;&gt;SERVICE_DRAINING&lt;/code&gt; (re-read the endpoint file).&lt;/li&gt;
&lt;li&gt;A guard refusal also carries &lt;code dir=&quot;auto&quot;&gt;type&lt;/code&gt;, a URN &lt;code dir=&quot;auto&quot;&gt;urn:spec-kitty:write-refusal:&amp;#x3C;reason&gt;&lt;/code&gt; from a closed vocabulary of 15 reasons (provisional), each bound to one code. The CLI raises these reasons as text today; adopting the same vocabulary in the CLI is a follow-up.&lt;/li&gt;
&lt;li&gt;A refused batch names the unit that failed in &lt;code dir=&quot;auto&quot;&gt;instance&lt;/code&gt;, as the JSON pointer &lt;code dir=&quot;auto&quot;&gt;#/units/&amp;#x3C;index&gt;&lt;/code&gt; of the request.&lt;/li&gt;
&lt;li&gt;The codes and reasons are written as constants rather than an &lt;code dir=&quot;auto&quot;&gt;enum&lt;/code&gt;, because the contract lint admits only snake_case and PascalCase enum values. Their governance is the parity inventory &lt;code dir=&quot;auto&quot;&gt;tests/contract/fixtures/mission_write_refusal_parity.yaml&lt;/code&gt;: a test reads each cited CLI file for the literal and holds the contract, the client vocabulary and the inventory equal.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-7-the-event-envelope-is-referenced-not-redefined&quot;&gt;D-7: the event envelope is referenced, not redefined&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;A request row is the spec-kitty-events envelope (spec-kitty/spec-kitty-events#92). The contract requires only &lt;code dir=&quot;auto&quot;&gt;event_id&lt;/code&gt; and leaves the rest of the row open; the envelope’s owner defines it.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-8-the-client-side&quot;&gt;D-8: the client side&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli.status.write_service_protocol&lt;/code&gt; holds the typed shapes of the contract (requests with &lt;code dir=&quot;auto&quot;&gt;to_wire()&lt;/code&gt;, responses with &lt;code dir=&quot;auto&quot;&gt;from_wire()&lt;/code&gt;), the refusal vocabulary, version negotiation, the repository id and the endpoint-file reader. It has no transport.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;runtime.next._internal_runtime.events.bind_event_bridge&lt;/code&gt; binds both halves of the EventBridge port at the composition root, all or nothing. Open-core binds none.&lt;/li&gt;
&lt;li&gt;Neither has a &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; caller until the client adapter binds at the #6195 cut-over, so both are priced dead-code debt (ADR 2026-09-30-1) with that exit.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;d-9-the-contract-layout-admits-a-security-scheme&quot;&gt;D-9: the contract layout admits a security scheme&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;A contract module’s root &lt;code dir=&quot;auto&quot;&gt;openapi.yaml&lt;/code&gt; may declare &lt;code dir=&quot;auto&quot;&gt;components.securitySchemes&lt;/code&gt; and nothing else under &lt;code dir=&quot;auto&quot;&gt;components&lt;/code&gt;; anything more is still a bundled document (&lt;code dir=&quot;auto&quot;&gt;TRACKED_BUNDLE&lt;/code&gt;). This lets the bearer scheme be native, so a generated client sends it.&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;One checked boundary for the client, the service and the launcher.&lt;/li&gt;
&lt;li&gt;A stale file, a recycled port or another clone’s service is refused before any write.&lt;/li&gt;
&lt;li&gt;Moving validation into the service changes no code a user sees.&lt;/li&gt;
&lt;li&gt;The durability point of every write is explicit.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;An HTTP server sits on the write path; a local process of the same user that can read the endpoint file can write.&lt;/li&gt;
&lt;li&gt;20 codes now have two homes (the CLI and the contract) until the CLI writers are deleted at the cut-over; the parity test is what keeps them equal.&lt;/li&gt;
&lt;li&gt;Priced dead-code debt until #6195.&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 service and its contract are unchanged.&lt;/li&gt;
&lt;li&gt;The CLI writes events exactly as before; nothing binds the port in 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;The contract checks pass for &lt;code dir=&quot;auto&quot;&gt;contracts/mission-write&lt;/code&gt; (layout, structure, citations, examples, leak scan, lint, bundle, generator validation, client generation).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_mission_write_contract.py&lt;/code&gt;: six operations, the bearer scheme on all, the protocol header on all but the handshake and health, closed success bodies, a &lt;code dir=&quot;auto&quot;&gt;WriteRefusal&lt;/code&gt; for every refusal, refusal parity with the CLI sources, and the client shapes validating against the contract.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/status/test_write_service_protocol.py&lt;/code&gt;: the endpoint reader refuses an exposed, malformed, symlinked or non-loopback file and never names the token.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;open-questions-each-with-a-provisional-default&quot;&gt;Open questions (each with a provisional default)&lt;/h2&gt;
&lt;p&gt;Every provisional element is settled before the contract’s first release (&lt;code dir=&quot;auto&quot;&gt;1.0.0&lt;/code&gt;): after it, a change to a closed response is a major version.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Idempotent retry.&lt;/strong&gt; Default: a retry whose event ids are all persisted with identical rows (compared as JSON values) answers &lt;code dir=&quot;auto&quot;&gt;201&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;replayed: true&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;appendedLines: 0&lt;/code&gt;; an event id persisted with different content, or a unit only some of whose event ids are persisted, is &lt;code dir=&quot;auto&quot;&gt;409 EVENT_ID_CONFLICT&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A torn tail.&lt;/strong&gt; Default: a crash between the write and the &lt;code dir=&quot;auto&quot;&gt;fsync&lt;/code&gt; can leave an unterminated last line. The service checks the tail of a log before it serves its first write and refuses to append after an unterminated line until it is repaired; the repair rule belongs to the lock-interop spike (#6193).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Concurrency and backpressure.&lt;/strong&gt; Default: the service serializes writes per repository with a bounded queue; beyond it, it answers &lt;code dir=&quot;auto&quot;&gt;503 SERVICE_BUSY&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;Retry-After&lt;/code&gt;. It never queues without bound.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Token rotation.&lt;/strong&gt; Default: the token changes only at a service start; there is no in-life rotation.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;MCP mode.&lt;/strong&gt; Default: none in protocol major 1; an MCP surface would be a separate deployable over the same use cases.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Shutdown and idle exit.&lt;/strong&gt; Default: &lt;code dir=&quot;auto&quot;&gt;POST /shutdown&lt;/code&gt; drains (health reads &lt;code dir=&quot;auto&quot;&gt;draining&lt;/code&gt;, writes answer &lt;code dir=&quot;auto&quot;&gt;SERVICE_DRAINING&lt;/code&gt;) and exits; the service also exits after an idle period (ADR 2026-10-22-1 open question 4). Whether the launcher uses the operation, a signal or only the idle exit is open.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Request size cap.&lt;/strong&gt; Default: 1 MiB per request (&lt;code dir=&quot;auto&quot;&gt;413 REQUEST_TOO_LARGE&lt;/code&gt;). A batch of more than 64 units is a shape error (&lt;code dir=&quot;auto&quot;&gt;400 REQUEST_MALFORMED&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Write-location verification.&lt;/strong&gt; Default: until resolution moves into the service (ADR 2026-10-22-1 open question 2), a mismatch between the request’s location and the service’s resolution is &lt;code dir=&quot;auto&quot;&gt;422 WRITE_LOCATION_UNVERIFIED&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;When the status commit joins the unit&lt;/strong&gt; and whether the acknowledgement names it (&lt;code dir=&quot;auto&quot;&gt;statusCommit&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;An unknown refusal code.&lt;/strong&gt; Default: the client treats a code it does not know as a protocol error and refuses the write; a new code is a contract change.&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-local-socket-a-named-pipe-on-windows&quot;&gt;A local socket, a named pipe on Windows&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Pros:&lt;/strong&gt; file-system permissions guard the socket; no port to discover.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cons:&lt;/strong&gt; two transports to build and test (a Unix socket and a Windows named pipe); the read service’s HTTP stack, guard and contract tooling do not apply; OpenAPI does not describe it.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;loopback-http-with-a-bearer-token-chosen&quot;&gt;Loopback HTTP with a bearer token (chosen)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Pros:&lt;/strong&gt; one transport on every platform; the read service’s stack, guard and tooling apply; the contract is checked by the tools the repository already runs.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cons:&lt;/strong&gt; a port any local process can connect to, so the token and the guard carry the trust; a file that names the port can go stale.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;a-process-per-write&quot;&gt;A process per write&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Pros:&lt;/strong&gt; nothing resident.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cons:&lt;/strong&gt; a start on every transition (rejected by ADR 2026-10-22-1 D-2).&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;The read service: &lt;code dir=&quot;auto&quot;&gt;services/mission-status-api/README.md&lt;/code&gt; (bind and guard rules).&lt;/li&gt;
&lt;li&gt;Contract conventions: &lt;code dir=&quot;auto&quot;&gt;contracts/README.md&lt;/code&gt; (the security-scheme rule is added there).&lt;/li&gt;
&lt;li&gt;The current-state map: &lt;a href=&quot;/architecture/event-ledger-writers-and-readers/&quot;&gt;event ledger writers and readers&lt;/a&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;The launcher (#6676).&lt;/strong&gt; The launcher stays in core and resolves the binary from the pinned release (2026-10-29-1 D-3 to D-5). The native-image build half of #6676 moves to &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;. The protocol, the endpoint file and the trust model are unchanged; the pin records the protocol versions the build serves, and the launcher refuses a build whose versions do not intersect &lt;code dir=&quot;auto&quot;&gt;SUPPORTED_PROTOCOL_VERSIONS&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Nothing else in this record changes.&lt;/p&gt;</content>
</entry>
