@photivra/engine 0.5.1 → 1.0.0

package/docs/GENERIC_TIER_PRESETS.md

@@ -0,0 +1,269 @@
+# Generic equipment tier reference assets
+
+Release context: **package 1.0.0 candidate / root API 0.116.0**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_0.md).
+
+`resolveGenericEquipmentTierCatalog({ presetVersion: "1.0.0" })` returns immutable
+Consumer, Prosumer and Professional body/lens reference bundles. These are
+Photivra-owned synthetic educational approximations, with unquantified physical
+uncertainty. They are not measured calibration, commercial camera emulation or a
+universal ranking of real equipment.
+
+The tier is a catalog key. Scientific functions consume the ordinary explicit
+profiles; no tier multiplier enters their equations. Sensor format, native raster
+and capture geometry remain caller-owned. All three initial lens forms are 50 mm
+primes with a common f/4–f/16 capability range; prime/zoom and focal range are
+separate asset properties rather than tier meanings. This first catalog contains
+no zoom, macro, OIS or variable focal-length family.
+
+## Exact selection and reference binding
+
+```ts
+import {
+  createGenericEquipmentTierSelection,
+  parseGenericEquipmentTierSelection,
+  resolveGenericEquipmentTierLensProfiles
+} from "@photivra/engine";
+
+const selection = createGenericEquipmentTierSelection({
+  presetVersion: "1.0.0",
+  bodyTier: "consumer",
+  lensTier: "professional"
+});
+const saved = parseGenericEquipmentTierSelection(
+  JSON.parse(JSON.stringify(selection))
+);
+const profiles = resolveGenericEquipmentTierLensProfiles({
+  selection: saved,
+  state: {
+    bodyId: "photivra-consumer-body", bodyVersion: "1.0.0",
+    lensId: "photivra-professional-prime", lensVersion: "1.0.0",
+    focalLengthMm: 50, aperture: 4, focusDistanceM: 5,
+    captureMode: "still", frameRateHz: 0, stabilizationMode: "off",
+    outputWidth: 600, outputHeight: 400
+  }
+});
+```
+
+Omitting `lensTier` pairs matching tiers; all nine pairings are allowed through
+#109's capability resolver. The strict saved-selection parser binds exact IDs,
+preset version and every profile reference, including versions on wrappers for
+subsystems whose native profile lacks a version field. Unknown fields, missing
+references, changed versions and a `latest` alias fail. It returns the canonical
+immutable selection. Output dimensions must be explicit and valid; they do not
+select sensor size. This module does not mutate the POC or production plan.
+
+The optical resolver supports only the explicit still/reference acquisition
+state above. Aperture capability does not authorize extrapolating optical data
+outside f/4. Still stabilization must be off for this optical slice. It exposes:
+
+- radial distortion and lateral-CA channel maps (the CA map already includes the
+  common radial base; do not apply that base twice);
+- normalized illumination vignetting, separate breathing projection scale and
+  a synthetic flat 540–560 nm transmission reference;
+- nine scalar Fraunhofer complex-pupil slices at center, mid-field (10, 6 mm),
+  corner (18, 12 mm), each at signed image-plane defocus −20, 0 and +20 µm;
+- a 550 nm/vacuum clean-lens ghost/veil profile, and separately declared
+  reconstructed-linear geometry/CA/gain correction components.
+
+The 5×5 pupil grids and OPD arrays are independently authored discrete reference
+responses tagged to these exact contexts. They are not an inferred continuous
+lens model or a physically calibrated prediction at arbitrary defocus. No
+interpolation is offered. Normalized PSF shape energy remains one; relative pupil
+throughput stays separate. Pupil clipping and illumination falloff are separate
+contributions with distinct ownership. Their simultaneous production composition
+is not defined here. LoCA, spectral bokeh, onion rings, texture rendering and
+measured MTF are not implemented by these assets.
+
+Correction transforms retain the established destination-to-source semantics.
+Sequential common radial and channel-offset transforms are generic approximate
+compensation; they do not claim the exact inverse of the combined optical CA
+map. Gain is partial and amplifies sampled noise. Correction never recreates
+photons, updates metering, regenerates noise or changes physical capture history.
+The caller must provide any required source prefiltering; a resampler declaration
+is a contract, not proof that prefiltering was performed.
+
+## Curated declarations and tradeoffs
+
+| Explicit body declaration | Consumer | Prosumer | Professional |
+| --- | --- | --- | --- |
+| Maximum standard exposure index | 6400 | 12800 | 25600 |
+| Maximum declared cadence (fps) | 4 | 8 | 12 |
+| Maximum logical sequence frames | 8 | 16 | 24 |
+| Base electronic RMS read noise (electrons) | 6 | 3 | 2 |
+| Data readout duration (seconds) | 0.030 | 0.015 | 0.008 |
+| Pitch/yaw/roll stabilization gain | 0.35 | 0.65 | 0.85 |
+| Continuous AF mode | unavailable | available | available |
+| Highlight-weighted meter/ambience AWB | unavailable | available | available |
+
+ISO selects explicit readout regimes on a finite power-of-two setting grid.
+It is not a photon/noise equation. Full-well/storage physics is not inferred from
+pre-ADC saturation or ADC white. AF uses the same ideal instantaneous actuator
+for every tier; mode availability does not establish faster or more accurate
+tracking. Data readout duration does not establish exposure scan or flash motion
+geometry. Flash capabilities declare front/rear ordinary sync and no HSS; callers
+must resolve actual exposure-window compatibility separately.
+
+The lens declarations intentionally include a tradeoff: Professional has less
+clipping/stray light and lower radial/CA coefficients, but more f/4 falloff and
+peripheral gain cost than Prosumer. Near/far pupil character also differs rather
+than every wavefront coefficient shrinking monotonically. No overall quality or
+bokeh score is produced.
+
+## Acceptance boundary
+
+`test/generic-tier-presets.test.ts` reuses #130's canonical focal length, aperture,
+focus, illumination wavelength and exposure time. It leaves that fixture unchanged.
+A small explicit 9×9 sampled-ramp/noise target tests correction using one capture
+and one noise identity for Off/On. The target is a sampled executor fixture, not a
+radiometrically composed scene or a resolution/MTF claim. Multidimensional pupil
+checks cover all declared field/defocus slices and separate passivity/energy.
+Every advertised ISO setting resolves into an explicit regime. Matched angular
+disturbance, corner radial/CA, off-frame ghost/veil and correction Jacobian/source
+coverage checks consume the existing low-level APIs. The shifted output lattice
+exposes missing support and joint crop rather than extending edges.
+
+`test/fixtures/generic-tier-assets-v1.json` pins the complete canonical manifest
+with SHA-256. Retuning an existing version requires deliberate fixture change and
+review; accepted retuning must introduce a new preset/profile version while
+retaining historical definitions required by saved simulations. This initial
+resolver recognizes only 1.0.0 and rejects unavailable history without fallback.
+
+Initial acceptance was partial; the current #116 disposition is documented in
+[TIER_PRESET_ACCEPTANCE.md](TIER_PRESET_ACCEPTANCE.md). #119 remains the broader
+cross-tier validation ticket. The following inventory describes the initial slice.
+Remaining acceptance includes composed physical scene/corrected-image reports,
+residual CA/distortion and retained-FOV/stretch/edge-response envelopes, controlled
+bokeh/textured backgrounds and spectral effects where modeled, broader body
+stabilization/AF/drive/meter/WB execution cases, and applicable output paths.
+There is no separate tier-specific browser approximation to compare here; the
+public implementation remains browser-safe and uses the ordinary reference APIs.
+No private application acceptance is invented.
+
+Initial tier assets landed at root API 0.105.0; the current root API is 0.116.0.
+This acceptance-only extension does not change runtime/API or asset definitions. Selection schema 0.1.0, asset version 1.0.0, npm package,
+POC and production contracts remain independent. Human scientific/provenance
+review and contribution-specific DCO certification are still required.
+
+## Correction residual and sampled-edge acceptance
+
+`test/generic-tier-correction-acceptance.test.ts` extends #119 with the exact 1.0.0
+assets on a 9×9 synthetic slanted-step target and fixed alternating noise. Correction
+Off/On forks one sampled capture. Independent k1 radial arithmetic, finite-difference
+Jacobians, bilinear weights and polynomial partial-reciprocal gain predict every
+channel sample. These checks quantify sampled interpolation, not optical MTF or a
+radiometrically composed scene.
+
+Independent monotonic scalar bisection recovers ideal coordinates through each
+combined physical radial/CA map. Common green distortion is compensated, while
+sequential partial channel correction leaves a nonzero, reduced CA residual. The
+bounded sampled points require less than 0.1 mm residual displacement; this is a
+regression envelope for synthetic definitions, not measured accuracy or a continuous
+field guarantee. Full 2×2 Jacobians, determinants and principal stretches are checked
+independently. A shifted lattice checks exact missing-source support and the joint
+valid crop. Retained channel pixel-center ray envelopes remain distinct from captured
+pixel-edge FOV; the joint RGB crop cannot expand a channel's ray coverage.
+
+No runtime, root API, schema, preset manifest, package or POC behavior changes.
+This does not complete #116/#119: physical PSF/scene composition, broader body
+execution and applicable export acceptance remain separately tracked.
+
+## Body execution acceptance
+
+`test/generic-tier-body-acceptance.test.ts` executes the exact 1.0.0 body
+assets through existing public APIs using #130's matched optical/exposure state.
+Fifteen cases cover all three tiers:
+
+- Burst times follow the maximum of explicit cadence and exposure duration;
+  a slow shutter cannot overlap ordinary still exposures. Self-timer delay is
+  applied once. Frame seeds are reproducible/distinct within the tested sequence;
+  frame-count limits and unsupported focus bracketing reject.
+- Single AF acquires and holds; focus/release priority gates remain separate.
+  Consumer rejects continuous AF; Prosumer/Professional follow the same known
+  target and require explicit reacquisition after loss. The common ideal actuator
+  does not establish real tracking speed or recognition performance.
+- Uniform/highlight metering uses independently calculated weighted means and
+  target ratios, stays invariant to output crop, and rejects tone-mapped input.
+- Observable pre-WB weighted patches yield independent logarithmic-strength AWB
+  gains. Clipped samples are excluded/reported, unsupported policies reject,
+  and a locked state preserves resolved gains without altering RAW/exposure.
+- Global data-readout declarations retain nonzero duration with zero spatial
+  phase skew under all three shutter mechanisms. These tests do not establish
+  exposure-boundary scans, flash compatibility or rolling-motion behavior.
+
+Assets, runtime contracts and all versions remain unchanged. These are bounded
+synthetic body-policy execution checks, not measured camera calibration or full
+capture/production/output acceptance. Physical scene/PSF composition, applicable
+export wiring and broader stabilization/flash acceptance remain separate work.
+
+## Readout-to-file acceptance
+
+`test/generic-tier-output-acceptance.test.ts` binds the exact body 1.0.0
+readout/signal-chain profiles to an explicitly declared owned 2×2 Bayer/native-still
+test topology. The topology IDs are registered to those required by the assets;
+matching channel names alone is not the binding. Charge expectations, physical
+storage capacity and ideal test-color interpretation remain independent synthetic
+fixture contracts. This tiny raster is structural regression evidence and is not
+an external-editor acceptance file or a realistic pixel sampling model.
+
+Nine cases verify that ISO 100/400 resolve the same base regime and ISO 800 selects
+the explicitly declared high regime. Expected photons/charge and the realized
+stored charge remain unchanged while electronic noise and conversion gain change.
+Independent signed-signal/pedestal/quantization arithmetic predicts each RAW code.
+The producer itself still consumes an explicit regime: changing ISO metadata
+without changing that regime cannot alter its samples. Unsupported ISO settings
+reject in the upstream capability resolver.
+
+Both regimes export through all four orientations. Stored DNG codes match every
+native produced sample; downstream +1 EV preserves codes, capture/noise and RAW
+image identity while changing processed pixels. Repeated JPEG export is deterministic.
+These are genuine producer-to-file checks, with upstream radiometry and producer
+origin verification still explicitly unasserted. They do not establish tier lens
+PSF/scene composition, calibrated color, full production activation or external
+editor/high-resolution interoperability. Runtime, API/schema and asset versions
+remain unchanged.
+
+
+## Supported production and finite pupil scene acceptance
+
+`test/generic-tier-production-acceptance.test.ts` runs every body/lens pairing
+through the authoritative plan 0.7.0 environment route using the exact preset
+transmission values and body readout/ISO profiles. A separately identified fixture
+bridge explicitly binds the selected lens's transmission to its exposure-capability
+profile ID; those two IDs represent different contracts. The test does not retune
+or overwrite the saved 1.0.0 assets.
+
+The owned 2×2 sensor registration, 540–560 nm flat EQE, charge capacity, dark
+current and ideal output color are independent approximations, never facts inferred
+from body tier. All three body selections produce the same expected photo charge
+for a given lens. The lens transmission ratios independently predict photo-count
+ratios; ISO regime changes preserve photo charge. Executed RAW is preserved through
+processing and deterministic paired export. Both consumer manifests retain the same
+immutable executed result. Unsupported wavelength support and stale commitments
+reject before provider callbacks.
+
+Production explicitly omits PSF and declares unity field throughput. It does not
+claim to compose the assets' discrete 550 nm pupil data across a continuous spectrum,
+combine pupil clipping with illumination falloff, or execute every lens effect.
+That omission remains recorded as modeled-zero with evidence and limitations.
+
+A separate finite monochromatic sampled scene evaluates all 27 exact field/defocus
+pupil responses. An independent direct phase sum predicts each normalized PSF tap;
+controlled texture/highlight samples are summed at every tap with metric pitch and
++Y-up/native +Y-down signs. The same sampled physical response feeds correction
+Off/On, retaining capture/noise identity, full Jacobians and retained ray coverage.
+This coarse sampled scene is neither measured MTF nor a continuous optical model,
+color-fringing prediction or a perceptual bokeh score. No interpolation, sharpen
+pass, hidden quality multiplier or external data is introduced.
+
+See the acceptance disposition for #116 ownership, merged #119 validation and
+scientific limits. Runtime/API/schema/asset/package/POC versions stay unchanged.
+
+
+## Versioned cross-tier reports
+
+The reviewed/merged #119 acceptance layer is [TIER_ACCEPTANCE.md](TIER_ACCEPTANCE.md).
+It links a reproducible three-domain report, normative finite regression envelopes,
+explicit multidimensional pupil/texture and crop/gain tradeoffs, and matched signed
+stabilization/ordinary-flash checks. Existing body, correction and producer-to-file
+acceptance remains part of that evidence. Measured calibration and unsupported
+optical metrics are not invented; runtime/assets and all versions are unchanged.

