@photivra/engine 1.5.0 → 2.1.0

package/docs/SCIENTIFIC_ASSURANCE.md

@@ -1,280 +0,0 @@
-# Scientific Assurance and Uncertainty Composition
-
-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 keeps **scientific status**, **source evidence**, **uncertainty**, **limitations**, and **reproducibility identity** as related but distinct concepts.
-
-This document defines the cross-engine composition contract used when independently valid scientific modules are combined into a higher-level result.
-
-The public contract is exposed as:
-
-- `SCIENTIFIC_ASSURANCE_CONTRACT_VERSION`;
-- `ScientificAssuranceComponent`;
-- `composeScientificAssurance()`;
-- `ComposedScientificAssurance`.
-
-The first contract version is `0.1.0`.
-
-## Core rule
-
-A composed result must not appear more scientifically certain than the required inputs that produced it.
-
-Photivra therefore:
-
-1. preserves each component's source/profile identity;
-2. preserves component evidence records;
-3. preserves component uncertainty declarations;
-4. identifies the weakest required scientific status;
-5. reports missing required evidence explicitly;
-6. refuses to invent an aggregate numeric uncertainty without a defensible propagation rule.
-
-A composition helper does **not** turn provenance into a confidence score.
-
-## Scientific status
-
-Composition-level status uses:
-
-- `calibrated` — every required component supports calibrated status and all required evidence is present;
-- `approximation` — at least one required component is an explicit approximation and none is unknown/missing required evidence;
-- `unknown` — at least one required component has unknown status or required evidence is missing.
-
-A downstream composition cannot promote an approximation to calibrated merely because a later mathematical operation is exact.
-
-For example:
-
-```text
-calibrated radiance
-  × calibrated transmission
-  × approximate paraxial bridge
-  = approximation
-```
-
-If a required evidence-backed component declares no evidence, the composition status becomes `unknown` and the missing component ID remains visible.
-
-## Evidence basis
-
-Each component declares one basis:
-
-- `evidence-backed-fact`;
-- `photivra-model-assumption`;
-- `not-applicable`.
-
-An `evidence-backed-fact` requires evidence.
-
-A Photivra model assumption may cite explanatory/reference evidence, but it remains explicitly a model assumption rather than being upgraded into a measured fact.
-
-Evidence continues to use the existing `EvidenceProvenance` contract:
-
-- source origin and reuse rights remain separate;
-- factual-reference-only material is not reusable numeric data;
-- reusable data requires a license;
-- Photivra-owned evidence must originate from Photivra.
-
-## Uncertainty states
-
-Component uncertainty has explicit semantic states.
-
-### Quantified relative uncertainty
-
-```ts
-{
-  kind: "relative",
-  fraction: 0.02,
-  basis: "calibration repeatability"
-}
-```
-
-### Quantified absolute uncertainty
-
-```ts
-{
-  kind: "absolute",
-  plusMinus: 0.1,
-  unit: "mm",
-  basis: "fixture measurement"
-}
-```
-
-### Existing CalculationQuality
-
-Modules that already expose multiple quantified `CalculationQuality.uncertainty` components may preserve the whole validated quality object:
-
-```ts
-{
-  kind: "calculation-quality",
-  quality
-}
-```
-
-This prevents a multi-component uncertainty description from being flattened into one invented scalar.
-
-### Not quantified
-
-```ts
-{
-  kind: "not-quantified",
-  limitation: "Model error exists but no defensible bound is available."
-}
-```
-
-**Not quantified does not mean zero.**
-
-### Unknown
-
-```ts
-{
-  kind: "unknown",
-  limitation: "No uncertainty characterization is available."
-}
-```
-
-Use `unknown` when the uncertainty state itself is unavailable, not merely when a known approximation lacks a numeric error bound.
-
-### Not applicable
-
-```ts
-{
-  kind: "not-applicable",
-  reason: "This identity-only component has no numeric quantity."
-}
-```
-
-## Composed uncertainty
-
-`composeScientificAssurance()` preserves all component declarations but does not automatically calculate a combined numeric uncertainty.
-
-Its aggregate uncertainty state is:
-
-1. `unknown` if any required component uncertainty is unknown;
-2. otherwise `not-quantified` if any required component has known-but-unquantified uncertainty;
-3. otherwise `not-propagated` when one or more required components have quantified uncertainty but no explicit propagation model has been supplied;
-4. otherwise `not-applicable`.
-
-This ordering prevents a quantified component from hiding a less-characterized required component.
-
-### Why no automatic quadrature
-
-Photivra does not assume that uncertainty components are statistically independent.
-
-Do not automatically:
-
-- add relative errors;
-- add variances in quadrature;
-- choose worst-case sums;
-- publish an aggregate confidence interval.
-
-A module may perform analytic propagation when the model, covariance/independence assumptions, and affected quantities are explicitly defined. That propagated result should remain traceable to the component uncertainties it consumed.
-
-Monte Carlo simulation is not required where an analytic treatment or an explicit `not-propagated` state is scientifically more appropriate.
-
-## Source identity and reproducibility
-
-Each assurance component has a stable source identity:
-
-- profile;
-- result;
-- model;
-- fixture.
-
-IDs and versions are preserved where available.
-
-Material evidence/uncertainty changes must participate in the owning result/snapshot/plan's reproducibility identity. The production-plan tests verify that changing scene-radiance uncertainty changes both capture and plan fingerprints.
-
-The canonical `basic-reference-scene` fixture is covered as a Photivra-owned `fixture` assurance source.
-
-## Production composition (#111)
-
-Production image-formation plan contract `0.4.0` adds `scientificAssurance` when the plan has composed scientific results.
-
-The current physical path records required components for:
-
-- scene-radiance result;
-- optical throughput profile;
-- Photivra primary-optics bridge model;
-- each selected front-of-lens filter;
-- non-unity field-throughput model when present.
-
-The temporal path records the capture temporal-schedule approximation when temporal composition is active.
-
-The primary optics bridge remains an approximation, so calibrated upstream data alone cannot cause the current scene-radiance → sensor-irradiance composition to claim calibrated status.
-
-Optimized and reference consumer manifests receive the same assurance object unchanged.
-
-## Cross-engine audit
-
-### Scene radiance
-
-Scene-radiance/provider contracts already distinguish:
-
-- calibrated vs approximation status where supported;
-- relative quantified uncertainty;
-- `not-quantified`;
-- evidence and limitations.
-
-#111 maps those declarations into the common assurance component without reinterpreting them.
-
-### Optics
-
-The scene-to-sensor optical bridge already preserves:
-
-- profile/transmission status;
-- profile/transmission/working-f-number evidence;
-- relative or unquantified uncertainty;
-- explicit limitations.
-
-The bridge itself is still an approximation and is represented as a separate Photivra-model component.
-
-Front-of-lens filters preserve each filter's identity, status, evidence and uncertainty separately.
-
-### Sensor
-
-Sensor modules use several domain-specific readiness/profile/result contracts plus `CalculationQuality` where appropriate.
-
-Those domain contracts remain authoritative. The common assurance layer must preserve them rather than replacing sensor-specific physical applicability with one generic score.
-
-When a sensor result exposes multiple `CalculationQuality` uncertainty components, the common contract can retain the whole validated quality object.
-
-### Exposure and metering
-
-Current relative exposure/metering/control paths are deterministic model/policy outputs, often without a calibrated real-camera error distribution.
-
-Do not invent numeric uncertainty merely because an exposure offset or setting is numeric.
-
-Where the source is an educational/generic approximation, composed consumers should use explicit approximation + not-quantified semantics unless a future calibration contract supplies a real uncertainty model.
-
-### Processed output (#112)
-
-The bounded processed-camera/output pipeline is merged. It retains reconstruction/rendering/correction child envelopes and conservative upstream assurance; it does not infer calibrated color from deterministic processing.
-
-When the processed output path composes source scientific results, it must:
-
-- carry upstream assurance/evidence/uncertainty forward;
-- add its own processing-model components;
-- never upgrade scientific status because the output transform is deterministic;
-- distinguish calibrated color/output transforms from generic approximations;
-- keep display/encoding choices from erasing upstream limitations.
-
-These requirements govern the merged shared processed-RAW/paired-JPEG path. Unsupported wider output/color combinations remain explicit; see [processed output](PROCESSED_OUTPUT.md).
-
-## Relationship to provenance
-
-`docs/PROVENANCE.md` remains the source of truth for legal/scientific source provenance and reuse rights.
-
-This contract adds **composition semantics**. It does not replace:
-
-- `CalculationResult.provenance`;
-- `CalculationResult.quality`;
-- `EvidenceProvenance`;
-- module-specific calibration/readiness/applicability contracts.
-
-## Release rule
-
-A public composed result must not:
-
-- convert `not-quantified` or `unknown` into zero uncertainty;
-- silently discard required evidence;
-- promote scientific status above a weaker required component;
-- fabricate a numeric aggregate uncertainty;
-- remove materially relevant uncertainty/evidence identity from deterministic serialization.
-
-Violations are scientific correctness defects, not documentation-only issues.

