@photivra/engine 0.6.0 → 1.0.1

package/docs/MOTION_AND_SIGNAL.md

@@ -1,5 +1,7 @@
 # Motion and Signal Foundation
 
+Release context: **package 1.0.1 candidate / root API 1.0.1**. 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_1.md).
+
 ## Projected subject motion
 
 Subject-motion blur is modeled from image-plane displacement rather than broad labels such as "fast sport" or "slow subject."
@@ -113,7 +115,7 @@ Mechanical, EFCS, and electronic shutter mechanisms determine only which concept
 
 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 a later integration layer must define how local capture-window times bind to that motion time basis.
+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.
 
@@ -160,7 +162,7 @@ These are intentionally separate. The seconds-valued measure is not shutter tran
 
 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. Photivra does not yet model shutter-transmission ramps, exposure-dependent sensor response, scene flicker, flash pulses, or other time-varying radiometric weighting.
+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.
 
@@ -197,7 +199,7 @@ The current inverse does not claim that an arbitrary rolling/capture-scan camera
 
 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.1 candidate / root API 1.0.1**. 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_1.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.1 candidate / root API 1.0.1**. 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_1.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.1 candidate / root API 1.0.1**. 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_1.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.