worldbox-observer-mod/docs/narrative-coherence-and-persistence-plan.md

# Narrative coherence and durable Legacy plan

## Status

**Implemented — phases 0–8 complete (2026-07-23).**

Release evidence: clean NML restart; 20/20 full regression scenarios; semantic presentation
coverage at `intake=1/0`, `compat=0`, `redundant=0`; 10/10 canonical event-family idempotency
matrix; persistence round-trip and corrupt/newer-schema recovery; Legacy lineage/combat
consolidation; episode grammar and ensemble balance; relationship live suite 3/3; seeded and
20-second natural story soaks. The persistence format and real save-complete/load-complete hooks
are integrated; automated verification intentionally uses isolated DTO round-trips rather than
overwriting a player's WorldBox save.

This is the successor to
[`mc-story-director-rewrite-plan.md`](mc-story-director-rewrite-plan.md). The story-first
director and current Saga UI are the foundation; this plan does not reopen that cutover or redesign
the HUD.

The work is complete only when:

- every selected orange reason is rendered once from semantic evidence;
- each observed game event enters narrative state through one idempotent writer;
- captions, threads, Cast, and Legacy refer to the same event identity;
- durable MC stories survive a real save/reload cycle;
- episodes communicate a deliberate development rather than only selecting the highest related
  score; and
- the old label-concatenation, duplicate-routing, and raw-fact Legacy fallbacks are removed.

## Product outcome

IdleSpectator should feel like an automatically edited chronicle of a small ensemble.

For every authored cut, the player should be able to understand:

1. **Who is this about?**
2. **What changed?**
3. **Who or what was involved?**
4. **Why is this development part of the current story?**
5. **What lasting consequence belongs in this life’s Legacy?**

The same confirmed observation must answer all five questions. Camera captions and Legacy may use
different tense and detail, but they must not invent separate versions of the event.

## Problems this plan resolves

### Multiple prose owners

An `InterestCandidate.Label` may already say `Gains a child, Omyahel`, after which
`CaptionComposer.EnrichBeat` asks `SagaProse.BeatClause` to add `their child`. Both pieces are
individually reasonable, but together they repeat the same relationship.

The structured `NarrativeProse` path avoids this for a small set of event ids. Most event families
still depend on authored labels, feed-local string construction, or generic relationship suffixes.

### Multiple fact writers

Several Harmony patches call both `LifeSagaMemory.Record...` and
`NarrativeDevelopmentRouter...`, while the memory helper also calls the router. Store idempotency
limits visible damage, but ownership is ambiguous and the system attempts to emit the same semantic
change more than once.

### Session-only stories

`LifeSagaSession.ResetForWorldChange` currently clears Saga memory and the narrative store after a
map load. This is safe, but it makes “Legacy” a session summary rather than a durable world history.

### Related-shot selection is not yet episode composition

`StoryScheduler` owns story-first selection and tracks episode purpose, but
`EpisodeShotSelector` still chooses mainly through one editorial score. It does not yet require the
episode to cover distinct editorial roles such as establishment, change, pressure, and consequence.

### Legacy has overlapping sources

Legacy currently combines narrative chapters, selected `LifeSagaFact` records, special combat
summaries, and presentation-layer suppression rules. It works, but its correctness depends on
several layers agreeing about duplicates.

## Non-goals

- No new tabs, dossier layout, or rail redesign.
- No return to event-first camera ownership.
- No invented emotions, motives, causal claims, victories, heirs, or rivalries.
- No forced establishing shots when presentable footage does not exist.
- No persistence of live `Actor` references, camera position, current combat phase, or active
  episode timing.
- No permanent compatibility setting for the old prose or old narrative writer.
- No attempt to turn every ambient activity into a durable life event.

## Target architecture

