0011: Separate Native Control, State Provenance, And Visual Observation

Status: Channel-separation principle accepted; capability-manifest decision superseded by ADR 0026

Detached-export terminology and consequences are superseded by ADR 0025. The versioned declaration described below was retired by ADR 0026; ordinary project maps and native operations now carry the retained control, state, and sight distinctions.

Context

The first Visual Rehearsal dogfood produced portable screenshots, videos, indexes, and receipts without first producing a useful engine-native review surface. That was Evidence-First Inversion: the evidence package worked, but ordinary visual iteration remained awkward and several captures had little product value.

Lanternworks tested the corrected direction. Its development player exposes a native Visual Almanac, accepts exact launch coordinates, renders canonical Borough content through the real presentation path, and writes a matching machine-readable state receipt. Direct observation confirmed that the native view and controls were present.

That successful path exposed a second distinction. A command can successfully control an Almanac while showing the wrong subject. A receipt can correctly describe requested state while the renderer is blank, pink, clipped, stale, or visually poor. A screenshot or live frame can look plausible while its subject, truth mode, seed, camera, or timeline position is unknown. Control, state, and sight therefore cannot validate one another by implication.

Decision

Treat an agent-capable Visual Almanac as three independent channels:

1. Native control selects and opens canonical subjects; seeks, plays, or changes presentation where supported; reports explicit failures; and resets and tears down temporary state.
2. State provenance reports the current native subject, truth mode, state or beat, presentation coordinates, and readiness through a machine-readable project-owned surface. It should bind to source and invocation coordinates when the project can do so credibly.
3. Visual observation exposes the engine's actual frame or motion through an interactive desktop, engine stream, project-owned capture, or another named surface. Its truth mode and limitations remain explicit.

Record the channels separately. Do not call a control adapter a visual-review adapter when no visual observation surface is available. Do not treat a state receipt as pixel evidence. Do not interpret an observed frame without enough state provenance to identify what it represents.

Human visual acceptance remains authoritative. Agent control and observation may be available and useful without granting product acceptance. Portable Evidence Export remains optional: direct observation of the native engine surface is sufficient for ordinary review when the reviewer can access it.

At the time of this decision, Visual Almanac declarations 0.1 and 0.2 modeled these channels. ADR 0026 later retired that duplicate interface without changing the channel-separation rule.

Consequences

• Agent workflows can distinguish a successfully invoked tool from a visually inspected result.
• A blank or incorrect renderer cannot pass merely because a ready receipt was written.
• A visually plausible frame cannot pass as reproducible evidence when its state coordinate is unknown.
• Projects may implement the three channels incrementally and report deferred channels honestly.
• State receipts stay small and useful without becoming a parallel screenshot catalog or an automated taste verdict.
• Persistent native routes record available control, state provenance, and observation channels in their ordinary project map and operating docs.