interactive-story/planning/DECISIONS/009-ai-dnd-production-base.md

ADR 009 — AI-DnD Is the Production Base

Status: Accepted
Date: 2026-09-01

Decision

Use AI-DnD as the production fork/base, pinned initially to upstream commit:

d72f7c1bda0f34fccd84afb7a25c34eb01c901de

AI-DnD is the ownership center for the production codebase.

Other candidate projects remain implementation references only unless a later explicit decision authorizes compatible code reuse.

Context

Phase 0A favored AI-DnD because it appeared to contain the most difficult correctness infrastructure. Phase 0B then cloned, built, tested, and exercised the three finalists with local Ollama and targeted experiments.

Phase 0B corrected one major assumption: AI-DnD's shipped Undo hard-deletes history and there is no Redo. A disposable follow-up spike demonstrated that the architecture can support non-destructive head-cursor Undo/Redo with a bounded change while retaining alternate history and branch-scoped memory isolation.

AI-DnD also demonstrated:

• browser UI and FastAPI backend,
• SQLite persistence,
• story-tree/lineage machinery,
• alternate takes,
• branch switching,
• per-node state snapshots,
• local Ollama operation,
• branch-scoped memory with local embeddings,
• prompt/context inspection,
• streaming,
• export/import foundation,
• substantial automated regression coverage,
• ability to run without RPG scenario state.

Open Dungeon would require a foundational history/persistence/summary rewrite with no existing automated test foundation. ai-adventure has the strongest state/privacy core but would require building most of the browser product around it.

Alternatives Considered

• fork Open Dungeon,
• use ai-adventure as the core and build browser/API layers,
• build a new application shell,
• continue repository-selection research.

Reason

AI-DnD minimizes the amount of high-risk correctness infrastructure that must be invented while providing the browser/service/test foundation the target product needs.

The remaining work is substantial but is more bounded and testable than the alternatives.

Consequences

Retain or adapt from AI-DnD:

• React/Vite browser application,
• FastAPI service boundary,
• SQLite and migration foundation,
• story tree and lineage queries,
• alternate takes,
• state snapshot pattern,
• local Ollama integration,
• Memory Bank concepts and branch scoping,
• Insights/context snapshots,
• SSE streaming,
• export/import framework,
• relevant automated tests.

Remove or replace:

• hosted/multi-user/auth/demo functionality,
• analytics,
• Postgres/Neon/Render paths,
• cloud model providers,
• QuickJS/campaign scripting,
• AI-Dungeon compatibility not needed by the product,
• RPG-specific presentation and relative-delta state mechanics,
• runtime remote fonts/assets,
• first-use remote tokenizer dependency.

Reimplement selected patterns from references:

• ai-adventure: typed state events, validation/commit discipline, checkpoints/head movement, replay/privacy patterns,
• Open Dungeon: focused story UX and future local-media interaction ideas,
• Chronicler/IFF: authority/trust concepts,
• Gamentic: provider-neutral optional media boundary.

Non-Decision

This ADR does not authorize production coding by itself. Implementation begins only after the revised planning package is approved and a milestone-specific prompt is prepared.