```text
Confirmed game observation
        |
        v
NarrativeEventRecorder  -- stable id + idempotency + provenance
        |
        +--> immutable NarrativeEventRecord (one world fact)
        |
        +--> character-perspective NarrativeDevelopment projections
        |       +--> threads / consequences / story potential
        |       +--> durable per-life indexes
        |
        +--> NarrativeEventReceipt
                +--> InterestCandidate semantic presentation + exact development id

InterestCandidate --> StoryScheduler --> camera cut
                                      --> NarrativeRenderer --> orange Beat / Context

NarrativeEventRecord + threads + consequences
                                      --> LegacyChapterBuilder --> Legacy

Durable records / identities / threads / preferences
                                      <--> versioned world narrative save
```

### One observation, multiple perspectives

A world event is recorded once. It may produce more than one character-perspective development.

Example: a birth creates one `NarrativeEventRecord`, then:

- the parent projection can render `Welcomes first child Omyahel`;
- the child projection can render `Is born to Joon`; and
- a partner projection may be created only when a confirmed parent/partner relationship supports it.

These projections share the same event id. They are not mirrored copies pretending to be separate
world events.

## Core contracts

### 1. One fact, one writer

Every confirmed narrative observation enters through `NarrativeEventRecorder.Record`. Callers do
not separately write Saga memory, narrative developments, consequences, or thread state.

### 2. One selected event, one presentation model

Every selected candidate carries an exact semantic presentation reference. Caption composition
must not search for “the latest similar event” and must not infer the related actor from prose.

### 3. One semantic fact, one phrase

The orange Beat is rendered as a complete sentence by one renderer. Relationship information is
included only when it contributes a fact not already expressed by the action.

### 4. Context adds information

Context may name confirmed pressure, an unresolved question, or a consequence. It must not
paraphrase the Beat, repeat Identity, or expose scheduler terminology.

### 5. Runtime and durable time are different

- World date/tick orders persistent facts and supplies display dates.
- Session monotonic time controls cooldowns, holds, momentum decay, and active episode timing.
- Session timestamps are never serialized as durable chronology.

### 6. Persistence is fail-safe

Missing, corrupt, or newer-version narrative data must not prevent a world from loading. The mod
logs the problem, preserves the unreadable file when possible, starts an empty narrative state, and
continues operating.

### 7. Episode grammar never fabricates footage

The scheduler may wait, hand off, or close an episode when a needed role has no presentable
candidate. It may not manufacture a development just to complete a planned sequence.

## Proposed data model

### `NarrativeEventRecord`

Immutable world observation:

- schema version;
- stable event id;
- semantic event kind;
- subject, other, and participant identity snapshots;
- relationship/evidence roles rather than player-facing relation text;
- correlation, family, city, kingdom, war, and plot keys;
- previous state, new state, and confirmed outcome;
- world tick/date;
- evidence source and confidence;
- magnitude and presentability;
- ingestion provenance and dedupe key.

### `NarrativeDevelopment`

Character-perspective projection:

- event id;
- perspective character id;
- development kind and narrative function;
- other character/participants in that perspective;
- thread id when assigned;
- confirmed change/outcome;
- session-observed time for runtime scheduling;
- world tick/date for durable ordering.

Existing `NarrativeDevelopment` fields should be migrated rather than duplicated where possible.
`SubjectId` becomes the perspective owner explicitly instead of relying on an implied viewpoint.

### `NarrativePresentationModel`

Player-facing semantic input, containing no final English:

- event/development id;
- presentation kind and tense;
- perspective id;
- primary and secondary identity snapshots;
- evidence-backed relationship role;
- ordinal/count when confirmed;
- change and outcome tokens;
- ensemble side snapshots when applicable;
- confidence and provenance.

The model is attached to or referenced by `InterestCandidate`. Dynamic ensemble cards may retain a
typed ensemble presentation rather than becoming durable character developments.

### `NarrativeEventReceipt`

Returned by the recorder:

- whether this was a new event or a duplicate observation;
- stable event id;
- development ids by perspective;
- semantic presentation model for the emitting candidate;
- any rejection or confidence reason.

### Persistence DTOs

Use separate plain DTOs rather than serializing runtime dictionaries or Unity/game objects.

Persist:

- durable event records within retention limits;
- identity snapshots;
- character story indexes;
- open/resolved threads and consequences;
- authored Legacy chapter state if it cannot be deterministically rebuilt;
- Saga Prefer choices;
- schema version, stable world key, and last durable world tick.

