@photivra/engine 0.6.0 → 1.0.0

package/docs/PHYSICS_FOUNDATION.md

@@ -1,5 +1,7 @@
 # Physics Foundation
 
+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 starts with analytical models that can be independently tested and whose assumptions can be stated explicitly.
 
 ## Implemented models
@@ -92,7 +94,77 @@ At a focus distance of at least 100 focal lengths, the ideal thin-lens projectio
 
 The focus-aware model improves internal consistency with thin-lens DOF/defocus calculations, but it is still an ideal paraxial model. It does not model real-lens focus breathing, pupil magnification, principal-plane movement, distortion, aberrations, or lens-specific macro behavior.
 
-Projected subject motion is a representative-point displacement model with constant linear world velocity. It does not yet describe scale blur of an extended object whose magnification changes materially during the exposure.
+Projected subject motion remains a representative-point displacement model with constant linear world velocity. The separate extended-object projection foundation now evaluates multiple explicit metric points under shared rigid translation, so depth-direction motion can produce spatially varying trajectories and validated planar magnification where appropriate.
+
+### Extended-object projection under rigid translation
+
+A representative point does not fully describe an extended object moving along the optical axis. Under rectilinear projection, an on-axis center point can remain fixed while off-axis points move radially as object depth changes.
+
+The extended-object foundation therefore projects each supplied metric point independently through time.
+
+For a rigid object and translating camera:
+
+```text
+relative velocity = object translation - camera translation
+position_i(t) = position_i(0) + relative velocity * t
+projected_i(t) = v * (x_i(t)/z_i(t), y_i(t)/z_i(t))
+```
+
+where `v` is the selected nominal or focus-aware image-plane projection distance.
+
+This first model is deliberately rigid and translational. It does not model object rotation, articulation, deformation or acceleration.
+
+A single uniform magnification is scientifically justified only for a constrained geometry. Photivra therefore reports a planar scale diagnostic only when the caller explicitly declares a fronto-parallel planar patch and every supplied point validates against the same reference depth. Under shared rigid translation the diagnostic scale is:
+
+`reference depth / current depth`
+
+That special-case result does not imply that arbitrary 3D geometry admits one scale or one homography.
+
+When bound to #12, each object point is evaluated on its own local exposure clock. This preserves rolling-capture timing without treating sensor data readout as exposure timing.
+
+The geometry result does not solve visibility. Axial/lateral motion can reveal/hide surfaces or move geometry through frame boundaries; a renderer must evaluate those states explicitly. Similarly, relative depth changes can alter defocus/PSF through the exposure, so a static blur/PSF composition is not automatically valid.
+
+### Mode-bound exposure/readout timing and temporal translation
+
+The #12 closure preserves two different clocks:
+
+1. **local exposure-window timing**, referenced to the first opening-boundary phase; and
+2. **sensor data-readout timing**, referenced to its own native readout phase.
+
+A capture-mode timing profile binds both sets of facts to one exact capture-mode/profile identity without asserting that those clocks are synchronized. Global readout removes spatial readout skew; it does not remove finite-exposure motion.
+
+The first supported exposure/readout schedules remain simultaneous or uniform-linear native scans. More complex non-uniform schedules are rejected unless a future explicit model represents them.
+
+Pure camera rotation can be evaluated without scene depth. Camera translation cannot. Under constant translation, a stationary scene point at metric position `(x,y,z)` is evaluated from its relative camera-space position over time, so image displacement scales with scene depth through rectilinear projection. Consequently, arbitrary 3D translation does not admit one globally valid image-plane homography.
+
+Optional subject velocity remains separate from camera translation and composes as relative motion. The model does not reinterpret subject motion as sensor/readout behavior.
+
+Temporal radiance integration uses deterministic midpoint nodes inside each authoritative local exposure interval. Scene-radiance providers must evaluate at those physical capture times; sensor readout timing is not substituted for exposure time. Per-node uncertainty/evidence is preserved, while aggregate uncertainty remains unquantified unless justified correlation assumptions are supplied.
+
+### Manual flash timing and scene-light boundary
+
+The first flash model composes two already-established domains instead of introducing a special image effect:
+
+1. #85 spatial/temporal illumination; and
+2. #12 exposure-boundary timing.
+
+A short manual-flash pulse is an aperiodic relative illumination waveform attached to an explicit spatial source. The source geometry therefore remains available to the scene-radiance transport layer for distance, surface-angle, visibility/shadow, and indirect-light behavior.
+
+Ordinary full-frame flash synchronization requires a non-empty interval where every point in the active capture is simultaneously exposed. For the currently supported simultaneous or uniform-linear boundary schedules:
+
+- latest opening phase is zero for a simultaneous opening, otherwise the declared opening traversal duration;
+- earliest closing phase is the nominal closing reference;
+- ordinary one-pulse sync is valid only when the complete pulse support lies inside that interval.
+
+This rule is derived from exposure boundaries, not sensor data readout.
+
+Front- and rear-curtain modes differ only in where the same pulse support is registered inside that valid interval. Their different relationship to subject motion/ambient trails must emerge from time-dependent scene-radiance integration rather than drawing a synthetic trail.
+
+Flash duration and shutter duration remain independent. Extending the shutter can integrate more ambient scene time without proportionally increasing a fixed short flash pulse.
+
+Schema 0.1.0 intentionally excludes HSS. A moving-slit exposure with no whole-frame-open interval cannot be made ordinary-flash-compatible by relabeling a single pulse as HSS.
+
+Manual flash also excludes TTL/preflash metering, recycle/thermal behavior, flash exposure lock, red-eye/modeling/AF-assist emissions and branded protocols. Camera WB remains downstream interpretation and never changes the emitted flash spectrum.
 
 ### Generic illumination vignetting
 
