@photivra/engine 0.5.1 → 1.0.0

package/docs/MOTION_AND_SIGNAL.md

@@ -1,5 +1,7 @@
 # Motion and Signal 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).
+
 ## Projected subject motion
 
 Subject-motion blur is modeled from image-plane displacement rather than broad labels such as "fast sport" or "slow subject."
@@ -51,11 +53,153 @@ This is camera **rotation only**. Translation is excluded because parallax requi
 
 The returned image-plane/sample components use +X right and +Y up. Native raster remains +X right/+Y down and requires the existing explicit coordinate transform at capture composition boundaries.
 
+## Sensor readout timing
+
+`calculateSensorReadoutTiming()` provides a standalone capture-specific **native sensor scan-timing** foundation.
+
+The model deliberately separates two evidence-backed seconds-valued facts:
+
+- **capture data-readout duration** — the caller's declared duration for the selected capture mode's sensor data-readout operation;
+- **rolling spatial-sampling skew** — the timing span that drives the first-to-last spatial scan phase in the current approximation.
+
+Photivra does not assume those values are equal, and it does not infer an ordering relationship between them. For global readout, spatial skew is zero in this model even when the declared data-readout duration is non-zero.
+
+For rolling readout, the caller also supplies an independently evidenced native scan direction. The current schedule is a `uniform-linear-single-axis` approximation over continuous native raster edge coordinates. This is intentionally **not** a claim that one `NativeImageRaster` row/column equals one physical photodiode row or one hardware readout line. Segmented, center-out, interleaved, multi-tap and other non-uniform schedules remain unsupported rather than being silently approximated as equivalent hardware.
+
+Native sensor timing is orientation-invariant. `calculateSensorReadoutTiming()` therefore does not accept physical camera orientation or output raster geometry. When presentation/capture orientation is needed, callers compose the returned native direction vector with the existing native-to-oriented vector transform. Digital output crop/resolution cannot alter the native timing schedule.
+
+Active-capture timing is also explicit: Photivra never scales a full-frame timing fact by crop dimensions to invent a cropped-mode timing. A caller must provide timing evidence appropriate to the selected capture mode/active area; later capture-mode work can bind those declarations more formally.
+
+Mechanical, electronic-first-curtain and fully electronic shutter mechanisms are reported independently but remain scientifically inert in this slice. The function does **not** define local exposure start/end times, mechanical curtain travel, EFCS curtain interaction, rolling-shutter image distortion, flash/flicker bands, or motion integration. Those later models must combine their own timing with this sensor schedule explicitly rather than treating sensor readout as a surrogate shutter-curtain model.
+
+## Readout/exposure spatial linkage
+
+`assessReadoutExposureTimingLinkage()` is the explicit boundary between the native sensor readout schedule and the capture exposure-window schedule.
+
+The contract deliberately distinguishes **spatial phase/order** from **absolute temporal synchronization**.
+
+A caller may declare:
+
+- `unlinked` — Photivra asserts no relationship for this capture. This is not evidence that the physical processes are independent.
+- `spatial-phase-linked` — one or more electronic exposure boundaries are asserted to share the rolling readout's normalized native spatial phase, either in the same direction or reversed.
+
+Every positive link carries its own provenance. The underlying readout direction/skew and exposure-boundary direction/traversal facts keep their own separate evidence.
+
+A positive spatial-phase link is valid only when:
+
+- sensor readout is rolling and therefore has a spatial scan;
+- the selected exposure boundary is electronic;
+- the selected exposure boundary is itself a uniform-linear native scan;
+- `same` phase orientation uses the same native scan direction;
+- `reversed` phase orientation uses the exact opposite direction on the same native axis.
+
+The rolling-readout spatial skew and exposure-boundary traversal duration do **not** have to be equal. Their dimensionless ratio is reported diagnostically. A ratio of 1 still does not prove a shared clock origin or temporal coincidence.
+
+`captureReadoutDurationSeconds` is preserved with units/evidence but is never used to validate an exposure linkage. Data transfer/readout duration can describe a different physical interval from exposure-boundary traversal.
+
+Absolute temporal alignment remains `not-established` in this foundation. A future mode profile may supply an evidence-backed temporal offset/synchronization relationship if defensible data exists, but Photivra will not infer it from shutter mechanism, scan direction, matching timing spans, output resolution, or adjacent camera specifications.
+
+## Capture exposure windows
+
+`calculateCaptureExposureWindows()` adds the next standalone timing layer after native sensor readout timing.
+
+It represents **opening and closing exposure boundaries separately**. Each boundary can currently be simultaneous or a caller-declared uniform-linear scan in invariant native sensor coordinates. The nominal exposure duration is another independent evidence-backed seconds-valued quantity.
+
+The output time reference is the **first opening-boundary phase**, not a claim that every native location has the same local exposure start. For each point, local start and end offsets are derived independently, and the engine reports local exposure duration.
+
+Mechanical, EFCS, and electronic shutter mechanisms determine only which conceptual actuator owns the opening/closing boundary. They do not invent traversal timing:
+
+- mechanical: mechanical opening and closing;
+- EFCS: electronic opening, mechanical closing;
+- electronic: electronic opening and closing.
+
+The complete active rectangle is validated so a zero/negative local exposure duration cannot hide in an unsampled region.
+
+This contract remains deliberately separate from `calculateSensorReadoutTiming()`. Sensor readout phase is not automatically an exposure boundary. It also remains separate from `calculateCameraRotationImageMapping()`: that API still accepts seconds from its existing exposure-start reference, and the capture rotation and production adapters explicitly bind local capture-window times to that motion basis.
+
+The first exposure-window model does not include curtain acceleration, nonlinear or segmented electronic scheduling, flash/flicker interaction, shutter shock, EFCS-specific pupil/bokeh behavior, or rolling-shutter image distortion.
+
+## Capture rotation exposure trajectories
+
+`calculateCaptureRotationTrajectories()` is the first explicit integration between local capture exposure windows and the existing pure-camera-rotation mapping.
+
+For each caller-selected native raster point, the engine:
+
+1. resolves the point's local exposure start/end with `calculateCaptureExposureWindows()`;
+2. maps that native point into the pre-orientation image plane at the **first opening-boundary phase**;
+3. explicitly binds that capture reference to `t = 0` of `calculateCameraRotationImageMapping()` for this composition;
+4. evaluates the same stationary world ray at the local exposure start and end;
+5. reports the two mapped endpoints plus their image-plane chord.
+
+The output is deliberately a **forward stationary-reference-ray trajectory**, not a rolling-shutter image warp.
+
+That distinction matters because in a rolling capture the exposure/capture time depends on image location while camera motion also changes where a world ray lands. A renderer-ready rolling-shutter transform therefore requires a self-consistent inverse destination-to-source mapping rather than one forward displacement evaluated at a destination coordinate.
+
+The endpoint chord also is **not a blur kernel**. Pure rotational image motion can follow a curved image-plane path, and exposure integrates radiance over the entire local interval rather than only its two endpoints.
+
+Sensor data-readout timing from `calculateSensorReadoutTiming()` is intentionally absent. A particular electronic capture mode may have a documented relationship between sensor readout and exposure boundaries, but Photivra will require that relationship to be declared explicitly rather than assuming it universally.
+
+The trajectory foundation remains rotation-only. Camera translation/parallax, subject motion, panning intent, object rotation/deformation, occlusion changes, exposure integration, flash/flicker, shutter shock, and the final inverse rolling-shutter warp remain future work.
+
+## Capture rotation temporal quadrature
+
+`calculateCaptureRotationTemporalQuadrature()` extends the instantaneous inverse mapping into a deterministic **temporal-geometry quadrature** over each destination point's complete local exposure interval.
+
+The first model uses the uniform midpoint rule. For `N` temporal samples, normalized local phases are:
+
+```text
+phase_i = (i + 0.5) / N
+```
+
+so the exact opening and closing boundaries are not sampled. Each phase is evaluated through the already-public `calculateCaptureRotationInverseMappings()` contract rather than introducing a second camera-motion equation.
+
+Every temporal node reports two different measures:
+
+- `normalizedTimeWeight = 1 / N` — dimensionless weight for a downstream **time average** under the declared uniform temporal-response approximation;
+- `timeMeasureSeconds = localExposureDuration / N` — seconds-valued `dt` measure for a downstream **time integral**.
+
+These are intentionally separate. The seconds-valued measure is not shutter transmission, photon count, radiometric throughput, scene radiance, sensor response, or a calibrated energy measurement.
+
+The local exposure interval remains destination-dependent. A scanned opening/closing schedule can therefore shift node times between sensor locations, and different opening/closing traversal schedules can produce different local durations and therefore different `timeMeasureSeconds` values.
+
+The first temporal-response model is `uniform-over-local-exposure`. That is an explicit approximation. This geometric primitive does not model shutter-transmission ramps or exposure-dependent sensor response. Registered temporal illumination/manual flash and explicit scene/EQE exposure APIs separately integrate declared changing light; geometry nodes alone provide no radiometric weighting.
+
+The API returns **nodes and weights only**. It does not average reference coordinates, compute a blur radius/kernel, sample scene radiance, resolve visibility/occlusion, or write output pixels. Averaging geometric coordinates is not a substitute for integrating the radiance seen along the time-varying rays.
+
+No geometry-only quadrature error estimate is reported. Image-integration error depends on downstream scene radiance, visibility, texture/edge frequency, and reconstruction as well as the camera trajectory. Renderer/reference implementations can compare increasing temporal sample counts in their radiance domain when convergence evidence is needed.
+
+## Instantaneous capture rotation inverse mapping
+
+`calculateInverseCameraRotationImageMapping()` is the exact inverse of the existing forward pure-rotation ray mapping under the same constant-axis assumptions. Once capture time is known, the captured image-plane ray is rotated analytically back into the exposure-start reference camera frame. There is no numerical root/fixed-point solve.
+
+`calculateCaptureRotationInverseMappings()` composes that inverse with local exposure-window timing.
+
+For each destination native sensor point:
+
+1. the destination point selects its local exposure window;
+2. the caller supplies `localExposurePhase` in `[0, 1]`;
+3. capture time is `start + phase × localDuration`;
+4. the destination native point is mapped into the ideal pre-lens image plane;
+5. the captured ray is analytically inverted to the first-opening-boundary reference frame;
+6. image-plane, native effective-sample, and physically oriented sample displacements are reported.
+
+The phase is mandatory because a finite exposure has no single sharp geometry. Phase `0` means local exposure start, `0.5` is the local temporal midpoint, and `1` is local exposure end. None is automatically privileged as the final rendered image.
+
+This inverse is renderer-oriented in the limited sense that it maps **destination capture location -> reference ray**. It still is not a finite-exposure renderer. Motion blur requires integration over the local interval, with an explicit exposure-weighting model if weighting is not uniform.
+
+Sensor data-readout timing remains absent. A documented mode-specific relationship may later link readout and electronic exposure timing, but no such equality is assumed here.
+
+The mapping is evaluated in the ideal pre-lens image plane. Radial distortion, chromatic aberration, PSF, output crop/resampling, camera translation/parallax, subject motion, occlusion changes, flash/flicker and shutter shock remain separate stages.
+
+Reference rays are not clamped to the active source frame. Under camera motion, a valid captured destination can map to reference geometry outside the available reference image; a renderer must treat that as missing source coverage rather than silently stretching or clamping edge pixels.
+
+The current inverse does not claim that an arbitrary rolling/capture-scan camera is globally one-to-one. More general motion models can produce folds, repeated visibility or other multi-perspective behavior; those cases require additional validity analysis rather than being inferred from this pure-rotation slice.
+
 ## Temporal image-formation basis
 
 The image-formation contract defines physical time in **seconds from exposure start**.
 