Rebuild after load:

- dictionaries and reverse indexes;
- effective story potential and runtime decay anchors;
- live actor bindings;
- current Saga ranking;
- captions, active episode, cooldowns, and camera state.

## Implementation phases

| Phase | Primary outcome | Risk |
|---|---|---|
| 0 | Measurable baseline and explainable cuts | Low |
| 1 | Relationship/lineage captions rendered once | Medium |
| 2 | One canonical, idempotent narrative writer | High |
| 3 | Complete typed orange-reason coverage | High |
| 4 | One semantic Legacy chapter pipeline | Medium |
| 5 | Save/reload durability and recovery | Very high |
| 6 | Deliberate episode grammar | High |
| 7 | Long-horizon ensemble balance | Medium |
| 8 | Old-path deletion and release proof | Medium |

The order is intentional. The visible caption defect is fixed first, canonical ingestion then
removes its root ownership ambiguity, and persistence begins only after the in-memory facts and
chapters have one stable shape. Scheduler behavior changes after persistence so camera tuning
cannot hide state migration defects.

## Phase 0 — Baseline, inventory, and observability

### Work

1. Capture the current full regression result and a natural story-first soak as the comparison
   baseline.
2. Add a machine-readable inventory of candidate families and current prose provenance:
   structured narrative, `EventReason`, feed-authored label, ensemble renderer, or compatibility
   fallback.
3. Add selection telemetry for:
   - candidate key and asset id;
   - event/development id, when present;
   - prose path;
   - perspective and related ids;
   - thread and episode purpose;
   - whether Beat, Context, or relation semantics overlap.
4. Add a deterministic reproduction of:
   `Gains a child, Omyahel · their child`.
5. Add a harness snapshot that explains one selected cut from observation through rendered caption.

### New harness targets

- `narrative_prose_redundancy`
- `narrative_cut_explain`
- `narrative_prose_coverage`

### Exit gate

- Existing regression remains green.
- The child redundancy test fails for the expected semantic reason before the fix.
- Every naturally selected authored cut reports its prose provenance.

## Phase 1 — Semantic presentation foundation and relationship cutover

This phase fixes the reported orange-reason problem first while establishing the model used by the
remaining migrations.

### Work

1. Add `NarrativePresentationModel`, explicit viewpoint, and a renderer that owns the complete Beat.
2. Stamp an exact event/development reference onto `InterestCandidate`; stop using
   `NarrativeStoryStore.LatestFor(..., 8f)` when an exact id exists.
3. Implement semantic rendering for:
   - lover formed/broken;
   - friend formed;
   - parent/child and birth;
   - death and grief with confirmed relationship;
   - gifts or relationship interactions that name both actors.
4. Encode relationship roles as data. Do not derive them from already-rendered text.
5. Add semantic novelty checks:
   - a relation descriptor is omitted when the action already states it;
   - ordinal detail such as `first child` is allowed because it adds information;
   - names appear once within a Beat;
   - Context cannot repeat the Beat’s event, relationship, role, or outcome tags.
6. Structured Beats bypass `CaptionComposer.EnrichBeat`.
7. Keep the legacy label path only for unmigrated event families during this phase.

### Required prose matrix

Test each applicable event with:

- named and unnamed related actor;
- living and dead related actor;
- MC as subject and MC as related actor;
- parent and child viewpoints;
- first, second, and 3+ child;
- current and former lover;
- best friend and ordinary friend;
- missing/stale actor binding with a valid identity snapshot;
- status-banner ownership;
- re-entry caption;
- Beat plus thread Context.

### Exit gate

- No relationship or lineage Beat repeats its action, relationship, or related name.
- All relationship candidates bind to the exact development they display.
- No viewpoint reversal in the deterministic matrix.
- Existing caption, relationship, Legacy, and presentability scenarios pass.

## Phase 2 — Canonical event ingestion and single-writer cutover

### Work

