M10: the seam for media, and no media

The media extension contract asks for a scene snapshot a future image or video
provider could be handed: location, who is present, what they hold, what must
stay true, and where in the story it sits. Building one was the milestone's
obvious first task, and it was the wrong one. That snapshot has existed since
M5. `narrative_state["scene"]` holds the summary, the location, the cast and the
coordinate it was written at; a validated `set_scene` event writes it, every
position snapshots it, and every head move restores it. It survives Undo, Redo,
Retry, divergence, Save Point restore and a process restart because it is the
authoritative state rather than a copy of it.

So there is no scenes table here. A second scene store would have been a second
answer to "where is the story now", with its own lineage rules to get wrong —
and the lineage rules are the expensive part, which is the argument for reusing
the ones that already work rather than against it. The Scene Packet is derived
on read, and its identity is computed from the campaign and the position rather
than allocated: the same position yields the same id in another process, after a
restart, and after the packet is thrown away and rebuilt, with no row to keep in
step. That is the part of a future media_assets table that would be expensive to
retrofit, so it is fixed now even though the table is not built.

One table, then: visual_profiles, the only thing the contract's scene list asks
for that nothing already stored. Campaign-scoped and not per-position, because a
character does not change appearance when the story forks — a reader who
diverged would otherwise lose their cast, and the same descriptors would land in
every per-position snapshot, measured at 245 copies of 367 bytes in a 120-turn
campaign to say something that never varies. Keyed by the M5 entity key rather
than a new identity namespace, and one table for characters, locations and items
alike, because a location is an entity with a type and splitting them would
reintroduce the genre shape M5 spent a milestone removing.

What the packet leaves out is the more interesting half. Not the transcript, and
not imported knowledge — none of it, not merely the sources marked hidden. The
rule is what the story established at this position, not everything the narrator
was told, and drawing it by class is what makes it hold for a secret nobody
thought to mark. A hidden Canon source proves it, with a positive control
showing the narrator did receive the sentinel the packet does not carry. Once a
validated event puts the observer in the room, the observer is in the packet:
that is no longer narrator-only knowledge, and a packet that hid it would be
hiding the story from itself.

The providers are contracts and nothing else. Protocols for image, video, audio,
speech and transcription, an empty registry, no adapter, no dependency, no
socket, and no media setting to point anywhere — a setting that exists can be
pointed at a cloud by mistake. A future provider endpoint must be loopback,
stricter than narration's trusted-LAN allowance, because a picture of a scene
carries the scene with it. Transcription returns an editable draft with no
commit method, so STT structurally cannot bypass the authoritative path.

Nothing here can write the story. Not by convention: no module under media/
imports the code that writes state, no media event type exists in the state
vocabulary, and every test in the authority suite compares the authoritative
document byte for byte either side of a media operation — including one where a
provider insists Alice is in a red coat in a corridor, and the campaign goes on
disagreeing.

One defect, found by the milestone's own tests. M10 first added a migration
creating an index that create_all already builds from the column, so an upgraded
database ended up with two indexes and a fresh install with one. Comparing the
two schemas is what caught it; neither database examined alone would have. The
migration is gone rather than renamed, and the right number of migrations for a
new table whose indexes are declared on its columns is zero.

Backend 1,191 passed / 14 skipped / 0 failed, 89 of them M10's. Frontend 145
passed. Lint, production build and Docker build clean. No frontend file changed:
M10 adds no reader-facing surface, and ordinary play — turns, state, memory,
knowledge, Undo, Redo, Retry, Save Point restore, restart — runs with no media
configuration, no warning, no connection attempt and no media row written.

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

backend/app/routers/adventures/__init__.py

@@ -42,6 +42,7 @@ from . import (  # noqa: F401
     memories,
     actions,
     knowledge,
+    visuals,
 )
 from ... import limits  # noqa: F401  `adventures.limits` is patched by tests.
 from .crud import SNIPPET_MAX, _snippet

backend/app/routers/adventures/visuals.py

