0012: Separate Visual Subjects, Review Scenarios, And Staging

Status: Historical terminology; canonical-identity and question-separation principles retained; dedicated Scenario architecture superseded by ADR 0027

Detached-export terminology and consequences are superseded by ADR 0025. ADR 0027 removes Visual Review Scenario as required STAGE vocabulary. Projects may preserve a reproducible setup in their own language when recurring utility earns it.

Context

The first Visual Rehearsal implementation optimized for portable captures and contact sheets. That produced technically valid evidence while forcing ordinary visual iteration outside the engine. Replacing that workflow with a native Visual Almanac corrected the review surface, but a flatter problem remained: an Almanac can list real assets, cameras, lighting modes, and animation controls without explaining what a reviewer is meant to judge.

Lanternworks exposed this gap directly. Its first native Almanac resolved real Borough content, staged it through the actual presentation path, provided deterministic states, and exposed camera and lighting controls. Its entries were nevertheless organized primarily as subjects. Most static entries showed one generic authored state, while the useful First Light entry succeeded because it implicitly formed a coherent sequence with meaningful progression. The implementation had the mechanics of review, but not an explicit review question.

A content catalog and a review workflow therefore have different jobs. The catalog answers what content exists. Review needs to answer why a particular state, view, or motion should be inspected. Mirroring the complete catalog into STAGE would recreate Catalog Shadowing; multiplying generic angles would recreate Matrix Without A Question.

Decision

Model native visual review with four distinct concepts:

1. A Visual Subject is the stable project-owned identity of real game content. It is resolved from the project's authoritative catalog, prefab, scene, definition, generator input, or runtime registry.
2. A Visual Review Scenario is a human-authored question applied to one subject or a coherent group. It selects only the states, beats, contexts, and truth modes needed to answer that question.
3. A Presentation Profile is human-owned staging intent: camera, distance, background, lighting, rendering, timing, fixtures, seeds, and related inspection settings. Profiles may be shared between scenarios and remain editable through ordinary project authoring surfaces.
4. A Native Stage is the engine-owned scene, editor tool, runtime gallery, or composed game route that resolves and presents the real subject under the selected scenario and profile.

A Review Beat is a named state or temporal coordinate within a scenario, such as anticipation, impact, recovery, loop seam, selected, damaged, dense, or error. A beat exists because it contributes to the scenario's question; it is not anonymous timestamp coverage.

The Visual Almanac should browse or derive Visual Review Scenarios for developer review. A player-facing content browser may separately derive one entry per discovered or intentionally visible canonical Subject. That browser is a legitimate product feature, not merely a convenience, but generic Subject preview is not evidence that a review question was answered. The two catalogs reuse canonical identity, resolution, rendering, staging, camera, and lifecycle while retaining different purposes and cardinality. One Visual Subject may have multiple Scenarios, and one Scenario may compose multiple Subjects.

Scenario definitions remain sparse and project-owned. A persistent route's ordinary project map points to their source and lifecycle but does not copy the project's subject inventory or Scenario records. Generated defaults may propose a Scenario, but they may not overwrite a human-authored question or Presentation Profile.

State provenance should identify the active scenario, resolved subject IDs, Review Beat, truth mode, Presentation Profile, readiness, and relevant effective settings when the project can report them credibly. Visual observation remains independent of that report. Optional Evidence Export preserves the same native coordinates rather than inventing a second shot grammar.

Earlier declaration versions attempted to expose the project-owned Review Scenario source, human question authority, and named-beat capability without copying Scenario records. ADR 0026 retired that duplicate manifest. The same boundary remains current through the ordinary project map and project-owned authoring sources.

Consequences

• A reviewer can understand the intended judgment before moving the camera or playing motion.
• The developer Scenario catalog grows by useful questions rather than by asset count; a player content browser may grow with canonical game content.
• Real project catalogs remain authoritative and are not mirrored into STAGE.
• Human camera and lighting decisions remain durable project data rather than generated capture defaults.
• Static previews must earn their place through a meaningful question, not a single generic angle.
• Agent control, state provenance, and visual observation can refer to the same scenario coordinate without implying human acceptance.
• The distinction can be dogfooded in engine code before another public schema is frozen.

Dogfood Result

Lanternworks replaced the generic subject browser with two authored Scenarios: one asks whether every Structure remains distinguishable at gameplay distance under three lighting contexts; the other asks whether the progression from an empty Borough to First Light communicates clearly. The first uses one lineup beat containing all five canonical Structure Subjects. The second uses five progression beats. Both run through the existing native stage and one human-owned Presentation Profile.

That change made the boundary operational without adding a detached scenario schema. It also exposed two lifecycle requirements that generic startup checks had hidden: readiness must prove the selected Review Beat is rendered, and teardown must tolerate Unity scene-destruction order without redrawing through a destroyed view. The dogfood therefore supports the decision that a useful scenario is a question plus truthful native staging, not a renamed catalog entry.

A follow-up product dogfood restored catalog-sized Subject browsing for the player without inflating developer review. The player can inspect every canonical Structure and its field notes, while developer mode still exposes exactly the same two question-driven Scenarios. Both paths use the same resolver, deterministic BoroughSession, BoroughWorldView, camera, and teardown. The correction also made controller operation explicit: opening establishes focus, Submit activates the focused entry, Cancel closes, and the HUD focus is restored. Lanternworks has no canonical production animation, so the dogfood deliberately added no fake motion merely to generate a video.