1. Introduce `NarrativeEventRecorder` and `NarrativeEventReceipt`.
2. Define stable dedupe keys from semantic identity and durable world chronology. Use a
   source-instance/correlation token when the game exposes one; otherwise use a bounded
   family-specific dedupe window so two legitimate same-kind events are not collapsed. Do not use
   final prose or session-only `Time.unscaledTime` as persistent identity.
3. Make the recorder transaction:
   - validate evidence;
   - record or identify the event;
   - create perspective developments;
   - apply thread rules;
   - create consequences;
   - update per-life indexes;
   - return candidate presentation metadata.
4. Convert `LifeSagaMemory` into a read/index/projection facade. Its public `Record...` helpers
   either delegate once to the recorder during migration or are removed.
5. Remove direct `NarrativeDevelopmentRouter...` calls from patches that already record the same
   observation.
6. Migrate ingestion by family:

| Order | Family | Representative sources |
|---|---|---|
| 1 | Relationship and lineage | `ActorChroniclePatches`, `RelationshipEventPatches`, relationship feed |
| 2 | Death, kill, rivalry, combat outcome | actor patches, combat/story hooks |
| 3 | Role, founding, home gain/loss | roster deltas, city/kingdom hooks |
| 4 | War and plot | war/plot feeds and lifecycle patches |
| 5 | Transformation and recovery | status/happiness routers |
| 6 | World-context events | disasters, eras, discoveries, civic changes |

7. Preserve observation-before-confirmation rules: a behavior return value alone is not semantic
   success.
8. Add bounded duplicate-observation telemetry by event family and provenance.

### New harness targets

- `narrative_ingestion_idempotent`
- `narrative_ingestion_perspectives`
- `narrative_hook_single_writer`
- `narrative_event_candidate_alignment`

### Exit gate

- One game observation produces one event record regardless of how many patched surfaces observe it.
- Expected character projections are created once.
- No production patch calls both memory recording and the development router.
- Candidate, caption, consequence, and thread all report the same event id.
- Story potential and Legacy counts do not inflate under duplicate hook invocation.

## Phase 3 — Complete semantic orange-reason migration

### Work

Migrate all remaining selected candidate families to typed presentation:

| Family | Rendering rule |
|---|---|
| Role and succession | Describe the confirmed role transition; do not repeat Identity |
| Founding and home | Name the confirmed home/settlement when known |
| Combat and rivalry | Separate live action, decisive outcome, and earned rivalry |
| War and plot | Use confirmed sides/phase/outcome; avoid invented victory or betrayal |
| Disaster and loss | State the observed impact, not an assumed emotion or cause |
| Status and transformation | Distinguish application, ongoing condition, recovery, and completion |
| Family/war/plot/combat ensembles | Keep typed side/count presentation owned by the ensemble renderer |
| Milestones and discoveries | State the concrete first/change |
| Ambient texture | Use concise authored semantic templates; do not create durable consequences |
| Meta/world context | Preserve useful world-scale subjects without pretending they are MC developments |

Additional work:

1. Make `EventReason` a compatibility facade over typed rendering where it remains useful; prevent
   feeds from constructing selected prose ad hoc.
2. Replace string-based verb/relation classification with presentation enums/tags.
3. Remove generic `SagaProse.BeatClause` concatenation from caption composition. Relation evidence
   remains useful as semantic input to the renderer.
4. Add a safe unknown-event presentation that never appends inferred relationship prose.
5. Audit capitalization, punctuation, tense, names, raw ids, placeholder tokens, and missing actor
   behavior across the entire catalog.
6. Track structured coverage at registry intake and at actual selection.

### Exit gate

- 100% of selected authored candidates use a typed renderer or a typed ensemble renderer.
- No selected candidate uses a feed-local final sentence.
- No raw asset id, enum name, placeholder, or duplicated semantic tag reaches the HUD.
- The generic label-plus-relation-suffix path is deleted.
- Catalog prose audit and full presentability suite pass.

## Phase 4 — Unified Legacy chapter authoring

### Work

1. Introduce `LegacyChapterBuilder` as the only Legacy author.
2. Build chapters from semantic events, consequences, and resolved/meaningfully changed threads.
3. Replace presentation-time competition between:
   - narrative chapters;
   - raw `LifeSagaFact` lines;
   - roster-stamped prose chapters; and
   - special combat prose.
