M5: genre-neutral authoritative narrative state, with review corrections

Replaces AI-DnD's RPG relative-delta world state with the genre-neutral typed
narrative state of ADR 010: explicit, absolute, allowlisted events proposed by
the model, validated by the application, applied to one authoritative document,
and snapshotted per position so restore stays a row read.

This commit includes the corrective pass that followed the independent review
in planning/reports/M5-IMPLEMENTATION-REPORT.md. The invariant it exists to
hold is:

    visible active transcript position == stored head == authoritative state

Narrator editing (D10, STORY-BRANCH-SEMANTICS §§14-15)

  A narrator edit no longer rewrites a row. It returns to the state before the
  turn, takes the reader's exact text as the accepted narration, re-derives the
  state that text implies, and becomes a new active continuation — while the
  original narration keeps its words, its live flag and its whole future as
  retained history. At the tip the correction is another take; with story below
  it, it forks. No new history machinery: this is the existing fork/take/head
  path with the reader's text in place of a generated reply. The §14A refusal
  is therefore gone for narrator turns, and remains only for player input.

Pre-M5 positions

  Migration 88 backfills the empty narrative document onto every action written
  before M5, and a missing snapshot now restores the empty document instead of
  leaving the previous position's state standing. Restoring to an old Save
  Point no longer leaves a later position's entities and facts on screen.

Narrator context

  Replayed history carries prose only; the machine-readable block is no longer
  reconstructed into past turns, where it contradicted the authoritative state
  in the same prompt. A fact withdrawn by a manual correction is now named as
  no longer true, with the reader's reason, rather than silently dropped.

Also

  - state_changes joins the action-list bulk read, removing one query per row.
  - Extraction takes only the application's own protocol payload: an ordinary
    ```json or ```python block in a story survives, and a mangled proposal
    still does not reach the reader.

Planning: ADR 013 records the authoritative document shape; §§14-15/14A, D10,
C04 and BUILD-MILESTONES are updated to describe what exists. Debt is recorded
against M8 (scenario editor UX) and M9 (export of the audit trail).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PWU4gTfLYY6Qq9U7aa9Qw2

backend/tests/test_state_revert.py

@@ -1,4 +1,14 @@
-"""Tests for undo and retry rolling back the shared `world_state`.
+"""Tests for undo and retry rolling back the state a position left behind.
+
+M5 made `narrative_state` the authoritative document and `world_state` the
+legacy one, and the corrective pass added the narrative column to this file. The
+review found it covering only the legacy column (Finding 8) — which is how the
+NULL-snapshot rule that broke restoring to a migrated position (Finding 3) came
+to live in the very code this module exists to pin down, untested.
+
+The two columns follow deliberately different NULL rules, and both are asserted
+below: a missing narrative snapshot restores the empty document, a missing
+legacy snapshot is left alone.
 
 The state being rolled back was the scripting engine's `script_state` until
 M2 removed campaign scripting. The machinery under test — `attempts.restore_state`,
@@ -25,6 +35,7 @@ import pytest
 from fastapi import HTTPException
 
 from app import attempts, memorybank, models
+from app.narrative import model as narrative_model
 from app.database import Base, SessionLocal, engine
 from app.routers import adventures
 
@@ -335,3 +346,106 @@ def test_retry_restores_the_state_the_turn_started_from(db, monkeypatch):
     assert len(attempts.group(db, last)) == 1  # no sibling was filed
     assert last.world_state_after == {"gold": 20}  # its own outcome, untouched
     adventures.turns._active_turns.discard(adv.id)
+
+
+# --------------------------------------------- the narrative document (M5)
+#
+# `narrative_state` is what the reader is shown and what the narrator is told,
+# so these are the assertions that matter most. They were missing until the M5
+# corrective pass.
+
+
+def _document(**entities) -> dict:
+    """A minimal but real narrative document."""
+    state = narrative_model.empty()
+    for key, name in entities.items():
+        state["entities"][key] = {
+            "name": name, "type": "character", "status": "active",
+            "aliases": [], "attributes": {}, "conditions": [],
+            "description": "", "location": None,
+        }
+    return state
+
+
+def test_snapshot_outcome_records_the_narrative_document(db):
+    _, adv = _make_adventure(db, {})
+    adv.narrative_state = _document(mara="Mara")
+    node = models.Action(adventure_id=adv.id, type="ai", text="x")
+
+    attempts.snapshot_outcome(adv, node)
+
+    assert node.narrative_state_after["entities"]["mara"]["name"] == "Mara"
+
+
+def test_the_narrative_snapshot_is_an_independent_deep_copy(db):
+    _, adv = _make_adventure(db, {})
+    adv.narrative_state = _document(mara="Mara")
+    node = models.Action(adventure_id=adv.id, type="ai", text="x")
+    attempts.snapshot_outcome(adv, node)
+
+    adv.narrative_state["entities"]["mara"]["name"] = "Someone else"
+
+    assert node.narrative_state_after["entities"]["mara"]["name"] == "Mara"
+
+
+def test_snapshot_outcome_writes_an_empty_document_when_there_is_none(db):
+    _, adv = _make_adventure(db, {})
+    adv.narrative_state = None
+    node = models.Action(adventure_id=adv.id, type="ai", text="x")
+
+    attempts.snapshot_outcome(adv, node)
+
+    assert node.narrative_state_after == narrative_model.empty()
+
+
+def test_restore_state_puts_back_the_narrative_document(db):
+    _, adv = _make_adventure(db, {})
+    adv.narrative_state = _document(aldric="Aldric")
+    node = models.Action(adventure_id=adv.id, type="ai", text="x",
+                         narrative_state_after=_document(mara="Mara"))
+
+    attempts.restore_state(adv, node)
+
+    assert list(adv.narrative_state["entities"]) == ["mara"]
+
+
+def test_restoring_the_narrative_document_does_not_alias_the_snapshot(db):
+    _, adv = _make_adventure(db, {})
+    node = models.Action(adventure_id=adv.id, type="ai", text="x",
+                         narrative_state_after=_document(mara="Mara"))
+    attempts.restore_state(adv, node)
+
+    adv.narrative_state["entities"]["mara"]["name"] = "Changed live"
+
+    assert node.narrative_state_after["entities"]["mara"]["name"] == "Mara"
+
+
+def test_a_node_with_no_narrative_snapshot_restores_the_empty_document(db):
+    """M5 review, Finding 3 — the rule this file failed to pin down.
+
+    A pre-M5 position established nothing, and arriving there has to say so.
+    Leaving the live document alone instead left a *later* position's entities
+    and facts standing while the reader was somewhere earlier, which is the one
+    thing the head/state invariant forbids.
+    """
+    _, adv = _make_adventure(db, {"gold": 7})
+    adv.narrative_state = _document(mara="Mara")
+    pre_m5 = models.Action(adventure_id=adv.id, type="ai", text="x")
+    assert pre_m5.narrative_state_after is None
+
+    attempts.restore_state(adv, pre_m5)
+
+    assert adv.narrative_state == narrative_model.empty()
+    # The legacy column keeps the opposite rule, deliberately: nothing consults
+    # it, and blanking a running campaign's numbers would help no one.
+    assert adv.world_state == {"gold": 7}
+
+
+def test_restore_state_of_nothing_changes_neither_column(db):
+    _, adv = _make_adventure(db, {"gold": 7})
+    adv.narrative_state = _document(mara="Mara")
+
+    attempts.restore_state(adv, None)
+
+    assert list(adv.narrative_state["entities"]) == ["mara"]
+    assert adv.world_state == {"gold": 7}