package/docs/GEOMETRIC_PREPARATION_REUSE.md

@@ -0,0 +1,141 @@
+# Call-local geometry preparation reuse: #43
+
+Release context: **package 1.0.0 candidate / root API 0.116.0**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_0.md).
+
+`calculateGeometricSamplingPlan()` already parses and copies a complete transform
+list at its public boundary. It previously called the public scalar mapping API
+for every destination pixel, reparsing/copying that same list and rebuilding its
+preparation provenance each time. This change uses one private point evaluator
+for the call-owned mapping. The public scalar API still prepares external input
+on every call and uses that same evaluator.
+
+This is a bounded internal optimization against merged main
+`c1374c31473f893310d1ce4f0d5a737aaba43ab5`, not a new prepared/cache API. It consumes
+no pending export/tier/POC draft. Root API 0.103.0, geometry schema/model versions,
+POC, package and production contracts stay unchanged.
+
+## Whole-consumer measurements
+
+[Recorded evidence](benchmarks/2026-10-02-geometric-preparation-reuse.json) contains
+two independent ordinary paired runs and one GC-assisted run. Both source trees
+were built with `tsc`. Context is Node 24.19.0/V8 13.6.233.17-node.51, Linux x64,
+AMD EPYC 9V74 and 9 logical CPUs on shared execution infrastructure. Each run
+records the reference commit and candidate source-file SHA-256; the source/build
+labels are operator-attested, and the fingerprint identifies the runtime change.
+
+The consumers are merged `calculateGeometricSamplingPlan()` and the whole
+`calculateLensCorrectedCapture()` executor: common radial map, channel-specific
+CA, affine map, joint support, actual resampling, and peripheral gain. Both use
+the same owned synthetic capture/noise identity. The sampled linear plane spans
+24×24 mm, with explicit pitch and a separate physical profile normalization
+radius. Nearest sampling is explicit; the bounded compressing coordinate maps
+have no source-prefilter requirement. No prefilter is claimed or fabricated.
+These are real bounded engine consumers, not a copied equation microbenchmark
+or a complete physical production renderer.
+
+| Consumer | Reference ms, ordinary run 1 | Candidate ms, run 1 | Candidate/reference, run 1 | Ratio, run 2 | GC-assisted ratio |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Plan 1×1 | 0.035 | 0.025 | 0.716 | 0.702 | 0.969 |
+| Correction 1×1 | 0.303 | 0.261 | 0.864 | 0.833 | 0.869 |
+| Plan 5×5 | 0.476 | 0.267 | 0.560 | 0.593 | 0.603 |
+| Correction 5×5 | 3.364 | 2.124 | 0.631 | 0.635 | 0.651 |
+| Plan 17×17 | 5.566 | 2.987 | 0.537 | 0.568 | 0.646 |
+| Correction 17×17 | 39.255 | 24.333 | 0.620 | 0.612 | 0.606 |
+| Plan 33×33 | 22.461 | 11.942 | 0.532 | 0.584 | 0.625 |
+| Correction 33×33 | 155.051 | 100.624 | 0.649 | 0.618 | 0.642 |
+| Plan 65×65 | 90.566 | 59.639 | 0.659 | 0.691 | 0.599 |
+| Correction 65×65 | 640.165 | 468.194 | 0.731 | 0.740 | 0.749 |
+
+There are five measured blocks, alternating reference/candidate order and rotating
+scenario order. The 1×1/5×5 cases use 100 warmup calls and 100 calls per block;
+larger cases use two warmups and one whole call per block. Raw block timing and
+retained-heap deltas are preserved. Final runs occurred after release checks,
+without concurrent task benchmarks/tests. Shared host activity is uncontrolled.
+GC-assisted distributions are separate; do not infer GC causality from ratios.
+
+The two ordinary runs show 26–39% shorter corrected-capture calls at 17×17 through
+65×65. Corresponding sampling plans are about 31–47% shorter. Small cases also
+improve in these runs, but microsecond-scale results have more timing noise.
+These are not portable speed constants, browser frame times, observed product
+traffic, full-resolution throughput or proof of an end-user latency benefit.
+
+The decision is to retain this small internal candidate for review. The result
+justifies removal of duplicate preparation in this concrete consumer, not a
+public mutable prepared engine, extra solver, vignetting/rotation abstraction or
+cross-input cache. #45's POC result is independent and not its evidence basis.
+No browser-motivated public API is introduced; no browser performance claim is
+made. The public implementation remains browser-safe, with the existing package
+and static gates required.
+
+## Preparation, profiling and memory
+
+Separate preparation loops measured about 7–8 µs to parse/copy the three-transform
+mapping; that cost remains at every public boundary. There is no new preparation
+stage or long-lived state. The sampling-plan result still owns its normal mapping
+and all per-pixel diagnostics. Call-local reuse avoids repeating the same work
+for every point. Small grids above include one-off/amortization evidence rather
+than assuming a prepared path is always free.
+
+Separate CPU and allocation sampling used five whole 65×65 corrected captures
+per path. Reference CPU stacks included `prepareGeometricMapping` in 882 of 2,657
+samples inside the consumer (about 33%). Candidate had 1 of 1,779. This is sampled
+inclusive attribution, not exact elapsed time or a claim that preparation costs
+33% everywhere. Recursive finite checks, radial work and other categories overlap;
+do not sum the category counts. Inlining and sampling affect attribution.
+
+V8 Inspector heap sampling, at 32 KiB intervals and requesting inclusion of
+objects collected by major/minor GC, estimated 6,946,184,128 sampled bytes for
+reference and 4,840,744,824 for candidate over five captures (about 30% lower).
+Preparation-inclusive estimates fell from 2,075,859,720 to 656,240 bytes. These are
+statistical allocation estimates, not exact allocation counters, retained live
+memory or GC-pause measurements. Instrumented runs are separate from all timing
+comparisons. No raw inspector profiles/private paths are stored. Raw net retained
+heap deltas are also retained; they are not allocation counts or context sizes.
+
+## Correctness and copy boundary
+
+External prepared objects remain untrusted: every public entry parses/copies the
+current input before evaluating it. There is no persistent context or cache to
+invalidate. The private evaluator is reached only with that call-owned mapping.
+It retains per-point finite checks, every intermediate radial operating-envelope
+check, arithmetic order, full Jacobians/principal stretches and the ordinary
+point-result validation/provenance. Scalar and batch points use the same equation
+implementation. No numerical tolerance is relaxed and no inverse iteration bound
+is changed.
+
+Affine derivative arrays are copied per result point. They must not alias another
+pixel, the returned mapping, the caller or another call. This preserves the prior
+copy semantics despite sharing the internal parsed mapping. Existing masks,
+joint crops, source coverage, prefilter requirements, resampler identities and
+retained-ray/FOV diagnostics are unchanged.
+
+`test/geometric-preparation-reuse.test.ts` compares every point in a fixed 32-case
+corpus (seed `0x43c1374c`) against scalar evaluation, covering all four quarter
+turns, off-center lattices, noncommuting affine/radial order and varied coefficients.
+It also tests mutation isolation, revalidation after prior success, folded/singular
+input and intermediate-domain failure. Existing correction/geometry tests retain
+noise/capture identity and blur/resampling guarantees. The paired benchmark checks
+complete result/provenance equality with the unchanged reference for every measured
+scenario before timing. The canonical #130 fixture is unchanged and is not used
+as performance evidence.
+
+## Reproduction and review
+
+Build an independent reference checkout of the recorded main commit with
+`npm ci` / `npm run build`, and build this candidate checkout. Run sequentially
+without concurrent task checks or benchmarks; replace the reference-root below.
+
+```sh
+node scripts/benchmark-geometric-consumers.mjs --reference-root=/path/to/reference --reference-commit=c1374c31473f893310d1ce4f0d5a737aaba43ab5
+node --expose-gc scripts/benchmark-geometric-consumers.mjs --reference-root=/path/to/reference --reference-commit=c1374c31473f893310d1ce4f0d5a737aaba43ab5 --profile=sample
+```
+
+Repeat ordinary runs separately. Profiling is optional and separate from timing.
+There is no timing CI threshold, new runtime dependency, third-party data, paid
+service or production-stage activation. Human scientific/provenance review and
+contribution-specific DCO certification remain required before merge; measurements
+are not scientific or legal certification.
+
+## Final V1 remeasurement
+
+[Final V1 performance disposition](V1_PERFORMANCE_DISPOSITION.md) records current main #204, fresh paired timing/equivalence, preparation/memory profiles and dense executed environment-to-RAW evidence. PR #205 merged the final reviewed/signed no-further-change disposition; PR #206 merged final conformance. The measured engine commit remains the historical benchmark identity. Earlier candidate and pending-remeasurement statements above are historical.

