Add "Update from scenario" to pull scenario edits into a running adventure

An adventure copies its scenario's plot text and story cards at creation so
later authoring never disturbs a story in progress. This is the explicit
opt-out, alongside the existing per-script "Sync from library".

GET /adventures/{id}/refresh returns a plan (per-field old/new diff, card
add/update/remove, world-state added/removed paths, and any ${...} answers
still needed); POST applies it under the turn lock so it can't race a
generating turn. The Plot panel shows the plan in a confirm modal first.

Overwrites the plot fields and scenario-derived cards. Deliberately left
alone: the opening `start` action (the story is built on it, and it is baked
into memories and the summary), the adventure's own title and summary,
player-authored story cards, and the live value of every stat the schema
still defines.

Two enablers were needed:

- adventures.placeholders (migration 32). ${...} answers were used once at
  creation and discarded, so re-copying scenario text would have re-injected
  a literal ${Hero}. Adventures predating the column re-prompt once via the
  existing modal, then the answers are saved.

- story_cards.source_ref (migration 33), "card:<id>" / "npc:<key>", NULL for
  player-authored. Adventure cards had no link back to their source, so a
  rename read as delete-plus-add and player cards would have been clobbered.
  Legacy cards name-match once, then adopt the ref.

World state goes through a new worldstate.reconcile(): keep values the schema
still defines, add missing ones at their initial, drop removed ones and their
cooldown bookkeeping. Not instantiate(), which would heal the player to full
and wipe their milestones.

The confirm modal is portalled to <body>: .side-panel's panel-in animation
has fill mode `both`, which makes it the containing block for position:fixed
descendants, so an overlay rendered in place was trapped in the 420px panel
and clipped by its overflow.

14 new tests in backend/tests/test_scenario_refresh.py; 85 pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XzBCyXH4hBEVHqEaertcq4

backend/app/migrations.py

@@ -95,6 +95,15 @@ MIGRATIONS: list[tuple[int, str]] = [
     (30, "ALTER TABLE scenarios ADD COLUMN image TEXT NOT NULL DEFAULT ''"),
     # Emoji/glyph fallback used when `image` is empty.
     (31, "ALTER TABLE scenarios ADD COLUMN icon VARCHAR(16) NOT NULL DEFAULT ''"),
+    # The ${Placeholder} answers given when the adventure was started. Kept so
+    # "Update from scenario" can re-fill re-copied text; NULL for adventures
+    # created before this column, which re-prompt for them on first refresh.
+    (32, "ALTER TABLE adventures ADD COLUMN placeholders JSON"),
+    # Which piece of the scenario a copied story card came from ("card:<id>" or
+    # "npc:<key>"), so a refresh can update/remove exactly the scenario-derived
+    # cards and leave player-authored ones alone. NULL = player-authored, or a
+    # copy predating this column (matched by name once, then adopted).
+    (33, "ALTER TABLE story_cards ADD COLUMN source_ref VARCHAR(64)"),
 ]
 
 LATEST_VERSION = max((v for v, _ in MIGRATIONS), default=1)

backend/app/models.py

@@ -104,6 +104,10 @@ class Adventure(Base):
     # Phase 12: live RPG world state (world/player/npc stats + milestones),
     # instantiated from the scenario's stat_schema. Empty when there's no RPG layer.
     world_state: Mapped[dict] = mapped_column(JSON, default=dict)
+    # The ${Placeholder} answers collected when this adventure was started, kept
+    # so "Update from scenario" can re-fill freshly copied scenario text with the
+    # same values. NULL for adventures created before this column existed.
+    placeholders: Mapped[dict | None] = mapped_column(JSON, nullable=True)
     # Phase 6: opt-in per adventure (extra AI calls)
     auto_summarize: Mapped[bool] = mapped_column(Boolean, default=False)
     memory_bank_enabled: Mapped[bool] = mapped_column(Boolean, default=False)
