0014: Prefer Runtime-Native Almanac Hosts

Status: Historical; least-artificial-route principle retained; persistent Almanac-host preference superseded by ADR 0027

ADR 0027 keeps the smallest truthful engine or game route as the default and makes persistent gallery UI an optional project feature.

Context

Making the Visual Almanac engine-native corrected STAGE's first evidence-first workflow, but engine-native still described several materially different hosts. An editor window can resolve real assets while bypassing the production camera, post-processing, animation graph, particle update, input, pause, procedural generation, scene composition, or player lifecycle that gives those assets meaning in the game.

The Circussy visual trial showed the cost of inspecting detached representations. Lanternworks then showed that a development-player Almanac could reuse the game's real composition, expose stable review controls, and remain callable by an agent without creating an external substitute renderer. The useful distinction was not merely external versus engine-native. It was whether the selected host exercised the truth needed by the review question.

Decision

• Choose the least artificial Native Stage that can answer the Visual Review Scenario's question.
• Prefer a development runtime screen, dedicated runtime scene, or composed player route when the question depends on gameplay camera composition, lighting, post-processing, animation, VFX, physics, input, pause behavior, runtime factories, generated content, UI layout, or lifecycle.
• Use an editor window or asset preview for questions local to import state, mesh, material, texture, authored pose, or other asset-level presentation.
• Share subject resolution, scenario data, presentation profiles, validation, and lifecycle code between player, developer, and agent views where useful. Keep their controls and failure behavior audience-specific.
• Do not require a shipped player codex or expose development controls in a release build. A development-only runtime stage remains valid when no useful product surface exists, but ADR 0024 prefers a shared product-native Gallery with gated developer controls when the game can benefit from one.
• Record the actual host, entry points, and truth modes in the ordinary project map and operating docs. Do not add a visual-specific manifest when those project-owned surfaces already carry the distinction.

Consequences

• Unity guidance and templates default to a runtime UI instead of an editor menu.
• Review of player-visible behavior is more likely to exercise production rendering and lifecycle paths.
• Asset-local review can stay fast and isolated in an editor host.
• Some projects will maintain more runtime development UI, but that code can also support player galleries, test labs, debug menus, and agent operations.
• engine-native alone is no longer treated as a sufficient truth claim. The Scenario still records its inspection truth mode and limitations.
• A native host is not considered ready merely because one launcher configured it successfully. Every declared entry point must reproduce its subject, presentation, readiness, reset, and teardown contract from a fresh session; see ADR 0015.
• No separate Visual Almanac capability manifest is required; ADR 0026 retired the earlier duplicate interface.

ADR 0024 later narrowed the persistent-host preference. Runtime-native remains necessary for composed claims, but a separate development product is no longer the preferred destination when one in-game Gallery can serve players and reviewers through distinct modes over the same production implementation.