@@ -176,10 +248,44 @@ In composed POC capture mode, the equivalent-viewing helper uses the final retai
 
 The model is not a macro calibration model and does not include diffraction, pupil magnification, aberrations, focus breathing, or lens-specific principal-plane behavior in its DOF criterion.
 
+### Focus-control state versus optical focus
+
+Focus control is a camera-control state machine, not a blur algorithm.
+
+The #104 layer resolves a target/control event into the existing #103 `FocusPlane`. Downstream thin-lens, defocus and PSF calculations therefore depend only on the resulting finite/infinity optical focus state, not on whether that state came from MF, AF-S, AF-C or focus lock.
+
+Finite autofocus target distance uses the same longitudinal camera-space/conjugate distance convention as #103. Off-axis points on one fronto-parallel plane therefore resolve to the same ideal focus distance; renderer ray length is not an autofocus distance.
+
+The first autofocus actuator is an explicitly ideal instantaneous approximation. It supplies deterministic state semantics without modeling motor dynamics, AF sensor error, hunting, subject-recognition quality, low-light behavior or branded-camera performance.
+
+Single AF acquires once and holds. Continuous AF can consume time-ordered observations of one stable target identity. Target loss holds the last focus and requires an explicit reacquisition event; the engine never silently jumps to another subject.
+
+Focus lock freezes the resolved optical state independently from AE, metering and white balance. Release-priority policy is evaluated by a separate gate and cannot alter the optical focus calculation.
+
 ### Defocus circle
 
 Defocus is calculated geometrically by comparing the selected sensor plane for the focus distance with the ideal image plane for the subject distance and projecting an ideal circular entrance-pupil cone to the sensor.
 
