interactive-story/planning/TECHNICAL-DESIGN.md

# Adventure Storyteller — Technical Design

**Status:** v1.0 — architecture selected after Phase 0B  
**Production base:** AI-DnD `d72f7c1bda0f34fccd84afb7a25c34eb01c901de`

## 1. Design Objective

Build a local-first, browser-based interactive storytelling application in which:

- Ollama provides inference on user-controlled local infrastructure, either same-host or on an explicitly approved trusted-LAN machine,
- the application owns authoritative story state,
- complete story history is retained,
- user-facing Undo/Redo/Retry/Save Point behavior is simple,
- internal history is non-destructive and lineage-aware,
- long-running context is reconstructed from state, summaries, retrieval, recent turns, and local knowledge,
- imported knowledge remains local and authority-classified,
- prompt/context provenance is inspectable,
- future image/video/audio/TTS/STT providers can be added without coupling them to the story engine.

The application is an interactive-story system, not a D&D rules engine.

## 2. Production Base Decision

AI-DnD is the production fork/base.

Retain its high-value foundation:

- React/Vite browser application,
- FastAPI backend,
- SQLite persistence/migrations,
- story-tree and lineage machinery,
- alternate takes,
- branch switching,
- per-node state snapshot pattern,
- local Ollama/OpenAI-compatible integration where appropriate,
- branch-scoped memory concepts,
- prompt/context snapshots and Insights concepts,
- SSE streaming,
- export/import framework,
- automated test foundation.

Do not inherit candidate behavior merely because it exists upstream. The product specification and detailed behavior documents remain authoritative.

## 3. Reference Projects and Their Role

### ai-adventure

Primary implementation reference for:

- explicit typed state events,
- model-proposes/application-validates discipline,
- atomic commit behavior,
- head movement instead of destructive Undo,
- named checkpoints,
- replay/state reconstruction,
- narrow local-only endpoint handling,
- deterministic lexical lore concepts.

It is **not** the written specification and does not override this design.

### Open Dungeon

Reference for:

- focused story-reading UX,
- inline generated media presentation,
- character visual continuity,
- local media-service boundaries.

It is not a production-fork candidate.

### Other references

- Chronicler: memory authority/trust tiers.
- Interactive Fiction Framework: canon/application-owned-state concepts.
- Gamentic: provider-neutral asynchronous media boundary.

## 4. Selected High-Level Architecture

```text
                   Local Browser
                        |
                        v
              +-------------------+
              | React/Vite UI     |
              +---------+---------+
                        |
                        v
              +-------------------+
              | FastAPI Story     |
              | Director/API      |
              +---+-----------+---+
                  |           |
                  |           +-----------------------+
                  v                                   v
       +----------------------+             +----------------------+
       | SQLite Authoritative |             | Context / Retrieval  |
       | Story Store          |             | local only           |
       +----------+-----------+             +----------+-----------+
                  |                                    |
                  |                         +----------+-----------+
                  |                         | FTS + local semantic |
                  |                         | retrieval            |
                  |                         +----------+-----------+
                  |                                    |
                  +--------------------+---------------+
                                       |
                                       v
                               +----------------------+
                               | Ollama               |
                               | localhost by default |
                               | or approved LAN host |
                               +----------------------+
```

Future optional extension:

```text
Accepted Story / Scene State
          |
          v
  +------------------+
  | Media Coordinator|
  +--+---+---+---+---+
     |   |   |   |   |
     v   v   v   v   v
   Image Video Audio TTS STT
   local providers only by default
```

## 5. Local-Only Runtime Boundary

`Local-only` means user-controlled local infrastructure with no required Internet/cloud dependency; it does not require every process to share one host.

The architecture has **two boundaries, and they are not the same boundary**. The
storyteller is loopback-only, always. Inference may be same-host or on a
specifically configured trusted-LAN machine. Wording that describes Ollama as
simply "loopback/local" collapses the two and understates the intended
deployment:

```text
Browser ──loopback──> storyteller (FastAPI + SPA), bound to 127.0.0.1
                          │
                          ├── same-host Ollama on 127.0.0.1:11434        (default)
                          │
                          └── OR an explicitly configured trusted-LAN Ollama
                              on another user-controlled machine
                              http://<host>:11434/v1  or  https://<host>/v1
```

Read that as three separate rules:

1. **The storyteller's own listener is loopback, in every run path.** Dev
   server, production server, and container alike. Nothing about the inference
   choice changes it. Where a container must listen on `0.0.0.0` because a
   published port cannot reach anything else, the port is published to the
   host's loopback only.
2. **The inference endpoint is an outbound connection, chosen by the user.**
   Same-host loopback is the default. A trusted-LAN host is a first-class,
   supported v1 configuration — not a workaround and not a development-only
   convenience.
3. **The two are independent.** Reaching a LAN Ollama never requires, and must
   never cause, LAN exposure of the storyteller UI/API. There is no supported
   v1 configuration in which the storyteller itself is reachable from the LAN.

### Transport to a trusted-LAN endpoint

A LAN inference host is often reached over **HTTPS with a certificate issued by
a private or local CA**, and may offer no cleartext port at all. This is
ordinary for a self-hosted server, so v1 must handle it rather than assume the
same plain HTTP that same-host loopback uses:

- outbound HTTPS verifies against the **operating system's trusted CA store** in
  addition to any bundled certificate list, so a CA the user installed on their
  own machine is honoured here as it is by `curl` and their browser;
- certificate **and hostname** verification stay fully enabled;
- there is **no "ignore TLS errors" option** anywhere — not in the UI, not in
  configuration, not as an environment variable;
- the endpoint field therefore accepts `https://` on any port.

Prompts, story text, retrieved knowledge and embedding inputs all travel to
whichever inference host is configured, which is why it must be one the user
controls on a network they trust — and why the endpoint is always explicitly
configured, never discovered.

See ADR 002 (*Transport for a Trusted-LAN Endpoint*) and, for the demonstrated
deployment, `planning/archive/milestone-reports/M1-IMPLEMENTATION-REPORT.md` §F.

Allowed future local paths may also include explicitly configured local media services.

Production defaults must not require:

- cloud model providers,
- hosted authentication,
- analytics/telemetry,
- remote database services,
- runtime CDNs/fonts/assets,
- automatic web retrieval,
- external embeddings/vector stores,
- general plugins/MCP/shell execution.

### 5.1 Known AI-DnD hardening work

Phase 0B identified concrete inherited violations, and M1 added a fifth. **All
five are now resolved** — items 1, 2 and 5 in M1, items 3 and 4 in M2.

1. ~~`tiktoken` attempts to download the `cl100k_base` encoding on first use.~~
   **Done in M1.** The encoding table is vendored in the tree and loaded
   directly, with its SHA-256 verified against the digest `tiktoken` pins, so no
   code path in the tokenizer can reach the network.
2. ~~the SPA requests Google Fonts at runtime.~~
   **Done in M1.** All three families are self-hosted, and the CSP names no
   remote origin at all.
3. ~~hosted/multi-user/auth/demo/analytics/Postgres/cloud-provider/QuickJS paths are unnecessary.~~
   - remove them rather than merely hide them where practical.
   - **Done in M2, in full.** Removed rather than hidden: 52 API routes fell to
     36, and `/api/auth`, `/api/analytics` and `/api/scripts` are gone entirely
     rather than gated. See §5.2.
4. ~~endpoint validation must reflect this product's threat model.~~
   - same-host loopback Ollama is the default; an explicitly configured trusted-LAN Ollama endpoint is supported; arbitrary public/Internet model endpoints must be rejected or kept outside normal v1 configuration.
   - inference endpoint configuration must not change the storyteller's own loopback bind behavior.
   - **Done in M2.** `backend/app/endpoints.py` applies an address-based
     allowlist on save and again before every outbound request. Endpoint
     configuration has no influence on the storyteller's own bind address.
     ADR 011; `SECURITY-THREAT-MODEL.md` §10A.
5. ~~outbound TLS verified only against a bundled public-CA list, so a LAN host
   with a privately issued certificate was refused.~~
   **Found and fixed in M1.** Not visible to Phase 0B: every run up to that
   point used plain HTTP over loopback, where certificate verification never
   happens. See *Transport to a trusted-LAN endpoint* above.

### 5.2 Production architecture as established by M1 and M2

The architecture below is no longer a selection; it is what the code does. It is
recorded here so later milestones inherit facts rather than intentions.

| | |
| --- | --- |
| Production base | AI-DnD, forked at `d72f7c1` (§2, ADR 009) |
| Persistence | SQLite. Postgres, Neon and the Render deployment path are removed |
| Inference | Ollama only. No cloud provider code, no API key, no key UI |
| Storyteller bind | loopback by default, in every run path including the published Docker port |
| Ollama endpoint | same-host loopback by default; an explicitly configured trusted-LAN endpoint is equally supported |
| Public endpoints | refused by address, on save and before every request |
| Trusted-LAN HTTPS | supported, with full certificate and hostname verification against the machine's CA store; no bypass exists |
| Runtime assets | self-contained. Tokenizer table and fonts are vendored; the CSP names no remote origin |

Removed in M2 rather than hidden: hosted accounts and auth, guest/demo
behaviour, hosted analytics, cloud inference providers, API-key storage and its
UI, Postgres/Neon/Render support, and QuickJS campaign scripting.

**A trusted-LAN Ollama endpoint is accepted production behaviour**, not a
development convenience. Any statement that the only valid endpoint is literally
`127.0.0.1` is stale and should be read against §5 and §10A of the threat model.

## 6. Browser UI Boundary

The browser remains a presentation/control layer, not the owner of story authority.

Primary areas:

- campaign library/setup,
- active story transcript,
- input composer,
- Undo / Redo / Retry,
- alternate-take selector,
- Save Points,
- current story state inspector,
- imported-knowledge manager,
- prompt/context inspector,
- local-model status/settings,
- export/import,
- future media gallery/actions.

Normal storytelling should not expose branch IDs, database rows, embeddings, or event logs unless the user opens advanced diagnostics.

## 7. Story Director Boundary

The FastAPI service owns the turn lifecycle:

1. resolve campaign, active branch, and active head,
2. load authoritative state at that head,
3. assemble bounded lineage-safe context,
4. retain prompt/retrieval provenance,
5. invoke local Ollama narrator,
6. stream provisional narration,
7. obtain/parse a structured state proposal,
8. validate the proposal,
9. atomically accept the turn plus validated state consequences,
10. update derived memory/summary/index data without allowing derived failures to corrupt the accepted turn,
11. expose the new current head to the browser.

