@photivra/engine 0.6.0 → 1.0.1

package/docs/SCENE_RADIANCE_AND_ILLUMINATION.md

@@ -0,0 +1,298 @@
+# Scene Radiance and Illumination
+
+Release context: **package 1.0.1 candidate / root API 1.0.1**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_0_1.md).
+
+Photivra separates **illumination-source metadata** from **outgoing scene spectral radiance**.
+
+The public image-formation contract owns a `scene-radiance-evaluation` stage between scene projection and lens/pupil evaluation:
+
+```text
+scene geometry + illumination + material response + visibility + emission + time
+  -> outgoing scene spectral radiance
+  -> lens / pupil / PSF / transmission
+  -> sensor-plane spectral irradiance
+  -> sensor sampling and signal formation
+```
+
+This boundary prevents light-source controls, RGB renderer values, or photometric scene anchors from being treated as sensor input.
+
+## Shared spectral primitives
+
+Fundamental wavelength semantics live in the renderer-neutral core rather than the sensor layer.
+
+`SpectralWavelengthBasis` supports:
+
+- `air`;
+- `vacuum`;
+- `unspecified`.
+
+The shared parsers also expose a positive wavelength sample and a positive non-empty wavelength range in nanometres. They do not convert between air and vacuum wavelength coordinates.
+
+Existing sensor APIs continue to export/use the same root `SpectralWavelengthBasis` name. Moving ownership does not change its public values or meaning.
+
+## Scene radiometry versus scene radiance
+
+The existing `SceneRadiometry` contract remains valid.
+
+- `relative-linear` says scene-linear values preserve ratios without absolute photon calibration.
+- `absolute-luminance` provides a photometric luminance anchor in cd/m².
+
+Neither form is, by itself, an outgoing spectral-radiance field. Absolute luminance is a photometric anchor and must not be substituted for W/(m²·sr·nm), source irradiance, or sensor-plane spectral irradiance.
+
+The new illumination profile complements `SceneRadiometry`; it does not replace it.
+
+## Illumination profile
+
+Use `parseSceneIlluminationProfile()` for renderer-independent source metadata.
+
+Schema `0.1.0` supports these source families:
+
+- `point`;
+- `spot`;
+- `area`;
+- `directional`;
+- `environment`.
+
+Every source has a stable `sourceId`, explicit enabled state, geometry/binding, magnitude representation, spectrum representation, time behavior, and evidence.
+
+A visible/emissive source may bind to a stable scene object instead of duplicating its transform. Area-source geometry must use a scene-object binding in the first schema.
+
+## Magnitude semantics
+
+There is no generic unitless `intensity` field.
+
+All source families may use a clearly labeled relative linear scale for approximate/reference rendering. The first physical magnitude subset is deliberately narrow:
+
+- point: radiant intensity, W/sr;
+- area: surface radiance, W/(m²·sr);
+- directional: irradiance at an explicit reference plane, W/m².
+
+Physical spot magnitude is not yet represented because a defensible model needs an angular distribution. Absolute environment illumination is not yet represented because it needs a direction-dependent radiance field.
+
+Photometric quantities such as lumens, candela, lux, and luminance are not silently converted into radiometric quantities.
+
+## Spectrum representations
+
+Schema `0.1.0` supports:
+
+- unresolved spectrum with an explicit limitation;
+- linear-sRGB preview approximation;
+- explicit blackbody-temperature approximation;
+- continuous relative spectral shape with wavelength coordinates, interpolation semantics, uncertainty, and reusable-data provenance;
+- normalized discrete relative lines with explicit wavelengths and wavelength-integrated line fractions.
+
+A blackbody temperature is an explicit approximation. It is not a universal CCT/color control and must not be used to give arbitrary colored, LED, narrowband, UV, or other non-Planckian sources a fictitious Kelvin meaning.
+
+Embedded continuous numeric spectra require `reusable-data` or `photivra-owned` evidence. A calibrated relative spectral shape must use an explicit air/vacuum wavelength basis and quantified relative uncertainty.
+
+The continuous relative spectrum uses arbitrary relative normalization. Combining it with a broadband physical magnitude into an absolute spectral source distribution remains a later explicit composition step; the parser does not silently normalize or integrate it.
+
+Discrete line spectra use the separate `discrete-relative-lines` representation. Each line has an explicit wavelength and a normalized **wavelength-integrated** line weight; weights must sum to one. These are not per-nanometre density samples and are never broadened into synthetic continuous bumps. A calibrated relative line distribution requires reusable-data provenance, a resolved air/vacuum wavelength basis, and quantified relative uncertainty.
+
+`resolveSceneIlluminationDiscreteLineMeasure()` may distribute the source's wavelength-integrated magnitude across those normalized line fractions. Point radiant intensity becomes per-line W/sr, area radiance becomes per-line W/(m²·sr), directional reference-plane irradiance becomes per-line W/m², and relative source magnitude stays relative. Disabled sources resolve to zero contribution.
+
+This source-level line measure still does not authorize a calibrated outgoing scene-radiance claim because material/visibility/transport fidelity and combined uncertainty remain separate.
+
+## Shared spectral composition
+
+`composeSpectralCoverage()` defines the common continuous-spectral planning seam across scene, optics, materials, sensor response, or other wavelength-dependent factors.
+
+Each participant declares:
+
+- stable participant ID and role;
+- one resolved air or vacuum wavelength basis;
+- finite wavelength support;
+- strictly ordered internal interpolation breakpoints.
+
+Composition intersects all participant wavelength ranges and unions every breakpoint that lies inside the common overlap. It does **not** apply response/transmission/radiance values and does not integrate a spectral density. Air/vacuum conversion is never implicit.
+
+The existing sensor spectral response can participate through `createSensorSpectralCoverageParticipant()`, which exposes the channel response's usable overlap and interpolation knots without applying QE or A/W responsivity.
+
+Continuous scene-illumination data can participate through `createSceneIlluminationSpectralCoverageParticipant()`. RGB, blackbody approximations, unresolved spectra, and discrete line spectra are rejected by that adapter rather than being silently converted into a continuous curve.
+
+### Continuous versus discrete integration
+
+The mathematical distinction is hard:
+
+```text
+continuous density:  integral f(lambda) d-lambda
+discrete line measure: sum line_i
+```
+
+`integrateDiscreteSpectralLineMeasure()` therefore sums already wavelength-integrated line quantities. It never multiplies a line by a fabricated `dλ` and never invokes continuous quadrature.
+
+A continuous composition plan and a discrete-line measure may coexist in a future mixed-spectrum transport model, but schema/API 0.1.0 keeps them separate rather than pretending one representation is the other.
+
+## Temporal boundary
+
+Schema `0.1.0` supports time-invariant source emission only.
+
+Flash pulses, mains/LED flicker, and other time-varying source waveforms must later consume the existing seconds-based exposure-time contract. They must not invent a second time coordinate.
+
+## What this foundation does not calculate
+
+A parsed illumination profile explicitly reports that it has not:
+
+- calculated outgoing scene radiance;
+- applied material optical response;
+- evaluated visibility/occlusion;
+- evaluated indirect light transport;
+- modeled fluorescence;
+- modeled participating-media/volumetric spectral transport;
+- modeled polarization.
+
+Those are scientific boundaries, not renderer implementation preferences.
+
+RGB/PBR textures and RGB HDR environments can still be useful preview/reference inputs, but they are approximation paths unless compatible spectral and absolute-radiometric calibration is actually available.
+
+## Renderer boundary
+
+Photivra owns the semantic inputs and scene-radiance stage. It does not require one renderer implementation.
+
+A browser/WebGPU preview, Blender reference render, or future spectral renderer may use different bounded approximations while consuming the same source identities and declared meanings. Approximate backends must not inherit calibrated spectral/radiometric claims merely because they consume an engine-owned profile.
+
+## Scene-radiance provider and material-response boundary
+
+The engine now exposes a renderer-neutral provider boundary without becoming a renderer.
+
+`parseSceneMaterialResponseProfile()` describes stable material-response inputs. Schema `0.1.0` deliberately distinguishes:
+
+- unresolved material response;
+- `rgb-pbr-approximation`, with linear-sRGB base color plus bounded metallic/roughness parameters and an explicit limitation;
+- `spectral-wavelength-preserving-data`, bound to a SHA-256 identified data artifact, explicit wavelength basis/range, uncertainty and a provider-defined wavelength-preserving scattering model.
+
+RGB/PBR input is always approximation data. Spectral material data may itself be calibrated, but schema 0.1.0 does not model wavelength-changing behavior, fluorescence, material emission, volumetric material transport or polarization.
+
+`assessSceneMaterialResponseFidelity()` reports the conservative profile-level state: `spectral-data`, `rgb-pbr-approximation`, `mixed`, or `unresolved`.
+
+`parseSceneRadianceProviderProfile()` declares the provider's bindings and fidelity independently across:
+
+- spectral evaluation;
+- material response;
+- visibility;
+- direct transport;
+- indirect transport.
+
+Its output quantity is fixed to outgoing spectral radiance in `W/m^2/sr/nm`. Provider schema `0.1.0` is intentionally `approximation` only. Calibrated input artifacts therefore cannot automatically promote an incomplete renderer/transport path into a calibrated outgoing-radiance claim.
+
+### Evaluation request
+
+`parseSceneRadianceEvaluationRequest()` identifies one exact sample by:
+
+- provider/scene/illumination/material profile IDs;
+- surface point + scene object + material response, or an environment direction;
+- unit-length outgoing direction;
+- seconds from exposure start;
+- positive wavelength in an explicit air or vacuum basis.
+
+`unspecified` wavelength basis is rejected for physical outgoing spectral-radiance evaluation.
+
+### Evaluation result
+
+`parseSceneRadianceEvaluationResult()` validates provider-produced output with:
+
+- exact sample/provider/scene/wavelength identity;
+- `outgoing-spectral-radiance` quantity;
+- `W/m^2/sr/nm` units;
+- finite nonnegative spectral radiance;
+- approximation status, uncertainty, evidence and limitations.
+
+Parsing does **not** prove that the renderer's numeric radiance value is physically correct.
+
+`validateSceneRadianceEvaluationBindings()` then verifies the exact scene/profile/material/request/result relationships. A surface request must reference a declared material response, and the provider's declared material fidelity must agree with the supplied material-response profile.
+
+The validation result explicitly reports that calibrated radiance is not authorized and that optics, sensor-plane irradiance and photons have not been calculated.
+
+This means a browser preview, Blender reference path, or future spectral renderer can plug into one stable scientific seam without the engine prescribing its rendering algorithm.
+
+## Temporal illumination
+
+Time-varying source emission is represented as an additive temporal overlay on the existing illumination profile. The base source keeps its authoritative identity, enabled state, magnitude, geometry and spectrum; the temporal layer supplies a **relative multiplier over physical time**.
+
+Use `parseSceneIlluminationTemporalProfile()` to declare:
+
+- aperiodic piecewise-linear multiplier waveforms for flash/pulse-like behavior;
+- periodic piecewise-linear multiplier waveforms for flicker/repeating emission;
+- reusable numeric waveform evidence and scientific status;
+- one explicit source↔waveform binding per time-varying source;
+- exact registration of waveform-local `t=0` to the capture reference `first-opening-boundary-phase`.
+
+The registration equation is:
+
+```text
+waveform time =
+  capture time from first opening-boundary phase
+  - waveform t=0 offset from that capture reference
+```
+
+A calibrated waveform requires quantified relative uncertainty. A calibrated time registration requires quantified absolute timing uncertainty in seconds. Numeric waveform samples require reusable-data or Photivra-owned provenance.
+
+`evaluateSceneIlluminationTemporalMultiplier()` evaluates one registered source at one physical capture time. It supports times before or after the capture reference; periodic waveforms wrap deterministically, while aperiodic waveforms return zero outside their declared support.
+
+`integrateSceneIlluminationTemporalMultiplierOverExposureWindow()` consumes an authoritative `CaptureExposureWindows` sample from the existing shutter/exposure timing foundation. It uses deterministic uniform-midpoint quadrature over that local exposure interval and reports both:
+
+- a dimensionless average relative multiplier; and
+- a seconds-valued integrated relative multiplier.
+
+The integration does **not** use sensor data-readout duration as a timing proxy. Readout and exposure remain independent.
+
+The result also keeps source `enabled` state separate: a disabled source can retain a non-zero raw waveform value while its effective contribution is zero.
+
+### Scene-radiance provider binding
+
+`SceneRadianceProviderProfile` may now optionally declare `illuminationTemporalProfileId`. When it does, `validateSceneRadianceEvaluationBindings()` requires the matching temporal profile and verifies that it binds the same scene and base illumination profile.
+
+This is semantic binding only. The validator does not prove that the provider numerically applied the waveform correctly, and temporal illumination does not promote provider output beyond the existing approximation-only scene-radiance contract.
+
+### Metering and automatic-exposure boundary
+
+Temporal illumination is upstream input to future metering/automatic-exposure consumers. This foundation never chooses ISO, aperture, shutter duration, compensation, or a target exposure.
+
+That separation allows a future meter to observe changed pre-exposure radiance after a source changes without feeding final display/tone-mapped brightness back into source or exposure selection.
+
+## Downstream optical-radiometry bridge
+
+#110 now provides the first primary-optics consumer of a validated scene-radiance request/result pair.
+
+`calculateSceneRadianceToSensorIrradiance()` preserves the scene sample's:
+
+- sample/provider/scene identity;
+- physical time from exposure start;
+- wavelength coordinate and air/vacuum basis;
+- outgoing spectral-radiance value and provenance.
+
+It then applies an explicit lens-throughput profile to produce pre-sensor-stack spectral irradiance in `W/m^2/nm`.
+
+The first bridge is intentionally limited to:
+
+- paraxial circular-pupil acceptance;
+- explicit nominal/working f-number semantics;
+- one mutually exclusive transmission path:
+  - wavelength-resolved fractional transmission; or
+  - effective working T-stop approximation;
+- one optional field-throughput result applied exactly once.
+
+This downstream bridge does **not** change #85 scene-radiance semantics. In particular, the current provider/result schema remains approximation-only, so even calibrated optical-transmission data cannot promote the combined result to calibrated sensor-plane irradiance.
+
+The bridge also stops before:
+
+- PSF/diffraction redistribution;
+- distortion area-density correction;
+- sensor cover glass / OLPF / microlens;
+- CFA/filter response;
+- QE/responsivity;
+- photon/electron conversion;
+- stray-light contributions.
+
+Those remain separately owned stages.
+
+## Still outside this slice
+
+The following remain later work beyond the completed A–E foundation sequence:
+
+- fluorescence/excitation-emission;
+- participating-media spectral transport;
+- polarization;
+- a future calibrated scene-radiance provider contract with sufficient completeness evidence.
+
+The staged #85A–#85E foundation sequence is now represented in the engine. Remaining #85 work should be limited to explicitly approved later extensions or closure/hardening rather than widening the renderer contract by default.

