A persistent narrative environment for AI-authored stories. This repository implements the Phase 0–5 prototype: typed world contracts, the hand-authored River Valley fixture, revision-bound SQLite context compilation, noncanonical Story Runs, a validation-gated Story Delta write boundary, and POV-safe cross-story continuity, and deterministic background time advancement.
Python 3.12 or newer and uv are required.
uv sync
uv run storyworld db init --database .storyworld/river-valley.db
uv run storyworld load-fixture river-valley --database .storyworld/river-valley.db
uv run storyworld story contract create \
--file fixtures/river_valley/contracts/story_a.json \
--database .storyworld/river-valley.db
uv run storyworld story context story_archive_discovery \
--role pov --character char_mara \
--database .storyworld/river-valley.db
uv run storyworld story run create story_archive_discovery \
--adapter deterministic \
--database .storyworld/river-valley.db
uv run storyworld story run generate story_archive_discovery \
--variants 2 \
--database .storyworld/river-valley.db
uv run storyworld story run artifacts story_archive_discovery \
--stage final \
--database .storyworld/river-valley.db
uv run storyworld story delta submit \
--file fixtures/river_valley/deltas/story_a.json \
--database .storyworld/river-valley.db
uv run storyworld story delta validate delta_archive_discovery \
--database .storyworld/river-valley.db
uv run storyworld story delta approve delta_archive_discovery \
--by editor_jamie \
--database .storyworld/river-valley.db
uv run storyworld story delta commit delta_archive_discovery \
--database .storyworld/river-valley.db
uv run storyworld story publish story_archive_discovery \
--database .storyworld/river-valley.db
uv run storyworld story contract create \
--file fixtures/river_valley/contracts/story_b.json \
--database .storyworld/river-valley.db
uv run storyworld story run create story_courier_after_discovery \
--adapter deterministic \
--database .storyworld/river-valley.db
uv run storyworld story run generate story_courier_after_discovery \
--database .storyworld/river-valley.db
uv run storyworld story sources story_courier_after_discovery \
--database .storyworld/river-valley.db
uv run storyworld setting advance setting_river_chronicle \
--to year-51/day-28T15:00 --mode scheduled \
--partition partition_river_valley \
--database .storyworld/river-valley.db
uv run storyworld setting advances setting_river_chronicle \
--database .storyworld/river-valley.db
uv run storyworld story contract create \
--file fixtures/river_valley/contracts/story_c.json \
--database .storyworld/river-valley.db
uv run storyworld story context story_mara_tovin_reunion \
--role narrator \
--database .storyworld/river-valley.db
uv run storyworld story delta inspect delta_archive_discovery \
--database .storyworld/river-valley.db
The short-story workflow makes one structured planning call, then one writing and one continuity-edit call per variant. Plans, prompts, checkpoints, invocation metadata, drafts, and finals are stored inline in SQLite. Generated artifacts always remain noncanonical.
A final artifact can affect shared canon only through a separately authored, typed Story Delta. Validation binds the immutable delta, exact artifact passages, context manifest, Discovery Plan, semantic audit, and any required approval by hash. Successful commits apply the complete change set and its provenance in one SQLite transaction. Errors block commit; warnings may pass. Repeating a successful commit is idempotent.
Publication is explicit, uses the single Phase 4 audience_default stream,
and does not change canon. Published, artifact-backed
consequences can guide later narrator context and dramatic irony, but they are
never copied into a character's POV knowledge. Cross-story prompts contain
canonical summaries and immutable source IDs, not passages from prior stories;
the story sources command resolves those IDs to exact commit, delta, artifact,
and passage evidence for reviewers.
Phase 5 advances selected canonical partitions only when explicitly invoked.
The non-AI heartbeat uses a hashed steward rule set and a deterministic
fictional-time priority queue to process schedules, deadlines, journeys,
transmissions, plans, conditions, rumors, and event reactions. One atomic
background commit advances clocks and canonical revision, consumes story
triggers exactly once, and records a source trace for every engine-authored
narrative change. Public background state is not automatically audience or
character knowledge. Context compilation remains read-only; story contract create --catch-up is the explicit demand-advance path for a future contract.
For an explicit live OpenRouter run:
set OPENROUTER_API_KEY=...
uv run storyworld story run create story_archive_discovery \
--adapter openrouter --model provider/model-slug \
--database .storyworld/river-valley.db
uv run storyworld story run generate story_archive_discovery \
--database .storyworld/river-valley.db
No live model is selected by default. OpenRouter calls are non-streaming and are never made by the automated test suite.
The same provider boundary is available for semantic artifact audits:
set OPENROUTER_API_KEY=...
uv run storyworld story delta validate delta_archive_discovery \
--analyzer openrouter --model provider/model-slug \
--database .storyworld/river-valley.db
The deterministic analyzer remains the offline default.
Run all acceptance checks with:
uv run ruff check .
uv run ruff format --check .
uv run mypy src tests
uv run storyworld schemas check
uv run pytest
Golden context payloads change only through the explicit command:
uv run python scripts/update_goldens.py
The administrative fixture loader seeds authored canon. After initialization,
StoryDeltaService and the deterministic BackgroundService share the
canonical transaction writer; generation adapters still receive no database
handle and cannot write canon directly. Branches, reservations, rebase
material generation, publication editing, multi-series audience state,
deep-time simulation, and narrative-signal detection remain later phases.