4. Keep thread-specific merge policy:
   - partnership formation and loss remain distinct identity changes;
   - 3+ births consolidate into a lineage chapter;
   - repeated kills consolidate into one combat chapter;
   - an earned rivalry remains distinct from a kill count;
   - role gain/loss may form one reign chapter when both are known;
   - war/plot chapters prefer confirmed outcome over entry notification;
   - living Cast relationships do not echo in Legacy unless a historical transition matters.
5. Rank chapters by consequence importance, narrative completeness, recency, and diversity—not raw
   event volume.
6. Preserve more semantic chapters than the two-line panel can display; presentation chooses the
   best two without destroying history.
7. Ensure a deceased or currently unbound character’s Legacy renders entirely from snapshots.

### New harness targets

- `narrative_legacy_chapters`
- `narrative_legacy_lineage`
- `narrative_legacy_role_arc`
- `narrative_legacy_war_outcome`
- `narrative_legacy_snapshot_only`

### Exit gate

- Each displayed Legacy line traces to one chapter id and its source event/thread ids.
- Cast, current Context, and Legacy do not repeat the same unchanged fact.
- Existing combat consolidation remains correct.
- Raw-fact prose fallback is removed from production Legacy rendering.

## Phase 5 — Durable narrative persistence

### Phase 5A: integration spike

Before writing the format:

1. Identify the most reliable WorldBox/NML save-start, save-complete, and load-complete hooks.
2. Determine a stable world/save identity that survives process restart. The current runtime bind
   key contains object identity and is unsuitable for durable storage.
3. Confirm the supported mod-data location and atomic replace behavior on the target platforms.
4. Verify actor ids across a real save/reload and document cases where ids are recycled or absent.

Default implementation: a versioned sidecar in the supported mod-data location, keyed by stable
save/world identity. If the game exposes a reliable per-save mod-data container, prefer that after
the spike.

### Phase 5B: format and lifecycle

1. Add a versioned `NarrativeSaveState` DTO and explicit mapper.
2. Serialize only durable fields and world chronology.
3. Write atomically through temporary file plus replace; keep one last-known-good backup.
4. Tag each snapshot with its confirmed save generation/fingerprint and durable world tick.
5. Debounce dirty writes, but promote a snapshot to durable state only at a confirmed world-save
   boundary. A transition or clean-shutdown flush may preserve a recovery snapshot, but it must not
   silently become the history of an older game save.
6. On load, select the snapshot matching the loaded save generation. Never apply narrative events
   newer than the loaded world tick; preserve unmatched newer data as a separate recovery
   generation.
7. On load:
   - clear runtime state;
   - read and validate the matching world state;
   - rehydrate indexes;
   - rebind living actors;
   - retain missing/dead actors as snapshot-only history;
   - rebase runtime freshness from durable world time;
   - resolve or abandon threads whose evidence no longer exists;
   - rebuild roster ranking and clear the active episode.
8. Add retention limits by character/event importance and test maximum expected file size. Events
   referenced by retained threads, consequences, or Legacy chapters cannot be pruned; compact them
   into a durable semantic chapter record before their detailed event payload is removed.
9. Add schema migration support beginning with version 1. Unknown newer schemas load empty without
   overwriting the unreadable data.
10. Persist Saga Prefer by stable character/world identity. Do not persist transient rail order.

### New harness and live targets

- `narrative_persistence_roundtrip`
- `narrative_persistence_corrupt`
- `narrative_persistence_unknown_version`
- `narrative_persistence_missing_actor`
- `narrative_persistence_no_replay`
- a real save, process restart, and reload check

### Exit gate

- Relationships, births, deaths, threads, consequences, Legacy, and Prefer survive a real restart.
- Reload does not duplicate events or replay old changes as new camera developments.
- A corrupt or mismatched sidecar cannot block game load.
- Snapshot-only Legacy remains readable when an actor cannot be rebound.
- Persistence adds no recurring full-world scan and no visible save hitch.