+### Real-lens sampled PSF and complex-pupil propagation
+
+The #113 framework adds explicit combined primary-optical PSF representations without redefining the existing geometric-defocus or circular-Airy diagnostics.
+
+A sampled PSF is a full 2D unit-energy intensity distribution in image-plane metric coordinates. Regular-grid interpolation is bounded across focal length, focus state, aperture, field X/Y, wavelength and signed image-plane defocus. The engine never extrapolates beyond declared profile support.
+
+Field curvature and longitudinal chromatic focus are represented as field-/wavelength-dependent best-focus image-plane offsets. They do not modify distortion or lateral-CA coordinates.
+
+A complex pupil stores relative amplitude plus optical-path difference. The reference evaluator uses scalar Fraunhofer propagation:
+
+`PSF ∝ |FT{ A(x,y) exp(i 2π OPD(x,y)/λ) }|²`
+
+and then normalizes the sampled intensity to unit energy. Diffraction and aberration are therefore evaluated together in this path rather than composed as two unrelated image-space blur kernels.
+
+Mechanical pupil clipping may be represented in the pupil amplitude/PSF shape, but relative pupil throughput is an explicit separate factor. This prevents the normalized PSF from absorbing throughput that #110 would later apply again.
+
+MTF magnitude alone cannot uniquely determine a PSF because phase is absent. Photivra therefore accepts MTF magnitude as diagnostic/validation data but never reconstructs a unique PSF from it.
+
+Lens PSF remains upstream of the sensor optical stack, sensor sampling and reconstruction. Stray light is also separate because ghosts and veiling glare are not ordinary primary-image PSF blur.
+
 ### PSF/pupil foundation
 
 The engine now exposes a PSF/pupil foundation that evaluates existing geometric defocus and circular diffraction diagnostics in one explicit context while keeping the numerical contributions separate.
@@ -194,7 +300,7 @@ The context declares:
 
 The current foundation does **not** calculate a combined point-spread function or MTF. Defocus-circle diameter and Airy first-zero diameter are not added together or collapsed into one sharpness value.
 
-Reserved future contributions include non-circular diffraction, mechanical pupil clipping, field curvature, field-dependent aberration structure, and field-dependent bokeh.
+The dedicated ideal-polygon API evaluates on-axis non-circular diffraction density; the real-lens framework owns explicitly profiled pupil clipping, field curvature, aberration and bokeh. None is silently combined by the legacy diagnostic calculator. See [PSF and Pupil Foundation](PSF_FOUNDATION.md).
 
 Illumination vignetting remains outside the PSF contribution list because it is currently modeled as throughput-only.
 
@@ -208,7 +314,7 @@ where `λ` is wavelength and `N` is f-number.
 
 This is a monochromatic, ideal-circular-pupil diagnostic.
 
-It is deliberately separate from regular-polygon aperture geometry used for bokeh/sunstar exploration. Supplying a polygon blade count does not convert the circular Airy result into a polygon-aperture diffraction PSF; a physically consistent non-circular diffraction model remains future work.
+It is deliberately separate from regular-polygon aperture geometry used for bokeh/sunstar exploration. Supplying a polygon blade count does not convert the circular Airy result into a polygon-aperture diffraction PSF. Use `calculateIdealPolygonDiffractionPsf()` with an explicit physical equal-area pupil, propagation distance and wavelength for the ideal on-axis polygon model; arbitrary real diaphragms remain outside that model.
 
 ### Ideal diaphragm geometry and sunstar symmetry
 
@@ -228,11 +334,52 @@ The current model returns one global image-plane vector. It does not compute the
 
 Equivalent stabilization stops attenuate angular displacement by `2^-stops`; that attenuation is explicitly an educational approximation rather than a real IBIS/OIS or CIPA performance model.
 