package/docs/IMAGE_FORMATION.md

@@ -1,5 +1,7 @@
 # Image-Formation Contract
 
+Release context: **package 1.0.0 candidate / root API 0.116.0**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_0.md).
+
 Photivra's image-formation contract defines **scientific ownership, coordinate semantics, and dependency/coupling boundaries** for current and future camera effects.
 
 It is not a claim that every stage is implemented, and it is not a requirement that renderers execute one literal serial filter chain.
@@ -12,20 +14,22 @@ import { getImageFormationContract } from "@photivra/engine";
 const contract = getImageFormationContract();
 ```
 
-## Five scientific domains
+## Six scientific domains
 
-The contract groups image formation into five domains:
+The contract groups image formation into six domains:
 
 1. **scene / ray geometry**
-2. **lens mapping + pupil / throughput**
-3. **field- and wavelength-dependent PSF**
-4. **time-dependent exposure / readout**
-5. **native sensor sampling -> orientation -> output / display**
+2. **scene radiance formation**
+3. **lens mapping + pupil / throughput**
+4. **field- and wavelength-dependent PSF**
+5. **time-dependent exposure / readout**
+6. **native sensor sampling -> orientation -> output / display**
 
 These are scientific ownership domains. Some effects couple more than one domain.
 
 Examples:
 
+- scene illumination, material optical response, geometry/visibility, emission, indirect transport, and time belong upstream in `scene-radiance-evaluation`; source metadata or RGB renderer values are not sensor input;
 - focus breathing changes projection/magnification and therefore couples lens mapping to scene projection;
 - lateral chromatic aberration is wavelength/channel-dependent field mapping and may share wavelength basis with the PSF model;
 - illumination vignetting is throughput-only;
@@ -34,6 +38,20 @@ Examples:
 - rolling readout couples native sensor timing to temporal integration;
 - camera rotation should be evaluable as a function of physical exposure time so global and rolling readout can consume the same motion model.
 
+## Scene-radiance ownership
+
+`scene-radiance-evaluation` is a partial foundation between `scene-ray-projection` and `lens-field-pupil-evaluation`.
+
+Its authoritative quantity is **outgoing scene spectral radiance** produced from illumination, scene geometry/visibility, material response, emission, indirect transport, and physical time. The renderer-neutral scene request/result boundary supplies declared radiance samples; the production composer validates a bound sample and consumes #110 optical throughput. It does not execute a complete scene renderer or establish a measured radiance field.
+
+The existing `SceneRadiometry` metadata remains separate. `absolute-luminance` is a photometric luminance anchor, not a wavelength-resolved radiance field. Likewise, a light-source SPD, RGB HDR environment, source irradiance, and sensor-plane spectral irradiance are different quantities and must not be substituted for one another.
+
+See [Scene Radiance and Illumination](SCENE_RADIANCE_AND_ILLUMINATION.md).
+
+Shared spectral planning now distinguishes continuous support from discrete lines. Continuous scene/optics/sensor factors may share an explicit air/vacuum coverage intersection and breakpoint union. Delta-like line spectra remain wavelength-integrated measures and are summed without a dλ multiplier; they are never converted into synthetic continuous density merely to enter the continuous sensor quadrature path.
+
+Time-varying illumination now uses a separate temporal profile. Source waveforms are relative multipliers evaluated in physical seconds and must be explicitly registered to the capture `first-opening-boundary-phase` reference before flash/flicker can participate in exposure integration. The local exposure window—not total sensor data-readout duration—defines the integration interval. The temporal foundation returns multiplier/time measures only; source magnitude, material/visibility transport, outgoing radiance, optics, sensor response, metering and automatic exposure remain downstream/separate.
+
 ## Coordinate spaces
 
 The contract explicitly distinguishes:
@@ -99,6 +117,34 @@ Exposure duration and sensor readout timing are independent:
 
 This allows later rolling-shutter work to consume the same time-parameterized camera-motion model used for global exposure.
 
+The standalone `calculateSensorReadoutTiming()` foundation now supplies an invariant native-raster spatial readout phase schedule. Its first model is a caller-declared uniform-linear single-axis approximation with independently evidenced data-readout duration and rolling spatial skew. It does not define exposure windows or shutter-curtain motion, and it does not infer physical hardware readout lines from the effective native image raster.
+
+The additive `assessReadoutExposureTimingLinkage()` layer can validate an explicitly evidenced normalized spatial-phase relationship between rolling readout and an electronic exposure boundary. It never infers absolute temporal synchronization; total data-readout duration is not a surrogate for exposure timing, and matching direction/span alone is insufficient evidence of a shared clock.
+
+The standalone `calculateCaptureExposureWindows()` foundation separately describes local opening/closing exposure boundaries. It uses the first opening-boundary phase as its explicit time reference, preserves independent nominal/opening/closing timing, validates positive local duration across the whole active rectangle, and keeps mechanical/EFCS/electronic actuator identity separate from timing. It does not automatically bind those exposure boundaries to sensor readout phase or to the existing camera-rotation time origin.
+
+The standalone `calculateCaptureRotationTrajectories()` bridge now explicitly binds that first opening-boundary phase to `t = 0` of the existing pure-camera-rotation model and evaluates stationary reference rays at local exposure start/end. It remains forward temporal geometry only: it does not consume sensor readout timing, solve the implicit rolling-shutter image warp, or integrate motion blur over the exposure interval.
+
+The additive `calculateCaptureRotationInverseMappings()` layer now supplies an instantaneous destination-to-reference mapping at a caller-selected phase within each local exposure window. Under the current pure-rotation model the inverse is analytic once destination location fixes local capture time, so no iterative solver is used. This remains pre-lens, pre-output temporal geometry and does not replace finite-exposure integration.
+
+The additive `calculateCaptureRotationTemporalQuadrature()` layer now supplies deterministic uniform-midpoint time nodes and separate normalized-average/seconds-valued temporal measures across each local exposure. It preserves the instantaneous inverse mapping as the geometry source of truth but does not itself integrate radiance, visibility, shutter transmission, sensor response, PSF, or output pixels.
+
+## Production composition consumer
+
+The ownership graph is now consumed by a separate production-plan contract.
+
+The production planner:
+
+- expands required upstream stages from this graph;
+- preserves coupled-stage metadata;
+- never creates a second hidden stage order;
+- records modeled-zero, omitted, unsupported, and blocked states explicitly;
+- keeps renderer capability declaration separate from scientific stage ownership.
+
+Current plan schema `0.7.0` supports the physical sample path, attached-RAW processing and the bounded [executed environment capture](PRODUCTION_ENVIRONMENT_CAPTURE.md). Complete declared environment input can execute all fourteen graph stages through RAW and optional output. Sample-only and attachment-only routes preserve their missing upstream blockers; temporal geometry alone does not integrate radiance. See [processed output](PROCESSED_OUTPUT.md) for the attachment boundary. See [V1 composition and consumer map](V1_COMPOSITION_MAP.md) for current consumers and required handoffs.
+
+See [Production Image-Formation Plan](PRODUCTION_COMPOSITION.md).
+
 ## Renderer semantics
 
 Renderer implementations may use a bounded real-time preview approximation or a higher-fidelity deterministic reference evaluation, but both must consume the same engine-owned scientific contract.
@@ -110,9 +156,11 @@ For geometric warps:
 - scene depth/occlusion order is preserved across warps;
 - renderer backend choice may change implementation/fidelity, not model semantics.
 
-## Reserved sensor ordering
+## Sensor ordering and standalone boundaries
+
+The static ordering registry 0.4.0 retains broad foundation/reserved maturity labels; these are not route-specific capability checks. Plan 0.7.0 records actual bounded execution and blockers. The standalone layers below explain each primitive’s ownership and do not negate the separate executed environment route.
 
-The contract reserves a future sensor path without claiming it is implemented:
+The contract owns this sensor ordering. Individual descriptive profiles do not execute the whole path; the bounded environment production route explicitly composes supported terms:
 
 ```text
 optical PSF