-A future spatial camera-rotation model should be evaluable at arbitrary physical times rather than returning only one finished full-frame displacement. That allows global exposure and later rolling readout to consume the same camera-motion model.
+The separate spatial camera-rotation model is evaluable at arbitrary supported physical times rather than returning only one finished full-frame displacement. That allows global exposure and later rolling readout to consume the same camera-motion model.
 
 Exposure duration and sensor readout timing are independent concepts:
 

package/docs/NUMERICAL_CORRECTNESS.md

@@ -0,0 +1,191 @@
+# Numerical Correctness and Physical Units
+
+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 is a scientific engine. Numerical behavior and physical-unit meaning are public-contract concerns, not implementation details.
+
+This document defines the repository-wide numerical policy used by public calculations, parsers, schemas, tests, and composed image-formation work.
+
+## Core rules
+
+- Public physical quantities must use explicit units in field names unless the type itself unambiguously owns the unit.
+- The same physical concept should use the same unit and property name across modules.
+- Coordinate-system identity is part of the quantity definition. A number is not interchangeable merely because it has the same dimensional unit.
+- Public calculation results must remain JSON-safe. `NaN` and numeric infinities are not valid calculation outputs.
+- Invalid scientific inputs fail explicitly rather than being silently clamped, coerced, defaulted, or reinterpreted.
+- Unknown, unbounded, absent, and unsupported states must be represented semantically rather than by magic numeric sentinels.
+- Unit conversion happens exactly once at an explicit boundary.
+- Mathematical simplifications must not erase axis dependence, sign conventions, physical stage, provenance, or applicability.
+
+These rules supplement `docs/API_STYLE.md` and the coordinate/model rules in `docs/PHYSICS_FOUNDATION.md`.
+
+## Canonical public units
+
+Photivra does not require one internal SI-only representation. It does require explicit, stable units at public boundaries.
+
+Common conventions include:
+
+| Quantity | Public convention |
+| --- | --- |
+| focal/image/sensor distances | millimetres when named `*Mm` |
+| scene/object/focus distance | metres when named `*M` |
+| sampling pitch | micrometres when named `*Micrometers` |
+| time / exposure duration | seconds when named `*Seconds` |
+| wavelength | nanometres when named `*Nanometers` / `*Nm` |
+| angle | explicit radians/degrees fields, never an unlabeled angle |
+| ISO / exposure index | dimensionless named camera setting |
+| normalized factors / weights | dimensionless; document normalization and valid range |
+| spectral irradiance | explicit radiometric unit including wavelength-density basis |
+| irradiance | W/m² when physically calibrated |
+| radiance | W/m²/sr, with /nm when spectrally resolved |
+| electrons / photons / RAW codes | explicit domain-specific counts/codes; do not interchange |
+
+Do not infer units from neighboring fields or documentation when the public field name/type is ambiguous.
+
+## Coordinate identity
+
+A physical unit alone does not identify a coordinate.
+
+For example, these are different domains even when expressed in millimetres or pixels:
+
+- native sensor raster coordinates;
+- oriented capture raster coordinates;
+- output raster coordinates;
+- optical image-plane coordinates;
+- sensor physical coordinates;
+- scene/world coordinates.
+
+Crossing coordinate systems requires an explicit exported transform or a documented model boundary. Do not implement ad-hoc sign changes, axis swaps, recentering, or crop-local reinterpretation.
+
+## Finite-number policy
+
+Public calculation envelopes must not contain non-finite numbers.
+
+The existing `CalculationResult<T>` constructors recursively validate returned numeric values. If a calculation would emit `NaN`, `Infinity`, or `-Infinity`, it fails with `InvalidScientificResultError`.
+
+Inputs that are required to be finite must fail with a typed/domain validation error before the calculation proceeds.
+
+When the scientific state is genuinely unbounded, represent that state semantically. Example: depth of field uses `null` for an infinite far limit rather than numeric `Infinity`.
+
+Do not rely on JSON serialization to convert or erase non-finite numbers.
+
+## Domains and ranges
+
+Validation should distinguish:
+
+1. **structural validity** — correct type/shape/discriminant;
+2. **numeric validity** — finite, integer, nonnegative, positive, bounded fraction, etc.;
+3. **scientific applicability** — value lies inside the model/profile/calibration operating range;
+4. **composition compatibility** — independently valid inputs are valid together.
+
+Do not silently widen a model's operating envelope to accept a caller value.
+
+For reusable bounded ranges:
+
+- state units;
+- state whether endpoints are inclusive;
+- reject reversed ranges;
+- preserve exact evidence/applicability when calibrated;
+- do not extrapolate unless the model explicitly defines and labels extrapolation.
+
+## Exact equality vs tolerance
+
+Photivra does not use one global epsilon.
+
+Use exact equality when the contract is exact, including:
+
+- IDs, versions, enum/discriminant values;
+- integer/raster identities;
+- explicit zero/no-op states when represented exactly;
+- deterministic serialized/canonical structures where bitwise identity is part of the contract;
+- algebraic results whose implementation is expected to be exact in the represented arithmetic.
+
+Use a documented tolerance when floating-point evaluation is inherently approximate, including:
+
+- transcendental functions;
+- iterative numerical methods;
+- quadrature/integration;
+- interpolated calibration data;
+- numerically conditioned inverse mappings.
+
+Tolerance selection must be tied to the quantity, numerical scale, conditioning, algorithm, and scientific claim. A looser tolerance must never be used merely to hide an unexplained regression.
+
+Prefer:
+
+- absolute tolerance near a known scale/zero;
+- relative tolerance for scale-proportional quantities;
+- convergence/refinement tests for sampled numerical methods;
+- independently derived analytical/reference values where available.
+
+## Rounding and quantization
+
+Rounding is a scientific/output operation when it changes represented data.
+
+- Keep calculations in the highest practical deterministic precision until a defined output boundary.
+- Pixel/raster integer rounding rules must be explicit.
+- RAW/export quantization must define scale, offset/black level, clipping, rounding/tie behavior, and code range.
+- Do not round intermediate physical values for display convenience.
+- Do not let serializer/container limitations redefine the authoritative scientific value.
+
+## Signed zero and tiny values
+
+Do not use `-0` as a semantic state.
+
+When a public result is mathematically zero, normalize or test it according to the owning model if signed zero could leak into serialization/identity. Do not indiscriminately clamp small nonzero values to zero; that requires a documented model/tolerance decision.
+
+## Overflow, underflow, and extreme inputs
+
+Public functions must fail safely when arithmetic leaves the valid numerical/scientific domain.
+
+- A finite input does not guarantee a finite computed result.
+- Check derived values where overflow or invalid denominators can occur.
+- Avoid transformations that turn a detectable invalid state into an apparently plausible finite number.
+- Extreme-value tests should target the model boundary, not arbitrary machine limits alone.
+
+If a stable reformulation is needed for numerical conditioning, it must preserve the documented scientific model and provenance.
+
+## Determinism and runtime expectations
+
+For identical validated inputs and fixed stochastic seeds, the engine should produce deterministic scientific results within the documented contract.
+
+Do not depend on:
+
+- object iteration order that is not part of the serialized contract;
+- current wall-clock time;
+- random state without an explicit seed;
+- network/service responses;
+- renderer/UI state;
+- machine-specific hidden calibration.
+
+Browser-safe public code and supported Node runtimes must share the same semantic result contract. If an implementation permits small runtime-dependent floating-point differences, acceptance tolerances must be explicit and scientifically harmless.
+
+## Testing requirements
+
+Numerical tests should use the strongest applicable form:
+
+1. exact identity/invariant;
+2. independently derived analytical constant;
+3. dimensional/unit relation;
+4. monotonic/bounded behavior;
+5. round-trip/inverse invariant;
+6. numerical convergence/refinement;
+7. calibrated/reference tolerance with provenance.
+
+The canonical `test/fixtures/basic-reference-scene.json` fixture is the preferred shared reference for cross-domain deterministic cases once available.
+
+Do not generate the only expected value by calling the same production function under test.
+
+## Changes to numerical behavior
+
+A change that alters public numerical meaning must document:
+
+- equation/model change;
+- units and coordinate system;
+- assumptions/applicability;
+- old vs new behavior;
+- tolerance/precision impact;
+- API/schema/version impact;
+- provenance/uncertainty consequences;
+- migration implications when relevant.
+
+A pure implementation optimization must preserve the same scientific result semantics and provenance within the existing contract.

