docs/CERTIFICATE_API.md

Implemented v3 API and engine contract

aureole.certificates.CertificateMemory stores canonical point/emitter visibility, geometric clearance and its motion-ledger timestamp. begin_geometry() must run before querying a changed scene. The renderer must supply current authoritative geometry. This is not an API for inferring unreported physical changes.

1. Establish a namespace with immutable receiver/emitter coordinates and indexed opaque spheres. Unsupported topology or identity changes create fresh memory.
2. Advance the geometry ledger using the complete current snapshot.
3. Call lookup(ids). Its returned known mask, not the existence of a value, licenses exact reuse. For nearby points, supply query_points; for a future known trajectory, supply a correct extra_motion bound.
4. Use prepare(bound, prior, values, known, score) to construct control and residual support. score is positive on the full finite domain. Certified terms get probability zero; remaining terms are renormalized.
5. Call eliminate(h, q, oracle, n, rng). Each oracle(rows, j) returns the exact current RGB contribution and may commit the sampled visibility certificate. Geometry and lighting remain frozen throughout this batch.
6. Read enclosure(bound, values, known) separately when a deterministic interval is wanted. It bounds truth, not each stochastic estimate. Display clipping is not an unbiased transformation.

The low-level estimator trusts the caller's certificate and oracle. It cannot detect missing renderer events or a malicious/wrong certificate. The audit API exact_risk_two rejects a nonzero residual outside sampling support when it has an offline exact reference. Never supply that reference to the online policy.

save and load use NPZ with pickle disabled and validate namespaces, array shapes and value ranges. Valid certificates are meaningful only in the declared scene family; a file is not an independently machine-checked proof object.

Cost and implementation reality

The implemented certificate query computes distance to a trimmed segment for all three spheres. It is more expensive than a Boolean early-out query. A general triangle renderer needs a valid margin adapter: for example conservative distance lower bounds from a BVH, exact local primitive distances, or a scene-change dependency test. Finding a cheap, useful margin is an open systems problem. Hardware ray-tracing APIs do not automatically expose it.

The reference uses dense arrays and scans all receiver/emitter entries. A GPU implementation should gather only demanded surface tiles, validate in fused kernels, compact unresolved requests, and charge coherence, atomics, metadata, and memory bandwidth. Quantized margins must round conservatively; a numerical proof requires interval/error analysis that this float64 reference does not supply.

No CUDA kernels, game plugin, DLSS DLL, learned arbitrary-time dynamics or general SR/RR/FG module is included. The Windows scripts are entry points for CPU experiments.