Update planning package after Phase 0B
This commit is contained in:
JesseMarkowitz
@@ -4,11 +4,11 @@
|
||||
|
||||
## Decision
|
||||
|
||||
v1 will target local Ollama inference.
|
||||
v1 will target Ollama inference running on user-controlled local infrastructure. The default endpoint is same-host loopback, but v1 must also support an explicitly configured Ollama instance on a trusted local-area network.
|
||||
|
||||
## Context
|
||||
|
||||
The intended deployment already has a local Ollama inference engine. The project prioritizes local control, privacy, and predictable integration.
|
||||
The intended production deployment can eventually run the storyteller and Ollama on one machine, but development and testing may place Ollama on a separate machine on the user's LAN. The project prioritizes local control, privacy, predictable integration, and no dependency on Internet/cloud inference.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
@@ -26,4 +26,7 @@ Ollama is already available locally, provides a simple local API, supports both
|
||||
|
||||
- candidate forks supporting multiple cloud providers should be simplified or hardened,
|
||||
- candidate projects using another local API need an adapter,
|
||||
- the storyteller must support both same-host Ollama and an explicitly configured trusted-LAN Ollama endpoint,
|
||||
- LAN inference does not imply LAN exposure of the storyteller UI/API; the storyteller should still bind to loopback by default,
|
||||
- arbitrary public Internet/cloud model endpoints remain outside normal v1 configuration,
|
||||
- future backend abstraction may be added, but v1 should not be delayed to support it.
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
# ADR 004 — Local-Only Production Default
|
||||
|
||||
**Status:** Accepted
|
||||
**Status:** Accepted; Phase 0B hardening requirements identified
|
||||
|
||||
## Decision
|
||||
|
||||
The production application will be designed to operate without Internet access.
|
||||
The production application will operate without Internet access for ordinary v1 story use.
|
||||
|
||||
## Context
|
||||
|
||||
The project requires control over story data, imported material, prompts, and model outputs, with no unintended disclosure to outside services.
|
||||
The project requires control over story data, imported material, prompts, model outputs, memories, embeddings, and future generated media, with no unintended disclosure to outside services.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
@@ -18,18 +18,34 @@ The project requires control over story data, imported material, prompts, and mo
|
||||
|
||||
## Reason
|
||||
|
||||
Local-only operation best matches the privacy and control requirements.
|
||||
Local-only operation best matches the privacy and control requirements. For this project, "local-only" means operation on user-controlled local infrastructure without requiring Internet or cloud services; it does not require every component to run on the same physical machine.
|
||||
|
||||
## Phase 0B Evidence
|
||||
|
||||
The selected AI-DnD base does **not** satisfy this requirement unchanged:
|
||||
|
||||
- `tiktoken` attempted a first-use download of its encoding data,
|
||||
- the browser requested Google Fonts at runtime,
|
||||
- hosted/cloud/auth/analytics/Postgres/provider paths remain present upstream,
|
||||
- inherited endpoint guarding is oriented toward hosted deployment rather than enforcing the project's approved-local-infrastructure model boundary.
|
||||
|
||||
These are bounded production-hardening tasks rather than reasons to reject the fork.
|
||||
|
||||
## Consequences
|
||||
|
||||
The production application should avoid:
|
||||
The production application must avoid or remove:
|
||||
|
||||
- telemetry,
|
||||
- analytics,
|
||||
- cloud inference,
|
||||
- hosted authentication/accounts,
|
||||
- remote vector stores,
|
||||
- automatic web retrieval,
|
||||
- runtime CDN dependencies,
|
||||
- remote fonts/assets.
|
||||
- remote fonts/assets,
|
||||
- first-use runtime tokenizer/model-support downloads,
|
||||
- arbitrary remote model-provider configuration in normal v1 UI.
|
||||
|
||||
All inherited network behavior from a fork must be inventoried during Phase 0.
|
||||
Production packaging must contain all runtime assets required for ordinary story use after the user has installed the intended local Ollama models.
|
||||
|
||||
The storyteller application should bind to loopback by default. Ollama should default to same-host loopback but may be explicitly configured to an approved trusted-LAN endpoint for v1. This LAN inference path does not authorize LAN exposure of the storyteller UI/API. Arbitrary public/Internet inference endpoints remain prohibited in normal v1 configuration.
|
||||
|
||||
@@ -1,29 +1,44 @@
|
||||
# ADR 005 — Branch-Preserving Story History
|
||||
|
||||
**Status:** Accepted in principle; implementation pending Phase 0
|
||||
**Status:** Accepted; implementation direction validated in Phase 0B
|
||||
|
||||
## Decision
|
||||
|
||||
Returning to an earlier story point should preserve abandoned future history as another branch rather than destructively erasing it.
|
||||
Returning to an earlier story point preserves abandoned future history rather than destructively erasing it.
|
||||
|
||||
The selected implementation model uses a **movable active head over retained lineage**:
|
||||
|
||||
- Undo moves the head backward,
|
||||
- Redo moves it forward along the retained continuation,
|
||||
- accepted turns are not deleted by ordinary Undo,
|
||||
- a new write after moving backward creates a new continuation on first divergent write,
|
||||
- the displaced future remains retained/disposable,
|
||||
- normal UI presents Undo/Redo/Retry/Save Point rather than branch-management concepts.
|
||||
|
||||
## Context
|
||||
|
||||
The user must be able to recover from unwanted story developments and explore alternatives while retaining prior work.
|
||||
|
||||
Phase 0B found that AI-DnD's shipped Undo was destructive even though its tree/take infrastructure was otherwise strong. A disposable spike demonstrated non-destructive head-cursor Undo/Redo using existing lineage chokepoints and branch creation while preserving branch-scoped memory isolation.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- destructive undo,
|
||||
- overwrite-in-place editing,
|
||||
- complete copy of campaigns for every retry,
|
||||
- branch-preserving turn graph.
|
||||
- branch-preserving turn graph with movable active head.
|
||||
|
||||
## Reason
|
||||
|
||||
A branch-preserving history provides recovery, experimentation, and auditability without unnecessary campaign duplication.
|
||||
The selected model provides recovery, experimentation, auditability, and Redo without unnecessary campaign duplication or a complicated user-facing branch workflow.
|
||||
|
||||
## Consequences
|
||||
|
||||
- turn identity/parentage must be first-class,
|
||||
- state restore must be branch-aware,
|
||||
- retry/edit semantics must be explicitly defined,
|
||||
- the selected candidate repository must either support this or be adaptable to it.
|
||||
- turn identity/parentage remains first-class,
|
||||
- active head and retained tip are distinct concepts,
|
||||
- state restore is lineage-aware,
|
||||
- retry/edit/add-take must honor fork-if-behind-head behavior,
|
||||
- summaries/memories must respect active lineage/head,
|
||||
- named checkpoints point to durable story positions,
|
||||
- abandoned history is marked disposable but is not automatically cleaned up in v1,
|
||||
- export/import must preserve the active head coordinate as well as the retained history graph.
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
# ADR 008 — Complete Phase 0 Before Detailed Build Planning
|
||||
|
||||
**Status:** Accepted
|
||||
**Status:** Accepted and completed
|
||||
|
||||
## Decision
|
||||
|
||||
The project will complete repository research, validation, architecture selection, and critical prototypes before writing the detailed production implementation milestone plan.
|
||||
The project completed repository research, validation, architecture selection, and critical prototypes before finalizing the detailed production implementation milestone plan.
|
||||
|
||||
## Context
|
||||
|
||||
Multiple candidate open-source projects already implement overlapping parts of the desired system. The correct build sequence depends heavily on which codebase is selected.
|
||||
Multiple candidate open-source projects implemented overlapping parts of the desired system. The correct build sequence depended on which codebase survived local validation.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
@@ -18,10 +18,15 @@ Multiple candidate open-source projects already implement overlapping parts of t
|
||||
|
||||
## Reason
|
||||
|
||||
The third approach reduces speculative planning and prevents large amounts of rework.
|
||||
The bounded Phase 0 prevented false assumptions from becoming production architecture. In particular, runtime testing discovered destructive AI-DnD Undo, an offline tokenizer fetch, remote fonts, Open Dungeon's lack of tests and destructive summary/history assumptions, and the relative-delta state-protocol failure mode.
|
||||
|
||||
## Completion Record
|
||||
|
||||
Phase 0 selected AI-DnD as the production base, validated the non-destructive head-cursor approach, selected explicit typed narrative-state events, established local-only hardening requirements, and produced the production `BUILD-MILESTONES.md`.
|
||||
|
||||
## Consequences
|
||||
|
||||
- `BUILD-MILESTONES.md` remains intentionally high level during Phase 0,
|
||||
- production coding should not begin unless explicitly authorized,
|
||||
- Phase 0 ends with the final build plan.
|
||||
- the placeholder build plan has been replaced by a production milestone sequence,
|
||||
- `SPECIFICATION.md` and `TECHNICAL-DESIGN.md` are the v1.0 planning baseline,
|
||||
- production coding still requires explicit authorization and a milestone-specific prompt,
|
||||
- the current review intentionally stops before preparing that prompt.
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
# 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:
|
||||
|
||||
```text
|
||||
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.
|
||||
@@ -0,0 +1,100 @@
|
||||
# ADR 010 — Use Explicit Typed Narrative-State Events
|
||||
|
||||
**Status:** Accepted
|
||||
**Date:** 2026-09-01
|
||||
|
||||
## Decision
|
||||
|
||||
The production narrative-state engine will use an explicit, typed event/proposal vocabulary with unambiguous values, preferably absolute assignments for mutable values, rather than AI-DnD's relative-delta world-state protocol.
|
||||
|
||||
The application remains authoritative:
|
||||
|
||||
```text
|
||||
Narration/model output
|
||||
|
|
||||
v
|
||||
Typed state proposal
|
||||
|
|
||||
v
|
||||
Schema + semantic validation
|
||||
|
|
||||
v
|
||||
Accepted state events
|
||||
|
|
||||
+--> state snapshot/cache
|
||||
+--> provenance/audit record
|
||||
```
|
||||
|
||||
## Context
|
||||
|
||||
Phase 0B exercised AI-DnD's existing world-state referee against local models under realistic application context.
|
||||
|
||||
The protocol requested relative deltas, but the model sometimes emitted absolute values. An emitted value could be syntactically legal as a delta while semantically representing the wrong operation. The referee could therefore accept a valid-looking proposal that caused authoritative state to diverge from the narration.
|
||||
|
||||
The failure class is architectural: validation cannot reliably distinguish a legitimate large delta from an absolute value mistakenly expressed in a delta field.
|
||||
|
||||
ai-adventure uses a more explicit typed-event approach in which the requested operation and value semantics are directly represented.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- retain AI-DnD's relative-delta protocol,
|
||||
- infer whether a number is absolute or relative,
|
||||
- rely on a larger model to follow delta instructions,
|
||||
- use explicit typed events with clear value semantics.
|
||||
|
||||
## Reason
|
||||
|
||||
Explicit event semantics remove the relative-versus-absolute ambiguity and make proposals easier to validate, test, audit, and replay.
|
||||
|
||||
This does **not** make model proposals infallible. A model can still propose an incorrect absolute value or incorrect event. The application must still perform:
|
||||
|
||||
- schema validation,
|
||||
- allowlisted event-type validation,
|
||||
- referential-integrity checks,
|
||||
- domain/consistency checks where deterministic rules exist,
|
||||
- provenance recording,
|
||||
- safe failure/repair behavior.
|
||||
|
||||
## Event Style
|
||||
|
||||
Illustrative event forms:
|
||||
|
||||
```yaml
|
||||
- type: set_entity_status
|
||||
entity_id: mara
|
||||
value: injured
|
||||
|
||||
- type: set_current_location
|
||||
entity_id: aldric
|
||||
location_id: tavern-cellar
|
||||
|
||||
- type: set_possession
|
||||
item_id: silver-key
|
||||
owner_id: aldric
|
||||
|
||||
- type: add_fact
|
||||
subject_id: mara
|
||||
predicate: knows
|
||||
object_id: silver-key-origin
|
||||
authority: accepted_story
|
||||
|
||||
- type: open_story_thread
|
||||
thread_id: investigate-cellar-door
|
||||
```
|
||||
|
||||
For numeric or bounded values introduced by optional future modules, prefer explicit operations such as:
|
||||
|
||||
```text
|
||||
set_value
|
||||
increment_value
|
||||
```
|
||||
|
||||
rather than one ambiguous numeric field whose interpretation depends on prompt instructions.
|
||||
|
||||
## Consequences
|
||||
|
||||
- AI-DnD's existing RPG state/referee implementation is a source to replace/generalize, not preserve as the production narrative-state protocol.
|
||||
- Narrative state should remain genre-neutral: entities, facts, relationships, locations, conditions, possessions, threads, scenes, and similar generic concepts.
|
||||
- Accepted events and resulting state must be committed atomically with the accepted story turn where practical.
|
||||
- State snapshots/cache should make normal reads and restore fast; event history preserves audit/reconstruction value.
|
||||
- Tests must exercise state extraction at realistic context length against realistic local models, not only isolated prompts.
|
||||
Reference in New Issue
Block a user