lore-engine/docs/19-retcon-policy.md

19 — Retcon policy

Status: 📋 planned. Operationalizes the Contradiction / is_disputed machinery from docs/04-consistency.md and ADR 0002.

Goal

Worlds retcon. The engine's job is to preserve retcons (keeping the old state answerable) rather than silently overwrite. This doc is the operational contract for how that works end-to-end.

Principles

1. A retcon never deletes a fact. Old edges are marked superseded_by pointing at the new edge, not removed.
2. Both states are answerable. The LLM can answer "what was true before the retcon?" via was_true_at(entity, at_time=T, as_of=<pre-retcon date>).
3. The LLM surfaces retcons automatically. When a query crosses a retcon boundary, the response includes both the pre- and post-retcon answer with sources, and the LLM flags the transition in its reply.
4. World-builders declare retcons explicitly. No inference, no heuristic — a retcon is a codex edit, not a side effect of extraction.

Codex syntax (proposed)

A retcon is declared in the frontmatter of the superseding file:

---
title: The Refounding of House Vyr
type: event
date: 412 TA
supersedes:
  - id: founding-of-house-vyr
    as_of: 200 TA     # the in-world date of the old version
    reason: "Retcon in session 47: Aldric was the true founder, not Maric."
sources:
  - session-47-recap
  - world-builder-note-2026-05
---

The supersedes block is parsed at ingest time:

• The old edge(s) referencing founding-of-house-vyr get a superseded_by property pointing at the new event id.
• The new event gets a supersedes property (inverse).
• Both edges remain in the graph; queries can ask about either state.

Tool behavior

• was_true_at(entity, at_time, as_of=None) — as_of defaults to the latest known state. Pass a pre-retcon as_of to ask about the world as the world-builder saw it on a given date.
• lookup() — returns both the current and any superseded version, with a supersedes chain.
• lore_about() — surfaces retcon boundaries in the chunk store, with a retcon_boundary: true flag on chunks that cross one.

What the LLM does

When was_true_at returns an edge with is_disputed: true or the entity has a supersedes chain:

1. Lead with the current state.
2. Note the pre-retcon state in one sentence.
3. Cite the world-builder's reason from the retcon declaration.
4. Never pick one side silently.

Examples

• "Was Aldric the founder of House Vyr?" — current state: yes (post-412 TA retcon). Pre-412 TA state: no, Maric was. The LLM answers the current state and notes the retcon.
• "What did the chronicles say about House Vyr's founding before session 47?" — lore_about(..., as_of=session-46) returns the pre-retcon chunks, with a retcon_superseded: true flag.

Out of scope (deferred to slice 8)

• UI for retcon review (timeline view, diff view).
• Bulk retcon migrations (a campaign-wide retcon that touches 100+ edges).
• "Soft retcons" (deliberate ambiguity the world-builder wants preserved across both versions — current model treats these as full retcons; the LLM picks a side).

Cross-references

• docs/04-consistency.md — the Contradiction machinery
• docs/adr/0002-disputed-edges-stay-separate.md — why we keep both edges
• docs/plan/02-slice-consistency.md — the slice that ships this