Implement A9 state-change logging in the state store

Retrofit for the conventions merged in #4 (issue #3):

- OpLog: JSON-lines emitter with the fixed envelope (ts, agent,
  event, task_id, cause); task_id set by the orchestrator at
  unit-of-work start
- StateStore owns emission: transition, intent begin/commit/abort,
  and schema migrations each emit their event right after the
  durable write commits; callers pass the cause
- reconcile_on_boot emits boot.reconcile with action and verdicts,
  and resolves intents with reconciliation-verdict causes
- Failed resolutions emit nothing (a line exists iff the write
  committed)

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

nisse-dev/tests/test_oplog.py

@@ -0,0 +1,112 @@
+"""State-change log conventions (spec A9): every durable mutation emits one
+JSON-lines event with the fixed envelope, from the store's own write path."""
+
+import io
+import json
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from nisse_dev.oplog import OpLog
+from nisse_dev.reconcile import reconcile_on_boot
+from nisse_dev.state import StateStore
+
+ENVELOPE_FIELDS = {"ts", "agent", "event", "task_id", "cause"}
+
+
+@pytest.fixture
+def stream() -> io.StringIO:
+    return io.StringIO()
+
+
+@pytest.fixture
+def store(tmp_path: Path, stream: io.StringIO) -> StateStore:
+    return StateStore(tmp_path / "state.db", oplog=OpLog("nisse-dev", stream))
+
+
+def events(stream: io.StringIO) -> list[dict]:
+    return [json.loads(line) for line in stream.getvalue().splitlines()]
+
+
+def test_every_event_carries_the_envelope(
+    store: StateStore, stream: io.StringIO
+) -> None:
+    store.transition("PLANNING_ARCH", cause="operator command: use demo")
+    intent_id = store.begin_intent("push_branch", {}, cause="milestone execution")
+    store.commit_intent(intent_id, cause="push verified")
+    for event in events(stream):
+        assert ENVELOPE_FIELDS <= event.keys()
+        assert event["agent"] == "nisse-dev"
+
+
+def test_transition_logs_from_to_and_cause(
+    store: StateStore, stream: io.StringIO
+) -> None:
+    store.transition("PLANNING_ARCH", cause="operator command: use demo", project="d")
+    store.transition("AWAIT_ARCH_SIGNOFF", cause="plan submitted", project="d")
+    first, second = events(stream)
+    assert first["event"] == "state.transition"
+    assert (first["from"], first["to"]) == (None, "PLANNING_ARCH")
+    assert (second["from"], second["to"]) == ("PLANNING_ARCH", "AWAIT_ARCH_SIGNOFF")
+    assert second["cause"] == "plan submitted"
+
+
+def test_intent_lifecycle_events(store: StateStore, stream: io.StringIO) -> None:
+    intent_id = store.begin_intent("push_branch", {"b": "m2"}, cause="milestone")
+    store.abort_intent(intent_id, cause="discarded")
+    begin, abort = events(stream)
+    assert begin["event"] == "intent.begin"
+    assert abort["event"] == "intent.abort"
+    assert begin["intent_id"] == abort["intent_id"] == intent_id
+    assert begin["kind"] == abort["kind"] == "push_branch"
+
+
+def test_task_id_threads_through_events(store: StateStore, stream: io.StringIO) -> None:
+    store.transition("IDLE", cause="boot")
+    store.oplog.task_id = "task-42"
+    store.transition("PLANNING_ARCH", cause="operator command")
+    before, during = events(stream)
+    assert before["task_id"] is None
+    assert during["task_id"] == "task-42"
+
+
+def test_migration_emits_event(tmp_path: Path, stream: io.StringIO) -> None:
+    db = tmp_path / "state.db"
+    with StateStore(db, schema_version=1):
+        pass
+
+    def add_notes(conn: sqlite3.Connection) -> None:
+        conn.execute("CREATE TABLE notes (id INTEGER PRIMARY KEY)")
+
+    with StateStore(
+        db,
+        schema_version=2,
+        migrations={1: add_notes},
+        oplog=OpLog("nisse-dev", stream),
+    ):
+        pass
+    [event] = events(stream)
+    assert event["event"] == "schema.migrate"
+    assert (event["from_version"], event["to_version"]) == (1, 2)
+
+
+def test_boot_reconcile_emits_action_and_verdicts(
+    store: StateStore, stream: io.StringIO
+) -> None:
+    store.begin_intent("push_branch", {}, cause="milestone")
+    reconcile_on_boot(store, {"push_branch": lambda intent: True})
+    boot = [e for e in events(stream) if e["event"] == "boot.reconcile"]
+    assert len(boot) == 1
+    assert boot[0]["action"] == "resume"
+    assert "effect verified" in boot[0]["verdicts"][0]
+    commit = [e for e in events(stream) if e["event"] == "intent.commit"]
+    assert commit[0]["cause"] == "reconciliation verdict: effect verified"
+
+
+def test_failed_resolution_emits_nothing(
+    store: StateStore, stream: io.StringIO
+) -> None:
+    with pytest.raises(KeyError):
+        store.commit_intent(9999, cause="test")
+    assert events(stream) == []