A failed generation must not partially advance authoritative story state.

## 8. Non-Destructive History Model

### 8.1 Core rule

Undo moves the active head. It does not delete accepted history.

Phase 0B demonstrated that AI-DnD already contains the architectural chokepoints needed for this approach:

- stored head depth/position,
- lineage reads through a common path abstraction,
- branch-at-depth behavior.

The disposable spike is evidence, not production code to merge blindly.

### 8.2 Active head versus retained tip

The design distinguishes:

- **retained tip:** newest retained turn on a continuation,
- **active head:** the story position from which the user is currently reading/continuing.

After Undo, the active head may sit behind a retained tip.

Redo moves the head forward along the previous active continuation while no divergent write has occurred.

### 8.3 Divergence after moving backward

If the user writes/retries/edits from a head behind the retained tip:

- the new continuation forks on first write,
- the previous future remains retained,
- ordinary Redo into that old future is invalidated,
- the displaced future is marked abandoned/disposable,
- lineage-sensitive state, summary, and memory selection follows only the new active path.

### 8.4 Retry

Retry preserves alternate narrator takes for the same user input.

Production implementation must ensure retry/add-take while behind the current tip uses the same safe fork/head semantics as other writes.

### 8.5 Checkpoints / Save Points

A named checkpoint is a durable pointer to a recoverable story position.

Conceptually:

```text
campaign_id
branch_id
turn_id or equivalent head coordinate
name
notes
created_at
```

Restoring a checkpoint moves the active head to that position. The existing later future remains retained. A new branch is created only if/when the user creates a different continuation.

### 8.6 Abandoned history

No automatic cleanup policy is required in v1.

Abandoned history must:

- remain retained,
- be marked disposable/inactive through implementation-appropriate metadata,
- stop influencing current state/context/memory/summary,
- remain available for future recovery/cleanup features.

### 8.7 As implemented in M3

M3 built this model. The following is fact rather than direction, and ADR 012
records it as the architectural decision. Sections 8.1-8.6 stand; this says how
they were realised.

**The head is stored, not derived.** A campaign carries a branch and a depth,
and that pair is the active head. No read may recompute it from the newest row —
that was the pre-M3 behavior, and it is what made Redo impossible and made an
export reopen an undone campaign at its tip.

**Lineage reads are capped at the head, in one place.** The path abstraction that
already resolved a branch's ancestry now also limits every entry to the head, so
the transcript, the assembled narrator context, take/parent resolution and memory
retrieval narrow together. There is exactly one way to read past the head — a
named, uncapped view of the same lineage — and only two callers may use it: Redo,
and the check that decides whether a write must fork. Any new feature that reads
story rows directly, rather than through the capped lineage, will see retained
history the story is not telling.

**Head movement is one mechanism.** Undo, Redo, and anything later that restores
a position resolve a target depth and then call a single move operation, which
sets the coordinate and restores the state recorded at it. Undo and Redo differ
only in which way they resolve the target. Both step over a whole turn — a
player's action and the reply to it — so the head never rests between the two
halves of one turn.

**State comes from the node, not from a replay.** Each node records the state it
left behind, so moving the head is a row lookup plus a restore: the same cost at
any distance, in either direction, and identical whether the position is reached
from in front of it or from behind. This is the property §10.4's hybrid storage
must preserve.

### M6 — derived context: summaries, memory and budgeting

Four things future milestones rely on, all built on the lineage machinery M3-M5
established rather than beside it.

**Summary lineage — both halves.** A summary is a `summaries` row carrying
`(branch_id, depth)` for the last node it covers plus a
`source_start`/`source_end` range. The invariant M6 holds is:

> Both summary eligibility and the prior-summary input to the summarizer are
> lineage-scoped.

*Eligibility* is `lineage.Path.clause` over the row's coordinate — the same
capped-path clause that filters actions and memories — so Undo, Redo, Save Point
restore and divergence need no summary-specific rule. *Input* is
`summaries.current`, the same question the context builder asks, so a summary is
only ever built on top of one that is valid where the story now stands; where
none is, generation starts from nothing.

The second half is not decorative. The first M6 implementation had only the
first, seeding generation from `adventures.story_summary`, and the review
demonstrated abandoned prose reaching an active prompt inside a row that was
itself correctly anchored. Anchoring the output does not make the content safe.

Nothing is deleted when a line is abandoned. `adventures.story_summary` survives
as a reader-facing convenience only — the Plot panel edits it, the export bundle
carries it — mirroring whichever summary is eligible, kept in step by
`summaries.record` and by `attempts.restore_state` when the head moves. Nothing
authoritative reads it.

**Memory lineage and provenance.** Unchanged from what M3 built and M6 verified:
a memory carries `(branch_id, depth)` and a source range, and retrieval filters
through the capped path. M6 adds provenance to the *retrieval result*, in the
same query that fetches the text, so the inspector can answer "where did this
come from?" without a query per memory.

**Memory authority.** `Memory.authority` is `accepted_story` or `heuristic`,
decided by the application in `memorybank.classify_authority`, and rendered into
the prompt as an explicit mark. Retrieval never writes state; the M5 typed-event
path remains the only route to an authoritative change.

