Events in core
Who is this for (1)
- Stakeholder Persona: Maintainer — Written for the Maintainer reader.
When you need this page. Your change appends to an event log, reads one, or bumps
spec-kitty-events. The map of every writer and reader, and the gaps against the ADRs, is in Event ledger writers and readers. This page is the short version: what to call, what not to do.
The target is one canonical event writer (ADR 2026-10-14-1): a resident Java write service per repository behind the Python EventBridge port (ADR 2026-10-22-1). It does not exist yet. Until it does, follow the rules below so you do not add a writer that the migration has to remove later.
Writing events
| You want to record | Call | Not |
|---|---|---|
| A work package lane transition | emit_status_transition_transactional (coordination/status_transition.py); it falls back to the flat shell emit_status_transition (status/emit.py) for a Mission without coordination topology | building a StatusEvent and appending it yourself |
| An inner-state annotation | emit_inner_state_changed (status/emit.py) | a raw row in status.events.jsonl |
| A glossary fact | glossary.events.append_event (src/glossary/events.py), which writes through spec_kitty_events.persistence.append_event | a hand-built dict |
| A new kind of fact | Ask first. The fact needs a model in spec-kitty-events before core writes it (ADR 2026-10-14-1 D-4). Write it through spec_kitty_events.persistence.append_event | a new *.jsonl file with a core-owned row shape |
Rules:
- Never
open(path, "a")an event log. A plain append has no lock and no torn-tail check.tests/architectural/test_status_events_writes_gate.pyrejects any write tostatus.events.jsonloutsidestatus/store.pyand its ledgered sites, andtests/architectural/test_event_log_writes_gate.pydoes the same for every other log (see Appending to an event log (interim)). - Never import from
specify_cli.status._unsafe. ItsALLOWED_CALLERSlist is shrink-only; adding a module failstest_status_unsafe_allowlist.py. - Never add a new
canonical-producer-exemptmarker or a new local envelope. Sixteen markers remain insrc/; the migration removes them. - Serialize status rows with
store.serialize_event_line, the one authority for the on-disk row shape. Do notjson.dumpsa status row yourself. - Keep
prepare_transitionpure. It does no writes, locks, git or fan-out (status/transition_pipeline.py); git-derived values such as thelane_headstamp come in through an injected probe. - A side effect that reacts to an event is a consumer, not a new line in a shell.
Today the shells still run commits inline; do not add more. The produce seam
status/adapters.pyis where a transport registers a handler. Open-core registers none, so everyfire_*is a no-op, and nothing hosted belongs in this repository. - Call the state files by their names. The migration ledger
(
.kittify/migration-ledger.jsonl,upgrade/ledger.py) and the activation ledger (.kittify/charter/activation.yaml) are state ledgers, not event logs. Never write bare “the ledger”. - The migration ledger’s append is locked, and one selection rule is structural.
MigrationLedger.append/append_manyhold.kittify/migrations/<ledger file name>.lock(akernel.locks.machine_file_locksidecar in the IGNORED per-clone surface, bounded at 30 s) across their read-modify-write, so twoupgrade/migrateruns on one checkout cannot lose a record; a lock that never frees raisesMigrationLedgerLockTimeoutErrorand appends nothing. Selection is ledger-diff plus theruns_firststructural reselection: a recorded migration whosestructural_detectfires is re-selected (a pulledmetadata.yamlor a merge can revive the old state), whiledetect()stays the pre-apply()idempotency guard. See ADR 2026-10-17-1, Amendments 2026-10-20 and 2026-10-30.
Appending to an event log (interim)
Until the Java write service owns a log (#6193), an append to any event log other than
status.events.jsonl and canonical-events.jsonl goes through one door,
kernel.event_log_append (#6606). Those two keep the Mission status lock and the
status.store primitives.
- Call
append_event_log_lines(path, lines). Pass complete serialized rows without a trailing newline; the door adds the framing. You keep serializing your own row bytes: the door checks framing, never content, because the write service is the validation authority (operator ruling of 2026-10-25 on #6117). - The lock contract. The lock is anchored on the log, or on the family directory for
one-file-per-record logs (
kitty-ops/<op>.jsonl). It lives at<git-common-dir>/spec-kitty-locks/event-logs/<sha256[:32]>.lock, so every worktree of a repository shares it; outside a git repository it is<anchor>.event-log.lock. The wait is bounded (EVENT_LOG_LOCK_TIMEOUT_S, 10 s). Under the lock, a log whose last byte is not LF is refused, then the whole unit is written in oneO_APPENDwrite and fsynced. A new log is created with mode0o666less the umask; thekitty-ops/Op records (per-Op trails,ops-index.jsonl,op-closures.jsonl) are created owner-only (0600). The Java writer takes the same lock files (ADR 2026-10-22-1 D-4). One exception to the refusal: the glossary contract writer repairs a torn tail under the lock, moving the fragment to a.tornsidecar and retrying; repair is a per-log policy above the lock. - Refusals are
OSErrors with acode:EVENT_LOG_TORN_TAIL,EVENT_LOG_LOCK_TIMEOUT,EVENT_LOG_LOCK_UNAVAILABLE(git cannot be invoked, so the append refuses rather than lock where other writers do not),EVENT_LOG_SYMLINKandEVENT_LOG_SHORT_WRITE. A caller that already treats an I/O error as non-fatal keeps doing so; decide deliberately if yours should surface it. Each message ends withError code: <CODE>., so an operator can quote it. - A torn tail, per log. A crash in the middle of an append can leave a last line with
no trailing newline. Only the glossary logs repair it: the contract writer moves the
fragment to a
.tornsidecar (quarantine) and retries. Every other log refuses withEVENT_LOG_TORN_TAILuntil the bytes are cut by hand: the run journal (run.events.jsonl, sospec-kitty nextstops for that run),decisions.events.jsonl,mission-events.jsonl, thekitty-ops/trails, index, closure spine, lifecycle and propagation-error logs, the policy audit log, the mission archive log and the charter encoding provenance log. Writers that already treat an I/O error as non-fatal (the Op index, the propagation-error log, the encoding provenance log) log a warning and drop the row instead. The repair: keep a copy of the file, then truncate it to its last newline. A short write, orENOSPCafter a partial write, does not leave a torn tail: the door cuts the log back to its size before the write, under the lock, then raises. - When git cannot run, appends refuse. The lock path needs the git common dir. When
git cannot be invoked, including when it rejects the checkout for “dubious ownership”
(
safe.directory), every append refuses withEVENT_LOG_LOCK_UNAVAILABLE. Whether to fall back instead is an operator decision still open on PR #6681; until it is made, make git runnable in the checkout and retry. - One lock per name, not per file. The lock digest is taken over the anchor’s
resolved,
normcase-d path. Two hard-linked names of one file, or two spellings that differ only in case on a case-insensitive macOS file system (normcasedoes not fold case there), get two locks and do not exclude each other. Write a log through one name. - A check that must see the current file (an identity check, “already closed”) goes in
the
preconditioncallback so it runs under the lock;event_log_lock(path)holds the lock for a read-modify-write such as the glossary contract write. - The gate.
tests/architectural/test_event_log_writes_gate.pyledgers every caller of the door and ofspec_kitty_events.persistence.append_event(under any alias) by module and function, fails a raw write whose path it resolves to a named log or any other.jsonl, and pins raw writes whose path reads like a log. A new caller is added to its ledger in the change that adds it. It cannot see a path that arrives only as a parameter whose callers disagree, a path built from a glob, or an imported constant with a neutral name, so do not lean on it: use the door. - Retirement. Each log’s interim append, and its ledger entry, is deleted when the write service takes that log over whole (#6193); the module goes with the last one. Do not build new behaviour on it.
Reading events
- Lane state:
status.lane_reader.get_wp_lane/get_all_wp_lanes, orstatus.reducer.materialize_snapshotfor a whole snapshot. Never parsestatus.events.jsonlwith your ownjson.loadsloop and never take “the lastto_lanein the file”: file order is not lane order. - Ordering is wall clock. Every reducer-based CLI lane read (
reduce,materialize_snapshot,materialize) reachesspec_kitty_events.diary.reduce_parsed, which orders by the writer’sat, thenevent_id, with a lift that sorts a departure fromapprovedafter its approval (#4941). CLI rows carry no Lamport clock. Do not write code or docs that assume Lamport ordering on the status path. - Streaming:
status.tail_reader(andspec-kitty events tail) read raw bytes with a cursor; use them for a change feed, not for lane state. - Mission Status Read API: a consumer reads it across its contract
(the
mission-statuscontract in spec-kitty-eventscontracts/, bundled in the pinned release), never this log or CLI internals.
Adopting a new spec-kitty-events release
The library ships reducer behaviour changes in patch releases, and three recent bumps
(10.4.0 in September, 10.4.2 and 10.4.6 in October) went red on main in tests the bump PR
never ran (the history is in the
architecture page).
Do these in one PR:
- Read before you bump. Read the library’s
CHANGELOG.md,COMPATIBILITY.mdand itsdocs/changelog/*diary*entries. Flag any change to a reducer, a validator, the envelope or a symbol core imports. - Bump with the repo tooling.
uv lock --upgrade-package spec-kitty-events; update thepyproject.tomlrange if the floor moves (pinned bytests/architectural/test_pyproject_shape.py) and.kittify/release/shared-package-compatibility.json. Follow Contract pinning. - Commit the envelope snapshot in the same PR.
uv run python scripts/snapshot_events_envelope.py --force, then runtests/contract/test_events_envelope_matches_resolved_version.py. - Run the event consumers, including the ones a lock-only change does not select per PR, and record
the counts in the PR:
tests/status tests/consolidation tests/migration tests/contract/spec_kitty_events_consumer tests/contract/test_mission_status_conformance.py tests/next tests/decisions tests/specify_cli/decisions tests/specify_cli/migration tests/ci/test_reducer_lock_census.py tests/upgrade/test_mission_corpus_recovery.py. This is the targeted blast radius of the bump, not a whole-repo run. - A/B any reducer change. Run the reducer-pinning tests on the same tree with the
old and new versions, and write the delta in the PR body. A changed verdict is a
decision for the reviewer, never an
xfailadded after the PR lands. - Check the Java read API on every bump. The conformance manifest records the installed
version, and
ManifestCouplingTestholds the service’sStatusReducer.PORTED_EVENTS_VERSIONequal to it, so every version move needs both: regenerate the corpus (.venv/bin/python -m tests.contract._mission_status_conformance --write) and advancePORTED_EVENTS_VERSIONwith a port-review paragraph in its Javadoc, even when nothing changed. If the release touchesdiary.reduce_parsed, the review is a real port, and a behaviour change needs a conformance golden that exercises it. - Never import a private symbol (
spec_kitty_events._*ormodule._name). If you need one, ask upstream for a public API first.
See also
- Event ledger writers and readers: the full map and gap table.
- Status model: lanes, guards and CLI commands.
- Contract pinning and Consumer census.
spec-kitty-eventsdocs/api/ledger-write-contract.md: thepersistence.append_eventcontract.