## Phase 6 — Editorial episode grammar

### Data additions

Add:

- `EpisodeShotRole`: Establish, Development, Pressure, TurningPoint, Payoff, Consequence,
  Reintroduction, WorldContext;
- covered/pending role ledger;
- recent semantic event/action keys;
- non-progress and repeated-subject counters;
- explicit episode completion reason;
- per-thread coverage debt and last-shown world time.

### Work

1. Assign shot roles from semantic development/function and current episode state.
2. Define a minimal grammar by `EpisodePurpose`:

| Purpose | Desired communication |
|---|---|
| Establish | protagonist/cast plus the confirmed opening change |
| Develop | new pressure or state change |
| Payoff | turning point or confirmed outcome |
| Consequence | what the outcome changed for the protagonist |
| Reintroduce | identity/context plus a genuinely new development |

3. Apply eligibility constraints before scalar score:
   - the shot must advance an uncovered role or be a permitted interrupt;
   - identical semantic action/subject combinations cool down;
   - texture cannot satisfy episode progress;
   - routine combat remains within its existing budget;
   - critical world events can interrupt and the episode may later resume.
4. Use thread coverage debt to favor stories that have developed off-camera.
5. End or hand off when:
   - the information goal is met and a settle beat has elapsed;
   - no presentable development arrives before expiry;
   - the thread resolves or becomes invalid;
   - a stronger coherent episode has materially greater coverage debt.
6. Log why each selected shot satisfied the episode and which role remains uncovered.

### New harness targets

- `narrative_episode_grammar`
- `narrative_episode_no_forced_footage`
- `narrative_episode_reintroduction`
- `narrative_episode_interrupt_resume`
- `narrative_episode_coverage_debt`

### Exit gate

- Deterministic episodes cover distinct roles instead of repeating the same development class.
- Ordinary unrelated material cannot break productive continuity.
- Critical interrupts and return behavior remain correct.
- An unavailable payoff closes safely rather than starving world coverage.
- Existing combat share and maximum-run gates remain green.

## Phase 7 — Ensemble balance and long-horizon direction

### Work

1. Add bounded screen-time debt for roster MCs and active threads.
2. Count meaningful authored exposure, not seconds spent on unavoidable camera holds.
3. Prefer an under-covered MC only when they have a presentable new development.
4. Prevent prolific event generators—combatants, rulers, or frequently reproducing characters—from
   monopolizing the narrative through volume alone.
5. Reintroduce dormant MCs only after a confirmed change.
6. Preserve priority order:
   critical world event > productive episode > meaningful under-covered thread > bounded world fill.
7. Add telemetry for:
   - authored cuts per MC/thread;
   - development-family diversity;
   - repeated semantic action runs;
   - episode completion/expiry;
   - dormant reintroduction;
   - screen-time debt before and after selection.

### New harness targets

- `narrative_ensemble_balance`
- `narrative_prolific_mc_guard`
- `narrative_dormant_reintroduction`

### Exit gate

- A prolific MC cannot win repeatedly without distinct developments.
- Under-covered MCs receive attention when meaningful footage exists.
- No balancing rule forces a weak or unpresentable cut.
- Prefer and world-critical behavior remain unchanged.

## Phase 8 — Cleanup, documentation, and release hardening

### Delete or retire

- generic label-plus-relationship Beat enrichment;
- latest-similar-development caption lookup when exact ids exist;
- direct patch-level dual writes;
- router side effects hidden inside memory helpers;
- raw-fact Legacy prose fallback;
- session-time-based durable event ids;
- temporary shadow adapters, migration counters, and harness-only cutover flags.

### Documentation updates

- `README.md`
- `docs/life-saga.md`
- `docs/event-reason.md`
- `docs/event-e2e.md`
- `docs/story-planner.md`
- this plan’s status and completed checkpoints

Historical plans remain history; their ownership tables must not override the final architecture.

### Final verification sequence

1. Clean NML compile.
2. New narrative scenario group.
3. Existing relationship, caption, Saga, Legacy, scheduler, and persistence scenarios.
4. Full `./scripts/harness-run.sh regression`.
5. Three organic developed-world soaks:
   - relationship/lineage-heavy;
   - conflict/war-heavy;
   - mixed long-running world.