@@ -0,0 +1,131 @@
+"""M10: reading and writing how a campaign's entities look.
+
+Four endpoints on the campaign, and one on the scene beneath it. They are the
+only reader-facing surface M10 adds, and they are an API surface rather than a
+browser one: M10 builds no gallery, no picker and no preview, because there is
+nothing to generate and a screen for configuring depictions nobody can make
+would be a feature pretending to be a seam.
+
+## Why a scene-packet endpoint exists at all
+
+`GET .../scene-packet` returns exactly what a future media coordinator would be
+handed (`media/packet.py`). Nothing in v1 calls it, and it generates nothing.
+
+It is here because it is the one part of M10 whose *contents* are a
+correctness claim — that a provider is given a bounded view and not the
+campaign, and that narrator-only material does not travel through it. A claim
+like that should be inspectable by whoever is reviewing the boundary, not only
+by a test that imports a private function. It is a read: it writes nothing,
+emits no event, and cannot move the head.
+
+## What these endpoints deliberately are not
+
+They are not a state API. A visual profile is presentation metadata and writing
+one changes no story fact (`models.VisualProfile`), so there is no event, no
+proposal, no snapshot and no head movement anywhere below here. The separation
+is structural — this module reaches `media.profiles`, and that module imports
+nothing that can write authoritative state.
+"""
+
+from fastapi import Body, Depends, HTTPException
+from sqlalchemy.orm import Session
+
+from ... import models
+from ...database import get_db
+from ...media import packet as scene_packet
+from ...media import profiles as visual_profiles
+
+from .deps import current_adventure, router
+
+
+@router.get("/{adventure_id}/visual-profiles")
+def list_visual_profiles(
+    db: Session = Depends(get_db),
+    adventure: models.Adventure = Depends(current_adventure),
+):
+    """Every visual profile in the campaign, by entity key.
+
+    Campaign-scoped rather than scoped to the story being read, because that is
+    what a profile is: a character does not change appearance when the story
+    forks, so there is no position for this list to be relative to.
+    """
+    return {
+        "profiles": [
+            {"entity_key": row.entity_key, **visual_profiles.as_dict(row)}
+            for row in visual_profiles.all_for(db, adventure)
+        ],
+    }
+
+
+@router.put("/{adventure_id}/visual-profiles/{entity_key}")
+def set_visual_profile(
+    entity_key: str,
+    payload: dict = Body(...),
+    db: Session = Depends(get_db),
+    adventure: models.Adventure = Depends(current_adventure),
+):
+    """Records how one entity looks. Replaces any existing profile.
+
+    A `PUT` rather than a `PATCH`, and the whole profile rather than a delta,
+    for the reason `profiles.set_profile` gives: merging would make a descriptor
+    impossible to remove.
+
+    The entity must exist in the campaign's state at the active head. A 400 for
+    a name nobody has is better than a row describing nobody, which would then
+    be invisible until a future depiction quietly ignored it.
+    """
+    try:
+        row = visual_profiles.set_profile(
+            db, adventure, entity_key,
+            descriptors=payload.get("descriptors"),
+            features=payload.get("features"),
+            style_notes=payload.get("style_notes"),
+        )
+    except visual_profiles.ProfileError as exc:
+        raise HTTPException(400, str(exc)) from exc
+    db.commit()
+    db.refresh(row)
+    return {"entity_key": row.entity_key, **visual_profiles.as_dict(row)}
+
+
+@router.get("/{adventure_id}/visual-profiles/{entity_key}")
+def read_visual_profile(
+    entity_key: str,
+    db: Session = Depends(get_db),
+    adventure: models.Adventure = Depends(current_adventure),
+):
+    row = visual_profiles.get_profile(db, adventure, entity_key)
+    if row is None:
+        raise HTTPException(404, f"No visual profile for {entity_key!r}.")
+    return {"entity_key": row.entity_key, **visual_profiles.as_dict(row)}
+
+
+@router.delete("/{adventure_id}/visual-profiles/{entity_key}", status_code=204)
+def delete_visual_profile(
+    entity_key: str,
+    db: Session = Depends(get_db),
+    adventure: models.Adventure = Depends(current_adventure),
+):
+    """Removes a description. Never the entity, which lives in the state."""
+    if not visual_profiles.delete_profile(db, adventure, entity_key):
+        raise HTTPException(404, f"No visual profile for {entity_key!r}.")
+    db.commit()
+
+
+@router.get("/{adventure_id}/scene-packet")
+def read_scene_packet(
+    start: int | None = None,
+    end: int | None = None,
+    db: Session = Depends(get_db),
+    adventure: models.Adventure = Depends(current_adventure),
+):
+    """What a future media provider would be given for the current scene.
+
+    `start` and `end` are depths on the active branch, and both are optional:
+    omitted, the packet describes the scene at the position the story last set
+    one. Passing a range is what a future video request would do — a scene is
+    not assumed to be one turn (`MEDIA-EXTENSION-CONTRACT.md` §30-31).
+
+    Generates nothing and contacts nothing. There is no provider to send it to.
+    """
+    return scene_packet.build(db, adventure, start=start, end=end)