package/docs/PERFORMANCE_BASELINE.md

@@ -0,0 +1,56 @@
+# Measured-performance baseline: #43 / #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).
+
+This independent first slice records merged main `83a99a4c1ec525fd1add7cccff134fcee0f5159b`, root API 0.93.0, POC API 0.20.0, in `docs/benchmarks/2026-10-01-main-baseline.json`. No pending capture/output/correction/preset implementation is consumed. It does not close either issue or justify an optimization by itself.
+
+## Context and method
+
+Measurements used Node 24.19.0/V8 13.6.233.17-node.51 on shared Linux x64 execution infrastructure reporting AMD EPYC 9V74 and 9 logical CPUs. This is not the user's Mac, a browser frame-time result or a dedicated machine. Local source was restored to the recorded main snapshot and transpiled with Node's type stripper because canonical TypeScript tooling is unavailable locally; this build method is explicit in the artifact. The script's source commit/build label is operator-attested, not independently verified by the script. CI separately verifies the canonical build/gates.
+
+The existing #43 sampling benchmark retains its 33x33 field and 5 temporal samples, alternating scalar/batch pairs, nine measured repeats and five inner repeats. It is reused unchanged. New `scripts/benchmark-composed-baseline.mjs` measures four whole POC request shapes against #130: base, 16 defocus samples, 16 samples each of defocus/size/motion, and the same mixed set with portrait/off-center staged capture. Each scenario has 200 warmup requests and nine 100-request blocks; scenario order rotates. Both ordinary and forced-GC-assisted runs are recorded, not combined. Net post-GC retained heap is **not** allocation count or GC-pause evidence.
+
+| POC scenario | Ordinary median µs/request | Forced-GC-assisted median µs/request |
+| --- | ---: | ---: |
+| Base | 13.17 | 16.88 |
+| Defocus 16 | 29.20 | 36.77 |
+| Mixed 16 per kind | 62.46 | 76.05 |
+| Staged portrait mixed | 124.76 | 130.16 |
+
+These distributions establish reproducible request shapes, not portable speed constants or ordinary-vs-GC causality. Raw timing/heap samples are retained in the artifact.
+
+## Findings and disposition
+
+For #43, existing lateral-CA batch/scalar median ratio was 0.628 (about 37% shorter in this run); radial batch ratio 1.019 showed no benefit in this run. Vignetting and temporal rotation remain recorded microbenchmark candidates, not demonstrated consumer hotspots. This supports retaining the existing narrow CA batch surface, not adding a generic prepared engine abstraction now.
+
+For #45, a separate ordinary V8 CPU-profile run had 250 sampled stacks inside `simulatePocCamera`; 83 included `calculateThinLensImageDistance` (33.2%). 157 included recursive finite-result validation (62.8%). These are **overlapping inclusive sampled stacks** and cannot be summed or equated to exact time/savings. Zero samples attributed to `requirePositiveFinite` do not imply zero validation work; sampling/inlining can hide frames. Startup/outside-call samples are excluded from the fraction denominator. The profiled run's timings are not used in the unprofiled timing table.
+
+Repeated projection/result validation is therefore a plausible bounded investigation target, but no reuse candidate, amortization break-even, retained prepared-state cost, exact equivalence corpus, actual consumer frequency or browser behavior has been demonstrated. **No runtime optimization is implemented and neither issue receives a final no-change closure.** After representative V1 composition/output paths merge, repeat profiling with those paths and relevant browser/worker consumers; then compare the smallest internal request-scoped reuse candidate, or record a supported no-change decision. No public context/cache or API/version change is justified here.
+
+## Reproduction
+
+Use a checkout of the commit being measured and build it before measuring; retain runtime/hardware/commit context for every comparison. The new script is developer tooling, not the browser root. Example after `npm ci` / `npm run build`, replacing the commit with the exact source revision used:
+
+```sh
+node scripts/benchmark-composed-baseline.mjs --commit=83a99a4c1ec525fd1add7cccff134fcee0f5159b --build-method=tsc
+node --expose-gc scripts/benchmark-composed-baseline.mjs --commit=83a99a4c1ec525fd1add7cccff134fcee0f5159b --build-method=tsc
+node --expose-gc scripts/benchmark-image-formation.mjs
+node --cpu-prof --cpu-prof-name=poc.cpuprofile scripts/benchmark-composed-baseline.mjs --commit=83a99a4c1ec525fd1add7cccff134fcee0f5159b --build-method=tsc
+node scripts/summarize-composed-cpu-profile.mjs poc.cpuprofile
+```
+
+To reproduce this historical engine baseline after the tooling lands, use the recorded engine checkout plus these tooling scripts, rather than labeling a newer engine build with the old SHA. Do not commit raw CPU profiles: they can contain private local paths. The summary emits fixed public function categories only. The archived artifact contains no raw profile/path or source-private metadata.
+
+Scripts and scenarios are independently authored using the owned canonical fixture and existing benchmark. No third-party code/data or dependency is incorporated. AI-assisted draft remains subject to human review and DCO certification; performance evidence is not scientific/provenance certification.
+
+## Subsequent bounded #45 experiment
+
+The baseline conclusions above are historical. [POC_PROJECTION_REUSE.md](POC_PROJECTION_REUSE.md) records the main 0.103.0 request-local defocus candidate, paired whole-request timing, preparation, separate allocation sampling and complete-response equivalence. It advances #45 independently; it does not change #43's disposition or establish browser performance.
+
+## Subsequent bounded #43 experiment
+
+The baseline conclusions above are historical. [GEOMETRIC_PREPARATION_REUSE.md](GEOMETRIC_PREPARATION_REUSE.md) records the main 0.103.0 call-local geometry-preparation candidate, real merged sampling/correction consumers, separate CPU/allocation evidence and scalar/copy-safety tests. It advances #43 independently and does not establish browser performance or #45's conclusion.
+
+## 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/PHOTOGRAPHIC_EXPORT.md