@@ -181,6 +185,11 @@ class StoryCard(Base):
     keys: Mapped[str] = mapped_column(Text, default="")  # comma-separated triggers
     entry: Mapped[str] = mapped_column(Text, default="")
     notes: Mapped[str] = mapped_column(Text, default="")
+    # Adventure copies only: which piece of the scenario this card came from —
+    # "card:<scenario_card_id>" or "npc:<npc_key>". "Update from scenario"
+    # refreshes/removes exactly these; NULL means player-authored (left alone),
+    # or a copy predating the column (matched by name, then adopted).
+    source_ref: Mapped[str | None] = mapped_column(String(64), nullable=True)
 
     scenario: Mapped[Scenario | None] = relationship(back_populates="story_cards")
     adventure: Mapped[Adventure | None] = relationship(back_populates="story_cards")

backend/app/routers/adventures.py

@@ -142,6 +142,51 @@ def fill_placeholders(text: str, values: dict[str, str]) -> str:
     )
 
 
+# Adventure fields that start as a copy of the scenario's text and so can be
+# re-copied by "Update from scenario". `title` is excluded on purpose: it is the
+# adventure's own name, which players rename, and `story_summary` is play output,
+# not scenario content.
+SCENARIO_TEXT_FIELDS = ("memory", "authors_note", "ai_instructions")
+
+# Story-card fields copied from the scenario, and compared to detect drift.
+CARD_FIELDS = ("type", "name", "keys", "entry", "notes")
+
+
+def scenario_card_specs(scenario: models.Scenario, values: dict[str, str]) -> dict[str, dict]:
+    """Every story card a scenario implies, keyed by a stable `source_ref`:
+    its own cards ("card:<id>") plus one per NPC defined in its stat_schema
+    ("npc:<key>"), with placeholders already filled in.
+
+    Shared by adventure creation and refresh so the two can't drift.
+    """
+    specs: dict[str, dict] = {}
+    existing_names = {(c.name or "").strip().lower() for c in scenario.story_cards}
+    for card in scenario.story_cards:
+        specs[f"card:{card.id}"] = {
+            "type": card.type,
+            "name": card.name,
+            "keys": fill_placeholders(card.keys, values),
+            "entry": fill_placeholders(card.entry, values),
+            "notes": card.notes,
+        }
+    # Phase 12: each defined NPC gets a story card (for its description as lore +
+    # in-scene triggering), unless a card with that name already exists.
+    for npc_key, ndef in (scenario.stat_schema or {}).get("npcs", {}).items():
+        if not isinstance(ndef, dict):
+            continue
+        name = worldstate.npc_name(ndef, npc_key)
+        if name.strip().lower() in existing_names:
+            continue
+        specs[f"npc:{npc_key}"] = {
+            "type": "character",
+            "name": name,
+            "keys": fill_placeholders(str(ndef.get("keys") or name), values),
+            "entry": fill_placeholders(str(ndef.get("desc") or ""), values),
+            "notes": "",
+        }
+    return specs
+
+
 @router.post("", response_model=schemas.AdventureOut, status_code=201)
 def create_adventure(
     payload: schemas.AdventureCreate,
@@ -166,41 +211,16 @@ def create_adventure(
         ai_instructions=fill_placeholders(scenario.ai_instructions, values) if scenario else "",
         # Phase 12: seed the live RPG state from the scenario's template.
         world_state=worldstate.instantiate(scenario.stat_schema) if scenario else {},
+        # Kept so a later "Update from scenario" can re-fill re-copied text with
+        # the same answers instead of re-injecting literal ${...} tokens.
+        placeholders=dict(values),
     )
     db.add(adventure)
     db.flush()
 
     if scenario:
-        existing_names = {(c.name or "").strip().lower() for c in scenario.story_cards}
-        for card in scenario.story_cards:
-            db.add(
-                models.StoryCard(
-                    adventure_id=adventure.id,
-                    type=card.type,
-                    name=card.name,
-                    keys=fill_placeholders(card.keys, values),
-                    entry=fill_placeholders(card.entry, values),
-                    notes=card.notes,
-                )
-            )
-        # Phase 12: each defined NPC gets a story card (for its description as
-        # lore + in-scene triggering), unless a card with that name already exists.
-        for npc_key, ndef in (scenario.stat_schema or {}).get("npcs", {}).items():
-            if not isinstance(ndef, dict):
-                continue
-            name = worldstate.npc_name(ndef, npc_key)
-            if name.strip().lower() in existing_names:
-                continue
-            db.add(
-                models.StoryCard(
-                    adventure_id=adventure.id,
-                    type="character",
-                    name=name,
-                    keys=fill_placeholders(str(ndef.get("keys") or name), values),
-                    entry=fill_placeholders(str(ndef.get("desc") or ""), values),
-                    notes="",
-                )
-            )
+        for ref, spec in scenario_card_specs(scenario, values).items():
+            db.add(models.StoryCard(adventure_id=adventure.id, source_ref=ref, **spec))
         for position, script in enumerate(scenario.scripts):
             db.add(
                 models.AdventureScript(
@@ -900,6 +920,203 @@ def update_adventure_script(
     return script
 
 
+# ---------- Refresh from scenario ----------
+#
+# An adventure copies the scenario's plot text and story cards at creation so
+# later authoring never disturbs a story in progress (same reasoning as the
+# per-script "Sync from library" above). This is the explicit opt-out: pull the
+# scenario's current content back down over the copy.
+
+
+def resolve_source_scenario(
+    adventure: models.Adventure, db: Session, user: models.User
+) -> models.Scenario | None:
+    """The scenario an adventure can refresh from — the one it was started from,
+    if it still exists and is still readable (own, or a shared demo one). None
+    once the scenario is deleted (scenario_id goes NULL) or was unshared."""
+    if adventure.scenario_id is None:
+        return None
+    scenario = db.get(models.Scenario, adventure.scenario_id)
+    if scenario is None or (scenario.user_id != user.id and not scenario.is_public):
+        return None
+    return scenario
+
+
+def _placeholder_names(*texts: str) -> list[str]:
+    """Unique ${Placeholder} names across the given texts, first appearance first
+    (mirrors the frontend's extractPlaceholders)."""
+    names: list[str] = []
+    for text in texts:
+        for match in PLACEHOLDER_RE.finditer(text or ""):
+            name = match.group(1).strip()
+            if name and name not in names:
+                names.append(name)
+    return names
+
+
+def scenario_placeholder_names(scenario: models.Scenario) -> list[str]:
+    """Every placeholder the scenario's *refreshable* content asks for. The
+    opening prompt is excluded — a refresh never rewrites it."""
+    texts = [scenario.memory, scenario.authors_note, scenario.ai_instructions]
+    for card in scenario.story_cards:
+        texts += [card.keys, card.entry]
+    for ndef in (scenario.stat_schema or {}).get("npcs", {}).values():
+        if isinstance(ndef, dict):
+            texts += [str(ndef.get("keys") or ""), str(ndef.get("desc") or "")]
+    return _placeholder_names(*texts)
+
+
+def _scenario_cards(adventure: models.Adventure) -> dict[str, models.StoryCard]:
+    """The adventure's scenario-derived cards, keyed by source_ref.
+
+    Adventures created before `source_ref` existed have none, so those fall back
+    to matching the scenario's cards by name — but only when the adventure has no
+    tagged cards at all, otherwise a player-authored card that happens to share a
+    scenario card's name would be adopted and overwritten.
+    """
+    return {c.source_ref: c for c in adventure.story_cards if c.source_ref}
+
+
+def _match_legacy(
+    adventure: models.Adventure, specs: dict[str, dict]
+) -> dict[str, models.StoryCard]:
+    by_name: dict[str, models.StoryCard] = {}
+    for card in adventure.story_cards:
+        by_name.setdefault((card.name or "").strip().lower(), card)
+    matched: dict[str, models.StoryCard] = {}
+    for ref, spec in specs.items():
+        card = by_name.get((spec["name"] or "").strip().lower())
+        if card is not None:
+            matched[ref] = card
+    return matched
+
+
+def plan_refresh(
+    adventure: models.Adventure, scenario: models.Scenario, values: dict[str, str]
+) -> tuple[dict, dict, dict]:
+    """Work out what a refresh would change, without touching anything.
+
+    Returns (plan, specs, matched) — `plan` is the UI-facing summary, `specs` the
+    scenario's card specs by ref, `matched` the existing adventure card for each
+    ref that already has one.
+    """
+    fields = {
+        field: {"old": getattr(adventure, field), "new": fill_placeholders(
+            getattr(scenario, field), values)}
+        for field in SCENARIO_TEXT_FIELDS
+    }
+    changed_fields = {f: v for f, v in fields.items() if v["old"] != v["new"]}
+
+    specs = scenario_card_specs(scenario, values)
+    tagged = _scenario_cards(adventure)
+    matched = tagged or _match_legacy(adventure, specs)
+
+    added, updated = [], []
+    for ref, spec in specs.items():
+        card = matched.get(ref)
+        if card is None:
+            added.append(spec["name"])
+        elif any(getattr(card, f) != spec[f] for f in CARD_FIELDS):
+            updated.append(card.name or spec["name"])
+    # Only cards the scenario is known to have produced are removable; a
+    # player-authored card (no source_ref) is never touched.
+    removed = [c.name for ref, c in tagged.items() if ref not in specs]
+
+    _, world = worldstate.reconcile(adventure.world_state, scenario.stat_schema)
+
+    plan = {
+        "scenario_id": scenario.id,
+        "scenario_title": scenario.title,
+        "fields": changed_fields,
+        "cards": {"added": added, "updated": updated, "removed": removed},
+        "world_state": world,
+    }
+    plan["has_changes"] = bool(
+        changed_fields or added or updated or removed
+        or world["added"] or world["removed"]
+    )
+    return plan, specs, matched
+
+
+@router.get("/{adventure_id}/refresh", response_model=schemas.RefreshPlan)
+def preview_refresh(
+    adventure_id: int, db: Session = Depends(get_db), user: models.User = CurrentUser
+):
+    """What "Update from scenario" would change, for the confirm dialog."""
+    adventure = get_adventure_or_404(adventure_id, db, user)
+    scenario = resolve_source_scenario(adventure, db, user)
+    if scenario is None:
+        raise HTTPException(404, "No scenario to update from")
+    stored = adventure.placeholders if isinstance(adventure.placeholders, dict) else {}
+    plan, _, _ = plan_refresh(adventure, scenario, stored)
+    # Adventures started before placeholder answers were stored have none, and an
+    # author can add a new ${...} after the fact — either way the player is asked
+    # for the missing ones, and the answers are saved for next time.
+    plan["placeholders_needed"] = [
+        n for n in scenario_placeholder_names(scenario) if n not in stored
+    ]
+    return plan
+
+
+@router.post("/{adventure_id}/refresh", response_model=schemas.AdventureOut)
+def refresh_from_scenario(
+    adventure_id: int,
+    payload: schemas.AdventureRefresh = Body(default=schemas.AdventureRefresh()),
+    db: Session = Depends(get_db),
+    user: models.User = CurrentUser,
+):
+    """Pull the scenario's current plot text, story cards and stat schema down
+    over this adventure's copy.
+
+    Overwrites the plot fields and every scenario-derived card, adds what the
+    scenario gained and removes what it dropped. Deliberately left alone: the
+    opening `start` action (the story is built on it, and it is baked into
+    memories and the summary), the adventure's own title, its story summary, its
+    player-authored story cards, and — via `worldstate.reconcile` — the live
+    value of every stat the schema still defines.
+    """
+    adventure = get_adventure_or_404(adventure_id, db, user)
+    scenario = resolve_source_scenario(adventure, db, user)
+    if scenario is None:
+        raise HTTPException(404, "No scenario to update from")
+
+    values = {**(adventure.placeholders if isinstance(adventure.placeholders, dict) else {}),
+              **payload.placeholders}
+
+    # A refresh rewrites the same state a turn is mid-way through mutating, so it
+    # takes the turn slot rather than racing the generator.
+    acquire_turn_lock(adventure_id)
+    try:
+        _, specs, matched = plan_refresh(adventure, scenario, values)
+
+        for field in SCENARIO_TEXT_FIELDS:
+            setattr(adventure, field, fill_placeholders(getattr(scenario, field), values))
+
+        for ref, spec in specs.items():
+            card = matched.get(ref)
+            if card is None:
+                db.add(models.StoryCard(adventure_id=adventure.id, source_ref=ref, **spec))
+                continue
+            for field in CARD_FIELDS:
+                setattr(card, field, spec[field])
+            # Adopt the ref so a name-matched legacy card syncs by id next time.
+            card.source_ref = ref
+        for ref, card in _scenario_cards(adventure).items():
+            if ref not in specs:
+                db.delete(card)
+
+        adventure.world_state, _ = worldstate.reconcile(
+            adventure.world_state, scenario.stat_schema
+        )
+        adventure.placeholders = values
+        db.commit()
+    finally:
+        _active_turns.discard(adventure_id)
+
+    db.refresh(adventure)
+    return adventure
+
+
 # ---------- Insights ----------
 
 @router.get("/{adventure_id}/context")

backend/app/schemas.py

@@ -149,6 +149,31 @@ class AdventureUpdate(BaseModel):
     memory_bank_enabled: bool | None = None
 
 
+class AdventureRefresh(BaseModel):
+    """Body for "Update from scenario". `placeholders` supplies answers the
+    adventure has no stored value for (see AdventureCreate.placeholders); they
+    are merged over the stored ones and saved."""
+
+    placeholders: dict[str, str] = {}
+
+
+class RefreshPlan(BaseModel):
+    """What a refresh would change — drives the confirm dialog."""
+
+    scenario_id: int
+    scenario_title: str
+    has_changes: bool
+    # field name -> {"old": ..., "new": ...}, only for fields that differ.
+    fields: dict[str, dict] = {}
+    # {"added"|"updated"|"removed": [card name, ...]}
+    cards: dict[str, list[str]] = {}
+    # {"added"|"removed": [stat path, ...]} — live values are otherwise kept.
+    world_state: dict[str, list[str]] = {}
+    # ${Placeholder} names the scenario asks for that the adventure has no
+    # stored answer to; the client must collect these and send them back.
+    placeholders_needed: list[str] = []
+
+
 class ActionOut(ORMModel):
     id: int
     adventure_id: int

backend/app/worldstate/__init__.py

@@ -12,6 +12,7 @@ from .engine import (
     instantiate,
     npc_name,
     npc_triggers,
+    reconcile,
     render_delta_block,
     render_reference,
     render_state_section,
@@ -28,6 +29,7 @@ __all__ = [
     "instantiate",
     "npc_name",
     "npc_triggers",
+    "reconcile",
     "render_delta_block",
     "render_reference",
     "render_state_section",

backend/app/worldstate/engine.py

@@ -120,6 +120,111 @@ def instantiate(stat_schema: dict | None) -> dict:
     return ws
 
 
+def reconcile(world_state: dict | None, stat_schema: dict | None) -> tuple[dict, dict]:
+    """Bring a live world_state back in line with an edited schema.
+
+    Deliberately NOT `instantiate`: a value the schema still defines keeps
+    whatever it has reached in play (re-instantiating would heal the player to
+    full and wipe their milestones). Only the difference is applied — stats,
+    NPCs, flags and milestones the schema gained appear at their initial value,
+    and ones it no longer defines are dropped, along with their `last_changed`
+    bookkeeping. Returns (new_state, report) where the report lists paths under
+    `added` / `removed` so the UI can show what a refresh would do.
+
+    Note the additions are mostly cosmetic: rendering and delta-application both
+    fall back to a stat def's `initial` when the live state has no value for it,
+    so a newly added stat already behaves correctly. This materialises it (and,
+    unlike those read-through paths, actually cleans up removals).
+    """
+    report: dict = {"added": [], "removed": []}
+    if not has_schema(stat_schema):
+        # The scenario dropped its RPG layer entirely — so does the adventure.
+        stale = bool(world_state)
+        if stale:
+            report["removed"].append("(all world state)")
+        return {}, report
+
+    ws = copy.deepcopy(world_state) if isinstance(world_state, dict) else {}
+    if not ws:
+        return instantiate(stat_schema), report
+
+    def sync_section(container: dict, defs: dict, prefix: str) -> dict:
+        out = {}
+        for name, d in defs.items():
+            if not isinstance(d, dict):
+                continue
+            if name in container:
+                out[name] = container[name]
+            else:
+                out[name] = d.get("initial", "" if d.get("type") == "text" else 0)
+                report["added"].append(f"{prefix}.{name}")
+        for name in container:
+            if name not in out:
+                report["removed"].append(f"{prefix}.{name}")
+        return out
+
+    for section in STAT_SECTIONS:
+        ws[section] = sync_section(
+            ws.get(section) if isinstance(ws.get(section), dict) else {},
+            stat_schema.get(section) or {},
+            section,
+        )
+
+    npc_defs = stat_schema.get("npcs") or {}
+    old_npcs = ws.get("npc") if isinstance(ws.get("npc"), dict) else {}
+    new_npcs = {}
+    for key, ndef in npc_defs.items():
+        if not isinstance(ndef, dict):
+            continue
+        old = old_npcs.get(key) if isinstance(old_npcs.get(key), dict) else {}
+        new_npcs[key] = sync_section(old, ndef.get("stats") or {}, f"npc.{key}")
+    for key in old_npcs:
+        if key not in new_npcs:
+            report["removed"].append(f"npc.{key}")
+    ws["npc"] = new_npcs
+
+    flag_defs = stat_schema.get("flags") or {}
+    old_flags = ws.get("flags") if isinstance(ws.get("flags"), dict) else {}
+    new_flags = {}
+    for name, d in flag_defs.items():
+        if not isinstance(d, dict):
+            continue
+        if name in old_flags:
+            new_flags[name] = bool(old_flags[name])
+        else:
+            new_flags[name] = bool(d.get("initial", False))
+            report["added"].append(f"flags.{name}")
+    for name in old_flags:
+        if name not in new_flags:
+            report["removed"].append(f"flags.{name}")
+    ws["flags"] = new_flags
+
+    # Milestones store only the ones reached, so there is nothing to add here —
+    # an unreached milestone is simply absent. Drop reached ones the scenario
+    # no longer defines, or they'd sit in "Achieved" forever with no label.
+    milestone_defs = stat_schema.get("milestones") or {}
+    reached = ws.get("milestones") if isinstance(ws.get("milestones"), dict) else {}
+    ws["milestones"] = {k: v for k, v in reached.items() if k in milestone_defs}
+    for k in reached:
+        if k not in milestone_defs:
+            report["removed"].append(f"milestones.{k}")
+
+    # Cooldown bookkeeping for paths that no longer exist would never be read,
+    # but it accumulates in every stored snapshot — prune it with the rest.
+    meta = ws.setdefault("_meta", {})
+    last_changed = meta.get("last_changed")
+    if isinstance(last_changed, dict):
+        removed = set(report["removed"])
+        meta["last_changed"] = {
+            path: at for path, at in last_changed.items()
+            if not any(path == r or path.startswith(f"{r}.") for r in removed)
+        }
+    else:
+        meta["last_changed"] = {}
+
+    return ws, report
+
+
 def band_label(stat_def: dict, value) -> str | None:
     """The word label for `value` from a stat def's bands, if any.