@photivra/engine 0.5.1 → 1.0.0

package/docs/TEMPORAL_PHOTO_RAW.md

@@ -0,0 +1,83 @@
+# Temporal EQE photo signal to native RAW
+
+Release context: **package 1.0.0 candidate / root API 0.116.0**. 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.md).
+
+Root API **0.110.0** adds `createSensorEqeTemporalPhotoSignal()` and
+`parseSensorEqeTemporalPhotoSignal()`. RAW producer result schema is **0.3.0**.
+The compact `eqe-temporal-photo-signal` record enters the existing dark-current,
+accumulated-charge, capacity, stochastic readout and paired DNG/JPEG path.
+The full `eqe-temporal-quadrature-expected-counts` diagnostics remain distinct;
+casting or relabeling them is not an accepted handoff.
+
+## Construction and arithmetic
+
+Supply a public, nonpersonal `temporalIntegrationId` and an `exposure` request
+for [`calculateSensorEqeTemporalExposure()`](SENSOR_EQE_TEMPORAL_EXPOSURE.md).
+The creator evaluates that physical input again, checking response applicability
+and operating range at every time. It returns owned, frozen `photoSignal` plus
+the full `exposure` child envelope retaining evidence and uncombined uncertainty.
+No runtime dependency, third-party code/data or new cost is introduced.
+
+The compact record retains the exact site/channel/binding and local shutter
+start/end/duration, untreated photo-only flags, and 1–256 ordered samples of
+photon/electron rates in s^-1 at exact uniform midpoints. It has no stationarity
+ID, constant-photo-rate field or stationarity claim. The parser recomputes
+compensated sums of rate times `duration / sampleCount` in seconds and requires
+exact count agreement. It rejects unknown fields, sparse arrays, invalid public
+identities, nonfinite/negative values, stale midpoint times, electron rates
+above photon rates, invalid evidence and sampled/processed substitutions.
+Shared accumulation arithmetic prevents calculator/parser drift.
+
+```ts
+const temporal = createSensorEqeTemporalPhotoSignal({
+  temporalIntegrationId: "exposure-1-site-0",
+  exposure: temporalEqeInput
+});
+const photoSignal = temporal.value.photoSignal;
+const darkCharge = calculateSensorDarkCurrentCharge({
+  exposure: photoSignal, darkCurrentProfile, operatingTemperatureC
+}).value;
+const charge = { photoSignal, darkCharge, completenessProfile };
+// Supply the same exact event for every native site before RAW production.
+// simulateSensorRawFrame({ frame, sites, exposureWindow }) feeds paired export.
+```
+
+## Event and scientific boundaries
+
+Temporal dark charge carries the same `temporalIntegrationId`, never a fabricated
+stationarity ID. Dark current still uses the supplied fixed operating temperature
+and existing exact-temperature/interpolated profile rate times duration. Heating
+or varying temperature within an exposure is not integrated. Accumulated charge
+requires exact agreement of site/channel/binding, identity and start/end/duration;
+completeness/additional components and physical capacity remain separate gates.
+Both global windows and supported one-to-one rolling windows use the existing
+RAW timing calculation. Orientation never changes native seed ownership.
+
+The handoff validates arithmetic and declarations; an identity or evidence
+reference does not prove optical-source execution, authenticity or calibration.
+The instantaneous EQE model assumes applicability at each time without detector
+lag/hysteresis. Midpoint samples can miss short pulses/discontinuities and give
+no automatic convergence bound. No combined uncertainty is inferred. Source
+transport, projection, PSF, production-stage activation, high-resolution execution
+and external-editor acceptance remain separate #16/#178/#112 work. The 25/32 V1
+tracker count and umbrella status are unchanged.
+
+## Compatibility and acceptance
+
+Existing stationary photo/dark inputs remain accepted with their original result
+shapes, dark/charge model 1.0.0 and arithmetic. Narrow stationary calls retain
+their original TypeScript evidence shape through overloads and default generic
+types. `ComposeSensorPhotoAccumulatedChargeInput` and
+`SensorPhotoAccumulatedChargeComposition` expose the broader contracts; union
+inputs require normal type narrowing. Temporal dark/charge composition uses model **1.1.0** and
+the compact creator model is **0.1.0**. Capture noise model **0.2.0**, RAW readout
+model **2.0.0**, package/POC/production/RAW-frame schemas and stochastic seed
+schedule are unchanged. New capture provenance includes the new root stamp;
+historical capture replay and pinned paired-file hashes retain their stored stamp.
+
+[`test/temporal-photo-raw.test.ts`](https://github.com/Photivra/photivra/blob/main/test/temporal-photo-raw.test.ts) independently
+calculates SI photoelectron counts from two changing irradiance instants and
+checks dark/total counts, global/rolling events, deterministic RAW, exact DNG strip
+codes and JPEG lineage from the same frame. Malformed records and stale downstream
+bindings fail closed. Fixtures are owned synthetic regression data, not measured
+camera calibration or final V1 acceptance.

package/docs/TIER_ACCEPTANCE.md

@@ -0,0 +1,129 @@
+# Generic tier acceptance suite
+
+Release context: **package 1.0.0 candidate / root API 0.116.0**. 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.md).
+
+Fixture/report version **1.0.0** records the reviewed/merged #119 acceptance disposition
+for the exact Consumer, Prosumer and Professional preset assets **1.0.0**. This is
+Photivra-owned synthetic regression evidence with unquantified physical uncertainty,
+not measured equipment calibration, a perceptual bokeh score or a universal ranking.
+PR #204 merged after substantive owner review/DCO; final science conformance merged in PR #206.
+
+## Reproduce and review
+
+Run `node scripts/generate-tier-acceptance-report.mjs` after `npm ci` to regenerate
+[the committed report](validation/tier-acceptance-report-v1.json). An optional
+output path writes a separate comparison report. The generator uses a temporary
+TypeScript build, removes it afterwards, and has no published package surface.
+It does not change runtime profiles or dependency/version contracts.
+
+Run `npx vitest run test/generic-tier-report-acceptance.test.ts` for the report gates.
+The normative [versioned envelopes](https://github.com/Photivra/photivra/blob/main/test/fixtures/tier-acceptance-envelopes-v1.json)
+are finite regression limits, not physical error bars. Report JSON rounds displayed
+numbers to twelve significant digits; CI uses full-precision calculations and
+numeric tolerances. The report is a review artifact rather than a brittle exact
+image golden. Stable scene ID `photivra:tier-matched-reference-v1`, #130 optical
+state/exposure/seed, exact selected profile versions and complete catalog SHA-256
+bind the evidence. Saved selections retain their existing strict drift guard.
+
+## Three distinct report domains
+
+**Physical** records the nine exact 550 nm field/defocus pupil responses per lens,
+corner representative-channel CA, illumination falloff, breathing scale, in-frame
+and off-frame ghost/veil, and sampled physical edge values. Pupil diagnostics retain
+unit shape energy, separate relative throughput, peak/outer-sample fractions,
+centroid, full 2D covariance and horizontal/vertical/diagonal sampled texture response.
+The outer fraction is the boundary of the finite 5×5 kernel, not a measured optical
+ring. The 100 cycles/mm texture response is discrete OTF magnitude of those taps,
+not calibrated or continuous MTF. Existing #203 direct phase-sum tests independently
+validate every tap and execute controlled textured/highlight scenes for all 27 slices.
+
+**Correction costs** records full-Jacobian determinant, principal stretches and
+output magnification (reciprocal of the smallest destination-to-source stretch),
+corner gain and gain-only variance ratio, missing-source joint crop, retained ray
+bounds and separately captured pixel-edge FOV. Variance ratio is gain squared
+before clipping; it does not include covariance created by interpolation or imply
+that photons/SNR were restored. The shifted crop retains 7×9 of 9×9 requested
+samples, exposing the cost of unavailable support instead of padding it.
+
+**Corrected** records residual displacement/representative-channel CA, center and
+corner edge rows, clipping events and the unchanged capture/noise identities. The
+physical sampled target uses the existing inverse combined radial/CA map and
+illumination model at each source site, then adds one fixed alternating noise
+array tied to #130's seed. Correction Off/On forks that same frozen capture.
+Independent bilinear weights and polynomial gain predict all corrected green
+samples; existing #179 tests independently check every channel, Jacobian and
+residual using a scalar inverse oracle. The 9×9, 3 mm-pitch correction canvas is
+an explicitly specialized executor target; it does not redefine #130's sensor
+geometry or establish camera pixel resolution/optical MTF.
+
+Pupil clipping, normalized PSF redistribution, illumination attenuation, stray
+light and digital gain keep distinct ownership. These reports do not assert a
+new simultaneous radiometric composition of every lens effect. The supported
+narrow-band environment-to-RAW/output route and all nine pairings remain tested
+by #203; its explicit PSF omission and unity field throughput remain visible.
+
+## Intended relationships and honest unsupported metrics
+
+The versioned limits enforce all three tiers' finite multidimensional responses,
+sub-0.03 mm residual displacement, sub-0.06 mm residual CA, positive determinant,
+bounded magnification and retained crop. These are sampled regression envelopes,
+not a global continuous-field accuracy guarantee.
+
+Professional retains less corner clipping/stray light and smaller radial/CA
+coefficients, while its f/4 corner illumination and gain-only variance are worse
+than Prosumer. Its near/far pupil responses differ, and its near-defocus sampled
+texture response is lower than Prosumer's in this particular reference. Higher
+tier therefore does not require more digital correction or superiority in every
+metric. No aggregate sharpness/bokeh/quality score is computed.
+
+LoCA/spectral fringing, onion-ring structure, measured MTF, arbitrary field/focus/
+defocus interpolation and real-camera calibration are not represented by the
+initial assets. The suite names these unsupported metrics explicitly rather than
+fabricating numerical envelopes. Field and defocus comparisons use only their
+exact declared slices. No third-party calibration or branded behavior is added.
+
+## Body execution and ordinary flash
+
+New signed pitch/yaw/roll tests independently predict each tier's delayed linear
+response, pre-latency behavior, correction clamp and residual for ordinary and
+large disturbances of both signs. The supplied 1 ms latency, gain and angle limits
+own the differences. Panning bypass, translation, digital stabilization and
+support policy are not enabled by these exact assets; no substitute stop rating
+or device performance is inferred.
+
+An owned 2 ms mechanical opening/closing scan is explicitly registered under the
+exact mode/timing IDs required by each tier's flash capability. The tier's global
+DATA readout declarations remain independent. Front/rear placement follows the
+whole-frame exposure interval, never 30/15/8 ms data-readout duration. A declared
+2 ms triangular pulse integrates to 1 ms of relative-modulation time through the
+ordinary temporal source overlay and each local exposure window. No source power,
+material/visibility, TTL, HSS, recycle, or sensor signal is inferred from that integral.
+Too-short exposure, oversized pulse, HSS and stale timing identity reject.
+
+Existing #181 tests retain matched AF availability/hold/loss/release gates,
+drive cadence/timer limits, independent meter/AWB arithmetic and readout semantics.
+Existing #182/#203 evidence covers exact ISO/readout, all orientations, rendering
+exposure with unchanged native RAW and deterministic paired export. It is reused,
+not replaced by a second production path.
+
+## Browser/reference and acceptance disposition
+
+These tier assets have no separate browser approximation or private-app calibration
+backend. The browser-safe public functions are the ordinary reference path; #203
+checks that interactive/reference manifests share the same immutable executed
+results and fingerprints. No unimplemented preview is assigned an invented error
+bound. Any future approximation must add its own same-input fidelity comparisons.
+
+| #119 criterion | Evidence |
+| --- | --- |
+| All three tiers, deterministic versioned fixtures | Scene/envelope/report 1.0.0; exact selection references, catalog hash, replay |
+| Matched optical specifications | Stable #130 50 mm/f/4/5 m state; explicit 550 nm pupil slices and specialized targets |
+| Multidimensional bokeh | All 27 energy/throughput/centroid/covariance/outer/texture diagnostics plus #203 phase-sum and sampled scenes |
+| Physical/correction/final outputs separate | Three report domains, same frozen edge/noise state; #179 residual/Jacobian/support oracle |
+| Correction not monotonic by tier | Magnification/gain costs and explicit Prosumer/Professional tradeoff assertions |
+| Testable tradeoffs | Near/far asymmetry, axis/field response and contrary Professional/Prosumer metrics |
+| Profile drift visible | Complete catalog SHA-256, exact references, versioned envelopes and strict saved-selection parser |
+| Identical correction A/B state | Frozen source and fixed noise; independently predicted interpolation/gain; no remetering/re-noising |
+| Applicable browser fidelity | Same root implementation; shared immutable consumer results; no distinct approximation exists |
+
+This historical acceptance contribution changed no runtime/API/schema/asset/package/POC versions. Final performance #43/#45 and conformance #131 are now merged; #180 prepares the distribution without changing independent model IDs. No new V1 deferral is approved.

package/docs/TIER_PRESET_ACCEPTANCE.md

@@ -0,0 +1,59 @@
+# Generic tier preset acceptance disposition
+
+Release context: **package 1.0.0 candidate / root API 0.116.0**. 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.md).
+
+This is the reviewed/merged #116 asset/catalog disposition against engine API
+0.116.0 and production plan 0.7.0. The reviewed/merged release gate still applies.
+#119 owns broader calibration and acceptance fixtures; #131 owns final conformance.
+This document does not certify calibrated performance or silently approve a V1
+science deferral.
+
+## #116 acceptance evidence
+
+| Criterion | Implementation and evidence |
+| --- | --- |
+| Generic bodies/lenses; exactly three stable names | `generic-tier-assets.ts`; complete SHA-256 manifest fixture; labels Consumer, Prosumer, Professional |
+| Form, focal range and sensor format independent of tier | Explicit 50 mm prime assets; caller-owned geometry; selection flags; finite-state rejection tests |
+| Matching defaults and cross-tier compatibility | Exact-version selection and #109 capability resolution; all nine pairings through executed production and output |
+| Body/lens labels never enter scientific equations | Explicit resolved ISO/readout/transmission/pupil/correction profiles; independent photon transmission-ratio test and body-invariant photo expectation |
+| Bokeh from explicit profiles | All 27 finite pupil slices independently checked by direct phase summation and evaluated on the same controlled texture/highlight scene |
+| Matched optical conditions | #130 focal length, f/4, focus, exposure and seed reused; field/defocus variants remain explicit and do not modify the canonical fixture |
+| No universal Professional ranking | Existing Prosumer/Professional falloff and gain-noise tradeoff; near/far and field responses remain multidimensional |
+| Deterministic versioned definitions | Assets 1.0.0 and selection 0.1.0 unchanged; full manifest hash, immutable results, saved-profile drift rejection and replay tests |
+| Exact saved references | Strict parser pins every body/lens/science reference; unknown versions and aliases reject without fallback |
+| Physical/corrected outcomes distinct | Existing residual/CA/crop/Jacobian/interpolation/gain tests plus finite pupil scene correction Off/On using the same sampled capture/noise identity |
+| Applicable body/output execution | Existing AF/drive/meter/AWB/stabilization/readout tests and new nine-pair authoritative scene→RAW→processed-output→paired-file tests |
+
+## Ownership and limits
+
+#116 defines and demonstrates the supported generic preset assets. No new optical
+family, calibration dataset or tier-specific scientific engine is required for its
+catalog acceptance. The existing foundations own their ordinary validity envelopes.
+A lens with f/4–f/16 exposure capability has optical reference data only at f/4; the
+resolver rejects unsupported optical acquisition states rather than extrapolating.
+
+The new production fixture is a narrow-band ideal environment with independently
+owned synthetic sensor registration/response/capacity/color declarations. It uses
+exact tier readout profiles and transmission values via an explicitly identified
+capability-binding fixture bridge. Its coarse 2×2 raster proves binding/lineage and
+execution, not normal camera resolution or physical pixel pitch. Provider transport,
+visibility, sensor calibration and absolute color accuracy remain unverified.
+
+Exact complex pupils exist only at 550 nm, three field points and signed defocus
+−20/0/+20 µm. Their controlled sampled-scene tests use those exact slices. Production
+cannot silently interpolate them over spectrum/field/defocus, so its separate
+continuous-spectrum test explicitly omits PSF. Pupil throughput and illumination
+falloff retain separate ownership. No simultaneous composition is asserted.
+
+#119 has its reviewed/merged matched report/envelope and stabilization/flash
+acceptance disposition in [TIER_ACCEPTANCE.md](TIER_ACCEPTANCE.md), merged in PR #204. LoCA/spectral bokeh, measured MTF,
+manufacturer AF performance, arbitrary lens-state optical interpolation and external
+calibration are outside these initial assets' implemented representation; none is
+invented by catalog labels. Unsupported required effects continue to block under
+the authoritative production contract. #43/#45 remeasure the final consumers;
+#131 reviews final scientific conformance; #180 performs the final documentation
+and release audit.
+
+All new scene data and phase-sum calculations are Photivra-owned synthetic test
+material; no third-party calibration, brand profiles, dependencies or license changes.
+Root API 0.116.0, preset 1.0.0, selection 0.1.0 and all other versions are unchanged.