@photivra/engine 1.4.0 → 2.0.0

package/docs/SENSOR_EQE_TEMPORAL_EXPOSURE.md

@@ -1,74 +0,0 @@
-# Nonstationary EQE exposure quadrature
-
-Release context: **package 1.2.0 candidate / root API 1.2.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_2_0.md).
-
-`calculateSensorEqeTemporalExposure()` evaluates physical spectral irradiance at
-explicit local shutter midpoints, validates sensor response at every instant,
-and accumulates expected photons and photoelectrons. It reuses the instantaneous
-spatial/spectral reduction, applicability, operating-range, EQE and local binding
-steps used by `calculateSensorEqeLocalExposure()`. The stationary adapter's
-arithmetic, evidence and return shape remain unchanged.
-
-The shared input is the stationary adapter's input without `irradianceSamples`
-or `stationarityProfile`. Instead, `samples` holds `temporalSampleIndex`,
-`timeSecondsFromOpeningReference` and complete `irradianceSamples` for each time.
-All instants use the same site, profiles, native registration and shutter event.
-No stationarity profile is required or fabricated. Providers supply actual
-instant-specific values; this API does not execute a renderer or motion model.
-
-For local start `a`, duration `D` and `n` samples, temporal index `i` must have
-exact time `a + (i + 0.5) * (D / n)`. Times use the authoritative shutter's
-`first-opening-boundary-phase` reference, including rolling offsets. Callers
-must use this same arithmetic; a different/global clock or stale window fails.
-Times must be representable, interior and strictly increasing. Each node has
-integration measure `D/n` seconds and separate dimensionless average weight
-`1/n`. Only the seconds-valued measure multiplies the instantaneous rate.
-
-Expected counts are compensated sums of `photonRate_i * D/n` and
-`electronRate_i * D/n`. Counts retain fractional expectations. Spatial area,
-wavelength measure, response and temporal duration each apply once. Response
-operating validity is checked independently at every time; valid average
-irradiance cannot hide an invalid bright instant. AA/source support, response
-plane, per-bin validity and photon-energy basis retain the existing fail-closed
-rules. Child envelopes retain uncombined uncertainty and evidence.
-
-Coverage is complete and index-based; shuffled declarations produce identical
-canonical output. Missing, duplicate, sparse, out-of-range or mistimed samples
-reject. Execution allows 1–256 temporal samples and at most 100,000 supplied
-spatial × spectral × temporal irradiance nodes across the entire request.
-These are reference safety limits, not production-resolution performance claims.
-
-## Result boundary
-
-The distinct kind `eqe-temporal-quadrature-expected-counts` reports integrated
-photo expectations with `timeStationarityEstablished: false` and
-`timeVaryingSignalIntegrated: true`. It is **not** the existing stationary
-`SensorEqeExposureIntegration`. Dark/charge/RAW consumers reject this full diagnostic record;
-do not cast it, synthesize stationarity fields or relabel its kind. The explicit
-[temporal photo-signal handoff](TEMPORAL_PHOTO_RAW.md), added at root API 0.110.0,
-recomputes physical input and produces a distinct validated compact record.
-Dark current, completeness, physical capacity, noise, readout and RAW remain
-separate responsibilities. Production gates are unchanged.
-
-The field samples remain declarations. This calculation does not establish
-scene projection/visibility/PSF/transport, calibrated source truth, scene
-stationarity, detector bandwidth, quadrature convergence or propagated
-uncertainty. Shared response state assumes the existing instantaneous EQE model
-is applicable at each time; it does not model temporal response lag or hysteresis.
-Uniform midpoint sampling can miss short pulses or discontinuities; increase
-resolution and measure convergence against the actual quantity, or use a future
-explicit breakpoint/pulse model. No error bound is inferred from sample count.
-
-Tests use owned synthetic fields and independent SI photon-energy/area/response
-arithmetic. Constant fields match stationary counts; a quadratic field shows
-expected midpoint convergence; rolling offsets and single-instant operating
-range failure are verified. These are mathematical regression evidence, not
-photographic calibration. Separate [handoff acceptance](https://github.com/Photivra/photivra/blob/main/test/temporal-photo-raw.test.ts)
-now covers nonstationary RAW/export from owned synthetic inputs.
-
-This additive API advances root API 0.108.0 to **0.109.0**, with model 0.1.0.
-Package, POC, production, capture/RAW schemas and noise identities are unchanged.
-Historical replay retains its stored root stamp and pinned paired-file hashes;
-new capture identities may include the new API stamp. No dependency or cost is
-introduced. Remaining #16/#178/#112 work includes source execution, PSF,
-production activation and editor/resolution acceptance; this slice closes no umbrella ticket.

package/docs/SENSOR_PSF_QUADRATURE.md

@@ -1,90 +0,0 @@
-# Local sampled-PSF sensor quadrature
-
-Release context: **package 1.2.0 candidate / root API 1.2.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_2_0.md).
-
-`calculateSensorPsfIrradianceQuadrature()` applies the existing #113 sampled PSF
-resolver to incident spectral irradiance at each pre-AA sensor quadrature point.
-It is an explicitly declared **destination-local shift-invariant approximation**,
-not a complete field-dependent forward optical transport solver. Production
-stages remain gated; provider/projection/visibility execution remains separate.
-
-## Physical domains and coordinates
-
-Inputs are spatial/spectral sensor plans, `psf` resolver settings excluding the
-owned field position/wavelength, complete per-node `sourceSamples`, one finite
-`timeSecondsFromOpeningReference`, and evidence-backed `spatialModel` and
-`psfWavelengthBasis` declarations. `inputMeaning` must be
-`pre-psf-pre-sensor-stack-pre-aa-spectral-irradiance`.
-
-At every spatial/wavelength node, the destination is the sensor plan's
-`preAntiAliasingSourcePointMm` in **native +X-right/+Y-down** axes. The lens PSF
-query uses `{x: destination.x, y: -destination.y}` in **image-plane +Y-up** axes.
-Wavelength comes from that exact spectral node. Schema 0.1.0 sampled PSF profiles
-lack a wavelength-basis field, so the extra evidence declaration explicitly binds
-the source profile's wavelength meaning to the plan's air/vacuum basis. The
-adapter neither infers nor converts the basis.
-
-For kernel column `j` and row `k`, the image-plane displacement is
-`((j-centerX)*pitchX, (k-centerY)*pitchY)` in micrometres. Inverse sampling in native
-sensor millimetres therefore reads:
-
-```text
-source.x = destination.x - (j-centerX)*pitchX/1000
-source.y = destination.y + (k-centerY)*pitchY/1000
-```
-
-Each tap must have exactly that `sourcePointNativeSensorMm`, the same instantaneous
-time, unique integer X/Y kernel indices, and finite nonnegative **W/m²/nm**.
-All taps, including zero-weight taps, must be supplied. Array order is irrelevant;
-results retain canonical wavelength/spatial/kernel order and owned source copies.
-No off-sensor support is clamped, mirrored, repeated or dropped. Missing support
-fails; it never triggers renormalization or a smaller blur kernel.
-
-## Weighting and downstream handoff
-
-The output at one node is `sum(kernel.normalizedIntensity[i] * E_lambda(source_i))`.
-The #113 resolver owns kernel interpolation/normalization and its finite-support
-meaning. These weights are discrete unit-energy shape weights, not irradiance
-density, area, optical transmission, QE or shutter measures. Do not multiply them
-by kernel cell area a second time.
-
-`relativePupilThroughputFactor` is retained in each resolved PSF child envelope
-and is **not applied** by this adapter. The upstream optical-throughput path must
-own it exactly once. Likewise, do not independently add diffraction/defocus/other
-effects already included by `responseIncludes`, or pass already blurred input
-under a pre-PSF declaration. Declarations do not establish upstream execution.
-
-The existing irradiance reducer applies sensor aperture/AA/spectral measures
-once to the resulting pre-AA samples. Its returned `reduction` is diagnostic;
-when handing `irradianceSamples` to `calculateSensorEqeTemporalExposure()`, use
-the samples directly without multiplying the diagnostic reduction again. Compute
-this PSF adapter separately at each exact local shutter midpoint; the downstream
-sensor adapter validates response and operating range before integrating EQE
-rates. Existing compact temporal photo/dark/charge/RAW/file contracts stay intact.
-
-## Explicit limits
-
-`psfRedistributionApplied` is true only for this named local approximation.
-`localShiftInvarianceEstablished`, `globalFieldEnergyConservationEstablished`
-and `sceneProviderExecutionVerified` remain false. A kernel resolved at the
-destination is not equivalent to spatially varying forward transport
-`E_out(q)=integral E_in(s)*h_s(q-s) ds`; depth/visibility changes within its support
-also require a richer solver. The supplied limitation/evidence remains visible.
-No calibrated photographic accuracy, combined uncertainty, infinite-tail
-convergence or production capability is asserted.
-
-The aggregate spatial × spectral × kernel input budget is 100,000 source nodes,
-checked before per-node PSF resolution. Existing PSF profile and sensor plan
-validity/coverage gates remain unchanged. Approximation output retains all child
-PSF evidence/uncertainty and explicit basis/spatial-model declarations.
-
-Tests use owned synthetic profiles: uniform light preserves irradiance independent
-of pupil throughput; an asymmetric affine field independently predicts inverse
-X/Y offsets; distinct wavelength shapes remain distinct; temporal sensor handoff
-matches SI photon/EQE expectations. Missing/duplicate/sparse/negative support,
-coordinate/time/basis/stage/model/evidence drift and work overflow reject.
-
-Root API **0.111.0 → 0.112.0**, model 0.1.0. No existing public contract is
-reinterpreted; package/POC/production/RAW/noise versions are unchanged. Historical
-capture/file replay keeps its stored API stamp. No dependency, third-party asset,
-network access or cost is introduced. At this introduction checkpoint, #16/#178/#112 were open and V1 was 25/32. They are now reviewed/merged; final conformance is complete.