@@ -0,0 +1,206 @@
+# Simulated Sensor RAW DNG / JPEG export
+
+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).
+
+Current producer-derived files and external closure gates are recorded in
+[Export acceptance](EXPORT_ACCEPTANCE.md). The new reproducible generator uses
+current typed fixtures; the earlier pinned serializer-only files remain historical.
+
+See [Reference RAW frame compatibility](RAW_FRAME_ENVELOPE.md) for stage-specific
+limits, full-native counting and parser preflight behavior.
+
+`createPhotographicExportPair()` is an optional browser-safe asynchronous export
+boundary. Both owned byte arrays come from one revalidated, privately copied RAW
+input. The JPEG never uses the capture's independent float planes. Web Crypto
+SHA-256 is required. No filesystem, clock, random generator, network or encoder
+dependency is added. Callers supply public identities and an explicit UTC event
+timestamp, and own saving the bytes.
+
+This is a bounded reference implementation. The entire native frame must contain
+at most **4,096 sites**, with complete single-frame, one-site-per-native-sample,
+registered 2×2 RGB Bayer coverage. RAW codes remain in native row-major CFA
+coordinates. A fixed repeating black tile and common digital white code are
+required. Below-black codes and original saturation codes are preserved without
+stretching to the 16-bit container limit. This does not support typical camera
+resolutions or establish calibrated camera behavior.
+
+## Explicit development
+
+`RawFrameReconstructionInput` supplies complete absolute CFA phase profiles and
+a native region covering the final crop. Existing reconstruction preserves
+signed black-subtracted values and exact weighted source contributions. Missing
+edge support fails; no automatic kernel, padding, sharpening or denoising runs.
+
+`ExportSensorColorProfile` explicitly declares an invertible 3×3 normalized
+camera-channel-to-XYZ/D65 matrix, owned/reusable numeric evidence, profile
+identity and limitations. Only approximation status is accepted. RGB/CFA names
+do not establish primaries, spectral response or calibration. Output kernels
+must use the declared RGB order and exact CFA profile. The reference white must
+map to positive camera-neutral coordinates.
+
+WB is explicitly `not-required` with no captured intent, or
+`apply-resolved-sensor-gains` with intent. Existing resolved camera-channel gains
+apply once before camera-to-XYZ and the existing XYZ-to-linear-sRGB transform.
+No second WB estimator runs. Existing SDR rendering handles rendering exposure,
+named tone mapping, clipping, transfer and 8-bit quantization. Rendering clipping
+is separate from RAW saturation.
+
+Only 1:1 output cropping is supported. The final oriented crop is translated
+through the active crop to exact native coordinates. JPEG pixels receive
+orientation once and EXIF Orientation=1. DNG keeps native pixels and records
+orientation, native ActiveArea and DefaultCrop. Resampling fails closed. JPEG
+coding replicates edges solely to fill partial 8×8 coding blocks; it does not
+supply missing reconstruction samples or change photograph dimensions.
+
+## Optional correction of the JPEG view
+
+The optional `correction` field reuses the choice contract documented in
+[CAPTURE_CORRECTED_SDR.md](CAPTURE_CORRECTED_SDR.md). Order is exact attached RAW
+reconstruction → resolved camera-channel WB → declared camera-to-XYZ/D65 →
+existing linear-sRGB transform → native-optical geometry/CA/gain correction →
+SDR → JPEG. The private intermediate plane contains only RAW-derived RGB; it
+replaces all independent float planes for this calculation and is never returned
+as a replacement capture. Parent `source` retains the exact RAW reconstruction,
+its provenance, site-level physical/digital saturation and source history.
+Intermediate RGB capture saturation is explicitly unmodeled; no scalar RGB white
+level is inferred from heterogeneous RAW site saturation flags.
+
+This branch requires reconstruction of the **full active native area**, square
+physical pixel pitch and 1:1 declared output crop sampling. The exporter supplies
+no prefilter, so `resampler.antialias` must be `none`; maps requiring compression
+filtering fail through the existing executor. It cannot claim a prefiltered input
+or silently create a filter. Correction state uses native output dimensions,
+exact committed optics and exposure-local time, independently of scene time.
+Profiles remain generic declarations for the post-color/WB linear-sRGB basis,
+not physical sensor-channel CA calibration. The pipeline does not redraw noise,
+blur or photons and does not activate reserved production stages.
+
+`invalidSupport` either rejects unavailable samples or chooses the existing
+largest joint-valid rectangle. `processedOutputView.rect` records that rectangle
+in the full oriented output raster, with dimensions used by JPEG SOF and EXIF.
+It is relative to the declared output crop, not the active/native sensor origin.
+The DNG's native codes, ActiveArea and original DefaultCrop remain unchanged;
+a nonlinear corrected JPEG cannot be represented by moving an uncorrected RAW
+crop. These paired files share the exact capture and source codes, while their
+processed geometry can differ. Physical focal equivalence remains capture-owned.
+
+The result exposes the processed `correction` calculation and a separate
+`rawCorrectionIntent` plan with application `metadata-only`. Custom XMP in both
+files records CorrectionProfileID/version, CorrectionSelectionKind/selections,
+ProcessedOutputRect and ProcessedIlluminationClippingEvents. CorrectionDisposition
+is `informational-intent-only` in DNG and `processed-view` in JPEG. This is
+informational metadata, not standardized DNG opcodes or a promise that editors
+apply the profile. Gain clipping events precede joint cropping and remain
+separate from RAW saturation and SDR gamut clipping. Full profile and choices
+enter SimulationHash; RawDataUniqueID still depends only on the exact RAW codes.
+Omitting correction preserves the original rendering/hash inputs and emits no
+correction XMP. The additive contract retains export schema 0.1.0.
+
+## Files and metadata
+
+DNG uses little-endian TIFF, version/backward version 1.1, one uncompressed
+16-bit CFA strip, CFA/black/white tags, inverse XYZ-to-camera ColorMatrix1,
+D65 CalibrationIlluminant1 and normalized AsShotNeutral. Rational values use
+bounded decimal approximations (maximum denominator 10^9); unsupported range
+or nonzero values rounding to zero fail. AsShotNeutral records development intent
+and does not alter RAW codes. No preview, compression, opcodes, NoiseProfile,
+calibration signature, RawImageDigest or NewRawImageDigest is claimed.
+
+JPEG is baseline sequential 8-bit YCbCr444 with an explicit constant quantization
+step 1..255, analytical DCT, custom canonical Huffman tables and byte stuffing.
+The step is not a manufacturer's quality scale. JPEG remains lossy at step 1.
+JFIF and EXIF ColorSpace=1 declare rendered sRGB; DNG is unclassified and carries
+the explicit virtual-camera matrix.
+
+EXIF records exposure, aperture, focal length, rounded 35mm equivalent when
+representable, dimensions, UTC event time/subseconds/offset, and ImageUniqueID.
+Integer selected virtual ISO ≤65535 is recorded as RecommendedExposureIndex
+with SensitivityType=REI: a simulation setting, not measured ISO speed or
+standard-output-sensitivity calibration. Make/Model identify Photivra's virtual
+camera, not a commercial device.
+
+XMP contains distinct xmpMM DocumentID/InstanceID and IPTC DigitalImageGUID per
+file, the caller-selected non-generative IPTC workflow type and the namespace
+`https://photivra.com/ns/simulation/1.0/`. SceneID/version are caller-declared
+public profiles bound to the capture's sceneStateId. SensorProfileID identifies
+the export color interpretation. SceneTime is simulation seconds, not wall-clock
+time. Finite focus distance is recorded; infinity never becomes a fake number.
+Private paths/GPS/serials and unsupported rights/calibration/AI fields are rejected.
+
+## Identity and lineage
+
+- SimulationHash is SHA-256 over sorted finite canonical JSON containing the
+  entire RAW frame, including capture identity/history/float planes, phase
+  profiles, region, color/scene profiles, WB policy, rendering, JPEG step and
+  the optional correction choice.
+  Save timestamp and artifact IDs are excluded. History changes may change the
+  hash without changing decoded pixels.
+- RawDataUniqueID is the first 128 bits of SHA-256 over versioned native
+  dimensions, CFA layout, 16-bit container declaration and exact codes. It is
+  not a standard RawImageDigest.
+- UniqueCameraModel includes public color profile identity/version and its full
+  hash; profile changes cannot silently keep the same family identity. File
+  SHA-256 fields hash exact returned bytes at creation.
+- Top-level pairing records JPEG generation from the exact attached RAW. Nested
+  metadata-only `imageDataPairing="not-verified"` retains its earlier projection
+  semantics. Upstream producer origin remains caller-declared/unverified. Hashes
+  are not signatures, C2PA or tamper-proof attestations.
+
+Returned arrays are owned and mutable; hashes describe creation-time bytes.
+Reconstruction/rendering calculation envelopes remain available for review.
+
+## Use and acceptance
+
+```ts
+import { createPhotographicExportPair, parsePhotographicExportInput,
+  type PhotographicExportInput } from "@photivra/engine";
+
+async function exportCommittedRaw(input: PhotographicExportInput) {
+  return createPhotographicExportPair(parsePhotographicExportInput(input));
+}
+```
+
+Callers supply actual committed input and explicit profile evidence. Test profiles
+are synthetic and are not suggested physical calibrations.
+
+Generate concrete acceptance files with `npm run build`, then
+`node scripts/generate-photographic-export-fixtures.mjs OUTPUT_DIRECTORY`.
+With an existing Pillow installation, run
+`python scripts/verify-photographic-export-fixtures.py OUTPUT_DIRECTORY`.
+This repository-only optional checker adds no engine dependency. It also uses
+existing lxml and LibRaw installations when available, and reports skipped
+checks explicitly. Both the 2×2 strip regression and 64×64 owned grayscale
+chart are generated with separate capture/artifact identities. The manifest
+records elapsed time and before/after heap usage for each bounded fixture;
+these are not peak-memory measurements or high-resolution evidence.
+
+Supplemental local checks use Pillow's independent TIFF-directory reader plus
+direct strip unpacking for exact RAW codes; Pillow decodes JPEG/EXIF and extracts
+XMP, and Python DOM parses both packets. Diverse 1×1, 7×8, 9×13 and 64×64 patterns
+decode at steps 1, 7 and 255; measured step-1 maximum channel error is ≤2 codes.
+Pillow cannot render the CFA photometric profile. LibRaw 0.21.2 independently
+opens, unpacks and processes the 64×64 DNG, retaining the native 64×64 size and
+WhiteLevel=1023. It rejects the 2×2 file as unsupported; that tiny file remains
+a strip/tag regression fixture, not an editor acceptance file. XMP attributes
+in both pair members are independently decoded and compared through DOM/Expat
+and lxml/libxml2. These checks do not establish Adobe acceptance, exact
+agreement between different demosaic/rendering algorithms or a complete
+schema-aware XMP implementation conformance claim.
+
+Concrete 64×64 files are checked into `test/fixtures/paired-export-acceptance/`
+for external review. Their owned synthetic ramp codes exercise the serializer,
+not the physical sensor producer. See its README for hashes and the exact
+remaining acceptance steps. No commercial-camera calibration is used.
+
+#16 is closed through reviewed/signed PR #201. [Export acceptance](EXPORT_ACCEPTANCE.md) records producer-derived pairs, independent LibRaw/TIFF/JPEG/XML checks, owner Lightroom orientation/as-shot/exposure/WB screenshots and landscape JPEG Photoshop/Chrome review, with unverified user-Mac hashes/builds explicitly preserved. The per-call API retains `independent-decode-required-editor-validation-pending`: it cannot attest that arbitrary newly generated bytes were checked in an external editor. That conservative result field is not the current issue status.
+
+Format references and DNG patent-license notice are recorded in `THIRD_PARTY.md`
+and `NOTICE`. No Adobe SDK or external encoder source is incorporated.
+
+Internal ownership: `src/color/sensor-color-development.ts` owns the declared
+sensor-channel gain → camera-to-XYZ → linear-sRGB calculation and conditioned
+inversion. Export retains profile/evidence validation, CFA binding, one-time WB
+authorization, geometry and DNG/JPEG container mapping. The adapter consumes
+validated data and does not infer sensor calibration or reuse the distinct ideal
+virtual-camera input contract. Existing arithmetic order and error policies are
+preserved; no public API or schema change is introduced.