package/docs/SCENE_SENSOR_QUADRATURE.md

@@ -0,0 +1,98 @@
+# Declared scene radiance to sensor irradiance nodes
+
+Release context: **package 1.0.1 candidate / root API 1.0.1**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_0_1.md).
+
+`calculateSceneToSensorIrradianceQuadrature()` connects the existing #85 scene
+request/result boundary and #110 paraxial optical bridge to the Cartesian nodes
+of sensor spatial/spectral quadrature. Its output is physical **W/m²/nm** at the
+**sensor-package-incident, pre-sensor-stack, pre-AA** plane. It remains a bounded
+static sample calculation, not complete production scene-to-file execution.
+
+## Bindings and calculation
+
+Inputs are existing `spatialQuadrature` and `spectralQuadrature` values,
+`sceneBindings` (provider, illumination, material and optional temporal
+illumination profiles), shared `optics`, explicit `timeSecondsFromExposureStart`,
+and a `samples` array. Each sample contains its exact spatio-spectral `node`,
+`sceneRadianceRequest`, `sceneRadianceResult` and `fieldThroughput` declaration.
+
+The adapter shares the irradiance reducer's internal Cartesian binding code:
+profile/channel/plan semantics, the existing 100,000 combined-node budget,
+complete coverage, safe integer indices, exact wavelength and duplicate checks
+are identical. Sparse arrays now receive an explicit scientific-input error;
+valid reduction arithmetic and prior ordinary invalid-input diagnostics are
+unchanged. The internal binder is not exported from the public package root.
+
+Provider/profile payloads are parsed, then every request/result is matched to
+those profiles. This adapter requires wavelength-resolved provider fidelity;
+RGB-derived and unresolved fidelity cannot enter this physical node path.
+Requests must match the node wavelength and basis and the common explicit time.
+Each node needs a distinct `sampleId`; identical values are allowed for an
+explicitly declared uniform field but do not prove that field is uniform.
+
+For each node the existing optical bridge computes
+`L_lambda * pi/(4*N_working²) * transmission * fieldThroughput`, with the
+existing mutually exclusive spectral-transmission/working-T-stop rules and
+optional front-of-lens filters. The adapter owns `imagePointMm`: it comes from
+the spatial node's **preAntiAliasingSourcePointMm**, never the destination
+aperture point or a caller substitution. Non-unity vignetting results must match
+that source point. Existing bridge validation retains finite-focus assumptions,
+wavelength support, passive transmission, units and separate uncertainties.
+
+No aperture area, spectral measure, AA weight, QE or exposure duration is folded
+into the per-node irradiance value. The returned `reduction` delegates those
+spatial/continuous-wavelength measures to the existing reducer once. Passing
+`irradianceSamples` to the EQE adapter recomputes that reduction for its own
+validated execution; **do not add or multiply the diagnostic reductions**.
+
+## Explicit EQE handoff
+
+```ts
+const optical = calculateSceneToSensorIrradianceQuadrature(sceneInput);
+const photo = calculateSensorEqeLocalExposure({
+  ...sensorInput,
+  irradianceSamples: optical.value.irradianceSamples,
+  responseApplication: {
+    ...sensorInput.responseApplication,
+    sourcePlane: { value: optical.value.sourcePlane, evidence: sourcePlaneEvidence }
+  }
+});
+```
+
+The sensor parameters must produce the same spatial/spectral nodes. The response
+must explicitly support **sensor-package-incident-effective-channel-response**.
+Do not relabel package-incident light as site-incident light, assume an absent AA
+kernel means the entire stack has unit transmission, or apply stack attenuation
+already included in effective package EQE. Site-incident/separable response needs
+an additional correctly modeled stack handoff. The separate stationarity profile
+still authorizes rate × local duration; one evaluated instant establishes no
+stationarity. Dark/completeness/capacity/readout remain explicit downstream data.
+
+## Result and limits
+
+The result retains canonical plan-order samples with owned request/result copies,
+pre-AA coordinates, provider binding assessments and child optical envelopes,
+plus `irradianceSamples` and the reduction envelope. Aggregate provenance is
+approximation. `sourceTargetProjectionVerified` and `sceneProviderExecutionVerified`
+remain false: a caller-declared environment/surface target is not an engine
+intersection/visibility/transport proof. The provider remains external; no
+callback, renderer, transport or network execution is added.
+
+`psfRedistributionApplied` and `temporalIntegrationApplied` remain false. This
+slice does not authorize skipping requested diffraction, defocus, aberration,
+visibility, motion, stray light or temporal transport. Production graph/gates
+are unchanged. Projection/PSF/temporal sampling and committed capture origin are
+remaining #16/#178 work, coordinated with #112; no feature is closed here.
+
+Tests independently predict optical irradiance, radiant power and photoelectron
+expectations using SI constants and declared synthetic curves. Split-AA tests
+check source-point vignetting and one-time area/weight/transmission arithmetic.
+Identity/time/basis/coverage/profile/plane failures reject; declared radiance
+passes through optics/EQE into deterministic four-site RAW and paired DNG/JPEG,
+with exact native DNG code preservation. All data is Photivra-owned synthetic
+fixture evidence, not physical camera calibration or source-truth validation.
+
+This additive public adapter advances root API **0.107.0 → 0.108.0**; its model
+version is 0.1.0. Package, POC, production, capture/RAW schemas and noise identities
+are unchanged. Newly created captures use the new root API stamp; historical
+replay keeps its stored stamp and pinned file hashes. No new dependency or cost.