package/docs/SENSOR_RAW_FRAME.md

@@ -1,20 +0,0 @@
-# Native sensor RAW frame attachment
-
-Release context: **package 1.2.0 candidate / root API 1.2.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_2_0.md).
-
-See [Reference RAW frame compatibility](RAW_FRAME_ENVELOPE.md) for stage-specific
-limits, full-native counting and parser preflight behavior.
-
-`createSensorRawFrame()` commits #14 `SensorRawCaptureSample` values alongside one immutable #15 capture. `parseSensorRawFrameInput()` validates the untrusted attachment boundary. Schema `0.1.0`, historical introduction root API `0.98.0`; package/POC/capture/production contracts stay unchanged. The attachment is merged and current root API is 1.0.1.
-
-The first slice accepts single-frame native-effective capture modes with an explicitly evidenced one-site-per-native-sample binding and periodic mosaic topology. The entire native frame must be provided in native row-major order, one sample per site. Absolute CFA phase, site/channel assignment, capture-mode/profile/readout identity and every per-site seed are preserved. RAW samples are never rotated, cropped, demosaiced, balanced or tone-mapped. Active capture/output geometry stays in the attached metadata; it never resets CFA phase.
-
-The 16-bit container holds integer RAW codes without re-quantization. Black and digital-saturation codes remain per-site metadata, with a positive span. Codes below black are retained; their black-subtracted normalized values can be negative. A code cannot exceed its declared digital maximum. Stored codes and normalization must agree exactly with the existing #14 formula. Physical and digital saturation flags remain distinct. This does not infer ADC bit depth, physical full well, a spectral camera color matrix, or calibrated sensor behavior.
-
-The frame's `producerBinding` is explicitly `caller-declared-capture-attachment`. Validation proves structural consistency, not that a caller actually ran the engine or that supplied linear planes were reconstructed from these RAW samples. Consumers must carry an actual same-capture producer/reconstruction handoff before claiming a paired JPEG. The attachment does not render pixels, manufacture RAW by masking RGB, or certify DNG/editor interoperability.
-
-Structural attachment is limited to 65,536 native samples; reference producer/reconstruction/export execution is limited to 4,096. External storage, streaming/high-resolution writers, grouped/remosaiced/layered/multi-frame modes and alternate RAW packing require separately explicit contracts. A new frame copies and freezes all records; caller-owned arrays remain mutable. This conservative reference implementation performs per-site authoritative binding validation and is not a 24/45/60 MP memory/performance claim.
-
-This is a prerequisite slice of #16. Remaining work includes canonical export metadata/pairing, DNG tag/color/WB mapping and specification/patent-notice review, an optional writer, same-RAW reconstruction through #112, standalone JPEG encoding, independent decode/Adobe acceptance and measured memory limits. TIFF/Linear DNG cannot replace the required genuine RAW DNG + standalone JPEG pair. #165 C2PA stays post-V1.
-
-Implementation and structural fixtures are independently authored. Fixtures contain declared synthetic code records and are not a sensor calibration or evidence of RAW-to-RGB numerical agreement. No new dependency, third-party material, IO, service or cost is introduced.