+### Sensor stochastic readout and RAW boundary
+
+The #14 closure separates deterministic expectation calculations from stochastic realizations and from digital encoding.
+
+Expected photo, dark and additional stored charge remain upstream scientific quantities. A seeded realization may sample photo/dark Poisson statistics and explicitly declared additional-component statistics without mutating those expectation APIs.
+
+Electronic read noise is a downstream input-referred stochastic contribution and remains separate from photon/dark shot noise. Multiple declared RMS read-noise components are sampled independently; their metadata is not collapsed into a claim about physical circuit origin unless evidence says so.
+
+The electronic chain preserves separate saturation domains:
+
+1. physical charge-storage capacity;
+2. pre-ADC electron-equivalent saturation;
+3. ADC/digital code saturation.
+
+A scalar clamp at physical capacity is not a blooming model. Blooming requires spatial charge-transfer/adjacency and anti-blooming semantics.
+
+Conversion gain is expressed as electrons per digital code for one explicitly selected operating regime. The engine does not infer that regime from ISO, CMOS/CCD family, capture-mode labels, or product tier.
+
+RAW codes retain absolute native sensor/CFA coordinates. Capture orientation and final output rotation do not rotate or re-phase the sensor mosaic.
+
+The first reconstruction model is an explicit linear native-neighborhood transform tied to exact capture-mode and CFA identities. It is intentionally not a generic claim that a CFA name determines a demosaic algorithm. It also does not claim moiré/aliasing physics unless an adequate pre-sampling optical/scene spatial-frequency model exists.
+
+### ISO/exposure-index and sensor-readout boundary
+
+ISO/exposure index is a camera control/reporting state, not a photon source.
+
+For fixed scene radiance, aperture, shutter duration, optical transmission and sensor collection geometry, changing ISO does not change the number of photons that arrived during the exposure. Accordingly, #7 never modifies upstream photon/photoelectron expectation or photon shot-noise statistics merely because a different ISO/EI was selected.
+
+The detailed ISO capability contract distinguishes:
+
+- standard exposure-index settings;
+- expanded low/high reported settings;
+- Auto ISO eligibility/ranges;
+- optional capture-mode restrictions.
+
+It does not infer physical gain, conversion gain, read noise or saturation from those numbers.
+
+When generic high-ISO behavior is needed, #7 maps an explicit ISO/capture-mode state to an explicit #14 readout regime. The selected regime—not the ISO number itself—contains the declared conversion gain, electronic read noise and downstream saturation/ADC behavior. This keeps piecewise or dual/multiple-gain behavior representable without smoothing it into a universal ISO→noise curve.
+
+Good/Better/Best labels are convenience mappings to full signal-chain profile identities. They are not sensor equations and do not rank real cameras. Sensor size/resolution, photon shot noise, processed-image denoising/sharpening, and technology-family labels such as CMOS/CCD remain separate domains.
+
 ### Radiometry readiness boundary
 
 Absolute scene luminance or relative exposure alone is not enough to derive a defensible photon count.
 
-Before any future composed photon simulation, Photivra requires an explicit prerequisite package covering:
+Before a composed photon simulation, Photivra requires an explicit prerequisite package covering:
 
 - scene spectral radiance or a documented spectral approximation;
 - optical transmission;
@@ -264,7 +411,7 @@ The contract intentionally avoids describing all image formation as independent
 
 Current analytical primitives remain valid and separately named. Adding a broader stage must not silently reinterpret existing focal length, defocus, diffraction, motion, crop, or sensor-sampling outputs.
 
-Reserved sensor stages in the contract are ordering placeholders only; they do not establish OLPF, CFA, photon, ADC, or reconstruction capabilities.
+The static ordering contract retains broad foundation/reserved metadata. Those labels alone do not establish execution. Production plan 0.7.0 separately records actual bounded environment-route execution through sampling, photons, charge, ADC and reconstruction; broader unsupported models remain blocked.
 
 ## Source provenance
 

package/docs/POC_API.md

@@ -1,5 +1,7 @@
 # Local POC Simulation API
 
+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 includes a minimal Node HTTP transport for proof-of-concept development and integration testing.
 
 It is **not** the recommended production runtime. Browser applications can consume the root `@photivra/engine` scientific surface directly; the production Photivra architecture is intended to keep the simulation math client-side rather than expose this unauthenticated POC server to the public internet.

package/docs/POC_PROJECTION_REUSE.md

