Amend A9 with state-change log conventions #4

2026-09-05T19:29:36Z

dev-agent commented

2026-09-05 19:29:36 +00:00

Addresses #3 — this doc PR is the plan gate; implementation follows only after it merges.

Conventions added to A9, per our discussion:

Scope: all durable mutations — transitions, intent begin/commit/abort, gate open/approve/reject, boot reconciliation, schema migrations
Emission owned by the state store: the log line is written by the same code path as the durable write, right after commit — a line exists iff the change hit disk, so the trail can't drift; callers pass the cause
Format: JSON lines with a fixed envelope (ts, agent, event, task_id, cause) plus per-event fields; dotted event taxonomy, names never reused
Correlation from day one: task_id minted at unit-of-work start and threaded through every event it causes
Diagnostic, never load-bearing: nothing derives state from logs — same rule that keeps Matrix history non-authoritative

Implementation plan once merged: a small StateStore retrofit PR (emit state.transition, intent.*, boot.reconcile, schema.migrate with a cause parameter threaded through the existing API), and the gate.* events land with the step-2 control-loop work.

🤖 Generated with Claude Code

Addresses #3 — this doc PR is the plan gate; implementation follows only after it merges. Conventions added to A9, per our discussion: - **Scope**: all durable mutations — transitions, intent begin/commit/abort, gate open/approve/reject, boot reconciliation, schema migrations - **Emission owned by the state store**: the log line is written by the same code path as the durable write, right after commit — a line exists iff the change hit disk, so the trail can't drift; callers pass the `cause` - **Format**: JSON lines with a fixed envelope (`ts`, `agent`, `event`, `task_id`, `cause`) plus per-event fields; dotted event taxonomy, names never reused - **Correlation from day one**: `task_id` minted at unit-of-work start and threaded through every event it causes - **Diagnostic, never load-bearing**: nothing derives state from logs — same rule that keeps Matrix history non-authoritative Implementation plan once merged: a small StateStore retrofit PR (emit `state.transition`, `intent.*`, `boot.reconcile`, `schema.migrate` with a `cause` parameter threaded through the existing API), and the `gate.*` events land with the step-2 control-loop work. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dev-agent added 1 commit 2026-09-05 19:29:37 +00:00

Amend A9 with state-change log conventions (issue #3 )

CI / checks (push) Successful in 7s

Details

CI / checks (pull_request) Successful in 7s

Details

41e103c35d

Every durable mutation emits one JSON-lines event, emitted by the
state store itself immediately after the commit returns, with a fixed
envelope (ts, agent, event, task_id correlation ID, cause) and a
dotted event taxonomy covering transitions, intents, gates, boot
reconciliation, and migrations. Logs stay diagnostic-only, never
load-bearing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

dongar approved these changes

2026-09-05 21:10:14 +00:00

dongar merged commit ba848281ec into main

2026-09-05 21:10:20 +00:00

dongar deleted branch logging-conventions-a9

2026-09-05 21:10:20 +00:00

dev-agent referenced this issue from a commit

2026-09-05 21:13:38 +00:00

Implement A9 state-change logging in the state store

dev-agent referenced this pull request

2026-09-05 21:13:45 +00:00

Implement A9 state-change logging in the state store #5