@@ -129,6 +177,54 @@ optical PSF
 
 Temporal exposure/readout couples into the photosite/charge stages rather than acting as an unrelated display blur.
 
+The standalone capture-mode profile now describes acquisition sequence, per-frame effective sampling, optional inter-frame sensor offsets, reconstruction-stage labels, processed-image raster, and downstream dependencies. It does **not** implement the reserved CFA/photosite/reconstruction algorithms. A mode's processed raster remains upstream of physical orientation and final output crop/resampling and cannot redefine physical sensor geometry or FOV.
+
+The standalone color-sampling topology profile now describes monochrome, arbitrary periodic mosaic phase/channel assignment, and layered color declarations with an explicitly unresolved spatial relationship. The periodic topology lives on a distinct native sensor sampling-site lattice rather than `NativeImageRaster`; no binding to effective image samples or physical photodiodes is inferred. This metadata foundation does not yet implement the reserved photosite/CFA sampling stage, spectral response, sparse site exceptions, RAW sampling, or reconstruction.
+
+The additive native-effective-raster/color-site binding now provides the missing structural bridge between capture-mode effective samples and monochrome/periodic topology. It requires evidence for the exact native raster relationship and grouped-mode phase, preserves full-frame absolute CFA phase, and reports compact pre-reconstruction source regions/channel counts. This still does **not** implement the reserved photosite/CFA sampling stage: no signal weights, spectral response, photons/electrons, RAW values, aliasing, or reconstruction are calculated.
+
+The standalone sensor optical-stack profile now makes the upstream stack boundary explicit without claiming a complete stack response. Ordered physical component roles and microlens presence are descriptive. Effective anti-aliasing response is separately modeled as unknown, absent, present-but-unresolved, or a normalized native-physical point-splitting approximation. The resolver exposes only that AA spatial term; cover/filter transmission/refraction, microlens angular/collection behavior, wavelength/field/polarization dependence, and convolution with the lens PSF remain future work. The profile alone is not a complete optical-stack simulation. The production environment route consumes the supported explicit spatial/response bindings and records approximation limits.
+
+The standalone sensor sampling-aperture profile now supplies explicit native-physical registration for the color-site center lattice and a first geometric sensitive-region footprint. The rectangle is a normalized spatial-area averaging support plus a separately reported geometric area/fraction; it is **not** QE or radiometric collection efficiency. AA point splitting, microlens redirection, diffusion/crosstalk, spectral response, photons/electrons, and RAW values are still absent. This advances the geometry needed by the reserved `photosite-cfa-sampling` stage without claiming that stage is fully implemented.
+
+The additive sensor spatial-quadrature layer now combines the resolved AA point-splitting term with the geometric aperture using deterministic native-physical midpoint nodes. AA is applied by inverse source lookup, the destination site's CFA channel remains fixed, and off-active-area pre-AA source support is preserved. The result is still a geometry/measure plan only: no optical field, spectral response, radiometry, temporal integration, RAW value, or reconstruction is calculated, so the `photosite-cfa-sampling` stage remains reserved.
+
+The additive spatial-sample reducer can now apply those weights to caller-supplied nonnegative linear relative values or physical irradiance. It does not turn a channel ID into spectral filtering, does not integrate over time/wavelength, and does not calculate photons, electrons or RAW codes. Consequently this is still a pre-response site sample and the full `photosite-cfa-sampling` stage remains reserved.
+
+The standalone sensor spectral-response profile now establishes explicit wavelength-dependent meaning for linked semantic channels. It can resolve effective external QE, effective A/W responsivity, or declared filter×detector-EQE at one wavelength while preserving response scope and reusable-data provenance. It performs no spectral irradiance integration, exposure-time integration, photon/electron conversion, or RAW reconstruction, so the complete `photosite-cfa-sampling` and downstream charge stages remain only partially founded/reserved.
+
+The additive sensor spectral-quadrature plan supplies deterministic wavelength nodes and dλ measures without turning them into signal. Response knots and explicit caller breakpoints define segment boundaries, a maximum subinterval width bounds midpoint spacing, and the selected response scope/provenance remain visible. Sensor-response coverage is not treated as scene/optics coverage, response values are not applied, QE is not conflated with A/W responsivity, and continuous-density quadrature does not silently approximate discrete spectral lines.
+
+The shared spectral-coverage layer can now derive the sensor channel's usable range and interpolation knots and combine them with separately declared scene/optics/material coverage. This is planning metadata only. Discrete illumination lines use a separate integrated-line measure path and are not accepted as additional continuous quadrature breakpoints.
+
+The additive spatio-spectral reducer now performs the first explicit spatial × wavelength measure composition for caller-supplied sensor-plane E_lambda(x,y) in W/m²/nm. It requires exact color-profile/channel linkage, retains every required edge/off-frame spatial source sample, caps the Cartesian product, and produces pre-response wavelength-integrated irradiance plus geometric-aperture incident flux.
+
+The additive response-application compatibility gate now checks whether that pre-response result is structurally eligible for a later spectral response. It requires exact response/color/aperture/stack linkage, source-plane compatibility with response scope, matching geometric-aperture normalization, explicit spatial response uniformity/separability, resolved wavelength basis, and compatible reference conditions or an explicit approximation. Full-site-cell and effective-collection-area normalizations remain blocked because the current reducer has not integrated those radiometric area bases.
+
+The additive response operating-range gate evaluates optical input against an evidence-backed linearity range with explicit wavelength applicability, reference conditions, uncertainty and nonlinearity criterion. It distinguishes broadband-total evidence from per-spectral-bin applicability and requires an explicit maximum bin width for the latter. Wavelength-dependent response conversion is authorized only when each spectral bin and the spatially reduced aperture satisfy the declared linearity model. Exposure characteristic-curve linearity, accumulated-charge/full-well saturation, conversion gain, readout electronics and ADC linearity remain downstream temporal/electrical contracts.
+
+The photon-energy wavelength foundation resolves the physical energy-per-photon basis used by EQE conversion. Vacuum wavelengths use exact SI h and c. Air wavelengths must first be converted to vacuum wavelength through a sourced phase refractive index at the exact wavelength, with explicit atmospheric-condition compatibility; no implicit air≈vacuum shortcut is allowed.
+
+The EQE electron-rate foundation applies the photon-domain response conversion after all prior gates. It evaluates each wavelength-bin radiant-power contribution independently, divides by photon energy to obtain incident-photon rate, applies effective external QE through the authoritative spectral-response resolver, and sums expected generated-electron rates with compensated summation.
+
+The sibling A/W responsivity foundation applies the current-domain response independently per wavelength bin and sums detector-terminal photocurrent magnitude. Its calibration is additionally bound to explicit detector bias and current-readout load conditions. This current is not treated as electron rate, accumulated charge, transimpedance voltage, or circuit-polarity truth.
+
+Both paths still stop before exposure-time integration, accumulated-charge/full-well behavior, stochastic noise, analog electronics, ADC/RAW and reconstruction.
+
+The local sensor-rate/exposure binding carries each engine-produced response rate back to its exact color-sampling site, through an evidenced one-to-one native-effective-raster relationship, and into the authoritative local shutter-window schedule. This establishes which local time interval belongs to that rate but deliberately does not assume the rate is constant through the interval.
+
+The constant-rate temporal-integration foundation now permits rate × local-duration only under a stationarity declaration bound to the exact site/window. EQE rates produce fractional expected photon/electron counts; A/W current produces photocharge magnitude in coulombs without carrier inference.
+
+The dark-current foundation adds pre-compensation thermally generated expected electrons to the EQE-side charge model using exact local exposure duration and explicit temperature applicability. It does not model black-level compensation, hot-pixel/defect excess, leakage/injection, dark-current nonuniformity unless separately evidenced, or dark-current shot-noise realization. A/W integrated charge is still not treated as stored pixel electrons.
+
+The accumulated-charge completeness foundation combines photo, dark and explicitly incremental other stored-electron expectations only when all terms bind to one exact local exposure. Completeness is not inferred from missing components; an evidence-backed declaration must enumerate the supplied additional charge components and state that all material stored-electron contributors are accounted for.
+
+The physical charge-capacity foundation compares the complete expected stored-electron total with an evidence-backed storage limit. It remains an expectation-domain assessment: no stochastic saturation probability, clamp, post-capacity charge, overflow amount, anti-blooming or neighbor redistribution is modeled.
+
+The camera saturation-capacity foundation is separate: it compares dark-corrected photo-signal electron-equivalent expectation against a measured/calibrated camera response-chain capacity. Dark/other stored charge is not added to that signal-domain comparison, and physical full-well is not reused. The first camera-capacity contract does not identify whether analog electronics, ADC/digital clipping, or another stage is the actual limiter.
+
+Stage-specific clipping transfer functions, stochastic noise, analog electronics, ADC/RAW and reconstruction remain downstream.
+
 ## Current implementation status
 
 Each stage is labeled:
@@ -141,7 +237,7 @@ Do not infer capabilities from a stage merely because it is present in the contr
 
 ## Test Fixture relationship
 
-The private Test Fixture may provide deterministic browser regression targets, but it is not the scientific source of truth for the open engine.
+External consumer fixtures may provide browser regression targets; engine implementation and independent conformance remain the scientific source of truth.
 
 Engine analytical/invariant tests establish model correctness. Test Fixture images provide secondary integration and renderer evidence.
 

package/docs/LINEAR_CAPTURE_ENCODING.md

@@ -0,0 +1,25 @@
+# Deterministic linear capture encoding: #15C
+
+Release context: **package 1.0.0 candidate / root API 0.116.0**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_0.md).
+
+`calculateLinearCaptureEncoding()` produces format-neutral unsigned 16-bit linear codes from one bounded inline `SimulatedCapture` plane. The exact plane/image-state identity is mandatory. The master stays unchanged; color, WB application, source reference value and upstream capture-saturation history accompany the encoded data. It neither chooses a file format nor invents a color conversion.
+
+Encoding schema `0.1.0` uses one uniform channel mapping. Let B be `blackValue`, b be `blackCode`, R be the source plane's `referenceWhiteValue`, and r be `referenceWhiteCode`. R must exceed B, codes satisfy 0 ≤ b < r ≤ 65535, and all derived ranges/scales must be finite and representable. The continuous code is `b + (sample-B)/(R-B)*(r-b)`; scale is `(r-b)/(R-B)` codes per relative source unit. Same normalization/scale on every channel preserves linear color ratios after subtracting the declared black baseline.
+
+| Contract | Meaning |
+| --- | --- |
+| blackValue / blackCode | Relative source baseline and its integer code; blackCode can reserve room for negative samples. |
+| referenceWhiteValue / referenceWhiteCode | Source normalization and its code; reference white can be below the code maximum to preserve headroom. |
+| representable limits | B − b/scale and B + (65535−b)/scale; these are encoded range limits, not physical capture saturation. |
+| headroomFactor | (65535−b)/(r−b), relative to the above-black reference-white interval. |
+| negativeValues | Explicit reject of any sample < 0, or preserve-if-representable. The latter still obeys the independently declared out-of-range policy. |
+| outOfRange | Explicit reject, or clip to 0/65535 with separate low/high source-sample counts. |
+| rounding | Nearest code; exact binary64 half ties toward the larger code. No dither or hidden stochastic state. |
+
+The implementation compares finite source values with representable limits before arithmetic, so extreme finite samples can clip without overflowing the mapping. Exact black/reference/endpoints return their declared codes; remaining in-range mapped values round with floor(code+0.5). Only endpoint arithmetic roundoff is bounded back to the code interval. Ideal in-range rounding error is at most 0.5/scale source units; this bound excludes clipping and binary64 arithmetic error. No promise of correctly rounded arbitrary-precision real arithmetic is made. NaN/Infinity/sparse source arrays and invalid or numerically unrepresentable ranges fail. Identical validated inputs produce identical codes across the supported JS runtimes.
+
+An encoded maximum or quantized sample at 65535 does not prove sensor saturation, and a sample rounded to an endpoint is not counted as source clipping. Source `captureSaturation` remains upstream history in its original capture domain. `defaultRenderingExposureEv:null` means the encoder selects no rendering exposure or display white. It performs no gain/WB/adaptation, gamma/transfer curve, tone/look/gamut mapping, resampling, RAW reconstruction or recovery of upstream LDR losses.
+
+Output is serializable numbers plus explicit metadata, in row-major interleaved source channel order. `captureMetadata` carries the sanitized source manifest without float planes: geometry/settings, resolved WB intent, adopted white, noise/source identities and model/evidence provenance remain available to serializers. `sourcePlane` carries color/WB/history/saturation and raster/channel identity without float storage. Packing bytes, endianness, checksums, TIFF/DNG tags and required format-specific range restrictions belong to #16; a serializer must honor the declared scientific meaning and reject mappings it cannot represent. XYZ, virtual channels and transformed RGB retain different identities, even if all can be quantized. Quantizing unresolved channels does not establish a usable sensor color profile or a DNG export-readiness claim. External float references remain manifests; this synchronous bounded executor rejects them rather than performing IO or trusting unverified bytes.
+
+Tests share #130 camera/seed metadata with the color tests. They check reference/headroom/clipping invariants, exact half ties and neighbors, offset-preserved negatives, independent negative/range rejection, extreme finite clipping, nonunit source reference/black, retained saturation, color→encoding consistency, deterministic results, state substitution, private/malformed policies and invalid samples/ranges. Implementation and arithmetic fixtures are independently authored, without third-party code/data or new runtime dependencies. Human science/provenance review and contributor DCO certification remain required before inclusion.