package/docs/SCENE_SENSOR_TEMPORAL_EXPOSURE.md

@@ -0,0 +1,86 @@
+# Declared temporal scene radiance to sensor EQE
+
+Release context: **package 1.0.1 candidate / root API 1.0.1**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_0_1.md).
+
+`calculateSceneSensorEqeTemporalExposure()` composes the existing scene-to-sensor
+optical quadrature and temporal EQE calculation. It evaluates optics, response
+compatibility, per-bin operating range and EQE **at every local shutter midpoint**
+before integrating rates with seconds-valued measures. It never averages light
+first and uses that average to hide an invalid bright instant.
+
+## Input and binding
+
+`sensor` is `CalculateSensorEqeTemporalExposureInput` without `samples`. Its
+aperture/AA, CFA/site/native registration and spectral response inputs own both
+quadrature plans. There is no independent caller-supplied optical plan that can
+drift from the sensor plan. `sceneBindings` and `optics` retain the static
+optical bridge's provider/material/illumination, working-f-number, transmission,
+filter and field-throughput validation.
+
+`timeReference` must explicitly be `first-opening-boundary-phase`. Each temporal
+sample has `temporalSampleIndex`, `timeSecondsFromOpeningReference` and complete
+`sceneSamples` in the existing optical quadrature shape. Every scene request
+timestamp must equal this local midpoint on the same declared reference. Scene
+query seconds are explicitly bound to that opening boundary by this composition;
+readout time or renderer frame time is not substituted. The temporal sensor
+calculator verifies the exact midpoint against the resolved local shutter window,
+including rolling offsets, with its existing representability checks.
+
+Indices must uniquely cover 1–256 temporal samples. Array order is not identity.
+The shared internal temporal preflight checks the aggregate 100,000 declared
+spatial × spectral × temporal node budget before optical calculations. The
+existing optical binder separately checks exact Cartesian coverage. Scene
+`sampleId` values must be unique across all instants as well as within an instant;
+reusing an earlier query identity for a new time is rejected.
+
+Output from optics remains **sensor-package-incident, pre-stack/pre-AA W/m²/nm**.
+The response application must explicitly declare that plane and the selected
+effective response must support it. This API cannot relabel light as site-incident
+or silently add stack attenuation already included in package-effective EQE.
+
+## Output and downstream handoff
+
+The approximation envelope retains canonical `opticalSamples` with child optical
+and provider binding evidence, and an `exposure` temporal EQE envelope with
+independent instantaneous sensor evidence. Child diagnostic reductions are not
+extra signal contributions: do not add them or multiply their measures twice.
+
+For compact RAW photo commitment, pass the retained irradiance samples to the
+existing creator, which independently revalidates the temporal physical input:
+
+```ts
+const scene = calculateSceneSensorEqeTemporalExposure(input);
+const photo = createSensorEqeTemporalPhotoSignal({
+  temporalIntegrationId: "capture-site-temporal-001",
+  exposure: {
+    ...input.sensor,
+    samples: scene.value.opticalSamples.map(sample => ({
+      temporalSampleIndex: sample.temporalSampleIndex,
+      timeSecondsFromOpeningReference: sample.timeSecondsFromOpeningReference,
+      irradianceSamples: sample.optics.value.irradianceSamples
+    }))
+  }
+});
+```
+
+Use `photo.value.photoSignal` with separately calculated exact-event dark charge,
+charge completeness/capacity evidence and existing RAW/noise/readout inputs.
+Revalidation is not a second exposure contribution; use only one photo signal.
+The paired exporter continues to derive JPEG from the exact attached native RAW.
+
+## Limits and compatibility
+
+Provider results, targets and visibility remain declared approximations. The
+engine does not invoke a renderer, intersect scene geometry or redistribute PSF
+energy here. `sourceTargetProjectionVerified`, `sceneProviderExecutionVerified`
+and `psfRedistributionApplied` remain false. No calibration, combined uncertainty,
+convergence bound, physical accuracy, full-resolution/editor acceptance or
+production-stage activation is inferred. Requested missing capabilities still
+block in the production graph. The historical introduction left #16/#178/#112 open. They are now merged for their bounded scope; the full feature/science checklist is 32/32.
+
+This additive public API advances root API **0.110.0 → 0.111.0**, model 0.1.0.
+Package, POC, production, capture/RAW and noise/readout versions stay unchanged.
+Existing temporal validation diagnostics/arithmetic and historical file replay
+remain unchanged. New capture commitments receive the new root API stamp.
+Tests use Photivra-owned synthetic evidence, not third-party calibration. No new
+dependency, asset, network operation or cost is introduced.