**Retrieval ranking and redundancy.** Ranking is cosine similarity plus an
explicit pin; the other factors `CONTEXT-AND-MEMORY.md` §20 contemplates are not
implemented. Before the final top-k cut, retrieval drops a candidate that
repeats one already chosen, never across authority classes, at a threshold
measured against the configured embedding model
(`memorybank.REDUNDANT_SIMILARITY`). Suppressed candidates are reported so the
selection stays inspectable. Without this, a stretch of repetitive story fills
the whole memory budget with near-copies and evicts the one memory that
mattered — which the review measured happening.

**Context budgeting.** The reply is reserved out of `context_token_budget`
before history is selected, with a fixed 64-token margin. Protected content —
narrator rules, canon, authoritative state, the reader's input, the reply
reserve — is never dropped to fit older prose; history is the elastic part and
is filled newest-first until the remaining budget is spent. If the protected
part alone exceeds the budget, `build_context` raises `ContextOverflow` rather
than assembling a prompt known to overflow.

**Background failure observability.** Derived work (memory extraction, summary
generation, embedding) runs in a fire-and-forget task and must not take an
accepted turn down with it. Each pass is wrapped so that a failure rolls back
only its own uncommitted work and writes a `derived_status` row naming the kind,
the error and the attempt count. That row is served by
`GET /adventures/{id}/derived` and shown in the Insights panel. M2 shipped with
the whole memory bank dead and the suite green; this is the mechanism that makes
the same failure visible.

**Prompt inspection.** The context report carries per-section token counts, the
budget, the output reserve, the protected total, the history allowance, the
summary's provenance, each retrieved memory's authority and source coordinate,
and the derived-work status.

**Divergence is a property of the lineage, not a flag.** The first write below a
moved-back head forks; Undo alone never does. After the fork, the displaced
future is no longer on the lineage being read, so ordinary Redo finds nothing
ahead and reports that it has nowhere to go. Nothing has to be invalidated,
cleared, or kept in step.