package/docs/SENSOR_RAW_PRODUCER.md

@@ -1,77 +0,0 @@
-# Capture-owned native sensor RAW producer
-
-Release context: **package 1.2.0 candidate / root API 1.2.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_2_0.md).
-
-See [Reference RAW frame compatibility](RAW_FRAME_ENVELOPE.md) for stage-specific
-limits, full-native counting and parser preflight behavior.
-
-## Temporal photo signal — root API 0.110.0
-
-Producer result schema **0.3.0** accepts both the original stationary EQE result
-and the distinct compact `eqe-temporal-photo-signal` record. The latter requires
-validated ordered midpoint rates and exact count sums, no stationarity fields,
-and matching `temporalIntegrationId` on dark charge. See
-[TEMPORAL_PHOTO_RAW.md](TEMPORAL_PHOTO_RAW.md) for construction, type compatibility,
-global/rolling paired-file acceptance and scientific limits. Noise/readout
-identities, native seeds and stationary arithmetic are unchanged.
-
-## Signed electronic shadows — root API 0.106.0
-
-The required `photivra-native-raw-noise` capture model is now **0.2.0**, preserving the existing per-site seed schedule while binding corrected readout behavior. `simulateSensorRawCode()` provenance uses `sensor-raw-code-stochastic-readout` model **2.0.0**. Physical stored charge remains nonnegative; after Gaussian electronic read noise, the signal may be negative. Apply only the upper pre-ADC saturation threshold, then conversion gain and black pedestal, round-half-up quantization, and clamp to `[0, digitalSaturationCode]`. Below-black integer codes survive when they fit the unsigned ADC range. `lowerCodeClampApplied` is true only when the quantized code is below zero. A negative electronic signal is not negative stored charge or physical saturation.
-
-Earlier behavior clamped the electronic signal to zero before adding the black pedestal, biasing shadows and making below-black producer values impossible. Positive electronic signals retain their code math, but result provenance and capture noise identities change. Replay requests carrying producer noise model 0.1.0 fail closed. For a deliberate recomputation, recreate the capture with model 0.2.0, keep its original seed, preserve the old artifact as historical output and record changed model/API identity. Do not relabel old codes as newly generated codes. Existing archived RAW-frame attachments remain a separate structural contract and are not automatically regenerated by this correction. Producer/profile/frame schema versions and package/POC versions do not change; the historical section below describes the original handoff.
-
-`simulateSensorRawFrame()` connects existing sensor charge/capacity/stochastic/readout contracts to `createSensorRawFrame()`. It computes codes rather than accepting fabricated site codes or masking an independent RGB plane. The returned frame feeds existing same-RAW reconstruction and `createPhotographicExportPair()` without another ADC quantization or RNG pass. This closes a bounded producer handoff gap, not the complete physical production composer or #16/V1 acceptance.
-
-Input has `frame` (the existing RAW-frame metadata/profile input without samples) and dense `sites` in full native row-major order, limited to 4,096 sites. Only single-frame native-effective periodic CFA with exactly one native sample per color site is accepted. Grouped/remosaiced/multi-frame acquisition is rejected. Full native coverage remains unchanged by active crop, output crop or orientation. Each site provides untreated EQE photo/dark exposure results, additional charge/completeness inputs, charge sampling and capacity profiles, explicit operating state, explicit readout profile and regime. No profile is inferred from ISO or copied from a different channel/site.
-
-The parser checks new fields and photo/dark result fields against allowlists, normalizes evidence through existing provenance parsers, and delegates existing profile/completeness rules to their existing parsers. Runtime checks reject already sampled/clipped/ADC/WB/processed substitutions, A/W charge, inconsistent constant-rate products or temporal rate integrals, missing/reordered/sparse sites and stale CFA/channel/event identity. A stationarity/completeness declaration remains evidence supplied by the upstream producer, not independent verification of pixel truth. The incident-count domain requires expected photoelectrons not exceed expected photons; effective gain/carrier models outside that EQE domain require a separate contract.
-
-Omitting `exposureWindow` preserves the **global exposure window**: all local windows are exactly 0 to committed `shutterSeconds` from `first-opening-boundary-phase`, with exact nominal duration and site binding ID.
-
-An explicit `exposureWindow` supplies shutter mechanism, sourced nominal duration, and opening/closing schedules from the existing exposure-window contract. Nominal duration must exactly match committed `shutterSeconds`. The producer owns the full native timing rectangle and row-major sample centers `(x+0.5,y+0.5)`; caller-supplied raster, active crop or sample coordinates are rejected. Full-native boundary traversal must be supplied explicitly; an active crop never scales it. The existing engine timing calculation validates affine extrema over the entire native rectangle and computes each local start/end/duration. Every photo/dark/additional/completeness event must match that exact site window. Stationarity remains a declaration for each local event, not a conclusion from rolling timing. The optional `localExposureWindows` child result preserves timing assumptions, evidence and computed windows.
-
-This accepts stationary or explicitly integrated temporal per-site photo expectations under simultaneous or uniform-linear electronic/mechanical/EFCS boundaries; it does not execute moving/time-varying scene transport, predict rolling-shutter geometry, synchronize data readout, or activate reserved production stages. Multi-frame and non-one-to-one timing remain unsupported. The RAW-frame schema and export metadata remain unchanged: `shutterSeconds` is nominal, not a claim that every local site duration equals it. Persist the producer timing result separately when local-window replay evidence is required. Timing evidence and upstream charge origin remain caller declarations, not independently verified transport truth. Capacity uses the supplied dark-result temperature and explicit operating state, independently from ISO. The engine re-composes total photo/dark/additional expectations and checks evidence-backed completeness before assessing capacity.
-
-Capture noise model must equal `SENSOR_RAW_PRODUCER_NOISE_MODEL` (`photivra-native-raw-noise`, version 0.2.0). Noise realization ID stays unchanged. The versioned seed schedule is charge seed `(capture.seedUint32 + 2*n) mod 2^32`, read-noise seed `(capture.seedUint32 + 2*n + 1) mod 2^32`, for native row-major index n. Both identities are preserved per RAW site, including unsigned wrap. Seeds are distinct within a frame; this is deterministic ownership, **not proof of statistical stream independence**. Existing Poisson and normal sampling implementations are reused, with their existing numerical/model limitations. No backend/global randomness is used.
-
-Order delegates to existing APIs: accumulated-charge completeness → physical-capacity assessment → stochastic charge realization → scalar physical saturation → read noise → pre-ADC saturation → conversion gain → ADC quantization/digital clamp → native CFA sample → immutable frame. Expected charge is never overwritten by realized/clipped charge. Physical scalar, pre-ADC, lower-code and digital saturation, overflow diagnostics and child provenance remain separate. Scalar saturation is the existing approximation, not a blooming/neighbor-transfer model. Capacity uncertainty is not propagated into stochastic saturation or output codes.
-
-All sites share the existing frame contract's readout profile ID/regime; channel-specific profile payloads remain explicitly bound to their respective channels. The original per-channel profiles are revalidated for each site, never rewritten from one channel to another. Uint16 storage requires ADC depth ≤16 and a positive black-to-digital-white span. Larger or varying readout identity/regime contracts need a separate RAW-frame schema; the producer does not bypass those constraints.
-
-Result schema 0.3.0 declares `codeProducer: "engine-charge-capacity-noise-adc"`, `upstreamOrigin: "declared-eqe-and-dark-exposure-results"`, `upstreamRadiometryVerified:false`. Child results preserve their own evidence/status; aggregate provenance is approximation. The existing attachment retains `producerBinding:"caller-declared-capture-attachment"` for compatibility: structural frame validity is not cryptographic evidence of upstream execution. Archive replay of a frame does not establish engine origin; downstream export's conservative origin-verification flag stays false.
-
-Independent float capture planes are not RAW inputs, are not replaced, and are not claimed reconstructed from generated RAW. The same-RAW exporter must consume the returned frame, whose JPEG derives from those exact stored codes. Capture exposure/focus/source/noise/geometry remain intact; no prepared production context or physical scene radiance is claimed by this adapter.
-
-Tests independently compare every generated site with existing per-site primitives, verify deterministic unsigned seed wrap and native CFA through all orientations, separate saturation stages, reject stale/treated/missing inputs and inspect DNG strip bytes from generated RAW plus deterministic same-RAW JPEG. Synthetic fixture EQE/dark/count/capacity/readout data is independently authored, not a measured calibration or externally validated radiance pipeline. No runtime dependency, third-party code/data or new cost is added.
-
-This additive timing handoff updates root API 0.103.0 → 0.104.0 and producer result schema 0.1.0 → 0.2.0. Existing input without timing remains valid with identical RAW codes/seed ownership. Package/POC/capture/RAW-frame/production and noise schedule versions are unchanged. Human science/provenance review and new contribution-specific DCO are required. Remaining work includes independently bound scene/spectral-response→exposure production input, source execution and PSF, reserved production-stage activation, broader output sampling support, high-resolution limits and Adobe/open-editor acceptance. None is marked complete here.
-
-Example timing override (schedules refer to the full native raster):
-
-```ts
-const result = simulateSensorRawFrame({
-  frame,
-  sites, // Each declared charge event must already match its computed local window.
-  exposureWindow: {
-    shutterMechanism: "electronic",
-    nominalExposureDurationSeconds: { value: frame.capture.exposure.shutterSeconds, unit: "s", evidence },
-    opening: {
-      kind: "uniform-linear-native-scan",
-      directionNative: { value: "top-to-bottom", evidence },
-      traversalDurationSeconds: { value: 0.001, unit: "s", evidence }
-    },
-    closing: {
-      kind: "uniform-linear-native-scan",
-      directionNative: { value: "top-to-bottom", evidence },
-      traversalDurationSeconds: { value: 0.001, unit: "s", evidence }
-    }
-  }
-});
-```
-
-The 1 ms traversal is an illustrative declared approximation, not camera calibration. Changing it requires corresponding per-site exposure results; this API does not rescale old charge counts.
-
-## Irradiance-to-photo-exposure composition
-
-[`calculateSensorEqeLocalExposure()`](SENSOR_EQE_LOCAL_EXPOSURE.md) now produces the existing `charge.photoSignal` value from explicit irradiance nodes through response validity, EQE and stationary local integration. It retains child envelopes and declares scene/optics origin unverified. Dark/completeness and readout inputs remain explicit; this does not activate production stages or change the producer schema.