@@ -0,0 +1,124 @@
+# Request-local defocus projection reuse: #45
+
+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).
+
+The measured candidate reuses the focus-plane image distance already calculated
+inside `simulatePocCamera()` for its subject and defocus sweep. It is a small
+private optimization against merged main
+`c1374c31473f893310d1ce4f0d5a737aaba43ab5`. It consumes no pending tier/export draft.
+Root API 0.103.0, POC API 0.20.0 and public scalar signatures/semantics stay unchanged.
+
+## Measurement and decision
+
+[Recorded evidence](benchmarks/2026-10-02-poc-projection-reuse.json) contains two
+independent ordinary paired runs and one GC-assisted paired run, all built with
+`tsc`. Each path/scenario has 500 warmup calls and nine blocks of 1,000 whole
+requests. Reference/candidate order alternates, scenario order rotates, and the
+final recorded runs were performed after local tests finished, without concurrent
+task benchmarks. Shared host activity remains uncontrolled.
+
+Runtime was Node 24.19.0/V8 13.6.233.17-node.51 on Linux x64, reporting AMD EPYC 9V74
+and 9 logical CPUs. Every run records runtime/hardware, baseline commit and SHA-256
+fingerprints of both candidate runtime source files. The source identity is
+operator-attested; fingerprints allow verification after commit. These are
+public POC developer-consumer request shapes, not observed product traffic or
+browser frame-time evidence.
+
+| Whole request | Ordinary reference µs, run 1 | Candidate µs, run 1 | Candidate/reference, run 1 | Ratio, run 2 | GC-assisted ratio |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Base, no sweep | 11.11 | 11.29 | 1.017 | 1.014 | 0.989 |
+| 1 defocus sample | 12.16 | 11.89 | 0.978 | 0.942 | 0.974 |
+| 2 defocus samples | 13.20 | 11.85 | 0.897 | 0.950 | 0.980 |
+| 4 defocus samples | 14.69 | 13.50 | 0.919 | 0.906 | 0.941 |
+| 8 defocus samples | 18.37 | 16.67 | 0.907 | 0.856 | 0.952 |
+| 16 defocus samples | 27.10 | 19.97 | 0.737 | 0.819 | 0.857 |
+| 16 each defocus/size/motion | 56.33 | 50.52 | 0.897 | 0.902 | 0.880 |
+| Portrait/off-center staged mixed | 95.54 | 90.79 | 0.950 | 0.924 | 0.970 |
+
+A ratio below one means a shorter measured request. The two ordinary runs show
+18–26% improvement on the 16-defocus shape, about 10% on mixed samples and 5–8%
+on staged capture. The base shape is about 0.16–0.18 µs slower (1.4–1.7%) in those
+runs; no universal speedup or zero overhead is claimed. GC-assisted timings are
+separate distributions and do not establish ordinary-vs-GC causality. Earlier
+exploratory runs are excluded from the final evidence.
+
+The decision is to retain this bounded private reuse candidate for human review.
+The repeatable sweep/mixed improvement justifies it, with the small base-path
+tradeoff explicitly visible. Further FOV/motion/sampling reuse or a generic
+prepared public API is not justified by this experiment. #43 retains its separate
+measurement/decision gate; this result does not establish its conclusion.
+
+## Preparation and memory
+
+Context creation copies three scalar numbers into a frozen object only when a
+non-empty defocus sweep is present. It adds no new thin-lens resolution: it borrows
+the same request's existing calculated projection. It cannot survive the request,
+is not returned in the response and has no global cache or cross-input lifetime.
+No-sweep requests allocate no context. An isolated object/freeze probe measured
+about 42–46 ns per preparation; its JIT/escape behavior can differ inside the
+whole call, so it is not an independent cost/error bound.
+
+Short sweeps are explicitly measured above; benefits increase enough at 16
+samples to amortize the context in these workloads. A single sample is close to
+noise, so no portable break-even count is asserted. Raw net retained-heap deltas
+are preserved but are not allocation counts or persistent-context size estimates.
+
+A separate V8 Inspector allocation-sampling pass measured 2,000 staged requests
+per path at 32 KiB sampling intervals, requesting inclusion of objects collected
+by both major and minor GC. Estimated sampled bytes were 593,837,880 for reference
+and 551,945,312 for candidate (about 7% lower); inclusive thin-lens sampled bytes
+were 177,301,960 and 138,224,096 (about 22% lower). These are statistical sampling
+estimates, not exact allocation counters, GC-pause measurements or latency
+attribution. Instrumented allocations are separate from all timing comparisons.
+No raw inspector profile/private path is stored.
+
+The sensor dimensions are an explicit 36×24 mm, 6000×4000 raster. This POC computes
+analytical diagnostics; it does not execute 24 million image samples. Raster
+size is therefore context, not a claim of full image-rendering throughput. The
+canonical tiny #130 fixture is used only for correctness, never as the runtime
+performance basis.
+
+## Correctness and boundary
+
+The public scalar `calculateDefocusCircle()` uses the same shared implementation
+without a borrowed projection. Its validation, arithmetic, result model,
+assumptions and provenance remain authoritative. The internal borrowed context
+requires exact physical focal/focus identity and positive finite projection.
+The POC constructs it from its already validated thin-lens result, never from
+serialized user projection values. Subject-plane projection still uses the
+ordinary thin-lens calculation; no equation or scientific stage is replaced.
+
+`test/fixtures/poc-projection-reuse-reference.json` stores 64 owned deterministic
+inputs and complete response/provenance SHA-256 commitments generated from the
+unchanged main reference build. The corpus includes all four orientations,
+off-center captures, legacy crops, varied focal/focus/aperture state and sample
+counts. Seed is `0x45c1374c`. Do not regenerate expectations from the candidate to
+hide drift. #130 remains unchanged. Additional tests compare the scalar oracle,
+invalid-input errors, stale context rejection and alternating request identities.
+
+Browser-surface and package gates remain required. This is a Node-measured POC
+optimization, not a browser-motivated public API; no browser performance or private
+application claim is made. It does not activate production rendering/radiometry
+or change capture/output/version contracts. Scientific/provenance review and
+contribution-specific DCO certification remain required before merge.
+
+## Reproduction
+
+Create an independent checkout of the recorded reference commit and build it with
+`npm ci` / `npm run build`. Build the candidate checkout too. Run only the
+benchmark during timing; replace the example reference-root with that checkout.
+The tooling consumes the reference's `dist/index.js` and first verifies complete
+response equivalence for every measured scenario.
+
+```sh
+node scripts/benchmark-poc-projection-reuse.mjs --reference-root=/path/to/reference --reference-commit=c1374c31473f893310d1ce4f0d5a737aaba43ab5
+node --expose-gc scripts/benchmark-poc-projection-reuse.mjs --reference-root=/path/to/reference --reference-commit=c1374c31473f893310d1ce4f0d5a737aaba43ab5 --allocation=sample
+```
+
+Repeat ordinary runs separately. Build labels are not independently attested by
+the script. There is no timing CI threshold, paid service, runtime dependency or
+new third-party material. This tooling is Node-only and outside the public root.
+
+## 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/PROCESSED_OUTPUT.md

