Jesse.Markowitz/interactive-story
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update planning package after Phase 0B

Browse Source
This commit is contained in:
JesseMarkowitz
2026-09-01 20:41:23 -04:00
parent ba737de9b4
commit 717670afe0
34 changed files with 2061 additions and 1204 deletions
Download Patch File Download Diff File Expand all files Collapse all files
planning/DATA-MODEL.md
+61 -42
View File
@@ -1,11 +1,11 @@
# Adventure Storyteller — Data Model
**Status:** Draft v0.1
**Status:** v1.0 conceptual model aligned to Phase 0B decisions
**Purpose:** Define the persistent information the application must represent, independent of the final fork or database implementation.
## 1. Design Goals
The data model must support persistent interactive stories, complete authoritative history, non-destructive branching, checkpoints and rollback, genre-independent narrative state, long-term memory, imported local knowledge, prompt/context provenance, future image/video generation, export/restore, and local-only operation.
The data model must support persistent interactive stories, complete authoritative history, non-destructive branching, checkpoints and rollback, genre-independent narrative state, long-term memory, imported local knowledge, prompt/context provenance, future image/video/audio/TTS/STT generation, export/restore, and local-only operation.
The same core schema should work for fantasy, science fiction, mystery, horror, historical fiction, westerns, and other narrative genres.
@@ -62,6 +62,7 @@ campaign:
created_at: timestamp
updated_at: timestamp
active_branch_id: uuid
active_head_turn_id: optional uuid
status: active | archived
story_profile:
@@ -95,14 +96,18 @@ branch:
created_at: timestamp
created_from_branch_id: optional uuid
fork_turn_id: optional uuid
head_turn_id: optional uuid
tip_turn_id: optional uuid
disposition: active | retained | disposable
status: active | archived
```
Rules:
- branches may share ancestral turns,
- shared history should not be duplicated unnecessarily,
- creating a branch must not modify the source branch.
- creating a branch must not modify the source branch,
- the campaign active head may sit behind the retained branch tip after Undo,
- Redo moves the active head forward while the prior continuation remains selected,
- a new write below the retained tip creates a new continuation and leaves the old future retained/disposable.
Detailed behavior will be defined separately in `STORY-BRANCH-SEMANTICS.md`.
@@ -162,7 +167,7 @@ take:
selected: boolean
```
Whether `Take` becomes a separate table or sibling turn nodes will be decided after Phase 0B.
Physical representation remains implementation-specific. The selected AI-DnD base already models alternate takes within its lineage machinery; production should retain that approach if it satisfies the required Retry/select/retention semantics without forcing a separate table.
## 8. Checkpoint
@@ -176,7 +181,7 @@ checkpoint:
created_at: timestamp
```
A checkpoint is a named pointer to a recoverable story position. It should normally remain tied to the turn where it was created.
A checkpoint is a named pointer to a recoverable story position. It should normally remain tied to the turn where it was created. Restoring it moves the campaign active head; it does not delete later retained history. A new branch is created on the first divergent write after restore, not merely because the checkpoint was opened.
## 9. Narrative Entity
@@ -386,7 +391,7 @@ Excellent auditability, but requires replay.
### C. Hybrid
Validated events plus periodic/current snapshots.
**Current preference: Hybrid**, pending Phase 0B.
**Selected for v1: Hybrid.** Store validated authoritative events plus efficient state snapshots/cache for normal reads and restore.
## 18. State Change Event
@@ -404,18 +409,21 @@ state_event:
Potential event types:
- entity_created,
- entity_updated,
- set_entity_status,
- set_entity_attribute,
- fact_added,
- fact_invalidated,
- relationship_added,
- relationship_ended,
- thread_opened,
- thread_resolved,
- location_changed,
- possession_changed,
- scene_changed.
- current_location_set,
- possession_set,
- scene_set.
Events must be validated before commit.
Event semantics must be explicit and typed. Prefer unambiguous absolute assignments for mutable values. If incremental operations are ever needed, encode the operation explicitly (for example `increment_value`) rather than relying on one numeric field whose interpretation is implicit.
Events must be schema-validated, semantically checked where deterministic rules exist, and accepted by the application before commit.
## 19. State Proposal
@@ -431,7 +439,7 @@ state_proposal:
validation_status: accepted | partially_accepted | rejected | repair_required
```
The model must never write directly to authoritative state tables.
The model must never write directly to authoritative state tables. The production protocol must not depend on AI-DnD-style ambiguous relative deltas; see ADR 010.
## 20. Scene Snapshot
@@ -598,7 +606,7 @@ media_job:
scene_id: optional uuid
source_turn_start_id: optional uuid
source_turn_end_id: optional uuid
type: image | video | audio
type: image | video | audio | tts | stt
provider: string
model: string
status: queued | running | completed | failed
@@ -615,7 +623,7 @@ media_asset:
campaign_id: uuid
media_job_id: optional uuid
scene_id: optional uuid
type: image | video | audio
type: image | video | audio | tts | stt
file_path: string
metadata: object
created_at: timestamp
@@ -645,7 +653,7 @@ A campaign export should be capable of preserving:
- media metadata,
- media files if selected.
Exact format remains open. A ZIP containing a database plus manifest is a strong candidate.
The physical container format remains an implementation choice, but the export must preserve the exact active branch **and active head position**, even when the head is behind a retained tip after Undo. A ZIP containing a database plus manifest remains a strong candidate.
## 30. Deletion vs Archival
@@ -692,54 +700,65 @@ Potential provenance:
- imported inspiration,
- derived inference.
## 33. Open Questions for Phase 0B
## 33. Phase 0B Decisions Applied
1. Does AI-DnD already model alternate takes separately from branch nodes in a reusable way?
2. Can its state snapshots hold generic narrative JSON without major redesign?
3. Is its branch lineage compatible with immutable turns?
4. Should checkpoints be branch-independent pointers to turns?
5. Should memories be physically branch-scoped or lineage-filtered at query time?
6. Should knowledge sources be reusable across campaigns in v1?
7. Should media tables physically exist in v1 or only interfaces/types?
8. How should manual edits to canon/state be versioned?
9. Which state needs full historical reconstruction versus only current-state storage?
10. Can ai-adventure's event/replay discipline be adopted without overcomplicating AI-DnD?
Phase 0B resolved the foundational data-model questions:
- AI-DnD story lineage/alternate-take machinery is the production starting point.
- The active head is distinct from retained tip history.
- Undo/Redo use head movement; destructive deletion is not part of ordinary history operations.
- Named checkpoints are durable pointers to recoverable head positions.
- State uses a hybrid event + snapshot/cache model.
- State proposals use explicit typed operations with unambiguous value semantics.
- Memories/summaries must be lineage-filtered or lineage-anchored.
- Imported knowledge requires separate source/chunk/index tables rather than overloading Story Cards.
- Scene/media records remain optional derived extensions and must carry source lineage.
- Export/import must preserve active head position as well as the retained history graph.
## 34. Acceptance Criteria
The final v1 data model must support all of these without destructive hacks:
- close/restart/resume exact story,
- Undo/Redo without deleting accepted turns,
- active head behind retained tip,
- branch from an earlier turn while retaining the original future,
- mark abandoned futures/takes retained/disposable,
- create and restore named checkpoints,
- know current characters/locations/relationships/story threads,
- reconstruct earlier authoritative state,
- validate typed state proposals before committing events,
- retrieve old events outside the active context window,
- identify which imported passages informed a turn,
- reconstruct what was sent to Ollama,
- export/import an undone campaign without silently redoing it,
- run fantasy and science-fiction campaigns without schema changes,
- attach future image/video assets to scenes or turn ranges.
- attach future image/video/audio/TTS/STT metadata to scenes or turn ranges without making media authoritative.
## 35. Current Recommendation
The target conceptual model should be:
## 35. Selected Conceptual Model
```text
Immutable Turn Graph
Retained Turn/Take Lineage
|
+--> validated state events
+--> Active branch + movable active head
|
+--> state snapshot/cache
+--> Validated typed state events
| |
| +--> state snapshot/cache
|
+--> lineage-safe summaries/memories
|
+--> prompt/retrieval provenance
|
+--> scene snapshot
|
+--> prompt/retrieval provenance
+--> future optional media records
Separate campaign knowledge subsystem
+--> sources
+--> chunks
+--> FTS/local embeddings
+--> authority/provenance
```
This combines the strongest observed concepts from:
- AI-DnD's story tree and snapshots,
- ai-adventure's append-only event/replay discipline,
- Open Dungeon's simple story UX and visual continuity.
The physical implementation remains provisional until Phase 0B validates the preferred production base.
This combines AI-DnD's retained story lineage and snapshot infrastructure with ai-adventure-style explicit event/commit discipline while preserving the project's own specification as the authority.