<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/reference/events-in-core/">
  <id>https://docs.spec-kitty.ai/development/reference/events-in-core/</id>
  <title>Events in core</title>
  <updated>2026-11-01T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/reference/events-in-core/"/>
  <summary>Contributor rules for writing and reading event logs in core today, what not to do, and how to adopt a new spec-kitty-events release without a red nightly.</summary>
  <content type="html">&lt;span id=&quot;events-in-core&quot;&gt;&lt;/span&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;When you need this page.&lt;/strong&gt; Your change appends to an event log, reads one, or bumps
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;. The map of every writer and reader, and the gaps against the
ADRs, is in &lt;a href=&quot;/architecture/event-ledger-writers-and-readers/&quot;&gt;Event ledger writers and readers&lt;/a&gt;.
This page is the short version: what to call, what not to do.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;The target is one canonical event writer (ADR
&lt;a href=&quot;/adr/4.x/2026-10-14-1-event-native-core-one-canonical-event-writer/&quot;&gt;2026-10-14-1&lt;/a&gt;):
a resident Java write service per repository behind the Python EventBridge port (ADR
&lt;a href=&quot;/adr/4.x/2026-10-22-1-the-java-write-service-is-the-canonical-event-writer/&quot;&gt;2026-10-22-1&lt;/a&gt;).
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.&lt;/p&gt;
&lt;h2 id=&quot;writing-events&quot;&gt;Writing events&lt;/h2&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;You want to record&lt;/th&gt;&lt;th&gt;Call&lt;/th&gt;&lt;th&gt;Not&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;A work package lane transition&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;emit_status_transition_transactional&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;coordination/status_transition.py&lt;/code&gt;); it falls back to the flat shell &lt;code dir=&quot;auto&quot;&gt;emit_status_transition&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;status/emit.py&lt;/code&gt;) for a Mission without coordination topology&lt;/td&gt;&lt;td&gt;building a &lt;code dir=&quot;auto&quot;&gt;StatusEvent&lt;/code&gt; and appending it yourself&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;An inner-state annotation&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;emit_inner_state_changed&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;status/emit.py&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;a raw row in &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;A glossary fact&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;glossary.events.append_event&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/glossary/events.py&lt;/code&gt;), which writes through &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.persistence.append_event&lt;/code&gt;&lt;/td&gt;&lt;td&gt;a hand-built dict&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;A new kind of fact&lt;/td&gt;&lt;td&gt;Ask first. The fact needs a model in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; before core writes it (ADR 2026-10-14-1 D-4). Write it through &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.persistence.append_event&lt;/code&gt;&lt;/td&gt;&lt;td&gt;a new &lt;code dir=&quot;auto&quot;&gt;*.jsonl&lt;/code&gt; file with a core-owned row shape&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Rules:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Never &lt;code dir=&quot;auto&quot;&gt;open(path, &quot;a&quot;)&lt;/code&gt; an event log.&lt;/strong&gt; A plain append has no lock and no torn-tail
check. &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_status_events_writes_gate.py&lt;/code&gt; rejects any write to
&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; outside &lt;code dir=&quot;auto&quot;&gt;status/store.py&lt;/code&gt; and its ledgered sites, and
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_event_log_writes_gate.py&lt;/code&gt; does the same for every other log
(see &lt;a href=&quot;#appending-to-an-event-log-interim&quot;&gt;Appending to an event log (interim)&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Never import from &lt;code dir=&quot;auto&quot;&gt;specify_cli.status._unsafe&lt;/code&gt;.&lt;/strong&gt; Its &lt;code dir=&quot;auto&quot;&gt;ALLOWED_CALLERS&lt;/code&gt; list is
shrink-only; adding a module fails &lt;code dir=&quot;auto&quot;&gt;test_status_unsafe_allowlist.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Never add a new &lt;code dir=&quot;auto&quot;&gt;canonical-producer-exempt&lt;/code&gt; marker or a new local envelope.&lt;/strong&gt;
Sixteen markers remain in &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;; the migration removes them.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Serialize status rows with &lt;code dir=&quot;auto&quot;&gt;store.serialize_event_line&lt;/code&gt;&lt;/strong&gt;, the one authority for the
on-disk row shape. Do not &lt;code dir=&quot;auto&quot;&gt;json.dumps&lt;/code&gt; a status row yourself.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Keep &lt;code dir=&quot;auto&quot;&gt;prepare_transition&lt;/code&gt; pure.&lt;/strong&gt; It does no writes, locks, git or fan-out
(&lt;code dir=&quot;auto&quot;&gt;status/transition_pipeline.py&lt;/code&gt;); git-derived values such as the &lt;code dir=&quot;auto&quot;&gt;lane_head&lt;/code&gt; stamp
come in through an injected probe.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A side effect that reacts to an event is a consumer, not a new line in a shell.&lt;/strong&gt;
Today the shells still run commits inline; do not add more. The produce seam
&lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt; is where a transport registers a handler. Open-core registers none,
so every &lt;code dir=&quot;auto&quot;&gt;fire_*&lt;/code&gt; is a no-op, and nothing hosted belongs in this repository.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Call the state files by their names.&lt;/strong&gt; The migration ledger
(&lt;code dir=&quot;auto&quot;&gt;.kittify/migration-ledger.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;upgrade/ledger.py&lt;/code&gt;) and the activation ledger
(&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/activation.yaml&lt;/code&gt;) are state ledgers, not event logs. Never write
bare “the ledger”.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The migration ledger’s append is locked, and one selection rule is structural.&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;MigrationLedger.append&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;append_many&lt;/code&gt; hold
&lt;code dir=&quot;auto&quot;&gt;.kittify/migrations/&amp;#x3C;ledger file name&gt;.lock&lt;/code&gt; (a &lt;code dir=&quot;auto&quot;&gt;kernel.locks.machine_file_lock&lt;/code&gt;
sidecar in the IGNORED per-clone surface, bounded at 30 s) across their
read-modify-write, so two &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;migrate&lt;/code&gt; runs on one checkout cannot lose a
record; a lock that never frees raises &lt;code dir=&quot;auto&quot;&gt;MigrationLedgerLockTimeoutError&lt;/code&gt; and
appends nothing. Selection is ledger-diff &lt;strong&gt;plus&lt;/strong&gt; the &lt;code dir=&quot;auto&quot;&gt;runs_first&lt;/code&gt; structural
reselection: a recorded migration whose &lt;code dir=&quot;auto&quot;&gt;structural_detect&lt;/code&gt; fires is re-selected
(a pulled &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; or a merge can revive the old state), while &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt;
stays the pre-&lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; idempotency guard. See
&lt;a href=&quot;/adr/4.x/2026-10-17-1-explicit-migration-ledger/&quot;&gt;ADR 2026-10-17-1&lt;/a&gt;, Amendments
2026-10-20 and 2026-10-30.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;appending-to-an-event-log-interim&quot;&gt;Appending to an event log (interim)&lt;/h2&gt;
&lt;p&gt;Until the Java write service owns a log (#6193), an append to any event log other than
&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;canonical-events.jsonl&lt;/code&gt; goes through one door,
&lt;code dir=&quot;auto&quot;&gt;kernel.event_log_append&lt;/code&gt; (#6606). Those two keep the Mission status lock and the
&lt;code dir=&quot;auto&quot;&gt;status.store&lt;/code&gt; primitives.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Call &lt;code dir=&quot;auto&quot;&gt;append_event_log_lines(path, lines)&lt;/code&gt;.&lt;/strong&gt; 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).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The lock contract.&lt;/strong&gt; The lock is anchored on the log, or on the family directory for
one-file-per-record logs (&lt;code dir=&quot;auto&quot;&gt;kitty-ops/&amp;#x3C;op&gt;.jsonl&lt;/code&gt;). It lives at
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;git-common-dir&gt;/spec-kitty-locks/event-logs/&amp;#x3C;sha256[:32]&gt;.lock&lt;/code&gt;, so every worktree of a
repository shares it; outside a git repository it is &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;anchor&gt;.event-log.lock&lt;/code&gt;. The wait
is bounded (&lt;code dir=&quot;auto&quot;&gt;EVENT_LOG_LOCK_TIMEOUT_S&lt;/code&gt;, 10 s). Under the lock, a log whose last byte is
not LF is refused, then the whole unit is written in one &lt;code dir=&quot;auto&quot;&gt;O_APPEND&lt;/code&gt; write and fsynced.
A new log is created with mode &lt;code dir=&quot;auto&quot;&gt;0o666&lt;/code&gt; less the umask; the &lt;code dir=&quot;auto&quot;&gt;kitty-ops/&lt;/code&gt; Op records
(per-Op trails, &lt;code dir=&quot;auto&quot;&gt;ops-index.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;op-closures.jsonl&lt;/code&gt;) are created owner-only (&lt;code dir=&quot;auto&quot;&gt;0600&lt;/code&gt;).
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 &lt;code dir=&quot;auto&quot;&gt;.torn&lt;/code&gt; sidecar and retrying; repair is a per-log policy above the lock.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Refusals are &lt;code dir=&quot;auto&quot;&gt;OSError&lt;/code&gt;s with a &lt;code dir=&quot;auto&quot;&gt;code&lt;/code&gt;:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;EVENT_LOG_TORN_TAIL&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;EVENT_LOG_LOCK_TIMEOUT&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;EVENT_LOG_LOCK_UNAVAILABLE&lt;/code&gt; (git cannot be invoked, so the
append refuses rather than lock where other writers do not), &lt;code dir=&quot;auto&quot;&gt;EVENT_LOG_SYMLINK&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;EVENT_LOG_SHORT_WRITE&lt;/code&gt;. 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 with
&lt;code dir=&quot;auto&quot;&gt;Error code: &amp;#x3C;CODE&gt;.&lt;/code&gt;, so an operator can quote it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A torn tail, per log.&lt;/strong&gt; 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 &lt;code dir=&quot;auto&quot;&gt;.torn&lt;/code&gt; sidecar (quarantine) and retries. Every other log refuses with
&lt;code dir=&quot;auto&quot;&gt;EVENT_LOG_TORN_TAIL&lt;/code&gt; until the bytes are cut by hand: the run journal
(&lt;code dir=&quot;auto&quot;&gt;run.events.jsonl&lt;/code&gt;, so &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; stops for that run), &lt;code dir=&quot;auto&quot;&gt;decisions.events.jsonl&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;mission-events.jsonl&lt;/code&gt;, the &lt;code dir=&quot;auto&quot;&gt;kitty-ops/&lt;/code&gt; 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, or &lt;code dir=&quot;auto&quot;&gt;ENOSPC&lt;/code&gt; after 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.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;When git cannot run, appends refuse.&lt;/strong&gt; The lock path needs the git common dir. When
git cannot be invoked, including when it rejects the checkout for “dubious ownership”
(&lt;code dir=&quot;auto&quot;&gt;safe.directory&lt;/code&gt;), every append refuses with &lt;code dir=&quot;auto&quot;&gt;EVENT_LOG_LOCK_UNAVAILABLE&lt;/code&gt;. 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.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One lock per name, not per file.&lt;/strong&gt; The lock digest is taken over the anchor’s
resolved, &lt;code dir=&quot;auto&quot;&gt;normcase&lt;/code&gt;-d path. Two hard-linked names of one file, or two spellings that
differ only in case on a case-insensitive macOS file system (&lt;code dir=&quot;auto&quot;&gt;normcase&lt;/code&gt; does not fold
case there), get two locks and do not exclude each other. Write a log through one name.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A check that must see the current file&lt;/strong&gt; (an identity check, “already closed”) goes in
the &lt;code dir=&quot;auto&quot;&gt;precondition&lt;/code&gt; callback so it runs under the lock; &lt;code dir=&quot;auto&quot;&gt;event_log_lock(path)&lt;/code&gt; holds the
lock for a read-modify-write such as the glossary contract write.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The gate.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_event_log_writes_gate.py&lt;/code&gt; ledgers every caller of
the door and of &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.persistence.append_event&lt;/code&gt; (under any alias) by module
and function, fails a raw write whose path it resolves to a named log or any other
&lt;code dir=&quot;auto&quot;&gt;.jsonl&lt;/code&gt;, 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.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Retirement.&lt;/strong&gt; 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.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;reading-events&quot;&gt;Reading events&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Lane state:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;status.lane_reader.get_wp_lane&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;get_all_wp_lanes&lt;/code&gt;, or
&lt;code dir=&quot;auto&quot;&gt;status.reducer.materialize_snapshot&lt;/code&gt; for a whole snapshot. Never parse
&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; with your own &lt;code dir=&quot;auto&quot;&gt;json.loads&lt;/code&gt; loop and never take “the last
&lt;code dir=&quot;auto&quot;&gt;to_lane&lt;/code&gt; in the file”: file order is not lane order.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Ordering is wall clock.&lt;/strong&gt; Every reducer-based CLI lane read (&lt;code dir=&quot;auto&quot;&gt;reduce&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;materialize_snapshot&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;materialize&lt;/code&gt;) reaches &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.diary.reduce_parsed&lt;/code&gt;,
which orders by the writer’s &lt;code dir=&quot;auto&quot;&gt;at&lt;/code&gt;, then &lt;code dir=&quot;auto&quot;&gt;event_id&lt;/code&gt;, with a lift that sorts a departure
from &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; after its approval (#4941). CLI rows carry no Lamport clock. Do not
write code or docs that assume Lamport ordering on the status path.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Streaming:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;status.tail_reader&lt;/code&gt; (and &lt;code dir=&quot;auto&quot;&gt;spec-kitty events tail&lt;/code&gt;) read raw bytes with a
cursor; use them for a change feed, not for lane state.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mission Status Read API:&lt;/strong&gt; a consumer reads it across its contract
(the &lt;code dir=&quot;auto&quot;&gt;mission-status&lt;/code&gt; contract in spec-kitty-events &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt;, bundled in the pinned release), never this log or CLI internals.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;adopting-a-new-spec-kitty-events-release&quot;&gt;Adopting a new &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; release&lt;/h2&gt;
&lt;p&gt;The library ships reducer behaviour changes in &lt;strong&gt;patch&lt;/strong&gt; releases, and three recent bumps
(10.4.0 in September, 10.4.2 and 10.4.6 in October) went red on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; in tests the bump PR
never ran (the history is in the
&lt;a href=&quot;/architecture/event-ledger-writers-and-readers/#why-event-changes-are-risky&quot;&gt;architecture page&lt;/a&gt;).
Do these in one PR:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Read before you bump.&lt;/strong&gt; Read the library’s &lt;code dir=&quot;auto&quot;&gt;CHANGELOG.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;COMPATIBILITY.md&lt;/code&gt; and its
&lt;code dir=&quot;auto&quot;&gt;docs/changelog/*diary*&lt;/code&gt; entries. Flag any change to a reducer, a validator, the
envelope or a symbol core imports.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Bump with the repo tooling.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;uv lock --upgrade-package spec-kitty-events&lt;/code&gt;; update the
&lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; range if the floor moves (pinned by &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_pyproject_shape.py&lt;/code&gt;)
and &lt;code dir=&quot;auto&quot;&gt;.kittify/release/shared-package-compatibility.json&lt;/code&gt;. Follow
&lt;a href=&quot;/development/how-to/contract-pinning/&quot;&gt;Contract pinning&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Commit the envelope snapshot in the same PR.&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;uv run python scripts/snapshot_events_envelope.py --force&lt;/code&gt;, then run
&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_events_envelope_matches_resolved_version.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Run the event consumers, including the ones a lock-only change does not select per PR&lt;/strong&gt;, and record
the counts in the PR:
&lt;code dir=&quot;auto&quot;&gt;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&lt;/code&gt;.
This is the targeted blast radius of the bump, not a whole-repo run.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A/B any reducer change.&lt;/strong&gt; 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 &lt;code dir=&quot;auto&quot;&gt;xfail&lt;/code&gt; added after the PR lands.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Check the Java read API on every bump.&lt;/strong&gt; The conformance manifest records the installed
version, and &lt;code dir=&quot;auto&quot;&gt;ManifestCouplingTest&lt;/code&gt; holds the service’s &lt;code dir=&quot;auto&quot;&gt;StatusReducer.PORTED_EVENTS_VERSION&lt;/code&gt;
equal to it, so every version move needs both: regenerate the corpus
(&lt;code dir=&quot;auto&quot;&gt;.venv/bin/python -m tests.contract._mission_status_conformance --write&lt;/code&gt;) and advance
&lt;code dir=&quot;auto&quot;&gt;PORTED_EVENTS_VERSION&lt;/code&gt; with a port-review paragraph in its Javadoc, even when nothing changed.
If the release touches &lt;code dir=&quot;auto&quot;&gt;diary.reduce_parsed&lt;/code&gt;, the review is a real port, and a behaviour change
needs a conformance golden that exercises it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Never import a private symbol&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events._*&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;module._name&lt;/code&gt;). If you
need one, ask upstream for a public API first.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/event-ledger-writers-and-readers/&quot;&gt;Event ledger writers and readers&lt;/a&gt;: the full map and gap table.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/status-model/&quot;&gt;Status model&lt;/a&gt;: lanes, guards and CLI commands.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/how-to/contract-pinning/&quot;&gt;Contract pinning&lt;/a&gt; and &lt;a href=&quot;/development/how-to/consumer-census/&quot;&gt;Consumer census&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;docs/api/ledger-write-contract.md&lt;/code&gt;: the &lt;code dir=&quot;auto&quot;&gt;persistence.append_event&lt;/code&gt; contract.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
