ADR: the Java write service is the canonical event writer, one resident service per repository
The Java write service is the canonical event writer, one resident service per repository
Status: Accepted (2026-10-22). Operator rulings of 2026-10-22, recorded on #6117, #6185 and #6608. Amended by ADR 2026-10-27-1 (open question 3, D-3, D-7); see Amendment 2026-10-27. Amended by ADR 2026-10-29-1 (the events services live in spec-kitty-events); see Amendment 2026-10-29.
What was ruled and what is derived.
- Ruled by the operator: the event writer is a Java service that reuses the read API’s domain models; one service per repository; the CLI decides when and what, the service how and where; a JVM jar fallback for a missing native binary; #6185 folds into #6117’s modules.
- Derived: every clause marked (derived) follows from those rulings together with the charter’s single-canonical-authority principle and ADR 2026-10-14-1. Each one comes from the research recommendation on #6608.
- Open: the open questions at the end carry defaults that hold until the operator rules otherwise.
Date: 2026-10-22
Deciders: Stijn Dejongh (operator).
Technical Story:
- Epic #6608 (event-native core) and its child epic #6117 (Mission Write API).
- #6185 (the native producer, folded into #6117’s modules).
- The research recommendation on #6608 (2026-10-22).
- The current-state map event ledger writers and readers.
- It amends ADR 2026-10-14-1 (D-1, D-2, D-5 and the Confirmation) and ADR 2026-10-03-1 (its “event system” rationale).
- It keeps ADR 2026-10-13-2 D-2 and D-3 (the committed ledger is the publication seam; retention) and ADR 2026-10-01-2 (the read API, read only) unchanged.
- ADR 2026-02-09-3 is amended the same day by a separate ruling: the ordering is wall clock for 4.0.0, the merge rules are kept, and Lamport-primary ordering is a post-GA direction (#6609). This record does not change the ordering.
- It supersedes three parts of #6117:
- decision 4’s recommendation of a per-command native binary;
- the per-command description of
command-cliin decision 12. The module names stand, andcommand-clibecomes the service deployable; - intended effect 6, “a write needs no running service”.
Reader: a maintainer building the write side of the event ledger, or changing how the CLI records a work package transition or a Mission state change.
Context and Problem Statement
ADR 2026-10-14-1 decided that core has one canonical event writer, the EventBridge, behind a domain port, and placed it as an adapter inside specify_cli. Nothing implements it yet:
- About fifteen append implementations in more than twelve modules write at least six row shapes.
- Only glossary writes through
spec_kitty_events.persistence.append_event(see the current-state map).
Two Java efforts exist on the tracker beside it:
- #6117 (Mission Write API). It designs “one Java write core … the command side of a CQRS split; the read API is the query side”. Decision 12 (ruled 2026-10-13) settles its modules:
domain-modelandevent-logshared, withquery-serviceandcommand-clias the deployables. It ships as a native binary run once per command. - #6185. A standalone native producer (
services/event-producer), which warns and continues when the binary is missing.
The operator ruled on 2026-10-22, verbatim:
“having a write service as a Java-based service is the way to go, as it enables many alternate deployment configurations, and makes it easier to reuse the same logical DSO models as the read api uses. If we ever decide to move from a local, file-based ledger to a database / hosted-first solution, the java-service architecture makes more sense.”
“Why does it need to be a per-worktree service daemon? Would that not defeat any and all benefits of a backend service? If we can run a GraalVM backend per repository, which writes to the required ledger location / worktrees / filesystem paths, that would make the CLI feel smoorther [sic] and snappier, as well as make ownership even clearer -> CLI controls when to send what. Service controls HOW and WHERE to store it, based on the request context.”
Further rulings the same day:
- A missing native binary falls back to a JVM jar.
- #6185 folds into #6117’s modules.
- #6117 becomes a child of #6608.
What the merged read service offers a write side (the #6608 recommendation):
- Reusable: an architecture and a current-state model:
Lane,WpState,StatusSnapshot,StatusReducer, the hexagonal layout, and a directional ArchUnit rule (query never depends on command). - Missing: a write domain.
StatusEventandActorare lossy read projections.- There is no encoder that reproduces Python’s
json.dumps(sort_keys=True)bytes. - The lane state machine and its guards (
src/specify_cli/status/wp_state.py) are not ported.
- Blockers before any Java writer shares a file with the CLI:
- Core locks with
fcntl.flock(src/kernel/locks.py:222), which on Linux does not exclude Java’sfcntlrecord locks. - No
spec-kitty-eventsfixture covers a lane-transition row.
- Core locks with
Decision Drivers
- Single canonical authority (charter): one writer, one implementation of the row format, the lock and the fold.
- No lost history: the status log is the sole authority for lane state, and consolidation reads it, so a write either lands or fails loudly.
- Reuse: the write side shares the read side’s domain models instead of keeping a second set.
- Deployment freedom: the same use cases can be deployed in more than one configuration, with storage behind a port.
- A snappy CLI: no process start or JVM warm-up on every transition.
- Clear ownership: the CLI decides when and what; the service decides how and where.
Considered Options
- Python in-process EventBridge (ADR 2026-10-14-1 as written).
- A native binary run once per command (#6117 as originally designed).
- A resident daemon per worktree (the charter service precedent, ADR 2026-10-03-1).
- A resident Java write service per repository, behind the CLI’s EventBridge port (chosen).
Decision Outcome
Chosen option: “A resident Java write service per repository, behind the CLI’s EventBridge port”. It is the only option that:
- gives one writer and one implementation;
- reuses the read side’s models;
- keeps storage swappable;
- avoids a start per transition.
All lane worktrees of a repository then share one writer.
D-1: the canonical event writer is the Java write service
- The command side of the Mission Write API (#6117) is the one module that persists events. Every event log ADR 2026-10-14-1’s Confirmation names is written only by its
event-logmodule:status.events.jsonl,canonical-events.jsonl,run.events.jsonl,decisions.events.jsonl,mission-events.jsonl,kitty-ops/*.jsonland the glossary logs.
- The modules are #6117 decision 12’s four:
domain-model,event-log,query-serviceandcommand-cli.command-cliis now the write-service deployable (D-2). There is no second Java write build: #6185’s producer folds into these modules, landing in #6193. - Python keeps no in-process append once a file has moved.
D-2: one resident service per repository
- Unit. One write service per repository. Reading “per repository” as “keyed on the git common dir” is (derived). Under that reading:
- every lane worktree, the coordination worktree and the repository root checkout of that repository talk to the same service;
- the service is keyed where core already keeps its write locks (
<git-common-dir>/spec-kitty-locks/).
- Launch. The CLI starts it when it is down and reuses it while it runs: the launch-when-down choice of ADR 2026-10-03-1 (derived).
- Reach. It is local only and serves write operations only. The transport, token and identity check are open question 3.
- Not per worktree. A per-worktree daemon would split one repository’s writes across processes and bring back cross-process locking. A per-command binary pays a start on every transition.
D-3: the CLI decides when and what; the service decides how and where
- The CLI owns the domain decision. The run loop and the transition shells call the Python EventBridge port. The port of ADR 2026-10-14-1 D-2 is kept (grown from
RuntimeEventEmitter); only its adapter changes (amended). The port’s adapter inspecify_clisends a command with its request context: Mission identity, work package, intended transition, actor, evidence, and the caller’s checkout. - The service owns how and where:
- It validates the command against the lane state machine and guards (open question 1).
- It resolves the write location: which partition, worktree and branch.
- It stamps git-derived evidence (
policy_metadata.lane_head), appends and commits. - It returns the persisted event or a named refusal.
- Write location during the strangler. Resolving the location is today the Python placement seam (
mission_runtimePlacementSeam.write_dir). Until that rule set is ported, the CLI sends the resolved write location in the request context and the service verifies it. Then the resolution moves into the service (open question 2).
D-4: git and synchronous consumers run inside the service’s unit of work (derived)
- One unit of work. The append, the status commit (where the topology commits status) and the cut-on-failure happen in one unit of work inside the service. The
lane_headprobe moves into the service’sGitPort. This replacesBookkeepingTransaction’s in-processsafe_commitand_cut_event_log(coordination/transaction.py). ADR 2026-10-14-1 D-5’s synchronous consumers move here. - Asynchronous consumers stay where they are: the produce seam
status/adapters.py, derived projections and the read API by cursor. They run after the service returns, or read the committed ledger by cursor. - Exclusion. The service serializes writes to one repository in process. While Python writers still exist, it also takes the same OS lock files with
flock(2)semantics (through FFM), not withFileChannel.lock. - Handover. Ownership of a log file is handed over whole, one file at a time. No file has a Python writer and a Java writer in the same release. The #6193 lock-interop spike is the go/no-go for the first handover.
D-5: native first, JVM jar as fallback, and no Python writer
- Fallback order (ruled: the JVM jar fallback).
- The service runs from a native image where one ships for the platform. No native image exists yet: #6185 self-reports native feasibility on Linux x86_64, macOS arm64 and Windows x86_64, and the support matrix is set at release.
- Otherwise it runs the same build as a JVM jar on a local JDK.
- (derived) With neither available, every write refuses with a named error code and a remedy, and nothing is written. Read-only commands keep working.
- (derived) No Python fallback writer. A fallback writer would be a second implementation of the format, lock and fold (charter: single canonical authority; ADR 2026-10-14-1 D-1). #6185’s warn-and-continue
binary-missingbehaviour is rejected, because it silently drops rows from the log that is the sole authority for lane state.
D-6: storage is a port; only the file adapter ships (derived from the ruled alternate deployments)
EventLogPortis a storage abstraction from the first Java write, and the only adapter that ships is the local file ledger.- A database or hosted adapter is not a drop-in replacement under the current decisions:
- the git-committed ledger is the publication seam (ADR 2026-10-13-2 D-2);
- the read API pulls the committed ledger (ADR 2026-10-01-2 D-6);
- merge semantics are file based (ADR 2026-02-09-3);
- the consolidation gates rely on git ancestry and on
lane_headstamps.
- Each of those needs its own ADR before such an adapter is built.
- This decision adds no hosted surface to open-core (#6164 stands).
D-7: byte-exact contract for every row the service writes (derived)
- Encoder. The service encodes rows to the bytes the CLI writes today. That means
store.serialize_event_line’sjson.dumps(sanitize_event_for_log(row), sort_keys=True)for status rows, and thepersistence.append_eventbytes for contract rows. - Fixtures.
spec-kitty-eventsgains astatus_appendfixture family, generated from core’s writer, besideledger_append. Both gate the Java writer byte for byte, through the Java binding of events#92. - Append semantics. Which semantics are authoritative is settled in the same step: core’s temp-file-and-replace, or the contract’s single
O_APPENDwrite.
D-8: the read service stays read-only and separate (derived)
query-service(services/mission-status-api/) keeps its guarantees: loopback-only, never writes, takes no lock, starts no process.- The write service is its own deployable, sharing
domain-model. - The read API stays conformance-gated against the Python reducer. #6268 (porting the #4941 approved-departure lift to the Java
StatusReducer) lands before the shared domain model is used to validate writes.
Consequences
Positive
- One writer and one implementation for every event log, across the CLI and any future deployment.
- The read and write sides share one domain model.
- A transition costs a local request to a warm service, not a process start.
- Ownership is explicit: the domain decides, the service persists.
- Storage can change behind one port without touching the CLI.
Negative
- A JVM toolchain, a native-image platform matrix, a JVM fallback and a port of the git policy sit on the event-writing critical path.
- The CLI’s write path depends on a local service’s lifecycle: launch, identity, token and crash recovery. Its launcher needs the same security review ADR 2026-10-03-1 requires for the charter service.
- “One canonical writer” now spans two languages, so it needs two gates.
- The lane state machine and guards must move, or be kept in parity, across languages.
Neutral
- ADR 2026-10-14-1’s D-3, D-3a and D-4 are unchanged. The writer still writes only
spec-kitty-eventscontract events, every event carries both version markers, and the internal lifecycle events are retired. - The read API is unchanged.
Confirmation
- Python side: the multi-file writes gate (#6603) shows no module appends to any event log once that file has moved, with an empty allowlist at the end of the migration.
- Java side: an ArchUnit rule shows only the
event-logmodule opens a ledger for writing. - Bytes: the
ledger_appendandstatus_appendfixtures pass byte for byte against the Java writer. - One service per repository: two worktrees of one repository reach the same service; a second repository gets its own.
- Fail closed: with no native image and no JDK, a write refuses with the named code and the log is byte-identical.
- Consolidation:
tests/consolidation/passes unchanged over logs that mix rows from both writers, at each cut-over step.
Migration order (each step gated on the previous) (derived; a default the operator may resequence)
- Python EventBridge port behind the two existing doors (
status/emit.py_persist_prepared,coordination/transaction.pyBookkeepingTransaction.append_events), plus the multi-file writes gate. No behaviour change (#6603). - Extract
domain-modelandevent-log(#6192). - Java binding plus the
status_appendfixture family (events#92). - Lock-interop spike (go/no-go), then the service writes one file owned whole. The glossary logs are the candidate, since they already use the contract writer (#6193).
- The service takes
status.events.jsonl: every row family in one cut, commit and cut inside the service, and the Python appenders deleted in the same release. - The remaining logs: run journal, decisions, Op records and lifecycle (ADR 2026-10-14-1 D-4). Then the
acceptwrites, then the consolidation bookkeeping writes.
Open questions (each with a default)
- Who validates a transition?
- Default: the service is authoritative and runs the ported lane state machine and guards, with a parity corpus against
status/wp_state.py. - The CLI may pre-check only for messages.
- Until the port lands, the service accepts a transition
prepare_transitionhas validated and re-checks onlyfrom_lanecontinuity against its reducer.
- Default: the service is authoritative and runs the ported lane state machine and guards, with a parity corpus against
- When does write-location resolution move into the service?
- Default: at step 4.
- Before then, the request carries the resolved write location and the service verifies it.
- Transport and trust model.
- Default: a local socket (a named pipe on Windows) rather than TCP.
- A per-repository token in the git common dir, readable only by the user.
- An identity check before each session, and write operations only.
- A security note precedes step 3.
- Idle shutdown.
- Default: the service exits after a period with no requests, and the CLI relaunches it on demand.
- A crashed service is detected by the identity check and relaunched. A write is acknowledged only after it is durable: after its commit where the topology commits status, and after the fsynced append where it does not (the flat shell,
status/emit.py).
- Several clones of one repository.
- Default: one service per git common dir, so separate clones get separate services.
- Worktrees of one clone share one.
Amendment 2026-10-27 (Accepted): loopback HTTP transport, rows during the strangler, one synced O_APPEND write
ADR 2026-10-27-1 settles points this record left open, by operator ruling of 2026-10-25 (#6675) and as derived there:
- Open question 3 (transport and trust model). The default of a local socket is replaced: the service listens on
127.0.0.1only, on a random port, and the port and a random bearer token are written to a file in the git common dir, owner-only. The identity check before writes is the handshake of ADR 2026-10-27-1 D-4. - D-3 (the CLI sends a command). During the strangler the request carries the rows the CLI built, with their context; the command form, in which the service also stamps
policy_metadata.lane_headitself, arrives with migration step 4. - D-7 (append semantics). The single
O_APPENDwrite of full JSON lines, synced before the acknowledgement, is authoritative; a multi-event operation is one write and onefsync. Windows semantics follow the lock-interop spike (#6193).
Nothing else in this record changes.
Pros and Cons of the Options
Python in-process EventBridge
- Pros: the cheapest for 4.0.0; no new runtime.
- Cons:
- The write domain stays in Python while the read domain is Java, so the models are kept twice.
- Storage cannot change without touching the CLI.
- #6117’s and #6185’s Java work becomes a second writer to reconcile later.
A native binary run once per command
- Pros: nothing resident; works offline; no service lifecycle.
- Cons:
- A process start on every transition.
- No home for alternate deployments.
- Every invocation re-reads and re-folds state.
A resident daemon per worktree
- Pros: follows the charter-service precedent.
- Cons:
- One repository’s writes are split across processes, so cross-process locking comes back.
- Lane worktrees of one Mission would talk to different writers.
- It defeats the point of a backend service.
A resident Java write service per repository (chosen)
- Pros: one writer per repository; warm state; clear ownership; storage behind a port; shares the read models.
- Cons: a service lifecycle and a JVM toolchain on the write path; a security-reviewed launcher; a cross-language parity burden during the migration.
More Information
- The current-state map and gap table: event ledger writers and readers.
- Contributor rules: Events in core.
spec-kitty-events:docs/api/ledger-write-contract.md,src/spec_kitty_events/conformance/fixtures/ledger_append/README.md.- The read service:
services/mission-status-api/README.md.
Amendment 2026-10-29 (Accepted): the events services live in spec-kitty-events
ADR 2026-10-29-1 records the operator and CEO ruling of 2026-10-29 that the events domain’s Java services and contracts move to spec-kitty-events, and that core consumes a released, pinned build.
- D-1 (the
event-logmodule writes all ledgers) and D-5 (native first, JVM jar fallback). Theevent-logmodule and thecommand-clideployable live inspec-kitty-events. Core takes both the native binary and the jar from a pinnedservice-v*release, executes either only when its sha256 matches the pin, and fetches it on first use. The no-Python-writer rule and the named refusal are unchanged; the refusal codes are listed in 2026-10-29-1 D-5.
Nothing else in this record changes.
Amendment 2026-11-06: D-6 records and step 4a
Status of this amendment: Proposed (2026-11-06), with the five records it names; the rest of this record stays Accepted. Operator ruling 4 of epic #7276 (DM 01M6QY371KRY5XXQMDQ4WZR1YE, Mission lane-worktree-model-hardening-01M6QY1M): write the ADR set for the Java write service writing coordination status without a coordination worktree; ADRs only, the implementation follows migration step 4. Slice S9, #7284.
D-6 applies. Committing a coordination Mission’s ledger into git objects, with no coordination worktree, is a new storage adapter of EventLogPort, not “the local file ledger”. D-6’s “each of those needs its own ADR before such an adapter is built” therefore binds, and these records discharge it:
- C-1 ADR 2026-11-06-4: a coordination branch is written by commit, not through a coordination worktree.
- C-2 ADR 2026-11-06-5: consolidation gates hold over a coordination branch with no worktree.
- C-3 ADR 2026-11-06-6: the committed ledger of a coordination Mission is the blob on its coordination branch.
- events ADR-0007
docs/adr/0007-write-service-commits-coordination-status-by-ref.md: the write service commits coordination status onto the branch ref by compare-and-swap. - events ADR-0008
docs/adr/0008-read-service-reads-coordination-ledger-from-git-objects.md: the read service reads a coordination ledger from git objects.
The two events records live in spec-kitty/spec-kitty-events, branch main (merged from issue-7284-coordination-ref-write-adrs), pull request spec-kitty/spec-kitty-events#215 (placement rule of ADR 2026-10-29-1 D-1: Java service internals and the mission-write contract are decided there).
Mapping. Each D-6 bullet, quoted, maps to exactly one record:
| D-6 bullet | Record | Confirmation tests named by that record |
|---|---|---|
“EventLogPort is a storage abstraction from the first Java write, and the only adapter that ships is the local file ledger.” | events ADR-0007 | ADR-0007 Confirmation (command-cli, spec-kitty-events): one commit per unit and per batch with the prior tip as parent and only the log path changed; the first write commits; index, HEAD and working tree unchanged and planted hooks never run; COORDINATION_REF_MOVED, SERVICE_BUSY, COORDINATION_BRANCH_DELETED, COORDINATION_REF_CHECKED_OUT, COORDINATION_LEDGER_UNREADABLE; replay and EVENT_ID_CONFLICT. Today: OperationsTest and contracts/tools/enum_pins.json. |
| “A database or hosted adapter is not a drop-in replacement under the current decisions:” | this amendment | Its four sub-bullets are the next four rows, each with its own record. |
| “the git-committed ledger is the publication seam (ADR 2026-10-13-2 D-2);” | C-3 | tests/status/test_events_tail_coordination_ref.py, tests/status/test_tail_cursor_source_ref.py, tests/status/test_read_door_missing_ref_parity.py (to be written by the step-4 Mission). |
| “the read API pulls the committed ledger (ADR 2026-10-01-2 D-6);” | events ADR-0008 | ADR-0008 Confirmation: oracle parity and corpus comparison on the no-worktree fixture; architecture rule 10; the native image answers with no git on PATH, starting no process and writing no file; one tip per read under a concurrent ref move; named answers for a missing ref and an unsupported ref backend. |
| “merge semantics are file based (ADR 2026-02-09-3);” | C-2 | tests/consolidation/test_late_window_reads_pinned_ref.py (to be written); S10’s tests/coordination/test_projection_teardown.py and tests/consolidation/test_late_teardown_projection.py on a ref-only coordination branch. |
“the consolidation gates rely on git ancestry and on lane_head stamps.” | C-2 | Unchanged and green: tests/consolidation/test_approved_bound.py, test_approved_bound_residuals.py, test_wp_attribution.py, test_wp_evidence.py, test_claim_integrity_refusal.py, tests/specify_cli/lanes/test_for_review_gate_parity.py; to be written: tests/consolidation/test_coordination_write_fence.py, test_rollback_without_coordination_checkout.py, test_resume_recovery_roles.py. |
| “Each of those needs its own ADR before such an adapter is built.” | this amendment | This table: every bullet above names one record, and each record names its tests. |
| “This decision adds no hosted surface to open-core (#6164 stands).” | this amendment | Unchanged: none of the five records adds a hosted surface; the services stay loopback and local. |
C-3 D-2 states the core side of the read API amendment (ADR 2026-10-01-2 D-3, D-6) and points to ADR-0008 for how the read service does it; it is not a second discharge of that bullet. C-1 discharges no D-6 bullet of its own: it is the placement decision every row above relies on, and the step below.
Step 4a. The migration order gains:
- 4a. Coordination writes by commit; the coordination worktree is retired (C-1). The write service serves
writeSurface: coordination_ref_commit(events ADR-0007); every coordination-partition kind has a rule (C-1 D-3); existing coordination worktrees are drained and removed under the destructive guard (C-1 D-9); the CLI’s five coordination-worktree codes retire (C-1 D-8).
Steps 4 and 4a ship in one release (C-1 D-10). coordination_ref_commit goes live only in the release that also ships C-1’s artefact rule (notes, trace, issue matrix, decisions, byproducts; #7266) and the drain and removal of existing coordination worktrees. Step 4 deletes the Python appenders and D-5 forbids a Python fallback writer, so a step 4 without step 4a would leave every existing coordination Mission refused with COORDINATION_REF_CHECKED_OUT on every transition.
Open question 2 (when write-location resolution moves into the service) keeps its default, step 4; for coordination Missions the location the service resolves is refs/heads/<coord>, and destinationRef becomes required for that surface (C-1 D-7, amending ADR 2026-10-27-1 D-3).
Nothing else in this record changes.