@@ -0,0 +1,157 @@
+# Processed camera output
+
+Release context: **package 1.0.0 candidate / root API 0.116.0**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_0.md).
+
+Root API 0.115.0 completes the bounded SDR post-capture handoff for #112.
+Production plan 0.6.0 adds explicit committed RAW processing. At introduction, package 0.6.0,
+POC 0.20.0, capture, RAW, color, correction and SDR schemas remain unchanged.
+This is the engine boundary used by preview and file consumers; integrating
+commercial UI controls and browser presentation belongs to the apps repository.
+
+## Entry points and domains
+
+| Authoritative input | Entry point | Semantic checks |
+| --- | --- | --- |
+| Scene-referred XYZ, virtual-camera channels or already transformed linear RGB | `calculateCaptureSdr()` | Exact #15 plane, profile/version, WB application history, channel order, reference white and raster binding |
+| Capture-bound linear plane with selected corrections | `calculateCaptureCorrectedSdr()` | Same color/WB checks, exact capture/lens/time/geometry state, compatible correction domains and explicit sampling/support policy |
+| Attached post-ADC native RAW | `calculateProcessedSensorRaw()` | Revalidated frame, explicit reconstruction kernels and coverage, registered RGB interpretation, resolved sensor gains, oriented crop and optional native correction |
+| RAW plus file metadata/encoder policy | `createPhotographicExportPair()` | Uses `calculateProcessedSensorRaw()` for JPEG pixels; preserves exact native RAW for DNG |
+| Committed production snapshot plus RAW policy | `createProductionImageFormationPlan()` | Optional `processedOutput: { outputStateId, processing }` binds attached capture, scene clock, seed, physical exposure, WB and available focus commits |
+
+There is no untyped "linear RGB" input or screenshot/canvas source. A caller
+with capture-linear data uses its declared #15 state. A RAW preview and paired
+JPEG use the same explicit `ProcessedSensorRawInput`: reconstruction,
+`ExportSensorColorProfile`, white-balance policy, `SdrRenderingProfile` and
+optional correction. Metadata and JPEG quantization are separate file choices.
+The returned arrays are high fidelity values before lossy JPEG packing, so a
+JPEG decoder is not expected to reproduce them bit for bit.
+
+The RAW result records input/output domains, color profile/evidence, WB policy
+and disposition, child reconstruction/rendering/correction envelopes, native
+DNG crop and processed output view. It owns copies of input values. Standalone
+results are ordinary owned values; a production plan deep-freezes its copy.
+Physical capture and actual display adaptation are explicitly unchanged.
+
+## Ordered processing
+
+RAW processing delegates to existing implementations:
+
+1. Reconstruct exact attached native post-ADC codes; preserve signed normalized
+   shadows and per-site capture/readout diagnostics.
+2. Apply the explicit approximate sensor-channel interpretation and resolved
+   sensor WB gains once; develop XYZ/linear sRGB/D65.
+3. Without correction, map the committed orientation and 1:1 output crop. With
+   correction, build the oriented full-active linear RGB view, then delegate
+   native optical correction, joint-valid retained view and orientation to the
+   capture correction executor.
+4. Apply rendering exposure, declared tone curve, explicit component gamut
+   handling, sRGB transfer encoding and quantization through the SDR renderer.
+5. Return output-referred encoding to the consumer. File packing and platform
+   display/view adaptation remain distinct downstream operations.
+
+The current correction executor supports its explicitly compatible RGB
+geometry/CA mapping followed by linear gain. It rejects unsupported domains or
+orders; it does not silently coerce reconstruction-adjacent channel correction
+into post-color RGB. Existing #118 mapping/resampling diagnostics retain crop,
+local Jacobian/stretch, support mask, interpolation/filter identity, gain/noise
+costs, residual assumptions and clipping. RAW correction intent is informational;
+DNG sensor codes are unchanged. Native prefiltering cannot be declared without
+an implemented source prefilter.
+
+Rendering controls never change aperture, shutter, ISO, focus, geometry,
+photo/dark charge, noise realization, physical saturation or RAW codes. Metering
+remains upstream: this API has no meter input, exposure resolver or feedback
+path. Consumers must identify whether histograms/zebras analyze capture data or
+these output-referred samples.
+
+## Encoding, clipping and future modes
+
+The existing SDR profile fully declares deterministic exposure EV, identity or
+positive per-channel Reinhard tone curve, clipping or rejection of out-of-range
+components, sRGB transfer, 8/16-bit nearest-ties-up quantization and no dither.
+Output explicitly records sRGB primaries, D65 and 80 cd/m² reference white.
+Component clipping is range handling, not a perceptual wide-gamut transform.
+See [SDR rendering](SDR_RENDERING.md) for equations and limitations.
+
+RAW preview supports both SDR bit depths. Baseline JPEG requires 8 bits and
+rejects a 16-bit profile; it never silently reduces the requested bit depth.
+Full-well/ADC flags stay in RAW samples, correction-gain clipping stays in the
+correction envelope, and rendering/tone/gamut counts stay in SDR diagnostics.
+Actual display saturation is unknown because display adaptation is external.
+
+HDR/PQ/HLG profiles fail validation. Future HDR encoding needs a separately
+versioned transfer/primaries/reference/mastering contract and explicit display
+semantics. Source float headroom does not become an HDR output declaration.
+Picture styles, restoration, sharpening and denoise remain future rendering
+choices, separately identified from sensor/optical quality.
+
+## Production plan and compatibility
+
+With a valid attached RAW policy and declared renderer support, the existing
+contract graph activates four executed downstream stages: `reconstruction`,
+`physical-orientation-transform`, `output-crop-resample`, `display-processing`.
+Each records model `processed-sensor-raw-sdr` 0.1.0 and attached frame identity.
+The plan retains the complete processed result, profile identity, requested
+output domain and approximate scientific status in its fingerprint. Scientific
+assurance includes the approximate processing component and unpropagated
+uncertainty, retaining color evidence and child results.
+
+Missing or mismatched processing records `processed-output-evaluation-blocked`;
+renderer stage declarations still gate each active stage. A request without an
+attachment preserves prior unsupported downstream behavior. Existing inputs
+remain valid; plan version and resulting fingerprints intentionally change.
+Serialized consumers must understand plan 0.6.0 and its optional result field.
+
+`outputStateId` explicitly binds numerical attached crop/raster policy to the
+snapshot's committed output identity; it is a caller assertion, not an invented
+geometry lookup. The RAW frame remains independently attached authoritative
+capture data. Matching IDs do not prove its upstream source transport. PSF,
+sensor-stack, photosite, charge, read-noise and ADC composition are still
+separate upstream work: their missing-stage blockers remain. An executed
+post-capture boundary does not make the whole production plan ready.
+
+## Bounded operating envelope
+
+Existing reconstruction permits at most 4,096 native sites, registered dense
+reference kernels, and complete required support. RAW output crop remains 1:1;
+source reconstruction must cover it, or the whole active region for correction.
+The color interpretation is explicit RGB-channel approximation, not sensor
+calibration. General resizing, streaming/native camera resolution, arbitrary CFA
+color models and external-editor qualification remain #16/#178 requirements.
+This boundary introduces no renderer/provider, file IO or network dependency.
+
+## Acceptance evidence
+
+| #112 requirement | Regression evidence |
+| --- | --- |
+| Tone/render EV cannot alter capture/noise/settings | `processed-sensor-raw.test.ts`, `raw-output-conformance.test.ts` |
+| WB applied once; preserved RAW intent; upstream balanced state | `capture-sdr.test.ts`, `photographic-export-correction.test.ts` |
+| Explicit image-state identity; reject unresolved/wrong domain | `capture-sdr.test.ts`, `sdr-rendering.test.ts`, `processed-sensor-raw.test.ts` |
+| Separate tone/gamut/transfer/quantization; deterministic SDR | `sdr-rendering.test.ts`, `processed-sensor-raw.test.ts` |
+| Primaries/reference white and explicit out-of-range policy | `sdr-rendering.test.ts`, `processed-sensor-raw.test.ts` |
+| RAW/correction/output clipping remain distinct | `raw-output-conformance.test.ts`, `capture-corrected-sdr.test.ts`, `processed-sensor-raw.test.ts` |
+| Metering remains pre-display | No processing API calls the upstream meter; `metering-equipment-integration.test.ts` preserves its separate domain |
+| Same rendering intent for preview/JPEG without screenshots | `processed-sensor-raw.test.ts`, four-orientation/WB checks in `photographic-export-correction.test.ts` |
+| HDR remains distinct; no implicit SDR reinterpretation | Profile rejection tests in `sdr-rendering.test.ts`, `processed-sensor-raw.test.ts` |
+| Correction domains/support/costs and immutable plan binding | `capture-corrected-sdr.test.ts`, `production-image-formation-plan.test.ts` |
+
+RAW/linear fixtures use the #130 canonical camera/seed through documented tiny
+owned derived variants; test pixels and ideal color profiles are synthetic,
+not measured/calibrated scene truth. Acceptance demonstrates the declared bounded
+post-capture foundation, not Adobe compatibility or complete physical rendering.
+
+This contribution independently composes existing Photivra APIs; it introduces
+no new scientific equation, third-party code/data, look assets or dependency.
+AI-assisted draft requires substantive owner review and contribution-specific
+DCO certification before merge. External editor/high-resolution acceptance and
+upstream physical activation retain their existing issue owners.
+
+## Executed upstream production handoff
+
+Plan 0.7.0 additionally supports `environmentCapture.processing`. Its
+reconstruction policy omits `rawFrame`: the plan supplies only the exact RAW
+returned by its executed source-to-ADC pipeline. This route cannot be combined
+with `processedOutput` or an independent physical scene sample. Existing
+attached-RAW plan inputs and their conservative origin limitations remain valid.
+See [production environment capture](PRODUCTION_ENVIRONMENT_CAPTURE.md) for
+binding, replay, stage activation and migration details.