6. One save → quit → restart → reload continuation soak.

### Release gates

- Zero camera-health, focus/reason alignment, placeholder, or object-focus failures.
- Zero detected semantic duplication in selected Beat/Context/Legacy.
- 100% typed presentation coverage for selected authored cuts.
- Zero double-ingestion failures.
- Zero old-event replay after reload.
- Combat remains at or below the existing 35% long-sample gate.
- Routine uninterrupted combat run remains at or below three.
- Recurring MCs show multiple distinct development families, not only repeated activity.
- Episode telemetry demonstrates establishment/development/payoff or an explicit evidence-based
  expiry reason.
- Persistence corruption and unknown-version tests fail safe.

## Planned source ownership

| Concern | Final owner |
|---|---|
| Confirmed observation and idempotency | `NarrativeEventRecorder` |
| Immutable world facts | narrative event store |
| Character perspective and consequences | narrative projector/store |
| Thread state | `NarrativeThreadRules` + `NarrativeStoryStore` |
| Candidate semantic presentation | event receipt + registry intake |
| Orange Beat/Context English | `NarrativeRenderer` / consolidated `NarrativeProse` |
| Relationship evidence | `SagaProse` relation resolver, returning semantic roles |
| Episode purpose and coverage | `StoryScheduler` |
| Shot eligibility and role choice | `EpisodeShotSelector` |
| Legacy chapter construction | `LegacyChapterBuilder` |
| Durable save lifecycle | narrative persistence service |
| Cast and Legacy layout | existing Saga presentation/UI |
| Camera switching and safety | existing director/camera path |

## Likely file changes

### Add

- `IdleSpectator/Narrative/NarrativeEventModels.cs`
- `IdleSpectator/Narrative/NarrativeEventRecorder.cs`
- `IdleSpectator/Narrative/NarrativePresentation.cs`
- `IdleSpectator/Narrative/NarrativeRenderer.cs`
- `IdleSpectator/Narrative/LegacyChapterBuilder.cs`
- `IdleSpectator/Narrative/NarrativePersistence.cs`
- `IdleSpectator/Narrative/NarrativePersistenceModels.cs`
- focused partial harness files if `AgentHarness.cs` is split during implementation

### Major edits

- `InterestCandidate.cs`
- `Events/EventFeedUtil.cs`
- relationship, combat, role, war, plot, status, and world-event feeds/patches
- `NarrativeModels.cs`
- `NarrativeDevelopmentRouter.cs`
- `NarrativeStoryStore.cs`
- `NarrativeThreadRules.cs`
- `NarrativeProse.cs`
- `StoryScheduler.cs`
- `EpisodeShotSelector.cs`
- `CaptionComposer.cs`
- `SagaProse.cs`
- `LifeSagaMemory.cs`
- `LifeSagaPresentation.cs`
- `LifeSagaSession.cs`
- `AgentHarness.cs`

File names may be consolidated to match existing repository conventions. The ownership boundaries
and exit gates are the contract.

## Implementation discipline

1. Land phases in order; do not combine persistence and scheduler behavior in one cutover.
2. Keep compatibility adapters internal and temporary.
3. Every migrated event family receives deterministic tests before its old path is removed.
4. Each phase ends with a clean build and targeted regression.
5. Do not tune editorial weights to hide ingestion or prose defects.
6. Do not solve semantic duplication with substring-only suppression. String checks may be a final
   safety net, but enums, roles, event ids, and evidence tags own correctness.
7. Do not persist presentation strings when they can be regenerated from semantic state.
8. Update this plan with checkpoint evidence as each phase completes.

## Definition of done

The plan is finished when a character can:

1. enter the ensemble through a confirmed development;
2. appear in a caption whose Beat states that development once;
3. continue through a deliberate multi-beat episode;
4. accumulate a concise, non-redundant Legacy;
5. survive save, quit, restart, and reload with that history intact; and
6. return to the camera only when their story has genuinely changed.