package/docs/SIGNAL_CONFORMANCE.md

@@ -1,23 +0,0 @@
-# Signal cross-domain conformance (#131B)
-
-Release context: **package 1.2.0 candidate / root API 1.2.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_2_0.md).
-
-`test/signal-conformance.test.ts` independently covers merged public APIs without consuming unmerged capture, output, optics or tier work. It complements the geometric conformance draft rather than depending on it. The canonical #130 fixture supplies wavelength and reference aperture/shutter/ISO settings; its source irradiance is **not** silently treated as detector energy.
-
-The explicit thought experiment supplies 4e-17 J already incident at one measurement region, constant test QE 0.5 and independent RMS read noise 3 electrons. These are Photivra-owned illustrative inputs, not calibrated equipment values. Vacuum wavelength is declared for this analytic variant. No photosite area is inferred from image sampling pitch, and no continuous spectral density is reinterpreted as a delta line.
-
-Independent expectations use exact SI h and c, E_photon = hc/lambda, mean electrons = incident energy / E_photon × QE, and SNR = mean electrons / sqrt(mean electrons + read noise squared). Relative optical exposure scales the supplied reference energy only under the explicitly stationary ideal t/N² thought experiment.
-
-Covered invariants:
-
-- Fractional mean electron counts survive without rounding; repeated evaluation is exact and deterministic.
-- Doubling duration doubles mean signal but increases shot-limited SNR by sqrt(2), not 2.
-- Half the exposure duration plus double nominal ISO preserves nominal rendered exposure, but not mean physical signal or signal-to-noise ratio. ISO does not create photons.
-- At fixed supplied energy, doubling vacuum wavelength doubles photon/electron expectations **only for this declared constant-QE experiment**, not a real sensor spectral response claim.
-- Zero QE produces JSON-safe zero SNR/null dB; invalid photon counts fail before downstream noise calculation.
-
-Normalized floating-point ratios use 13-decimal-place tolerances to avoid absolute tolerances inappropriate for joules around 1e-19. This is arithmetic/regression evidence, not a quantified physical uncertainty.
-
-This suite intentionally does not authorize a production radiance-to-RAW path. Spectral quadrature, response applicability, collection area, local exposure/stationarity, dark current, full-well, stochastic realizations, analog/ADC clipping and reconstruction keep their existing separate gates. The primitive calculation provenance does not upgrade these illustrative inputs to calibration. It does not exercise a sensor temperature or real-camera ISO mode.
-
-No API/runtime/version/dependency change. #131 closed through reviewed/signed PR #206; the final integrated conformance suite covers merged paths, outputs, presets and performance dispositions. This earlier slice remains independent evidence.

