interactive-story/planning/DECISIONS/013-authoritative-narrative-state-document.md

ADR 013 — The Authoritative Narrative State Document

Status: Accepted; implemented in M5 Date: 2026-09-04

Context

ADR 010 settled the protocol: the model proposes change as explicit, typed, absolute events drawn from a fixed allowlist, never as relative deltas. It did not settle what those events write into.

That shape turned out to be load-bearing. The prompt renders it, the browser's state panel groups it, export carries it, migration has to produce it for positions that predate it, and every Undo, Redo, take switch and Save Point restore reads a copy of it. The M5 review recommended recording it as a decision rather than leaving it an implementation detail of narrative/model.py. This ADR records what was built; it does not extend it.

Decision

The document

One JSON document is the campaign's authoritative account of its own story. It is genre-neutral: nothing in it names a stat, a level, a currency or a class.

entities        who and what exists — people, places, things, groups.
                Each carries a name, a type, aliases, a description, a status,
                free-form attributes, conditions, and a current location.
facts           what has been established, as subject/predicate/object.
                Each carries an id, a status, and where it came from.
relationships   how entities stand to one another, directionally.
possessions     which entity holds which item.
threads         open story threads, with a title and a status.
scene           where the story is now, and a short summary of the moment.

Two fields appear throughout and are the reason the document can be trusted:

• authority — who established this: the story, or the reader's own correction. A reader's correction outranks the narration, and the prompt says so in words.
• provenance — the branch and depth the change was made at, so a fact can be traced to the moment it entered the story.

Nothing is deleted. A fact a correction takes back is marked invalidated, with the reason and the position, because a record that vanished would audit nothing.

The pipeline

model output
    -> extraction        the protocol block is separated from the prose
    -> validation        envelope, allowlist, schema, references, canon
    -> validated events  recorded in `state_events`, with their provenance
    -> the document      applied to produce the new authoritative state
    -> per-position snapshot   stored on the node the turn produced

Each stage has one job, and the order is deliberate: the allowlist is checked before any field is read, so an unknown event type is rejected before its contents are touched.

Implementation note (post-M11). "The protocol block is separated from the prose" covers more than one fenced block. A small local model also pastes the rendered state into its prose, writes its proposal unfenced or quoted, and runs out of tokens partway through it. All of that is removed before the prose is stored, because stored prose is replayed as history. TECHNICAL-DESIGN.md §15.4 has the rules.

Where it lives

• adventures.narrative_state — the current authoritative document. This is what the narrator is told and what the reader is shown.
• actions.narrative_state_after — the whole document as it stood after that position played, on every node.
• state_events / state_proposals — the audit: what was proposed, what was accepted, what was refused and why.

What each is for

Event history is audit and provenance, not a source of truth. Restoring a position never replays it. This was proven by renaming the table away mid-campaign: Undo and Redo continued to work.

Snapshots are what make restore bounded. Arriving at a position is a single row read whose cost does not grow with the length of the story (ADR 012 §10.4). A position without a snapshot is a position the head cannot be restored to, so every node has one — including nodes written before M5, which migration 88 backfills with the empty document. A missing snapshot restores the empty document rather than leaving the previous position's state standing.

The document is the authority; the model only proposes. Every event, whether it came from the model or from a reader's correction, passes the same validation. The model cannot write a field directly, cannot invent an event type, and cannot refer to an entity that does not exist in this campaign.

The invariant

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

Everything above exists to hold this. The M5 review found two ways it had been broken — a narrator edit that rewound live state while the head stayed at the tip, and a restore to a migrated position that left a later position's state standing — and both were fixed by making the rule absolute rather than by adding a special case.

Consequences

• The document is larger than the RPG dict it replaced, so both it and the per-node snapshots are stored compressed.
• Genre lives in the campaign's canon and in the words the story uses, never in the schema. A science-fiction campaign and a fantasy one produce the same shapes.
• A reader's correction is durable and outranks narration, and the prompt states both what holds and what has been withdrawn.
• Export carries the document, the canon and every snapshot. It does not yet carry state_events / state_proposals, so an imported campaign keeps a correction's effect but not its audit trail. Deferred to M9.