The implemented finite-domain CPU API is documented separately in `docs/ESTIMATOR_CONTRACT.md`. The following contract remains the broader engine-integration design.

# Proposed engine integration contract

This contract is a specification, not an implemented SDK. It targets a renderer whose source or supported extension interface exposes the necessary state. A postprocess-only DLSS replacement is not supplied.

## Authority and time

Simulation time is represented in seconds with an explicit simulation tick and epoch. Every output request specifies the latest authoritative input time, requested display time, camera transform, projection, exposure, viewport, and footprint. Future controls are marked known, interpolated from available endpoints, or predicted. These labels cannot be silently interchanged.

The engine owns geometry, material handles, object creation/destruction, topology generations, transforms, animation parameters, streaming events, and known emitters. The estimator owns uncertain filtered response, insufficiently sampled transport, confidence, and evidence provenance.

## Canonical keys

Required fields: world epoch; object UUID; topology generation; material generation; canonical chart or primitive and rest mapping; quantized cell; footprint band; response class. Validate full keys on hash collisions. A reused GPU buffer address or primitive ID is insufficient identity. LOD/remesh correspondence must be supplied explicitly or reset.

## Observation record

| Field | Purpose |
|---|---|
| Time and simulation snapshot | Associate evidence with the correct world state. |
| Canonical key and dependency generations | Retain only valid evidence. |
| Camera, incoming/outgoing directions, footprint | Define the requested optical response. |
| Value and units | Linear radiance, visibility indicator, material response, or other declared measurement. |
| Exposure / normalization | Undo display-space changes before consolidation. |
| Observation map or encoded features | Relate the measurement to local/global latent factors. |
| Noise model and variance evidence | Estimate uncertainty without presenting a heuristic as exact. |
| Proposal PDF / inclusion probability | Correct for adaptive sampling and selection. |
| Lineage / seed / reservoir ancestry | Detect reused and correlated evidence. |
| Termination and rejection reason | Interpret censored or rejected path information. |
| Cost and completion deadline | Charge collection, transfer, assimilation, and synchronization. |

## Query and state operations

`legal_queries(snapshot)` returns permitted physical tests and batched traversal costs. `execute(query)` returns evidence under the recorded proposal. It must not grant future input or change gameplay physics as a side effect. Counterfactual cameras and lighting interventions are offline training operations unless explicitly supported in the renderer.

`assimilate(batch)` updates one logical belief and covariance/provenance. `invalidate(event)` updates all affected dependency factors. `query_output(time, view, task)` returns an estimate plus uncertainty and evidence age. `evict(key)` removes information and records the induced uncertainty. `commit_snapshot()` creates an immutable view for all decoders producing the same display frame.

## Minimal first integration

Implement opaque static/rigid geometry, sixteen local coefficients, diagonal uncertainty, a small shared light block, passive samples, and generation-based reset first. Add cross-correlations, active probes, future teachers, and new response classes as individually measured changes. Start with joint denoising/SR before integrating FG, volume state, or rare-regime experts.

Never feed generated frames back as independent measurements. Never lower uncertainty solely because a record was not observed. Never interpret an unannounced hidden event as an impossible event just because the old state was confident.