package/docs/SIMULATED_CAPTURE.md

@@ -1,65 +0,0 @@
-# Authoritative simulated capture: #15A/#15B
-
-Release context: **package 1.2.0 candidate / root API 1.2.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_2_0.md).
-
-The container commits a format-neutral float master manifest before tone mapping/LDR conversion. It does not itself generate or convert pixels. The separate [#15B color API](CAPTURE_COLOR.md) converts supported planes and [#15C encoding API](LINEAR_CAPTURE_ENCODING.md) quantizes them without mutating the master. TIFF/DNG serialization and production-stage activation remain separate. #15, #112 and #16 are merged. Their explicit adapters own rendering and paired export; the container alone performs neither.
-
-## Image state and storage
-
-`createSimulatedCapture()` validates, copies and deeply freezes input. Its calculated provenance describes structural commitment; upstream model status/evidence identities are preserved independently, never upgraded to calibrated/radiometry-ready.
-
-Planes have separate IDs/image-state IDs, exact raster binding and co-sited, tightly interleaved channels. Row order is top-left origin, +X right/+Y down. Native CFA/mosaic semantics are not inferred from multiple channels.
-
-| State | Required meaning |
-| --- | --- |
-| scene-referred-xyz | X,Y,Z order; explicit cie-1931-2-degree-xyz profile 1.0.0 and normalized encoding white |
-| virtual-sensor-channels | Declared channels/source profile; colorimetric transform/encoding white unresolved |
-| color-transformed-linear-rgb | red,green,blue order; encoding profile/white and explicit linear-color transform history |
-
-Samples are relative linear values normalized by referenceWhiteValue, not absolute radiance, photons, electrons or measured commercial-camera RGB. Finite negative values/headroom remain unchanged; NaN/Infinity and sparse arrays fail. Inline signed zero becomes ordinary zero for semantic serialization.
-
-Inline Float64-valued JavaScript number arrays have a one-million-sample aggregate budget. Large images use external-float32/64 references: IEEE 754 little-endian scalars, no header/padding, tightly interleaved row/channel order, complete-plane sample count, opaque public artifact ID and lowercase SHA-256 over exact bytes. No path/URL/runtime IO is introduced. The engine does not read/verify external bytes, finite values, digest or source quality; a future loader must do so before consuming samples. Declared storage precision is not an assertion about renderer precision.
-
-XYZ observer identity documents meaning without spectral integration or copied color tables. RGB profile references are preserved, not resolved into a transform by #15A. A serializer cannot infer color coefficients from a profile name. `resolveSimulatedCapturePlane()` requires the exact requested image state.
-
-## Geometry and deterministic commitment
-
-Reuse of ResolveCaptureGeometryInput preserves native, active, oriented and output geometry, off-center regions and four orientations. Planes must match oriented active capture or output dimensions. Exposure/focal metadata and finite/infinity focus remain explicit. The existing diagonal equivalent-focal-length calculator uses active physical capture; output crop never rewrites it.
-
-Scene time is seconds on the producer's scene clock. Fixed uint32 noise seed, realization/model identity, source checksums, public profile/evidence IDs and engine API version are retained. A seed alone does not prove pixel reproduction; the container does not rerun a renderer/noise generator.
-
-`parseSimulatedCapture()` recomputes and verifies derived geometry/focal equivalence and preserves historical creator API identity. `serializeSimulatedCapture()` emits normalized allowlisted JSON independent of input object property order; list order remains semantic. This is a manifest, not TIFF/DNG or a new cryptographic semantic hash.
-
-## WB, whites and saturation
-
-`createCaptureWhiteBalanceIntent()` consumes #108 resolved state and copies public state/profile identity, source, lock and gains; measurement/debug/free-text extras are discarded. It introduces no AWB estimator or true-illumination oracle:
-
-```ts
-import { resolveManualWhiteBalance, createCaptureWhiteBalanceIntent } from "@photivra/engine";
-const state = resolveManualWhiteBalance({
-  stateId: "wb-1", channelGains: { red: 2, green: 1, blue: 0.5 }
-});
-const intent = createCaptureWhiteBalanceIntent({ state });
-```
-
-Intent and plane application are separate: intent-only, applied-rgb-gains, applied-chromatic-adaptation or not-applicable. Applied gains require compatible RGB channels/resolved intent. Applied adaptation requires adopted white, transformed RGB and explicit adaptation history, independently of RGB intent. Recording does not verify upstream application; the separate #15B API performs actual conversion. Camera RGB gains cannot be directly declared applied to XYZ.
-
-Adopted white and encoding white remain separate normalized XYZ records (Y=1, positive X/Z). Null adopted white is unresolved, not an implicit D65/encoding white. No single physically unique white is claimed under mixed illumination.
-
-Source dynamic-range history is unknown, no-loss-declared or upstream-clipped. Float64 cannot recover prior clipping. Capture saturation is independently unmodeled or a declared virtual white level/upstream clipped-sample count. Reference white, capture saturation, future integer limits, rendering exposure and display white are separate. This API neither clamps samples nor infers clipped counts from values equal to white.
-
-## Public metadata and limits
-
-Unknown fields fail at capture/source/geometry/exposure/model/plane/transform/storage/WB-manifest boundaries. Public opaque IDs/versions permit ASCII alphanumerics plus dot/underscore/colon/hyphen, maximum 128 characters. Paths, slash-bearing URLs and emails fail. No private paths, prompts, internal URLs, proprietary manifests, names/emails, precise locations or hidden debug fields are supported.
-
-Producers must select genuinely public, non-personal IDs. Syntax cannot prove an otherwise valid ID is non-sensitive. Public-ID registry/provenance review remains the producer's responsibility; no arbitrary free-text metadata bag exists.
-
-## Versioning and evidence
-
-Schema is 0.2.0; legacy 0.1.0 archives normalize to 0.2.0 while preserving creator API identity. The new applied-chromatic-adaptation state cannot be declared in a 0.1.0 archive. Re-serialization emits the current schema, so archive bytes change on migration. Root API advances main 0.95.0 to 0.96.0. Package, POC and production contracts are unchanged. This independent branch consumes no pending #157/#158 code; reconcile API identity in final merge order.
-
-Tests reuse #130's canonical fixture for geometry/settings/seed, and cover unclamped data, immutable/canonical archive round trips, four orientations/off-center capture, active/output equivalence, WB sanitization/intent/application, image-state substitution, RGB history, large external planes, saturation distinction, private/malformed metadata, infinity and historical identity.
-
-Implementation/tests are independently authored; no third-party code, calibration data, color tables or protected prose included. Factual references: [CIE 1931 system](https://www.cie.co.at/eilvterm/17-23-045) establishes XYZ/observer semantics; [Academy encoding documentation](https://docs.acescentral.com/encodings/introduction/) distinguishes linear/interchange and downstream encoding. Neither provides coefficients or imposes ACES.
-
-AI-assisted draft requires substantive human science/provenance review and DCO certification under CONTRIBUTING.md/PROVENANCE.md before inclusion.

package/docs/STABILIZATION.md

@@ -1,234 +0,0 @@
-# Camera Shake and Stabilization
-
-Release context: **package 1.2.0 candidate / root API 1.2.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_2_0.md).
-
-Photivra separates deterministic projection geometry from a deliberately simplified educational stabilization model.
-
-## Controlled camera shake
-
-`estimateCameraShakeBlur()` accepts constant camera angular velocity around two axes:
-
-- yaw, in radians per second;
-- pitch, in radians per second.
-
-For shutter-open duration `t`, each angular displacement is:
-
-`theta = angularVelocity * t`
-
-The image-plane component is projected as:
-
-`d = v * tan(theta)`
-
-where `v` is the projection distance in millimetres.
-
-Projection has two modes:
-
-- without `focusDistanceM`, `v` is nominal focal length (the infinity-focus compatibility approximation);
-- with `focusDistanceM`, `v` is the ideal Gaussian thin-lens image distance for the selected focus plane.
-
-When pixel pitch is supplied, the same displacement is also reported in sensor pixels.
-
-The returned X/Y shake components are expressed in the primitive's sensor/image-plane axes. `estimateCameraShakeBlur()` does not accept `CaptureOrientation` and does not rotate its vector into portrait/oriented output coordinates. A caller combining this primitive with the capture-orientation layer must explicitly transform the vector with the orientation helpers.
-
-The supplied shake profile is synthetic input. The model is not an empirical statement about how much a particular photographer shakes.
-
-### Spatial limitation and the separate rotation primitive
-
-`estimateCameraShakeBlur()` intentionally remains one global image-plane yaw/pitch vector for backwards compatibility with the existing stabilization-equivalent teaching model.
-
-The root engine now separately exposes `calculateCameraRotationImageMapping()`, which models field-position-dependent **pure camera rotation** for yaw/pitch/roll at arbitrary physical time from exposure start.
-
-The two APIs do not share sign semantics:
-
-- the legacy shake estimator preserves its historical direct image-plane displacement convention;
-- the spatial rotation primitive represents physical camera rotation using right-hand pitch/yaw/roll, then maps a stationary world ray through the inverse camera rotation.
-
-Do not substitute one result for the other without an explicit migration.
-
-The spatial primitive does not apply stabilization stops. The separate time-domain stabilization system now provides generic synthetic rotational IBIS/OIS/coordinated correction; translation/parallax and mechanism-specific ray-geometry effects remain separate.
-
-## Time-domain physical stabilization system
-
-The #97 foundation adds a separate, versioned physical-stabilization model for time-varying rotational disturbance.
-
-It does **not** replace or reinterpret the legacy `estimateCameraShakeBlur()` API.
-
-### Disturbance trajectory
-
-`parseStabilizationDisturbanceTrajectory()` describes camera rotational displacement over the same capture-reference clock used by #12:
-
-`first-opening-boundary-phase`
-
-The first schema requires:
-
-- a zero-displacement sample at `t = 0`;
-- strictly increasing sample times;
-- explicit pitch/yaw/roll displacement in radians;
-- no embedded subject motion;
-- no embedded camera translation;
-- no embedded support/tripod state.
-
-This preserves the architecture:
-
-```text
-physical disturbance -> stabilization response -> residual rotation -> exposure-time image formation
-```
-
-Stable support remains simply an explicit zero disturbance trajectory. It does not automatically switch stabilization on or off.
-
-### Generic physical architectures
-
-`parseStabilizationSystemProfile()` supports generic synthetic:
-
-- `off`;
-- `sensor-shift`;
-- `lens-optical`;
-- `coordinated-physical`.
-
-Schema 0.1.0 deliberately does not claim branded camera/lens behavior.
-
-Each corrected axis can declare:
-
-- correction gain from 0 through 1;
-- response latency in seconds;
-- maximum image-equivalent angular correction in radians.
-
-The first dynamic response is:
-
-```text
-requested correction(t)
-  = gain × disturbance(t - latency)
-
-applied correction
-  = symmetric clamp(requested correction, angular limit)
-
-residual
-  = current disturbance(t) - applied correction
-```
-
-Before the latency interval has elapsed, the delayed measurement is zero.
-
-This is an explicit generic approximation. It is not a CIPA stop-rating conversion, control-loop identification, or commercial IBIS/OIS calibration.
-
-### Coordinated body + lens behavior
-
-A `coordinated-physical` profile includes explicit body/lens allocation fractions that sum to one.
-
-Those fractions describe ownership of **one total correction**. The engine does not apply body correction and lens correction independently and then add them again.
-
-This prevents coordinated stabilization from double-counting correction.
-
-### Panning
-
-The model never infers pan intent.
-
-A profile may explicitly use:
-
-`declared-axis-bypass`
-
-for one pitch/yaw/roll axis. Correction on that axis is then suppressed while the other declared axes continue to use the selected response.
-
-### Correction limits
-
-Angular travel/range limits are explicit.
-
-If requested correction exceeds an axis limit, the applied correction is clamped and the result reports `correctionLimitReached: true`.
-
-The engine does not produce unlimited correction merely because a profile has high gain.
-
-### Capture-time sampling
-
-`calculateStabilizedCaptureTemporalSamples()` evaluates stabilization at deterministic midpoint nodes inside each committed #12 local exposure window.
-
-This is especially important for rolling/local exposure timing: two native sensor positions may evaluate the same disturbance/stabilizer at different capture times.
-
-Sensor **data-readout timing is not used as exposure timing**.
-
-The result reports disturbance, applied correction and residual rotation at each node. It does not itself calculate:
-
-- image-plane mapping;
-- radiance;
-- blur kernels;
-- PSF;
-- final pixels.
-
-Those remain downstream image-formation responsibilities.
-
-### Explicit boundaries
-
-The first time-domain model does not include:
-
-- camera translation/parallax correction;
-- sensor-shift position within the lens image circle;
-- OIS lens-group ray-geometry changes;
-- spontaneous stabilizer drift;
-- settling/recentering transients beyond declared latency;
-- inferred panning;
-- support/tripod auto-detection;
-- shutter shock or wind/floor vibration generation;
-- digital/electronic stabilization.
-
-Digital stabilization remains downstream geometric warp/crop/resampling work and must preserve any field-of-view/crop consequences rather than being represented as physical residual camera motion.
-
-## Ideal stable support boundary
-
-Photivra's current **ideal stable support** is an explicit zero-disturbance boundary condition, not a separate blur equation and not a claim that real tripods are vibration-free.
-
-Represent the boundary by supplying:
-
-```ts
-angularVelocityRadPerSec: {
-  yaw: 0,
-  pitch: 0
-}
-```
-
-With this explicit input:
-
-- unstabilized shake displacement is exactly zero;
-- stabilized shake displacement is also exactly zero for any `stabilizationStopsEquivalent`;
-- focal length, shutter duration, finite-focus projection, infinity/pinhole projection, and pixel pitch do not create motion from a zero-motion input;
-- subject motion remains independent;
-- physical orientation/output transforms preserve the zero vector.
-
-Do **not** represent stable support by an arbitrarily large stabilization-stop value. Stabilization attenuates supplied camera motion; it is not the source of the stable-support state.
-
-This boundary also does not silently remove disturbances that are not currently modeled, including shutter shock, release-button impulse, wind, floor/ground vibration, support flex/resonance, or future tripod dynamics. Those effects must enter through their own explicit motion/support models.
-
-Omitting the camera-shake input is semantically different from explicitly supplying zero motion: omission means the effect/input was not supplied, while explicit zero motion states the modeled stable-support boundary.
-
-Real-camera policies about whether IBIS/OIS should be enabled on a tripod are equipment/mode-specific and remain separate from this generic boundary.
-
-## Equivalent stabilization stops
-
-The model accepts `stabilizationStopsEquivalent`.
-
-For educational exploration, the supplied angular displacement is attenuated by:
-
-`residualMotionFactor = 2 ^ (-stops)`
-
-For example, 3 equivalent stops produces a residual factor of 1/8 for the controlled synthetic shake profile.
-
-This attenuation is an **approximation**. It is useful for demonstrating the effect of reducing camera motion, but it is not a model of a particular IBIS/OIS implementation and does not imply that a real stabilization system deterministically reduces every motion path by that factor.
-
-Because the returned result combines this attenuation assumption with the geometric projection, the calculation envelope uses `provenance.kind = "approximation"`.
-
-## CIPA reference
-
-CIPA publishes **DC-011-2024** for measurement and description of image-stabilization performance.
-
-Photivra is not affiliated with, sponsored by, endorsed by, certified by, or claimed to comply with CIPA. The current educational approximation does not implement the CIPA test method.
-
-Reference:
-
-- CIPA DC-011-2024 overview: https://www.cipa.jp/e/std/image-stabilization.html
-
-Only the public standard identifier and high-level terminology are referenced here; CIPA logos and protected standard content are not incorporated into this project.
-
-## Not yet modeled
-
-The legacy stabilization-equivalent model intentionally remains limited to its original teaching contract. The separate #97 system adds rotational roll-capable time-domain correction, latency, axis limits, explicit panning-axis bypass, coordination, and #12 local-exposure sampling without changing legacy results.
-
-Still outside the current stabilization foundations are translational camera-shake correction, frequency-domain control-loop calibration, photographer-specific empirical motion, shutter-button impulse generation, realistic tripod/support mechanics, focal-length-dependent real-equipment calibration, mechanism-specific IBIS/OIS ray geometry, automatic pan detection, and digital-stabilization crop/warp behavior.
-
-Those capabilities should remain separate, documented models rather than being silently folded into either stabilization API.