**A branch the story leaves records the depth and time it was left**, as metadata
nothing reads to decide behavior (§8.6's "implementation-appropriate metadata").
It makes a divergence observable and gives later cleanup and recovery features
something to select on; because no decision depends on it, a stale or hand-edited
value cannot make the story wrong.

**Operations that change what the story says at a position must ask whether
story descends from that position and is off screen.** Switching which take is
live, and editing a turn's text in place, both refuse in that situation rather
than act silently, because retained history must not be made to disagree with
itself in a way the user cannot see. See `STORY-BRANCH-SEMANTICS.md` §10 and
§14A.

### 8.8 Save Points, as implemented in M4

M4 added durable named Save Points and built nothing in §8 that was not already
there. This records what the milestone establishes as fact.

**A Save Point is a name and a coordinate.** The stored row holds the name, an
optional note, and `(branch, depth)` — the same pair §8.7 calls the head. It
holds no transcript, no state, no summary, no memory, and no branch contents.
`DATA-MODEL.md` §8 describes the pointer as naming a turn; the coordinate is
that turn's address, and `DATA-MODEL.md` §8's implementation note records why
this project uses the address rather than a row id: one coordinate can hold
several attempts at a turn, and a retry replaces the live one. "Turn 42 of this
line" survives a retry; a row id would pin a take the story no longer tells.

**Restore is head movement, and nothing else.** It resolves the coordinate,
refuses it if it no longer names a live turn, and then moves the head — the
depth through §8.7's single move operation, unchanged. The transcript, the
assembled context, the state and memory eligibility all arrive together because
they already read through the one capped lineage. There is no second restore
path, no state reconstruction, no memory pruning and no separate redo stack:
D13 is satisfied by the mechanism rather than by code written to satisfy it.

**A Save Point may name a position on a line the story has left.** Save Points
survive divergence, so this is reachable in ordinary use, and the depth half of
the head cannot reach a branch the current path does not contain. Restore
therefore moves the branch half as well when, and only when, the coordinate is
not on the path being read — the same single assignment a branch switch makes.
The distinction matters in the other direction too: a Save Point in a shared
prefix must *not* drag the reader onto the ancestor, because which continuation
follows that turn is exactly what the reader has already chosen.

**Restore never forks.** Moving the head is not a decision to abandon anything.
The first write below the restored head forks, through §8.7's existing check,
and the displaced future stays retained — so Redo still walks the original
continuation until the user writes something different, and stops offering it
once they have.

**Nothing removes a Save Point but the user.** There is no cleanup pass, and none
is wanted: a Save Point pointing behind the head, or into a line the story left,
is doing its job.

That rule is enforced against the one operation that could break it. Deleting a
branch deletes everything forked from it, so a Save Point naming a position in
that subtree would go too — silently, since the story is what the user asked to
delete. **The deletion is therefore refused while any Save Point names that
subtree**, and the refusal names them. The user deletes the Save Point
explicitly, which deletes no story, and then the branch. `STORY-BRANCH-SEMANTICS.md`
§19.1 states the rule; §28 already required a future cleanup feature to retain
paths a checkpoint references, and this is that requirement applied to the
deletion path that exists today.

## 9. Export / Import and Head Position

AI-DnD's current export carries branch information but reconstructs the imported head at the branch tip.

That is invalid after non-destructive Undo because an exported campaign can intentionally have:

```text
active head < retained tip
```

The production export format must preserve:

- active branch,
- active head turn/depth/coordinate,
- retained alternate/disposable history,
- checkpoints,
- state/history/provenance required for recovery.

For compatibility with earlier bundles, import may fall back to the retained tip only when no explicit active-head field exists.

Export/import regression tests must include an undone campaign and verify the imported story reopens at the exact exported head rather than silently redoing later turns.

### 9.1 As implemented in M3

The bundle carries the active head depth beside the active branch, and the import
honors it. This moved the head depth across the format's own rule about what a
bundle carries: a bundle carries what was *chosen* and recomputes what is
*derived*, and before M3 the head depth was genuinely derived — the newest row was
the only place a story could be read. It is a decision now, because the same tree
exports identically whether the user undid three turns or none, so the file has to
say.

A file that does not state a head is opened at the tip of its active branch. That
is a fallback only in form: such a file was written when the head could not be
anywhere else, so deriving the tip reproduces the position it actually recorded.
Pre-tree bundles take the same path. No format version bump was required, because
an absent field is unambiguous.

The head depth is validated before any row is written — a depth past the branch's
own retained story is a file disagreeing with itself and is refused, while a depth
*behind* it is the feature.

The bundle also carries which branches the story has left, and at what depth.
Every row of an abandoned line is exported either way, so without that metadata a
restored campaign could not distinguish abandoned history from active history —
which is precisely what a later cleanup or recovery feature has to select on.

### 9.2 Save Points in the bundle, as implemented in M4

Save Points are exported and imported with the campaign, which is `I04`. They
fall on the "chosen" side of §9.1's rule without argument: a position someone
named is not recoverable from the rows, since nothing about a turn records that
a player once bookmarked it.

No format version bump. A bundle written before M4 has no `checkpoints` key and
imports with none, which is what such a campaign had — the same unambiguous
absence §9.1 relies on for the head depth, and the same treatment the persona
block and the branch disposition received.

The head and the Save Points are independent, deliberately. An import opens the
campaign where `headDepth` says, never at a Save Point merely because the file
carries one: the bundle records where the story was being read and, separately,
which positions were named, and choosing between them is the user's to make
after the file is open.

A Save Point whose coordinate names no turn in the file is dropped rather than
refusing the import — the opposite of the head depth's treatment, and for a
stated reason. A misplaced head affects every read in the file; a bookmark
pointing outside the story affects only itself, and rejecting a whole campaign
to protect one bookmark would lose the story to save the pointer.

## 10. Authoritative Narrative State

### 10.1 Do not retain the RPG state protocol as the product model

AI-DnD's world-state machinery is useful evidence that state snapshots and rollback are structurally separable from RPG presentation, but the production state model must be genre-neutral.

Core concepts include:

- entities,
- facts,
- relationships,
- locations,
- possessions,
- conditions,
- organizations,
- story threads,
- scene state,
- chronology where needed.

### 10.2 Explicit typed state events

Use the ADR 010 model:

```text
model proposes explicit typed operation
        -> schema validation
        -> semantic/referential validation
        -> accepted event(s)
        -> state snapshot/cache
```

Prefer explicit absolute semantics for mutable values.

Examples:

```text
set_current_location
set_entity_status
set_possession
add_fact
invalidate_fact
add_relationship
end_relationship
open_story_thread
resolve_story_thread
set_scene
```

Avoid one generic relative-delta protocol whose numeric meaning depends primarily on prompt compliance.

### 10.3 Validation limitations

Typed events remove the delta/absolute ambiguity but do not guarantee semantic truth.

Validation should include deterministic checks where possible:

- event type allowlist,
- schema/type validation,
- entity/reference existence,
- impossible transitions where explicitly modeled,
- authority constraints,
- conflict handling,
- transaction integrity.

The accepted transcript remains available even if derived state extraction must be retried/repaired according to the final turn-acceptance workflow.

### 10.4 Hybrid storage

Selected direction:

> **validated state events + efficient current/historical snapshots/cache**

Events provide audit/reconstruction value. Snapshots/cache make normal reads, Undo/Redo, and context construction fast.

**Constraint added by M3 (see ADR 012).** The snapshot half is not an
optimization to be traded away. M3's head movement is a row lookup plus a
restore, which is why Undo, Redo and — later — Save Point restore cost the same
at any distance into a campaign's history. A state model that could only be
reconstructed by replaying events from the campaign opening would make every one
of those operations proportional to campaign length, on exactly the long
campaigns this product exists for. Whatever M5 introduces must keep the
authoritative state at a retained position efficiently recoverable — a per-node
snapshot, or an equivalent cache with the same property — while adding the typed
event model.

## 11. Context and Memory

Retain AI-DnD's useful lineage-aware memory foundation, but align it with the product authority model.

Narrator context is assembled in explicit layers:

```text
Narrator/system rules
Campaign profile
Global/explicit canon
Current authoritative state
Lineage-safe summary
Relevant older story memories
Relevant imported knowledge
Recent active-lineage turns
Current user input
```

Requirements:

- no abandoned future may appear in active recent history,
- no memory derived solely from an abandoned future may be retrieved,
- summaries are anchored to source lineage/turn ranges,
- derived memory/summary never becomes more authoritative than accepted state/canon,
- prompt snapshot records what was actually supplied,
- token budgets remain explicit and inspectable.

Phase 0B verified AI-DnD branch-scoped memory isolation against real local embeddings with a negative control. Preserve that property through the history rewrite.

## 12. Realistic-Context Model Testing

The Phase 0B referee failure appeared under full application context even though the same model followed the state protocol correctly in an isolated probe.

Therefore structured-output/state tests must include:

- realistic narrator/context length,
- representative state complexity,
- actual local models likely to be used,
- repeated runs rather than one clean prompt,
- malformed/incorrect semantic proposals,
- validation and recovery behavior.

Model capability recommendations are deferred until these measurements exist; this does not block the architecture.

## 13. Imported Knowledge Subsystem

Do not turn AI-DnD Story Cards into the production imported-knowledge store.

Story Cards may remain a useful reference or authored-rule mechanism, but the imported-knowledge requirements need a separate first-class subsystem with:

- source records,
- `.txt` / `.md` import,
- Canon / Reference / Inspiration classification,
- enable/disable/delete,
- source/version/hash provenance,
- chunk records,
- campaign scoping,
- local lexical index (prefer SQLite FTS5),
- local Ollama embeddings/semantic index where enabled,
- authority-aware hybrid retrieval,
- retrieval provenance,
- export/import support,
- no automatic URL/image fetching,
- imported content treated as data, never executable instructions.

If a future knowledge item is derived from story history rather than imported as global campaign material, it must carry lineage/source-turn information sufficient to avoid abandoned-path leakage.

### 13.1 As implemented in M7

Every item above is built, in `backend/app/knowledge/`. Story Cards were not
promoted into it and are untouched. The pipeline, and where each decision lives:

```text
upload (multipart; no pathname is ever accepted)
  -> validate      size, strict UTF-8, real text, allowed extension, class
  -> hash          SHA-256 of the normalized text; the duplicate test
  -> store         the text in SQLite, under application control
  -> chunk         deterministic, heading-aware, 60-800 tokens
  -> index         SQLite FTS5, porter-stemmed
  ---- one transaction ends here; the source is now `ready` ----
  -> embed         local Ollama, best-effort, through the shared provider
```

```text
query   built from the head-capped story tail and the authoritative state
  -> FTS5 lexical candidates      (LIMIT in SQL)
  +  semantic candidates          (when an embedding model is configured)
  -> ADMISSION, absolute and per path:
       semantic  raw cosine >= SEMANTIC_FLOOR
       lexical   >= 2 distinct meaningful terms, or 1 that is neither a
                 standing entity nor a negligible share of the query
     a passage needs evidence from at least one path, or it is discarded
  -> RANKING, among survivors only:
       normalize each score against the best surviving value of its own path
       relevance = max(lex, sem) + 0.15 x min(lex, sem)
       score     = relevance x class weight  (canon 1.00, ref 0.85, insp 0.70)
  -> suppress redundancy, never across classes, before the budget cut
  -> fill Canon, then Reference, then Inspiration, each against a cap
  -> render with class framing and per-passage provenance
```

### 13.2 Relevance admission is a separate stage from ranking

**This is M7's most expensive lesson and it generalises beyond knowledge
retrieval.** M7 shipped with only a ranking stage: both scores were normalized
against the best candidate of their own path, and the relevance floor was
expressed as a share of that best. A floor defined as a share of the best is
structurally incapable of rejecting anything, because the best candidate clears
a share of itself by construction. With the semantic path scoring every embedded
chunk there was always a best, so **something was admitted on every turn**
whatever the reader was doing — a query about tide tables and container tonnage
retrieved all five sources of a fantasy campaign, narrator-only hidden Canon
among them.

The rule that follows:

> A relevance decision must be made on a signal that means something on its own.
> Normalization answers "which of these is best"; it can never answer "is any of
> these any good". A pipeline that ranks first and cuts second has no way to
> return nothing.

So the two stages are separated, and they consume different quantities:

- **Admission** reads the *raw* signals — the cosine the model returned, and how
  many distinct meaningful query terms a passage contains. Neither is computed
  by comparison with the other candidates.
- **Ranking** reads the *normalized* signals, because `bm25` has no fixed range
  and cosine's zero is not zero, so the two paths are not otherwise comparable.
  It decides order among things that matched.

Authority is applied in the second stage only. That is what makes
`IMPORTED-KNOWLEDGE-DESIGN.md` §30's two consecutive sentences —
`Canon > Reference > Inspiration`, and "do not include irrelevant Canon merely
because it is authoritative" — compatible rather than contradictory: the class
orders what matched and can never rescue what did not.

An absolute threshold on an embedding similarity is a property of the model, not
of the product, so it is measured, written down beside the constant, and
re-measured by a real-model test on every run that has one — the same discipline
`memorybank.REDUNDANT_SIMILARITY` already follows.

### 13.3 Semantic admission is calibrated per embedding model

**Semantic admission is calibrated for `nomic-embed-text`; uncalibrated
embedding models fall back safely rather than borrowing its threshold.**

The threshold is therefore **not portable**, and the two ways a different model
can break it are not symmetric. A model whose similarity scale sits *below* the
calibrated one admits nothing and degrades to lexical-only, which is a supported
path. A model whose scale sits *above* it would put unrelated material past the
threshold and reproduce the M7-F1 defect on a build whose tests all pass.

So the product does not apply a threshold to a model it has not measured:

```text
SEMANTIC_CALIBRATION = {"nomic-embed-text": 0.58}

calibrated model      -> semantic admission at its measured floor
uncalibrated model    -> semantic retrieval skipped entirely, reason reported,
                         retrieval degrades to lexical-only
```

The model's identity is the one already stored on each vector row, so no second
mechanism was introduced, and an uncalibrated configuration reports
`semantic_enabled: false` rather than claiming a semantic index that is never
consulted. Adding a model is a measurement — run the real-model retrieval test
against it and confirm the targeted and off-topic populations separate — not a
guess. Generic cross-model calibration is out of scope for v1.

The cost is stated rather than hidden: under an uncalibrated model a
conceptual-only paraphrase is not retrieved. That is a missing passage rather
than an irrelevant one, which is the direction this product prefers to fail in.

Four decisions are worth recording, because each replaced an obvious wrong one:

- **The class multiplies relevance; it does not add to it.** An additive class
  bonus satisfies "Canon outranks Reference" and makes "do not include
  irrelevant Canon" impossible, because a large enough constant wins alone.
- **Both retrieval scores are normalized per query, against the best of their
  own path — for ranking only.** `bm25` has no fixed range; cosine's zero is not zero, and a real
  embedding model scores any two pieces of English around 0.3-0.6. Blended raw,
  a lexical hit beats every semantic hit on every query.
- **Admission does not use those normalized values at all.** A normalized score
  cannot express "no match", which was M7's blocking defect; the correction is
  the two-stage separation §13.2 records.
- **Lexical retrieval is a production path**, not a fallback. It is what finds
  proper nouns and invented terms — most of what a setting bible is made of —
  and the library is fully usable with no embedding model at all.

Abandoned-path safety is met at the query rather than by a lineage coordinate on
the source, because an imported file has no lineage: the query is built from
`context.history.tail`, which reads through the head-capped clause, and from
`adventures.narrative_state`, which head movement repoints. Nothing reads the
uncapped action table.

## 13.4 The browser is a presentation layer, and M8 kept it one

M8 rebuilt the interface without moving a decision into it. Three rules made
that hold, and each replaced a tempting shortcut:

- **Server-authoritative availability.** Whether Undo and Redo have anywhere to
  go is the server's answer, carried on every window it returns. Neither is
  derivable in the browser: Undo can reach past the top of the loaded page, and
  Redo depends on a retained future the transcript is never sent. A React
  component that computed either would be wrong exactly when it mattered.
- **Reading is not deciding.** Stepping between alternate takes tells the server
  nothing. The decision is made by writing below one, and that is the only
  moment `after_id` is sent. This is why the take pager can be offered on every
  turn without any of them becoming a commitment.
- **UI state stays UI state** (§92 of `BROWSER-UX-SPEC.md`). Which panel is
  open, whether narrator-only text is revealed, whether a source's detail is
  expanded — none of it is written anywhere, and none of it changes what is
  retrieved, what is prompted, or what the story believes.

### Failure has a taxonomy, not a toast

`frontend/src/errors.js` sorts a failure into the five kinds §71 names — model,
generation, state, knowledge, server — because each one has a different thing to
*do* about it. It reads the message the server actually sent, which is a
coupling to backend strings, so it is written as a fallback ladder rather than a
lookup: an unrecognised message still gets a kind, still shows the server's own
words, and still offers Retry. Nothing is hidden when the match misses.

### Markup is never produced from input

`frontend/src/markdown.jsx` renders narrator prose, and it is where H06 and H07
are decided for rendered text. The safety is structural rather than filtered:
every node it returns is a React element built from parsed text, the text only
ever becomes a React child, and there is no `dangerouslySetInnerHTML` in the
file. A sanitizer is not needed to make markup safe if markup is never produced.

Link schemes are checked with the URL parser rather than a pattern, because the
bypasses are all in the parsing — `java\tscript:`, `JaVaScript:` and
`%6a%61vascript:` are one URL to a browser and three strings to a regex.

The knowledge and context panels deliberately do **not** use this renderer.
They exist to show a reader exactly what is in their file, and rendering is the
opposite of that; imported text goes into a `<pre>` as a text node.

### Campaign canon is configuration, and its provenance is per turn

M8 gave `campaign_canon` an API for the first time (`canon_rules`), which raised
a question the column had never had to answer: what happens when a reader edits
the campaign's highest authority *after* a story exists?

Measured, against a real server with real turns:

- **Every turn already played keeps the canon it was actually given.** The canon
  section is part of that turn's stored context snapshot, so a historical turn
  inspected after the edit still shows the old rule and not the new one. This is
  M7's principle — provenance is the rendered text, not a foreign key — doing
  the work without being asked.
- **The next turn is told the new canon**, which is the point of editing it.
- **Nothing recorded is rewritten**: accepted story text, the narrative state
  document and the state audit log are all byte-identical across the edit.
- **The edit itself is not audited**, because canon is *configuration*. It sits
  with `ai_instructions` and the narrator prompt, none of which are audited
  either, and unlike a manual state correction it asserts nothing about the
  story — it changes what the narrator is told from that point on.

So M5's `StateEvent` log is deliberately **not** extended to cover it. That log
audits accepted changes to narrative state; canon is not narrative state, and
routing a configuration change through it would create a second representation
of canon — the same duplication `BROWSER-UX-SPEC.md` §38 forbids for hidden
information, arrived at from a different direction.

What M8 added instead is at the editing surface: once a campaign has moments,
the canon editor says that the change applies from here on, that everything
already written stays as it is, and where the per-turn record can be seen. The
guarantee is not "the edit is logged" but "the edit cannot be mistaken for a
retroactive one, and every turn can prove what it was told".

## 14. Prompt and Provenance Inspection

Preserve and extend AI-DnD's Insights/context-snapshot capability.

For each narrator turn the system should be able to explain:

- narrator/system rules used,
- campaign/canon context,
- current authoritative state included,
- summary included,
- story memories retrieved,
- knowledge chunks retrieved,
- recent history included,
- user input,
- model/settings,
- state proposal,
- validation result,
- accepted events,
- source IDs/turn ranges where applicable.

## 15. Scene and Future Media Boundary

v1 does not require media generation.

It does require preserving scene/entity information so future providers do not have to infer continuity from the entire raw transcript.

Persist or derive a scene snapshot containing relevant fields such as:

- location,
- participants,
- significant objects,
- current actions,
- time/lighting/environment,
- mood,
- visual character/location profiles,
- continuity constraints,
- source turn range and lineage.

Future media coordinator consumes a normalized scene packet and records local asset provenance.

The story engine must remain fully functional with media disabled.

STT specifically follows:

```text
microphone/audio -> local STT -> editable draft -> normal user submission
```

STT never bypasses the ordinary authoritative story commit path.

## 16. Database Direction

SQLite remains the selected v1 authoritative store.

Reasons:

- already present in the selected base,
- local and single-user friendly,
- transactional,
- portable,
- supports FTS5,
- compatible with backup/export tooling,
- no external service required.

Remove Postgres/Neon support from the production fork unless a later explicit requirement reverses this decision.

The exact physical schema may evolve through migrations; the conceptual model is in `DATA-MODEL.md`.

## 17. Transaction Boundaries

Where practical, one accepted turn should atomically establish:

- accepted user input/narration relationship,
- turn/lineage identity,
- active-head advancement,
- validated authoritative state events,
- resulting state snapshot/cache,
- core prompt/model provenance needed for recovery/audit.

Derived work such as embeddings, memory extraction, summary generation, and future media jobs may occur separately, but failure must not corrupt the authoritative commit.

## 18. Testing Strategy

Use AI-DnD's inherited tests as a foundation, then rewrite/add tests around product semantics.

Required categories:

- offline startup/story use,
- no runtime remote assets/tokenizer fetch,
- same-host and trusted-LAN Ollama endpoint handling,
- turn persistence/restart,
- failed generation atomicity,
- non-destructive Undo/Redo,
- divergence after Undo,
- retry/take retention,
- named checkpoint restore,
- branch/lineage state reconstruction,
- abandoned-history memory/summary isolation,
- active-head export/import round trip,
- generic narrative state event validation,
- realistic-context structured state extraction,
- imported knowledge authority/provenance/isolation,
- prompt/context inspection,
- fantasy + science-fiction genre neutrality,
- 100-turn/long-run acceptance,
- future-media schema compatibility.

Acceptance-test IDs in `V1-ACCEPTANCE-TESTS.md` are the black-box release contract.

### 18.1 Wiring rule, from the M2 regressions

M2 shipped two defects that a 604-test green suite did not see: a removed
`Settings` attribute left two provider factories raising `AttributeError` inside
a background task, and a newly added timeout setting was stored, validated,
exposed and rendered without ever being passed to the provider that needed it.
Both were invisible because the tests at that boundary were mocks.

> **When removing a setting, attribute or dependency, test at least one real
> consumer construction path. When adding a setting, test that the configured
> value reaches the component that uses it. A green suite built entirely around
> mocks at that boundary is insufficient evidence.**

The corollary is where to look: subtractive changes and plumbing changes fail in
background and fire-and-forget paths, which are exactly the paths that report
nothing when they break.


## 19. Removal / Migration Strategy From Upstream

Production migration should be incremental and test-gated rather than a broad rewrite.

Remove or replace in controlled milestones:

1. runtime external dependency leaks,
2. hosted/multi-user/auth/demo/analytics/cloud/Postgres/QuickJS surfaces,
3. destructive Undo/no-Redo behavior,
4. RPG-specific state/referee protocol and UI assumptions,
5. Story Card assumptions where they conflict with the new knowledge subsystem.

Preserve upstream provenance and license notices.

Do not mechanically merge the ai-adventure or Open Dungeon repositories into the fork.

## 20. Deferred Questions That Do Not Block v1 Architecture

The following are implementation/release measurements, not unresolved foundational choices:

- which narrator/state models should be recommended to users,
- exact embedding model recommendation,
- performance of multi-hour stories,
- concurrency beyond the single-user turn lock,
- which future local image/video/TTS/STT provider is selected,
- abandoned-history cleanup policy/UI after v1.

## 21. Technical Design v1.0 Exit Status

Phase 0 has resolved the foundational choices required for v1.0:

- base repository selected,
- browser/backend stack selected,
- SQLite selected,
- non-destructive history/head model demonstrated,
- typed narrative-state-event direction selected,
- Ollama validated on local infrastructure, including the required trusted-LAN deployment mode,
- memory lineage behavior validated,
- imported-knowledge architecture selected,
- local-only hardening scope identified,
- export/import active-head defect understood,
- future media boundary retained,
- production milestone sequence defined in `BUILD-MILESTONES.md`.

This technical design is therefore the implementation baseline unless revised by a later ADR.