package/docs/SCIENTIFIC_CONFORMANCE.md

@@ -1,83 +0,0 @@
-# Scientific conformance: final V1 disposition (#131)
-
-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 cross-stage conformance layer complements, rather than replaces, narrow unit tests. `test/cross-stage-conformance.test.ts` consumes #130's canonical owned fixture and merged public APIs only. It checks a coherent ideal-focus/projection→FOV/object-size→pixel-motion/defocus path, then controlled one-stop shutter and aperture variants across exposure, motion and diffraction.
-
-Expectations follow independent Gaussian thin-lens reciprocal distance, angular span reconstruction, millimetre/micrometre pixel conversion, shutter-proportional lateral displacement, t/N² relative optical exposure, and wavelength/f-number Airy scaling. Neutral stationary/in-focus states and non-neutral variants preserve calculated provenance. Relative exposure is not photon-count evidence; no source/sensor calibration is inferred.
-
-`test/signal-conformance.test.ts` adds independent energy/photon/QE/noise identities, including physical shutter exposure versus nominal ISO/rendered exposure. These analytic inputs are not a calibrated scene-to-sensor integration.
-
-## Capture and processed-output slice
-
-`test/raw-output-conformance.test.ts` exercises the merged capture-owned global sensor producer through charge/capacity/noise/ADC, immutable native CFA attachment, explicit reconstruction, declared color interpretation, WB, correction, SDR encoding and paired export. This slice uses the global-exposure fixture; local shutter-window coverage remains in the producer tests.
-
-The fixture reuses #130's 36×24 mm imaging area, 50 mm f/4 lens, 5 m focus, 0.008 s shutter, ISO 100 and stochastic seed. It explicitly replaces the 600×400 native raster with a **6×4 Bayer regression lattice**: square 6 mm pitch, 24 sites. These dimensions are deliberately artificial, suitable for fast ordering/geometry checks, not pixel fidelity, demosaic quality, camera calibration, editor interoperability or performance. The canonical JSON is unchanged. Existing owned phase kernels average each 2×2 tile; six synthetic tile levels and channel differences make an incorrect orientation or source shift observable. Photoelectron expectations are supplied directly, with zero dark expectation and the existing synthetic readout profile (2 electron RMS read noise, 1 electron/code, black 64, white 1023, 1000 electron capacity). No scene radiance, wavelength response or spectral integration is inferred from these numbers.
-
-Independent expectations are calculated from the emitted integer RAW codes, without using engine reconstruction, orientation, correction or SDR functions as an oracle:
-
-| Boundary | Conformance evidence |
-| --- | --- |
-| Native capture → DNG | Every stored 16-bit strip code equals the produced post-ADC code, without container stretching. Native codes and noise remain identical through four output orientations. |
-| RAW → reconstruction → color/encoding | Tile red/blue values and mean of the two green sites are independently black-subtracted and normalized by 959. The declared ideal RGB→XYZ→RGB round trip must preserve them within numeric tolerance. Integer orientation permutations and the piecewise sRGB transfer/8-bit rounding predict every processed pixel. |
-| Shutter / ISO / rendering exposure | Twice the shutter doubles expected charge at fixed rates. ISO-only metadata does not change the explicitly selected readout regime, realized charge, RAW codes or processed pixels. Rendering +1 EV doubles linear rendering values while keeping RAW codes and RawDataUniqueID unchanged. No monotonic claim is made about individual Poisson draws. |
-| WB → exposure → tone → encoding | Non-neutral gains (2, 1, 0.5), +1 rendering EV and positive Reinhard tone are evaluated independently in sequence. This catches double WB, WB after tone and transfer/quantization ordering errors. |
-| Native correction → joint support → orientation | Identity correction preserves the plain processed pixels and view. A one-native-pixel shift reuses the exact noisy capture, excludes the unsupported native edge and yields independently predicted source pixels through all four orientations. RAW codes/default crop/data identity stay unchanged; RAW correction intent is metadata-only. |
-| Signed dark values / display clipping | Zero photo/dark expectations preserve below-black read noise in stored RAW and signed reconstruction. Low clipping happens downstream. A separate +8 EV rendering clips all output channels without claiming physical or ADC capture saturation. |
-| Unsigned ADC lower boundary | Explicit large read-noise variants with black 0/64 exercise lower-code clamping and separate upper pre-ADC/digital saturation at zero stored charge. Negative electronic noise is not mistaken for negative stored charge. |
-
-Complete file bytes are checked for repeated-export determinism on the neutral rendering path. The strip reader here is a bounded structural regression check, not an independent external RAW editor or TIFF implementation. JPEG **pre-encoding pixels** are the analytic rendering oracle; a lossy JPEG decode is not used to prove exact pixel identity. Existing #16 decoder/editor acceptance remains separately authoritative.
-
-The producer's `upstreamRadiometryVerified: false`, reconstruction's `producerOriginVerified: false` and approximation provenance remain visible. The fixture's unrelated inline float plane contains 999 values; it cannot supply the JPEG reconstruction. ISO independence applies to this explicit regime configuration, not to all future ISO-dependent body profiles.
-
-The shadow check exposed a readout ordering defect: clamping negative electronic noise to zero electrons before adding the pedestal erased valid below-black RAW values. The correction preserves signed electronic signal through the upper-only pre-ADC threshold, adds the black offset, quantizes and then clamps to unsigned code zero/common digital saturation. Physical stored charge remains nonnegative. Readout provenance advances to model **2.0.0** and the producer's required capture noise identity advances to **0.2.0**, rejecting old 0.1.0 producer replay instead of silently recomputing changed shadows. See `SENSOR_RAW_PRODUCER.md` for migration. Public input/output field shapes remain unchanged; root API advances to 0.106.0. Existing positive electronic-signal code math and RNG seed schedule are unchanged.
-
-## Final integrated acceptance
-
-The final contribution is based on merged main `712c031689f5413003a1d15c2d0dfa9466bbbfb8` (#205): #16/#112 export/processing, #178 authoritative integration, #116/#119 tier acceptance and #43/#45 performance dispositions are merged. `test/final-scientific-conformance.test.ts` adds 16 normal-CI tests over those final public paths. PR #206 merged after owner review and contribution-specific DCO certification as `34c6d9aca1c2e365b253c1562734d11bc8e0235f`; post-merge CI 37032338620 passed Node 22.13/24. #131 is closed and the feature/science checklist is 32/32. #180 prepares the 1.0 distribution; tagging/publication remains owner-only.
-
-The suite extracts the existing bounded tier-production request into `test/helpers/tier-production-fixture.ts` and reuses it from both tier acceptance and final conformance. The existing nine-pair/27-pupil suite retains its expectations. No runtime/API/schema/asset/dependency change or reference-golden regeneration occurs.
-
-### Shared laboratory and explicit variants
-
-#130 remains unchanged and supplies the imaging area, optical/exposure/focus reference, wavelength, reflectance, light level and seed. The final path explicitly declares these minimal specialized variants:
-
-- The canonical planar monochromatic reference is extended to an owned **uniform angular environment with a flat 540–560 nm spectral-density band**, using its 550 nm centre, with incident spectral irradiance scaled by `1e-9`. This is not a delta-line spectrum or a measured environment. Lambertian reference radiance is independently `rho * E / pi`; provider values are explicitly supplied, not visibility/transport predictions.
-- Native geometry is the existing owned **2×2 Bayer regression lattice** with registered tier topology, an independently declared 800×600 µm rectangular sensitive aperture, effective package-incident EQE 0.4, and explicit synthetic response/linearity bindings. Geometric pitch does not infer photon-collection area, QE or real camera pixels. The 20 nm midpoint bin samples 550 nm. Its finite declared operating ranges remain enforced.
-- Exact generic 1.0.0 body/lens selections provide capability policies, finite-focus optical transmission and explicit readout regimes. Relative metering uses the same provider/illumination/material identities and registered time zero, with a supplied normalized scalar reduction. It remains uncalibrated; no physical radiance-to-luminance or manufacturer-specific meter is inferred.
-- Neutral constant light replaces the registered waveform with a constant. The controlled temporal variant uses the owned `1 + 200 t` ramp. Orientation and exposure/rendering variants preserve the same scientific stage ownership and seed.
-
-### Independent integrated expectations
-
-For the fixed focus distance `s` and physical focal length `f`, independently solve `v = 1 / (1/f - 1/s)` in millimetres. The declared ideal symmetric working f-number is `Nw = N(1 + v/s)` with explicit unity pupil magnification. With tier transmission `T`, the expected sensor spectral irradiance is `L * pi * T / (4 * Nw²)`.
-
-Expected generated electrons are independently:
-
-`E_sensor * (800 * 600 * 1e-12 m²) * (20 nm) * (550e-9 m) / (h*c) * 0.4 * integratedSeconds`.
-
-Here `h = 6.62607015e-34 J s`, `c = 299792458 m/s`. Constant light uses `integratedSeconds = duration`; the registered ramp integrates to `duration + 100 * duration²`. Uniform radiance makes normalized spatial weights integrate to unity. The chosen single spectral bin matches the declared midpoint rule; this is not a convergence/physical error bound.
-
-Uniform relative scene-light factors 0.5/1/2 drive aperture-priority shutter to `t/factor` at fixed aperture/ISO, preserving expected photo charge. The independently declared dark rate still adds `4 * resolvedDuration` electrons, so total charge is not incorrectly held fixed by the meter. Compensation −1/0/+1 EV changes physical duration by 0.5/1/2 before charge/noise, without mutating the meter snapshot. The ramp and its equal-mean constant-field variant agree before stochastic sampling; no monotonic statement is made about individual random draws.
-
-Post-capture +1 rendering EV doubles linear rendering values while preserving the complete physical result, capture serialization, native codes, noise seed and RAW data identity. The same realized RAW feeds production processing and paired export, with stored DNG codes independently read from the strip. Whole plan and file bytes replay deterministically. This structural strip check is not an external reader or independent TIFF implementation; #16's merged reader/editor acceptance remains its own evidence.
-
-### Acceptance and API-style disposition
-
-| #131 requirement / boundary | Final evidence and disposition |
-| --- | --- |
-| #130 across multiple domains | Existing `basic-reference-scene`, `cross-stage-conformance`, `signal-conformance`, `raw-output-conformance` suites plus the new shared-scene meter/optics/sensor/production/export path. Canonical fixture unchanged. |
-| Coherent end-to-end deterministic path | All three exact tiers: scene-derived relative meter → immutable target/compensation → capability-based aperture-priority resolution → committed capture → invoked scene queries → finite-focus optics → spatial/spectral/temporal EQE → dark/charge/capacity/seeded noise/ADC → native RAW → production processing → paired DNG/JPEG. Independent SI count arithmetic and exact file codes. |
-| Neutral and non-neutral variants | Constant neutral field; 0.5/1/2 scene light; −1/0/+1 compensation; registered temporal ramp/equal-mean field; four orientations; post-capture +1 EV. Existing suites cover focus, diffraction, motion, signed shadows, WB/tone, correction and spatially distinct orientation/crop patterns. |
-| Ordering/coupling failures | New stale scene/seed/exposure/tier commitments block processing before source invocation. A trusted callback exception propagates instead of producing fallback output. Existing production tests cover missing renderer/stage support, temporal count/motion/focus/geometry mismatch and double attached/executed RAW paths. |
-| Tier coherence and tradeoffs | Merged nine-pair production/output and 27 independently evaluated pupil cases in `generic-tier-production-acceptance`; versioned reports/envelopes, immutable correction A/B, stabilization/flash/flare in `generic-tier-report-acceptance`; no universal ranking or duplicate large fixture. |
-| Final performance disposition | Merged #205 [performance report](V1_PERFORMANCE_DISPOSITION.md), complete 64-case independent POC equivalence, scalar/batch mutation and numerical guards. No new timing threshold or tiny-raster throughput claim. Runtime sources unchanged, so no fresh performance implementation is implied here. |
-| API-style drift | Existing `api-style-compatibility` scans the entire root callable surface against documented verbs, compatibility sentinels and independent version surfaces. New path exercises input objects, calculation envelopes, versioned immutable records, exact identities and deterministic serialization. All checks must pass; no accidental convention change is introduced. |
-| CI cost and independence | 16 new bounded tests; no network, private app, Blender, proprietary data, new dependency or expensive photoreal renderer. Existing focused suites remain authoritative. |
-
-Scientifically meaningful API differences remain intentional under [API_STYLE.md](API_STYLE.md): parsers/targets/resolvers/plans/manifests return their semantic records, primitive calculations return `CalculationResult`, file export is asynchronous for encoding/hash work, and trusted caller-code exceptions may propagate while scientifically incomplete well-formed plans carry structured blockers. A physical approximation stays approximate even when its metadata/identity is valid. FNV plan fingerprints and SHA-256 capture/file/corpus commitments retain their separate contracts. No coercive wrapper or cosmetic public rename is warranted.
-
-### Limits and completion boundary
-
-The first physical route retains unity field throughput, optional destination-local PSF approximation and bounded sensor/provider-evaluation limits. The new neutral tier route explicitly omits PSF; existing executed environment/production tests cover declared sampled PSF and motion/rolling shutter, and tier pupil scenes independently validate finite profiles. No full field-dependent PSF transport, calibrated source visibility/radiometry/sensor color, generic arbitrary-optics integration, full-resolution throughput or private product fidelity is claimed. Upstream provider transport and radiometry verification remain false in the new complete path.
-
-This final conformance disposition consumes the finite approved V1 support and documented limitations. It neither invents a new V1 deferral nor certifies scientific accuracy merely from passing tests. #180 still owns the exhaustive human/agent/source documentation audit, 1.0 packaging/release preparation and final limitations review. No tag, package publication or release is authorized by this contribution. Human review and contribution-specific DCO remain required before #131 closes.

package/docs/SDR_RENDERING.md

@@ -1,33 +0,0 @@
-# Standalone SDR rendering primitives: #112A
-
-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).
-
-Current integration: [processed camera output](PROCESSED_OUTPUT.md) documents
-the shared preview/export path and explicit plan 0.6.0 post-RAW activation.
-The historical slice descriptions below retain their original scope.
-
-
-This low-level primitive defines bounded deterministic post-capture SDR rendering. Merged capture/WB/correction adapters and production plan 0.7.0 now integrate it through [processed output](PROCESSED_OUTPUT.md), preserving domain/order and shared color/WB ownership.
-
-`calculateSdrRendering()` accepts a declared `color-transformed-linear-rgb` image state, `linear-srgb-d65` color-space identity, source state ID, co-sited interleaved RGB raster and relative reference-white value. `whiteBalanceHandling` must be `already-applied-upstream` or `not-required`. Intent-only/unresolved WB is rejected; this primitive never estimates/applies WB, converts XYZ/spectral/sensor RGB or changes lens-correction order. These input identities are producer declarations, not verification of upstream pixel fidelity. The capture adapter verifies them against the authoritative capture/profile history.
-
-Profiles use schema `0.1.0`, public ID/version and explicit policies. No default tone/gamut/transfer or HDR mode is guessed. Inline samples are finite, dense and limited to 262144 values (at most 87381 RGB pixels); external storage/streaming/native-size processing remains outside this reference executor. Top-left raster origin, +X right/+Y down, tightly interleaved red/green/blue, row-major. Input is copied and never mutated.
-
-| Stage | Defined operation |
-| --- | --- |
-| Rendering exposure | Multiply source samples by `2^renderingExposureEv/referenceWhiteValue`. EV is bounded to [−32,32]; this is a rendering brightness choice, not aperture/shutter/ISO compensation. Non-finite scale/sample results fail before later processing can hide them. |
-| Tone curve | Identity, or positive per-channel Reinhard: positive x maps to x/(1+x); nonpositive values are retained until explicit gamut handling. This generic choice can change chromaticity and compresses reference white 1 to 0.5. No calibrated manufacturer look is claimed. |
-| Gamut handling | Explicit component clipping to [0,1], with separate low/high sample counts, or rejection of any component outside [0,1]. This is range handling in the defined sRGB basis, not a perceptual/hue-preserving gamut map. |
-| Transfer encoding | Standard sRGB component function: 12.92x for x≤0.0031308; otherwise 1.055x^(1/2.4)−0.055. Black/white endpoints return exact 0/1. |
-| Quantization | 8 or 16 bits, full range 0..(2^bits−1), nearest exact binary64 ties to larger code, no dither. Packing/file tags belong to the serializer. |
-| Display adaptation | Explicit external-platform seam, not applied; actual display capabilities are unknown. |
-
-The returned tone-mapped linear, gamut-bounded linear, transfer-encoded float and integer arrays let consumers inspect the stages independently. Diagnostics distinguish pre-tone negative/above-reference rendering samples, tone-changed samples and actual gamut-clipped samples. They count channel samples, not pixels. No sensor/full-well/ADC/RAW clipping is inferred; capture saturation is `not-consumed`. A source clipped upstream may have no output clipping, while an unsaturated source can clip in SDR output. The capture adapter retains upstream diagnostics independently.
-
-Output declares output-referred SDR sRGB, RGB primary xy coordinates (0.64,0.33), (0.30,0.60), (0.15,0.06), D65 white xy (0.3127,0.3290), and the standard reference-white luminance assumption 80 cd/m². This is an encoding/reference convention, not evidence that the user's screen emits that luminance. Actual viewing surround/display tone/black, platform color management, HDR adaptation and display saturation remain external and unknown. Floating-point source headroom does not establish PQ/HLG/HDR encoding.
-
-The function touches no capture settings, physical radiometry/noise/saturation, metering, CFA/reconstruction, geometry, WB estimator, denoise/sharpen or resampling. It serves a common preview/processed-export rendering intent; it does not require screenshot/canvas reuse or promise byte-identical file/display backends. It does not replace #15C's authoritative **linear** export encoding: this primitive quantizes **transfer-encoded processed SDR** and does not replace the capture encoding API.
-
-Compatibility: root API main `0.96.0` → `0.97.0`; package/POC/production schemas unchanged. This is the historical introduction version, not the current release version. Current package/root API 1.0.1 uses aligned release identity; #112 is merged. Schema/profile changes preserve explicit domains and independent version identities.
-
-Research: [ICC sRGB encoding registry](https://registry.color.org/rgb-registry/srgb) defines the standard primaries, white/reference assumptions and component transfer equations. These public numerical facts/equations inform independently authored code/tests; no third-party implementation, ICC profile binaries, protected prose, calibration data or color tables are incorporated. Calculation provenance refers to deterministic rendering arithmetic, not physical/perceptual accuracy or commercial-camera calibration. Human science/provenance review and DCO contributor certification remain required before inclusion.

package/docs/SENSOR_APERTURE_RAYS.md

@@ -1,23 +0,0 @@
-# Ideal pupil rays for bounded capture
-
-`calculateSensorApertureRays()` generates origin-aware rays for an explicitly declared ideal symmetric thin lens. Native sensor coordinates use +Y down; camera look directions use +Y up and +Z forward. Origins lie in the lens principal plane and use metres. Pupil sample points use millimetres.
-
-For focal length f and nominal f-number N, the circular pupil radius is f/(2N). The shared focus contract determines image distance v. For finite object-plane distance D, every unrotated ray intersects (xD/v, -yD/v, D). At infinity the rays remain parallel. The existing constant-axis camera rotation rotates both origin and direction about the principal-plane origin at the actual local shutter time.
-
-Uniform-area polar midpoints use r = R sqrt((i + 1/2)/Nr) and theta = 2 pi (j + 1/2)/Na. Each ray has normalized weight 1/(Nr Na). Counts are bounded to 1..32 radial and 4..64 angular samples, with at most 256 rays. These are integration samples, not a convergence guarantee.
-
-## Capture integration
-
-A caller may supply `pupil` and the separate `evaluateApertureRadiance(request, ray)` callback to `calculateEnvironmentSensorPhotoSignal()` or `simulateEnvironmentSensorRawFrame()`. The callback receives the actual pupil origin and look direction. It owns scene intersection, visibility and emitted/transported wavelength-resolved radiance; the engine owns focus, rotation, local shutter timing, sensor response and RAW production. The old single-argument environment callback remains compatible and unchanged when pupil sampling is omitted.
-
-The engine averages physical irradiances over normalized pupil weights before sensor integration. The existing working-f-number radiometric factor is applied once. Pupil area is not multiplied again. A sampled local PSF and pupil integration are rejected together: neither an implicit second defocus nor an unreviewed optical composition is permitted. Every ray and the total provider budget are preflighted before provider execution. Full-frame site completeness, seeds and 4,096-site/100,000-query limits remain unchanged.
-
-Diagnostics retain the original central `query`, plus `apertureRequest` and `apertureRay` for the actual evaluated ray. `pupilIntegrationApplied` and `pupilIntegrationProfile` report the declared integration. Provider transport and scene visibility remain unverified. The production composer rejects this standalone route until depth/visibility fidelity has an explicit composition contract; this API does not activate a production stage.
-
-## Limits and evidence
-
-This is an ideal paraxial approximation with unity pupil magnification. It does not model diffraction, aberrations, pupil clipping, lens housing, calibrated lens transmission, camera translation, scattering or physically measured sensor response. Existing separately declared field and spectral transmission remain separate. No megapixel RAW capability or physical device acceptance is established.
-
-Tests independently intersect finite rays with the focus plane, check pupil moments, through-focus footprints, infinity parallelism, coordinate signs and camera rotation. Capture tests check uniform radiance against the unchanged no-pupil path, origin-dependent visibility averages, exact seeded replay, callback ownership and rejection before provider work. These synthetic controls do not qualify arbitrary scene providers.
-
-Conceptual references: [PBRT projective camera models](https://www.pbr-book.org/4ed/Cameras_and_Film/Projective_Camera_Models) describes ideal lens sampling; [PBRT realistic cameras](https://www.pbr-book.org/3ed-2018/Camera_Models/Realistic_Cameras) distinguishes full lens geometry. Implementation and tests are original Photivra work using existing engine helpers; no reference code, data or prose is incorporated. AI-assisted work remains draft pending substantive human scientific/source review.

package/docs/SENSOR_ENVIRONMENT_QUERY.md

@@ -1,86 +0,0 @@
-# Sensor support to environment radiance query
-
-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).
-
-`calculateSensorEnvironmentRadianceQuery()` derives a renderer-neutral environment
-radiance request from an explicitly supplied physical sensor support point. It
-reuses the existing focus-aware ideal projection and analytic inverse camera
-rotation. This is a bounded environment-query adapter, not a surface-intersection
-solver or a scene renderer.
-
-## Coordinates, direction and clock
-
-`sourcePointNativeSensorMm` is an optical support point in native sensor axes:
-optical-axis origin, +X right, +Y down, millimetres. It can be a pre-AA quadrature
-point or a pre-PSF source tap. The adapter converts it to image-plane axes with
-`{x: native.x, y: -native.y}`. It never recentres off-axis support, applies digital
-crop/orientation, or clips a source point to the sensor's active bounds.
-
-Inputs retain physical `focalLengthMm`, an explicit finite/infinity `focus`, and
-constant `angularVelocityRadPerSec` in the existing right-hand pitch/yaw/roll axes.
-The existing `calculateInverseCameraRotationImageMapping()` owns the thin-lens
-projection distance and simultaneous axis-angle rotation. Infinity uses physical
-focal length; finite focus uses the existing Gaussian image distance. No alternate
-projection or camera-motion equation is introduced.
-
-`timeReference` must explicitly be `first-opening-boundary-phase`, mapping that
-capture boundary to the rotation model's t=0. `timeSecondsFromOpeningReference`
-is reused exactly for the query timestamp and rotation evaluation. Readout or
-renderer time cannot stand in for that declared clock. Call separately at each
-actual local shutter midpoint; this API does not establish local exposure timing.
-
-The reference ray is normalized in camera axes at the first opening boundary,
-with +Z forward. `referenceLookDirectionUnitVector` points **from camera toward
-the environment**. The request's `outgoingDirectionUnitVector` is its negative,
-representing radiance propagation **from environment toward camera**. This
-adapter requires the explicit `outgoing-radiance-toward-camera` convention.
-The selected provider must share it; providers indexing maps by a look direction
-must deliberately convert the sign. Existing manually declared request semantics
-are not rewritten by this additive API.
-
-The existing rotation inverse rejects rays at or behind the exposure-start
-reference camera plane. This forward-hemisphere limit is preserved, rather than
-silently extending the primitive to arbitrary 360-degree environment queries.
-
-## Request identity and handoff
-
-`request` supplies the existing scene/provider/illumination/material IDs, unique
-sample ID, schema version, wavelength and explicit air/vacuum basis. The adapter
-owns its environment target and timestamp, then parses the complete request
-through `parseSceneRadianceEvaluationRequest()`.
-
-Use the returned request with the provider responsible for scene radiance. Bind
-its result through the existing scene-profile/request/result validator and optical
-bridge. At sensor quadrature nodes, the generated request can replace a manually
-declared environment target in `calculateSceneToSensorIrradianceQuadrature()`.
-At PSF support points, evaluate radiance/optical irradiance separately at each
-point before supplying the local sampled-PSF adapter. Do not copy one environment
-scalar across directions without an explicitly uniform provider model.
-
-`geometricRayProjectionCalculated` is true for this named ideal model only.
-`sceneIntersectionCalculated`, `visibilityCalculated` and `providerExecuted`
-remain false. Existing scene/optical diagnostic origin flags remain conservative:
-calling this adapter does not rewrite them or provide measured source truth.
-
-## Limits and verification
-
-Environment/rotation reference axes are explicitly the camera axes at the first
-opening boundary. There is no world-pose translation or implicit Euler pose.
-Surface points/material visibility, translation/parallax, moving objects, lens
-distortion, chromatic field mapping, focus breathing, radiance transport and
-production activation remain separate. The adapter's approximation envelope
-retains the child analytic projection result; it claims no real-lens calibration,
-combined uncertainty or full photographic accuracy.
-
-Tests independently predict native/optical signs, direction normalization,
-finite-focus projection and axis-specific Rodrigues rotation. Forward/inverse
-rotation round trips preserve captured points. Actual pre-AA node requests pass
-the existing provider-binding/optical adapter with owned synthetic radiance.
-Unknown clock/direction/focus/basis, negative time, nonfinite point, invalid focal
-length and behind-reference-plane requests reject. Inputs/results are owned
-without mutating caller state.
-
-Root API **0.112.0 → 0.113.0**, model 0.1.0. Existing public contracts and other
-version surfaces stay unchanged; historical capture/file replay retains its API
-stamp. No dependency, external 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_EQE_LOCAL_EXPOSURE.md

@@ -1,104 +0,0 @@
-# Irradiance to stationary EQE local exposure
-
-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).
-
-`calculateSensorEqeLocalExposure()` is a bounded sensor-layer composition. It
-accepts explicit physical spectral irradiance samples in **W/m²/nm**, not RGB,
-and returns a photoelectron expectation suitable for the existing accumulated
-charge and RAW producer. It does not establish scene/optics origin, execute a
-renderer, or activate reserved production stages.
-
-## Input ownership and order
-
-The caller supplies `colorSamplingProfile`, `spectralResponseProfile`,
-`spatialSampling`, `spectralSampling`, `irradianceSamples`,
-`responseApplication`, `operatingRangeProfile`, `localExposure`, and
-`stationarityProfile`. Optional `airPhotonEnergyContext` retains the EQE API's
-explicit air-to-vacuum photon-energy requirements; vacuum wavelengths need none.
-
-The adapter delegates in this order:
-
-1. Spatial midpoint/AA quadrature uses the supplied local timing's native raster
-   and binding profile, plus the explicit physical imaging area/aperture/lattice.
-2. Spectral midpoint quadrature checks response support and requested wavelength
-   measure. The caller must separately establish scene/optics spectral coverage.
-3. Reduction requires one identified irradiance value for every Cartesian node.
-   Ordering is irrelevant; missing, duplicate, nonfinite or negative inputs fail.
-   Values are evaluated at each node's `preAntiAliasingSourcePointMm` before AA
-   and sensor response. Spatial units and wavelength measure apply once.
-4. Application compatibility establishes response plane/scope, collection area,
-   uniform spatial response and reference conditions. Operating range checks the
-   specified radiant-power domain and spectral/spatial linearity evidence.
-5. EQE converts radiant power to photons and expected electrons. Responsivity
-   profiles are rejected by this EQE path. A channel filter is applied only when
-   the existing separable-response contract requires it.
-6. Local shutter binding validates the site/channel and computes its exact
-   one-to-one native exposure window. The stationarity profile must match that
-   site, binding and window before rate × duration integration.
-
-Prepare sample identities with the existing public spatial/spectral quadrature
-functions and the same parameters. This composition recomputes those plans;
-caller-supplied result flags do not bypass these calculations or validity gates.
-The input is not frozen or mutated. Child results retain separate provenance,
-evidence and declared response uncertainty; no uncertainty combination or
-quadrature-convergence estimate is introduced.
-
-## Downstream handoff
-
-```ts
-const photo = calculateSensorEqeLocalExposure(request);
-const charge = {
-  photoSignal: photo.value.exposure.value,
-  darkCharge,
-  completenessProfile
-};
-// Feed charge with explicit sampling/capacity/readout state into
-// simulateSensorRawFrame(). Paired export consumes that returned RAW frame.
-```
-
-Dark charge, other stored charge, completeness, capacity, stochastic realization
-and electronics are still separate downstream responsibilities. Do not insert
-fake zero-dark or completeness evidence to obtain RAW. A rolling schedule in the
-RAW producer must match the local event used here. Nonstationary scene motion or
-irradiance requires actual temporal integration, which this adapter does not
-implement; a stationarity declaration is not such integration.
-
-The result declares `upstreamOrigin: "declared-spatio-spectral-irradiance-samples"`
-and `upstreamSceneAndOpticsVerified: false`. It retains spatial/spectral plans,
-reduction, compatibility, operating range, electron rate, exposure binding and
-exposure **envelopes**. Aggregate provenance is approximation. The RAW producer
-and attachment/export origin flags stay conservative: executing this adapter
-cannot prove the irradiance provider's history or calibration.
-
-## Evidence and compatibility
-
-`test/eqe-local-exposure.test.ts` independently predicts photon/electron counts
-using SI Planck/light-speed constants, µm²-to-m² conversion, two spectral
-midpoints and the synthetic QE curve. It checks order independence, exact rolling
-windows and duration scaling, invalid node/plane/range/channel/binding/window
-inputs, and all four native Bayer sites through deterministic RAW and paired
-DNG/JPEG. Fixtures are owned synthetic test declarations, not measured camera
-calibration or scene validation. Existing primitive tests remain in place.
-
-This additive entry point advances root API **0.106.0 → 0.107.0**. The composition
-model is 0.1.0; package, POC, production-plan, capture/RAW/producer schemas and
-noise identities remain unchanged. Newly created captures carry the new root
-API stamp, so their provenance-dependent export identities may differ. Historical
-capture replay preserves its stored root stamp and pinned paired-file hashes;
-no primitive equations, stochastic seeds or RAW readout arithmetic change.
-
-Remaining #16/#178/#112 work includes committed scene/optics/PSF-to-node origin,
-production-stage activation and broader
-resolution/editor acceptance. This handoff does not close those tickets.
-
-## Optical-node producer
-
-[`calculateSceneToSensorIrradianceQuadrature()`](SCENE_SENSOR_QUADRATURE.md) produces the exact physical input node values from declared wavelength-resolved scene radiance through the existing optical bridge. Its output plane is sensor-package-incident; use matching effective package EQE and explicit source-plane evidence. Projection/PSF/source-truth and stationarity remain separate requirements.
-
-## Nonstationary sensor calculation
-
-[`calculateSensorEqeTemporalExposure()`](SENSOR_EQE_TEMPORAL_EXPOSURE.md) reuses
-this adapter's instantaneous steps at every explicit local shutter midpoint.
-It returns a distinct nonstationary photo expectation, with no stationarity
-claim. The [temporal photo-signal handoff](TEMPORAL_PHOTO_RAW.md), added at API
-0.110.0, constructs a distinct compact record for dark/charge/RAW consumers.