@photivra/engine 0.6.0 → 1.0.0

package/docs/V1_COMPOSITION_MAP.md

@@ -0,0 +1,123 @@
+# OpenSource V1 composition and consumer map
+
+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).
+
+Release candidate: package 1.0.0, root API 0.116.0, production plan 0.7.0. Feature/science main is `34c6d9aca1c2e365b253c1562734d11bc8e0235f` (#206). [V1 #129](https://github.com/Photivra/photivra/issues/129) is **32/32**; #178 and #131 are closed. This audit reconciles current consumer boundaries below; #180 is the release-preparation contribution and publication remains owner-only.
+
+A closed foundation ticket establishes its primitive scope, not automatic
+availability of every optional model in every production route. Direct consumers,
+bounded executed composition and unsupported combinations are distinguished
+below; no unsupported combination is an approved V1 deferral.
+
+## All 32 scoped items
+
+Source paths identify the main primitive/boundary, not every helper in that
+feature. The consumer column distinguishes direct foundations, production-plan
+results and bounded capture/output adapters. The last column records coupling rules and supported-route limits; older ticket references identify merged owners, not outstanding feature tickets. No competing RAW writer or second scientific graph is needed.
+
+| Ticket / feature | Tracker | Primitive or boundary | Current entry point / consumer | Representative evidence | Coupling / supported boundary |
+| --- | --- | --- | --- | --- | --- |
+| [#1](https://github.com/Photivra/photivra/issues/1) Non-circular diffraction | closed | [polygon-diffraction.ts](https://github.com/Photivra/photivra/blob/main/src/optics/polygon-diffraction.ts) | Direct polygon PSF; production PSF execution absent | [polygon-diffraction.test.ts](https://github.com/Photivra/photivra/blob/main/test/polygon-diffraction.test.ts) | #16/#178: compose declared pupil support without double diffraction |
+| [#3](https://github.com/Photivra/photivra/issues/3) Extended-object motion | closed | [extended-object-projection.ts](https://github.com/Photivra/photivra/blob/main/src/motion/extended-object-projection.ts) | Direct temporal projection; production radiance accumulation absent | [extended-object-projection.test.ts](https://github.com/Photivra/photivra/blob/main/test/extended-object-projection.test.ts) | #16/#178: retain depth/visibility/time at requested nodes |
+| [#7](https://github.com/Photivra/photivra/issues/7) ISO and signal chain | closed | [iso-signal-chain.ts](https://github.com/Photivra/photivra/blob/main/src/sensor/iso-signal-chain.ts) | Explicit regime bindings; RAW producer consumes readout profiles | [generic-tier-output-acceptance.test.ts](https://github.com/Photivra/photivra/blob/main/test/generic-tier-output-acceptance.test.ts) | #16: bind committed ISO to explicit regime; preserve physical charge |
+| [#12](https://github.com/Photivra/photivra/issues/12) Readout and shutter | closed | [exposure-window.ts](https://github.com/Photivra/photivra/blob/main/src/sensor/exposure-window.ts) | Production temporal diagnostics; RAW local-window handoff | [sensor-raw-local-exposure.test.ts](https://github.com/Photivra/photivra/blob/main/test/sensor-raw-local-exposure.test.ts) | #16: integrate scene signal over those windows; no inferred synchronization |
+| [#14](https://github.com/Photivra/photivra/issues/14) Sensor pipeline | closed | [eqe-electron-rate.ts](https://github.com/Photivra/photivra/blob/main/src/sensor/eqe-electron-rate.ts) | Bounded irradiance→EQE local exposure composition; charge-to-RAW adapter | [sensor-raw-pipeline.test.ts](https://github.com/Photivra/photivra/blob/main/test/sensor-raw-pipeline.test.ts) | #16/#178: bind committed scene/optics/PSF origin to physical irradiance nodes |
+| [#15](https://github.com/Photivra/photivra/issues/15) Linear capture and color | closed | [simulated-capture.ts](https://github.com/Photivra/photivra/blob/main/src/capture/simulated-capture.ts) | Immutable capture; ideal XYZ color and linear encoding; sensor adapter distinct | [capture-color.test.ts](https://github.com/Photivra/photivra/blob/main/test/capture-color.test.ts) | #112/#16: bind physical capture origin; preserve color-channel basis |
+| [#16](https://github.com/Photivra/photivra/issues/16) Paired RAW DNG/JPEG | closed | [photographic-export.ts](https://github.com/Photivra/photivra/blob/main/src/capture/photographic-export.ts) | Exact attached-RAW reconstruction → development → correction/SDR → files | [raw-output-conformance.test.ts](https://github.com/Photivra/photivra/blob/main/test/raw-output-conformance.test.ts) | Producer-derived independent/Adobe/editor evidence merged in #201; 4,096-site bound remains explicit |
+| [#43](https://github.com/Photivra/photivra/issues/43) Prepared/batch performance | closed | [geometric-transforms.ts](https://github.com/Photivra/photivra/blob/main/src/output/geometric-transforms.ts) | Call-owned prepared geometric mapping reused by sampling execution | [geometric-preparation-reuse.test.ts](https://github.com/Photivra/photivra/blob/main/test/geometric-preparation-reuse.test.ts) | [Merged final remeasurement](V1_PERFORMANCE_DISPOSITION.md); retain merged call-owned reuse; no further abstraction |
+| [#45](https://github.com/Photivra/photivra/issues/45) POC projection reuse | closed | [poc-simulation.ts](https://github.com/Photivra/photivra/blob/main/src/simulation/poc-simulation.ts) | Private prepared projection in legacy POC defocus sweeps | [poc-projection-reuse.test.ts](https://github.com/Photivra/photivra/blob/main/test/poc-projection-reuse.test.ts) | [Merged final remeasurement](V1_PERFORMANCE_DISPOSITION.md); retain request-local reuse; POC remains separate |
+| [#95](https://github.com/Photivra/photivra/issues/95) Stable support | closed | [camera-shake.ts](https://github.com/Photivra/photivra/blob/main/src/stabilization/camera-shake.ts) | Direct ideal stable-support boundary, independent of correction | [camera-shake.test.ts](https://github.com/Photivra/photivra/blob/main/test/camera-shake.test.ts) | #16/#178: requested shake/stabilization must preserve physical ownership |
+| [#97](https://github.com/Photivra/photivra/issues/97) IBIS/OIS | closed | [system.ts](https://github.com/Photivra/photivra/blob/main/src/stabilization/system.ts) | Explicit disturbance/trajectory temporal sampling | [stabilization-system.test.ts](https://github.com/Photivra/photivra/blob/main/test/stabilization-system.test.ts) | #16/#178: consume selected trajectory in physical sampling, not a blur-quality scalar |
+| [#98](https://github.com/Photivra/photivra/issues/98) Sensor architecture | closed | [architecture.ts](https://github.com/Photivra/photivra/blob/main/src/sensor/architecture.ts) | Declared technology metadata and related standalone profile boundaries | [sensor-architecture.test.ts](https://github.com/Photivra/photivra/blob/main/test/sensor-architecture.test.ts) | #16: preserve selected architecture/bindings; metadata alone is not signal execution |
+| [#100](https://github.com/Photivra/photivra/issues/100) Metering | closed | [metering.ts](https://github.com/Photivra/photivra/blob/main/src/exposure/metering.ts) | Relative pre-exposure meter → exposure target/equipment resolver | [metering-equipment-integration.test.ts](https://github.com/Photivra/photivra/blob/main/test/metering-equipment-integration.test.ts) | #16/#112: retain pre-display signal and do not infer calibrated spectral weighting |
+| [#103](https://github.com/Photivra/photivra/issues/103) Finite/infinity focus | closed | [focus-state.ts](https://github.com/Photivra/photivra/blob/main/src/optics/focus-state.ts) | Explicit focus state consumed by optics and committed capture | [focus-state.test.ts](https://github.com/Photivra/photivra/blob/main/test/focus-state.test.ts) | #16/#178: preserve focus in field/depth/PSF evaluations |
+| [#104](https://github.com/Photivra/photivra/issues/104) Focus control | closed | [focus-control.ts](https://github.com/Photivra/photivra/blob/main/src/capture/focus-control.ts) | MF/AF state and release gate; tier body acceptance | [generic-tier-body-acceptance.test.ts](https://github.com/Photivra/photivra/blob/main/test/generic-tier-body-acceptance.test.ts) | #16: carry committed focus; no undocumented tracking renderer |
+| [#105](https://github.com/Photivra/photivra/issues/105) Release sequencing | closed | [release-sequence.ts](https://github.com/Photivra/photivra/blob/main/src/capture/release-sequence.ts) | Release frame → production snapshot binding; deterministic ownership | [production-capture-release-binding.test.ts](https://github.com/Photivra/photivra/blob/main/test/production-capture-release-binding.test.ts) | #16: carry frame timing/settings/seed to physical execution |
+| [#106](https://github.com/Photivra/photivra/issues/106) Manual flash/sync | closed | [flash.ts](https://github.com/Photivra/photivra/blob/main/src/exposure/flash.ts) | Declared sync and illumination overlay; no full production radiance integration | [flash.test.ts](https://github.com/Photivra/photivra/blob/main/test/flash.test.ts) | #16/#178: apply physical-time light transport when selected; no exposure-duration shortcut |
+| [#108](https://github.com/Photivra/photivra/issues/108) WB/custom/AWB | closed | [white-balance.ts](https://github.com/Photivra/photivra/blob/main/src/color/white-balance.ts) | Resolved WB → release/production binding; RAW intent and one-time sensor development | [photographic-export.test.ts](https://github.com/Photivra/photivra/blob/main/test/photographic-export.test.ts) | #112/#16: preserve matching basis; never re-estimate from rendered output |
+| [#111](https://github.com/Photivra/photivra/issues/111) Production plan | closed | [image-formation-plan.ts](https://github.com/Photivra/photivra/blob/main/src/composition/image-formation-plan.ts) | Authoritative graph expansion; physical sample/temporal results and blockers | [production-image-formation-plan.test.ts](https://github.com/Photivra/photivra/blob/main/test/production-image-formation-plan.test.ts) | #178/#16/#112: intentionally add downstream stages with contract/version review |
+| [#112](https://github.com/Photivra/photivra/issues/112) Processed camera output | closed | [capture-corrected-sdr.ts](https://github.com/Photivra/photivra/blob/main/src/output/capture-corrected-sdr.ts) | Capture-bound color/correction → oriented view/SDR; paired RAW consumer | [photographic-export-correction.test.ts](https://github.com/Photivra/photivra/blob/main/test/photographic-export-correction.test.ts) | Shared processed RAW/preview/JPEG merged in #200; executed upstream route in plan 0.7.0; final tier/conformance acceptance is merged |
+| [#113](https://github.com/Photivra/photivra/issues/113) Lens PSF/bokeh | closed | [lens-psf-profile.ts](https://github.com/Photivra/photivra/blob/main/src/optics/lens-psf-profile.ts) | Declared sampled PSF/MTF; separate complex-pupil model | [lens-psf-framework.test.ts](https://github.com/Photivra/photivra/blob/main/test/lens-psf-framework.test.ts) | #16/#178: wavelength/field/depth sampling and finite support; MTF-only is not renderable PSF |
+| [#114](https://github.com/Photivra/photivra/issues/114) Stray light | closed | [stray-light.ts](https://github.com/Photivra/photivra/blob/main/src/optics/stray-light.ts) | Separate declared ghost/veiling irradiance foundation | [stray-light.test.ts](https://github.com/Photivra/photivra/blob/main/test/stray-light.test.ts) | #16/#178: add only explicitly selected incremental light; never fold into primary PSF |
+| [#116](https://github.com/Photivra/photivra/issues/116) Generic tiers | closed | [generic-tier-presets.ts](https://github.com/Photivra/photivra/blob/main/src/equipment/generic-tier-presets.ts) | Exact-version selection; body and lens profile resolution | [generic-tier-presets.test.ts](https://github.com/Photivra/photivra/blob/main/test/generic-tier-presets.test.ts) | [Merged catalog acceptance disposition](TIER_PRESET_ACCEPTANCE.md); nine-pair production/output and 27 exact pupil scenes; #119 broader validation is merged; no calibrated ranking |
+| [#117](https://github.com/Photivra/photivra/issues/117) Lens corrections | closed | [lens-corrections.ts](https://github.com/Photivra/photivra/blob/main/src/output/lens-corrections.ts) | Capture-bound selected correction; RAW informational intent/JPEG processing | [generic-tier-correction-acceptance.test.ts](https://github.com/Photivra/photivra/blob/main/test/generic-tier-correction-acceptance.test.ts) | #112/#16: connect authoritative upstream capture while preserving residual/crop/noise costs |
+| [#118](https://github.com/Photivra/photivra/issues/118) Composed geometry/resampling | closed | [geometric-transforms.ts](https://github.com/Photivra/photivra/blob/main/src/output/geometric-transforms.ts) | Domain-compatible joint mapping/sampling → bounded correction executor | [geometric-transforms.test.ts](https://github.com/Photivra/photivra/blob/main/test/geometric-transforms.test.ts) | #112/#16: preserve full Jacobian/filter/support and existing domain order |
+| [#119](https://github.com/Photivra/photivra/issues/119) Tier acceptance | closed | [generic-tier-assets.ts](https://github.com/Photivra/photivra/blob/main/src/equipment/generic-tier-assets.ts) | Matched synthetic body/correction/readout-to-file fixture consumers | [generic-tier-output-acceptance.test.ts](https://github.com/Photivra/photivra/blob/main/test/generic-tier-output-acceptance.test.ts) | [Merged final tier acceptance](TIER_ACCEPTANCE.md): versioned physical/cost/corrected report, multidimensional finite pupils and matched body execution; existing paired-output evidence reused |
+| [#130](https://github.com/Photivra/photivra/issues/130) Canonical fixture | closed | [basic-reference-fixture.ts](https://github.com/Photivra/photivra/blob/main/test/helpers/basic-reference-fixture.ts) | Shared deterministic laboratory and minimal declared variants | [basic-reference-scene.test.ts](https://github.com/Photivra/photivra/blob/main/test/basic-reference-scene.test.ts) | #131: reuse without treating tiny/synthetic raster as performance or calibration evidence |
+| [#131](https://github.com/Photivra/photivra/issues/131) Final conformance | closed | [raw-output-conformance.test.ts](https://github.com/Photivra/photivra/blob/main/test/raw-output-conformance.test.ts) | Final meter/capture/production/output path plus incremental geometry/signal suites | [cross-stage-conformance.test.ts](https://github.com/Photivra/photivra/blob/main/test/cross-stage-conformance.test.ts) | [Reviewed/merged final conformance](SCIENTIFIC_CONFORMANCE.md), PR #206; 32/32 feature/science complete |
+| [#132](https://github.com/Photivra/photivra/issues/132) Numerics/units | closed | [validation.ts](https://github.com/Photivra/photivra/blob/main/src/core/validation.ts) | Typed input/result guards plus shared units/finite conventions | [numerical-correctness-contract.test.ts](https://github.com/Photivra/photivra/blob/main/test/numerical-correctness-contract.test.ts) | Apply throughout new composition; existing guards do not establish physical validity |
+| [#133](https://github.com/Photivra/photivra/issues/133) API conventions | closed | [API_STYLE.md](../docs/API_STYLE.md) | Root public naming/compatibility/version policy | [api-style-compatibility.test.ts](https://github.com/Photivra/photivra/blob/main/test/api-style-compatibility.test.ts) | Review new public handoffs and relevant independent versions before activation |
+| [#134](https://github.com/Photivra/photivra/issues/134) Evidence/uncertainty | closed | [scientific-assurance.ts](https://github.com/Photivra/photivra/blob/main/src/core/scientific-assurance.ts) | Production assurance composition retains weakest required status and unpropagated uncertainty | [scientific-assurance.test.ts](https://github.com/Photivra/photivra/blob/main/test/scientific-assurance.test.ts) | #16/#112: preserve child evidence/status; no invented combined uncertainty |
+| [#135](https://github.com/Photivra/photivra/issues/135) Front filters | closed | [front-of-lens-filter.ts](https://github.com/Photivra/photivra/blob/main/src/optics/front-of-lens-filter.ts) | Capture snapshot → #110 throughput exactly once | [front-of-lens-filter.test.ts](https://github.com/Photivra/photivra/blob/main/test/front-of-lens-filter.test.ts) | #16/#178: distinguish lens/filter/sensor response scope to avoid double transmission |
+
+## Authoritative production execution
+
+[`getImageFormationContract()`](https://github.com/Photivra/photivra/blob/main/src/core/image-formation.ts) owns the stage
+dependencies. Plan 0.7.0 expands that graph and can invoke the existing
+[`simulateEnvironmentSensorRawFrame()`](https://github.com/Photivra/photivra/blob/main/src/capture/environment-raw-producer.ts)
+through `environmentCapture`. It binds exact context/event/scene/provider/optics,
+geometry/shutter/rotation/seed/WB identities before provider code executes.
+Optional processing consumes only its realized native RAW frame. No second
+writer, scientific graph or seed schedule is introduced.
+
+| Stage family | Executed consumer | Independent acceptance |
+| --- | --- | --- |
+| Source projection, provider, optical throughput and temporal sampling | Generated inverse environment rays, exact local shutter midpoints and supplied synchronous provider through existing optical bridge | `environment-raw-integration.test.ts`, `sensor-environment-query.test.ts`, `scene-eqe-temporal-exposure.test.ts` |
+| Wavelength/field PSF | Existing sampled local PSF support per wavelength/destination; omitted PSF is an explicit point-optics model with evidence/limitation | `sensor-psf-quadrature.test.ts`, sampled/omitted PSF plan acceptance |
+| Optical stack, CFA/spatial/spectral response | Existing AA/aperture plans, exact destination channel, package-plane response compatibility/range and instantaneous EQE | `spatial-sampling-quadrature.test.ts`, `eqe-local-exposure.test.ts`, `eqe-temporal-exposure.test.ts` |
+| Charge, noise, signed readout and ADC | Existing temporal photo/dark, completeness/capacity and native seeded RAW producer | `temporal-photo-raw.test.ts`, `sensor-raw-producer.test.ts`, plan replay acceptance |
+| Reconstruction, color/WB, selected correction, orientation/crop and display | Shared processed-RAW executor consumes the exact executed frame; output changes retain native codes and upstream noise | `processed-sensor-raw.test.ts`, `photographic-export-correction.test.ts`, all-orientation/WB/correction plan acceptance |
+| Files | Existing paired exporter consumes that same frame; no file IO in the plan | `environment-raw-integration.test.ts`, committed #201 independent LibRaw/XML/TIFF/JPEG records and owner application evidence |
+| Renderer/reference consumers | Consumer manifest 0.2.0 exposes the same immutable execution/output results and plan identity | `production-image-formation-plan.test.ts` |
+
+See [production environment capture](PRODUCTION_ENVIRONMENT_CAPTURE.md) for the
+complete binding and migration contract. Successful bounded execution can reach
+all fourteen requested stages. Missing execution inputs, unsupported required
+effects and insufficient renderer capabilities retain explicit blockers. The
+sample-only and independently attached-RAW routes keep their conservative
+limitations; standalone child flags are not rewritten by the parent composer.
+
+## Scientific boundaries and ownership
+
+The implemented execution envelope remains the existing bounded ideal
+continuous-spectrum environment route: opening-reference scene time zero,
+complete one-to-one native CFA registration, explicit unity field throughput,
+constant-axis motion, optional destination-local sampled PSF and valid response
+scope/area/range. The native/reference budget is 4,096 sites and aggregate
+provider evaluations are limited to 100,000. Shared output-envelope checks reject
+unsupported resampling/coverage before provider calls; pixel-dependent kernel
+and correction support remain execution checks.
+
+Executed source queries establish invocation and numerical lineage, not measured
+transport, visibility, calibration, convergence, arbitrary world pose or global
+field-energy conservation. Renderer implementation remains external under the
+existing provider contract. A closed direct foundation does not license the
+composer to mark an unsupported optional model active. The table above retains
+feature-specific direct consumers and remaining integration ownership. No
+broader capability or unsupported scientific combination has been approved for
+deferral by this change.
+
+## Defect disposition and final gates
+
+- #178 finding 1: the 32-item primitive/consumer/evidence/ownership map is present;
+  the executed bounded environment route now composes the previously blocked
+  sensor stages through the authoritative graph. Unsupported requested effects
+  remain explicit; stale version diagnostics were fixed in #183.
+- Finding 2: the plan invokes the engine-owned environment/optics/PSF/response/
+  temporal path into the existing RAW producer, rather than accepting a caller
+  exposure result as evidence that source execution ran. Provider truth remains
+  separate from executed origin.
+- Finding 3: equivalent freeze/canonical JSON/allowlist/public-ID mechanics were
+  consolidated in #184/#185/#193. Current production capture bindings and output
+  envelope checks reuse the existing owners. Meaningful domain differences are
+  documented in [helper reuse review](V1_HELPER_REUSE_REVIEW.md).
+- Finding 4: reusable sensor-color development is owned by the internal color
+  adapter from #186; WB basis/application and export/container ownership remain
+  distinct.
+- Finding 5: shared producer/reconstruction bounds and early output compatibility
+  are documented/tested in #187 and this executed plan preflight; #201 records
+  the supported-size decision without claiming megapixel measurements. See
+  [RAW frame envelope](RAW_FRAME_ENVELOPE.md).
+- Finding 6: `distribute*` was documented in #183; the compatibility guard remains.
+
+#131 final conformance is reviewed and merged. #180 is this final human/agent/source documentation and 1.0 preparation contribution; final review/DCO, signed merge and final-main CI precede owner-only tag/publication. #165 remains post-V1. The linked source and tests define each supported boundary; a closed issue does not authorize every optional model combination.

package/docs/V1_HELPER_REUSE_REVIEW.md

@@ -0,0 +1,60 @@
+# V1 internal helper reuse review
+
+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 review addresses the remaining repeated validation mechanics in defect
+#178. It does not close production integration, performance, editor acceptance
+or final release preparation. The review follows main `e5a6ce2` and the earlier
+freeze, canonical JSON and sensor-color ownership changes. The temporal photo-signal handoff and shared validators were merged in
+PRs #192/#193. This is a current reuse assessment, not an unmerged stack.
+
+## Shared mechanics
+
+`src/core/record-validation.ts` now owns the equivalent record/own-enumerable-key
+allowlist check used by capture, RAW attachment/producer/reconstruction, export
+metadata, photographic export, linear encoding, capture color and SDR/correction
+boundaries, plus the temporal photo-signal boundary. It also owns the identical 1–128 character ASCII public opaque ID
+grammar used by capture, RAW, exporter, producer, color, SDR and temporal photo-signal boundaries.
+
+Domain wrappers retain their original diagnostics. Domains still own field
+lists, required fields, enum choices, evidence, numerical validity, copying,
+freezing and scientific contracts. The helper returns the existing record;
+it does not sanitize input or silently add stricter object semantics. This
+preserves the existing treatment of inherited/non-enumerable/symbol properties
+and is not a general serializer or hostile JavaScript object sandbox.
+
+## Separations retained
+
+- Finite-number validators differ in sign, integer ranges, negative-zero policy
+  and diagnostics. A single generic validator would obscure those contracts.
+- Dense arrays have different limits, required lengths, sparse-array behavior
+  and element validation. Their domain policies remain local.
+- UUID and SHA-256 grammars remain distinct from opaque public IDs.
+- Planner/focus/release freezing has intentionally different early-return
+  semantics from the shared child-first owned-data freeze.
+- Planner fingerprints and export hashes share canonical JSON mechanics, but
+  retain different undefined-value policies and identity algorithms.
+- Sensor-color development and ideal virtual-camera transforms retain their
+  separate basis, conditioning and physical meanings.
+- Evidence/calibration parsers retain their own model/version/applicability
+  checks. A public identifier grammar is not scientific applicability evidence.
+
+The equivalent helper findings are addressed by the shared implementation and
+these explicit retained boundaries. Future reuse should follow demonstrated
+semantic equivalence, rather than mechanical similarity alone.
+
+## Compatibility and verification
+
+No public export, version, schema, equation, seed schedule or byte-identity
+algorithm changes. Existing historical capture/RAW/DNG/JPEG hash regressions
+remain the exact-byte oracle. Public-boundary tests cover invalid record shapes,
+unknown fields and unsafe identities with unchanged domain error messages.
+The shared helpers stay internal to the package's root export contract.
+
+The final #180 audit must revisit this assessment against the integrated release
+candidate; this document is not that exhaustive final documentation audit.
+
+Production environment integration reuses the existing output-envelope check
+before invoking provider code. Capture identity/exposure/seed/WB/focus validation
+is shared between executed and attached-RAW plan routes; domain-specific scene,
+geometry, timing and provider bindings remain separate.

package/docs/V1_PERFORMANCE_DISPOSITION.md

@@ -0,0 +1,88 @@
+# Final V1 performance disposition: #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).
+
+Final measured main is `edc20e61538152fa758f3cce4b41cc34d1e8ba03` (#204), root API 0.116.0, POC API 0.20.0. #175 and #176 already merged the justified private optimizations. PR #205 merged this final remeasurement after human review/DCO; both issues are closed. The recorded engine commit identifies the measured build, not the latest release candidate. It adds no runtime optimization, public abstraction, dependency, numerical tolerance change or timing CI gate.
+
+## Context and reproducibility
+
+All measurements used Node 24.19.0 / V8 13.6.233.17-node.51, macOS arm64, Apple M5 Pro, 18 logical CPUs. The host is shared; ambient activity, thermals and power state are uncontrolled. Runs were sequential with no concurrent task tests/benchmarks. Both trees were compiled with canonical `tsc`. The independent pre-optimization reference is `c1374c31473f893310d1ce4f0d5a737aaba43ab5`; comparisons isolate the retained #43/#45 paths, not the entire intervening V1 feature set. Candidate source SHA-256 commitments are retained in every paired artifact. `candidateBaseCommit` now records the actual measured final main independently of the reference. Labels are operator-attested, not automatically git-verified.
+
+Two ordinary paired runs and one separate forced-GC/profile run reuse the existing owned benchmarks unchanged in workload/equivalence semantics. Reference/candidate order alternates, scenario order rotates. POC: 500 warmups and nine blocks of 1,000 requests per shape. Geometry: five blocks, 100 warmup/block calls for 1×1/5×5, two warmups/one block call for larger grids. Whole response/result including provenance must match the independent reference before timing. See [projection method](POC_PROJECTION_REUSE.md) and [geometry method](GEOMETRIC_PREPARATION_REUSE.md).
+
+Raw artifacts: [geometry ordinary 1](benchmarks/2026-10-02-v1-geometry-ordinary-1.json), [ordinary 2](benchmarks/2026-10-02-v1-geometry-ordinary-2.json), [GC/profile](benchmarks/2026-10-02-v1-geometry-gc-profile.json); [POC ordinary 1](benchmarks/2026-10-02-v1-poc-ordinary-1.json), [ordinary 2](benchmarks/2026-10-02-v1-poc-ordinary-2.json), [GC/profile](benchmarks/2026-10-02-v1-poc-gc-profile.json). Raw block timing and retained-heap deltas are preserved. GC-assisted timings are separate distributions and do not establish GC causality.
+
+## #43 decision: retain call-owned geometry reuse; no further prepared API
+
+| Whole consumer | Reference ms/call, run 1 | Final main ms/call, run 1 | Ratio run 1 | Ratio run 2 |
+| --- | ---: | ---: | ---: | ---: |
+| sampling-plan-1x1 | 0.0146 | 0.0117 | 0.799 | 0.796 |
+| corrected-capture-1x1 | 0.1264 | 0.1069 | 0.846 | 0.815 |
+| sampling-plan-5x5 | 0.2004 | 0.1157 | 0.577 | 0.594 |
+| corrected-capture-5x5 | 1.3817 | 0.8879 | 0.643 | 0.649 |
+| sampling-plan-17x17 | 2.3222 | 1.2968 | 0.558 | 0.566 |
+| corrected-capture-17x17 | 16.0390 | 10.2372 | 0.638 | 0.608 |
+| sampling-plan-33x33 | 8.6810 | 5.0144 | 0.578 | 0.577 |
+| corrected-capture-33x33 | 62.3895 | 39.9700 | 0.641 | 0.662 |
+| sampling-plan-65x65 | 34.3922 | 20.1464 | 0.586 | 0.557 |
+| corrected-capture-65x65 | 244.6844 | 165.3251 | 0.676 | 0.660 |
+
+For 17×17 through 65×65, ordinary sampling plans are approximately 41–44% shorter and whole corrected captures 32–39% shorter in these two runs. The current merged paths execute actual inverse support, joint masks/crops, three-channel nearest resampling and gain on an explicitly declared 24×24 mm synthetic field. These are bounded consumer measurements, not full-resolution or browser rendering. The gain remains material after the V1 processing/tier work stabilized.
+
+Separate geometry preparation medians are 3.129 µs reference and 3.298 µs final main; preparation stays at the untrusted public boundary. There is no persistent prepared state or added lifecycle to measure. A returned mapping still owns its transform data and per-point diagnostics. Small grids above measure amortization including boundary overhead rather than assuming preparation is free. No portable break-even grid size is asserted.
+
+At 65×65 correction, separate CPU sampling counted `prepareGeometricMapping` in 307/881 reference consumer stacks versus 2/599 final-main stacks. Heap sampling estimated 6,923,905,856 versus 4,842,216,576 allocated bytes over five captures (about 30% lower). Preparation-inclusive estimates were 2,070,409,472 versus 426,720 bytes. These are overlapping inclusive CPU categories and statistical allocation estimates, not exact counters, retained context size or GC-pause measurements. Large cumulative allocation is not simultaneous live memory.
+
+Acceptance reuses the existing 32-case deterministic scalar oracle corpus, mutation isolation, fresh-call revalidation and folded/intermediate-domain failures. No inverse iteration bound or scalar API behavior changes. The final disposition is to retain #176 and the existing radial/CA batch surface, and add no generic mutable prepared engine, vignetting/rotation cache or extra solver. The new production profile below supplies no evidence that such an abstraction would materially improve its whole request.
+
+## #45 decision: retain request-local defocus projection reuse; no broader context
+
+| Whole POC request | Reference µs, run 1 | Final main µs, run 1 | Ratio run 1 | Ratio run 2 |
+| --- | ---: | ---: | ---: | ---: |
+| 24mp-base | 5.330 | 5.388 | 1.011 | 0.997 |
+| 24mp-defocus-1 | 5.813 | 5.548 | 0.954 | 0.950 |
+| 24mp-defocus-2 | 6.317 | 5.801 | 0.918 | 0.924 |
+| 24mp-defocus-4 | 7.077 | 6.423 | 0.908 | 0.912 |
+| 24mp-defocus-8 | 8.877 | 7.589 | 0.855 | 0.866 |
+| 24mp-defocus-16 | 12.361 | 9.792 | 0.792 | 0.785 |
+| 24mp-mixed-16-per-kind | 26.267 | 23.470 | 0.894 | 0.897 |
+| 24mp-staged-portrait-mixed | 44.816 | 42.584 | 0.950 | 0.957 |
+
+The 16-defocus request is 20.8–21.5% shorter, mixed sweeps 10.3–10.6% shorter and staged portrait mixed requests 4.3–5.0% shorter in the two ordinary runs. Base and single-sample changes are small and noisy. No universal benefit or portable break-even count is claimed. The 6000×4000 sensor is analytical request context; the POC does not render 24 million samples. It remains a public compatibility/developer consumer, not observed private-product traffic or the production composer.
+
+Preparation creates a frozen three-scalar object only for a nonempty defocus sweep, borrowing the validated projection from the same request. The separate isolated probe median was 19.851 ns, with the existing escape/JIT caveat. No-sweep requests allocate no context; no context is retained across calls, exposed publicly or stored in the result. Net post-GC retained heap is not an object-size/allocation measurement.
+
+Separate sampled allocations for 2,000 staged requests were 605,749,360 bytes reference and 564,364,680 final main (about 7% lower); thin-lens-inclusive estimates were 175,036,920 versus 138,980,832 (about 21% lower). Whole-request distributions and the unchanged 64-case independent complete-response SHA corpus support keeping #175. Alternating focal/focus inputs, invalid input and stale-context rejection remain required. No additional FOV/motion/sampling context, cross-request cache or public projection API is justified.
+
+## Current V1 executed environment-to-RAW consumer
+
+The new repository-only `scripts/benchmark-v1-environment.mjs` reuses the owned sensor/environment fixtures and canonical TypeScript build in a disposable directory. Setup/compilation is outside timed calls. It executes the current full environment capture adapter: rolling local windows, rotated environment queries, spatial/spectral/temporal integration, optional sampled PSF, EQE, dark charge, capacity, seeded noise and ADC. Every scenario checks executed provider count and deterministic whole-result SHA replay before timing. Two warmups and five rotating one-call blocks are recorded.
+
+Four native sites are intentionally held constant while actual work increases from 128 to 36,864 provider evaluations. This is representative of bounded dense quadrature workloads in the supported executor, not full-native throughput, observed traffic or a performance conclusion based on the tiny canonical #130 raster. No 24/45/60 MP or complete physical renderer performance is claimed. The declared synthetic radiance callback is cheap; external provider transport/visibility cost is absent.
+
+| Temporal samples / aperture grid / PSF | Provider evaluations/call | Ordinary median ms | Separate GC-assisted median ms |
+| --- | ---: | ---: | ---: |
+| 4 / 2×2 / not applied | 128 | 7.987 | 8.795 |
+| 16 / 4×4 / not applied | 2,048 | 70.555 | 76.885 |
+| 16 / 2×2 / 9 taps | 4,608 | 183.633 | 195.540 |
+| 32 / 4×4 / 9 taps | 36,864 | 1448.311 | 1478.752 |
+
+[Ordinary evidence](benchmarks/2026-10-02-v1-environment-ordinary.json) and [GC/profile evidence](benchmarks/2026-10-02-v1-environment-gc-profile.json) include raw heap/RSS deltas, work counts and result commitments. The separate heaviest-case profile counted thin-lens calculation in 10/1,090 whole-consumer CPU stacks, geometric preparation in zero, and recursive finite validation in 889/1,090. Categories overlap, inlining can hide frames, and zero observed samples do not prove zero work. The adapter calls a private internal executor, so the public photo-signal wrapper need not appear in stacks.
+
+The independent allocation pass estimated 6,458,745,904 bytes cumulatively for one dense capture, not 6.46 GB retained live memory. Net RSS/heap deltas do not measure peak memory; no peak claim is made. Detailed diagnostic/provenance materialization and fail-closed validation have real cost. This descriptive baseline has no before/after candidate and cannot establish an optimization benefit. It supports an explicit no-further-change decision within #43/#45: no evidence shows their duplicate projection/preparation targets dominate this current consumer, and removing provenance/validation is outside their acceptance. A future narrowly evidenced diagnostic/budget optimization would need its own scope and equivalence. No new V1 deferral or feature is invented.
+
+## Browser boundary, acceptance and reproduction
+
+No browser-motivated public API or browser timing claim is proposed. Current root APIs stay browser-safe; existing browser-surface/package checks remain required. Node/macOS measurements do not establish browser, worker, WebGPU or end-user frame-time behavior. This finite disposition covers the merged Node-measured internal optimizations and current supported public consumer shapes. Browser-motivated future work requires real browser evidence.
+
+The paired POC script additionally compares every complete response in the existing 64-case corpus directly against the independent pre-optimization reference on this runtime and records their hashes. All 64 agree exactly, including the case whose Linux-authored golden SHA differs on this Mac. No golden is regenerated or tolerance relaxed. Local supported-Node check/coverage pass 1,581 tests with that previously reproduced unchanged-main Mac `equivalence-38` golden-hash difference; static/policy, build and package gates pass. Required Linux CI remains the unchanged release gate. Existing analytical/fuzz/copy-safety/provenance gates remain the correctness oracle. All runtime sources, API/schema versions, asset commitments, scalar errors, reference hashes, inverse limits and coverage thresholds are unchanged. #131 still owns final scientific conformance and #180 final documentation/release audit. PR #205 reviewed/merged this evidence and closed #43/#45; PR #206 closed final conformance.
+
+Build current main and the independent reference with `npm ci` and `npm run build`, using a supported Node runtime. Run sequentially without concurrent task tests. Replace the reference path below; repeat ordinary runs independently. Add `--expose-gc` before the script plus `--allocation=sample` (POC) or `--profile=sample` (geometry/environment) for a separate profile run.
+
+```sh
+node scripts/benchmark-poc-projection-reuse.mjs --reference-root=/path/to/reference --reference-commit=c1374c31473f893310d1ce4f0d5a737aaba43ab5 --candidate-commit=edc20e61538152fa758f3cce4b41cc34d1e8ba03
+node scripts/benchmark-geometric-consumers.mjs --reference-root=/path/to/reference --reference-commit=c1374c31473f893310d1ce4f0d5a737aaba43ab5 --candidate-commit=edc20e61538152fa758f3cce4b41cc34d1e8ba03
+node scripts/benchmark-v1-environment.mjs --commit=edc20e61538152fa758f3cce4b41cc34d1e8ba03
+```
+
+No raw inspector profiles/private paths are committed. Performance is informational, with no new dependency or third-party code/data. Human review and contribution-specific DCO certification are required for inclusion.

package/docs/api/camera-equivalent-focal-length.md

@@ -0,0 +1,53 @@
+# camera/equivalent-focal-length.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculateEquivalentFocalLength35Mm
+
+Calculates conventional 35 mm-equivalent focal length from physical focal
+length and the effective active-capture diagonal.
+
+The physical focal length remains unchanged and continues to be the optical
+input for projection and depth-of-field calculations. Focus distance and
+later digital/output crops are deliberately excluded from this conventional
+equivalence quantity.
+
+```ts
+export function calculateEquivalentFocalLength35Mm(
+  input: CalculateEquivalentFocalLength35MmInput
+): CalculationResult<EquivalentFocalLength35Mm>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateEquivalentFocalLength35MmInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateEquivalentFocalLength35MmInput {
+  /** Physical optical focal length in millimetres. */
+  focalLengthMm: number;
+  /** Effective physical active-capture imaging area. */
+  activeImagingArea: SensorImagingArea;
+}
+```
+
+## EquivalentFocalLength35Mm
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface EquivalentFocalLength35Mm {
+  /** Physical optical focal length supplied by the caller. */
+  actualFocalLengthMm: number;
+  /** Conventional diagonal-based 35 mm-equivalent focal length. */
+  equivalentFocalLength35Mm: number;
+  /** Diagonal crop factor of the active physical capture area. */
+  cropFactor35Mm: number;
+  /** Physical active-capture diagonal in millimetres. */
+  activeImagingAreaDiagonalMm: number;
+  /** Declares the equivalence convention used by this result. */
+  basis: "diagonal";
+}
+```

package/docs/api/camera-field-of-view.md

@@ -0,0 +1,119 @@
+# camera/field-of-view.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculateFieldOfView
+
+Calculates rectilinear angular field of view as
+2 * atan(sensorDimension / (2 * projectionDistance)).
+
+Without focusDistanceM, projectionDistance is nominal focal length for
+backwards-compatible infinity-focus/pinhole behavior. With focusDistanceM,
+projectionDistance is the ideal Gaussian thin-lens image distance for that
+focus plane.
+
+Neither mode models real-lens focus breathing or distortion.
+
+```ts
+export function calculateFieldOfView(
+  input: CalculateFieldOfViewInput
+): CalculationResult<FieldOfView>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateFieldOfViewBounds
+
+Calculates an asymmetric rectilinear FOV span from signed sensor-plane
+bounds relative to the optical axis.
+
+This is required for off-center active sensor crops where the optical axis
+is not at the center of the retained rectangle.
+
+```ts
+export function calculateFieldOfViewBounds(
+  input: CalculateFieldOfViewBoundsInput
+): CalculationResult<FieldOfViewBounds>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateFieldOfViewBoundsInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateFieldOfViewBoundsInput {
+  /** Lens focal length in millimetres. */
+  focalLengthMm: number;
+  /**
+   * Minimum sensor-plane coordinate in millimetres relative to the optical
+   * axis. Negative values lie on the negative side of the requested axis.
+   */
+  minimumSensorCoordinateMm: number;
+  /**
+   * Maximum sensor-plane coordinate in millimetres relative to the optical
+   * axis.
+   */
+  maximumSensorCoordinateMm: number;
+  /** Optional focus distance in metres. */
+  focusDistanceM?: number;
+}
+```
+
+## CalculateFieldOfViewInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateFieldOfViewInput {
+  /** Lens focal length in millimetres. */
+  focalLengthMm: number;
+  /** Sensor dimension corresponding to the requested field of view, in millimetres. */
+  sensorDimensionMm: number;
+  /**
+   * Optional focus distance in metres. When supplied, the ideal thin-lens
+   * image distance is used as the projection distance. Omit to preserve the
+   * infinity-focus/pinhole approximation.
+   */
+  focusDistanceM?: number;
+}
+```
+
+## FieldOfView
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FieldOfView {
+  /** Angular field of view in degrees. */
+  degrees: number;
+  /** Angular field of view in radians. */
+  radians: number;
+  /** Projection/image-plane distance used by the geometry, in millimetres. */
+  projectionDistanceMm: number;
+}
+```
+
+## FieldOfViewBounds
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FieldOfViewBounds {
+  /** Minimum signed angular bound in degrees. */
+  minimumDegrees: number;
+  /** Maximum signed angular bound in degrees. */
+  maximumDegrees: number;
+  /** Total angular span in degrees. */
+  degrees: number;
+  /** Minimum signed angular bound in radians. */
+  minimumRadians: number;
+  /** Maximum signed angular bound in radians. */
+  maximumRadians: number;
+  /** Total angular span in radians. */
+  radians: number;
+  /** Projection/image-plane distance used by the geometry, in millimetres. */
+  projectionDistanceMm: number;
+}
+```

package/docs/api/camera-projected-object-size.md

@@ -0,0 +1,54 @@
+# camera/projected-object-size.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculateProjectedObjectSize
+
+Calculates the projected size of a fronto-parallel object plane.
+
+Without focusDistanceM, the function preserves ideal pinhole projection
+using nominal focal length. With focusDistanceM, it projects to the ideal
+thin-lens sensor plane selected by that focus distance.
+
+```ts
+export function calculateProjectedObjectSize(
+  input: CalculateProjectedObjectSizeInput
+): CalculationResult<ProjectedObjectSize>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateProjectedObjectSizeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateProjectedObjectSizeInput {
+  /** Lens focal length in millimetres. */
+  focalLengthMm: number;
+  /** Object width in metres. */
+  objectWidthM: number;
+  /** Object height in metres. */
+  objectHeightM: number;
+  /** Object-plane distance from the camera in metres. */
+  distanceM: number;
+  /** Optional focus distance in metres for focus-aware sensor-plane projection. */
+  focusDistanceM?: number;
+  /** Optional sensor pixel pitch in micrometres. */
+  pixelPitchMicrometers?: number;
+}
+```
+
+## ProjectedObjectSize
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ProjectedObjectSize {
+  widthMm: number;
+  heightMm: number;
+  projectionDistanceMm: number;
+  widthPixels?: number;
+  heightPixels?: number;
+}
+```

package/docs/api/capture-capture-export-metadata.md

@@ -0,0 +1,107 @@
+# capture/capture-export-metadata.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## CAPTURE_EXPORT_METADATA_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+CAPTURE_EXPORT_METADATA_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## CaptureExportArtifactIdentity
+
+Caller-owned resource and saved-incarnation UUIDs; no random IDs or wall clock in the engine.
+
+```ts
+export interface CaptureExportArtifactIdentity { documentId: string; instanceId: string }
+```
+
+## CaptureExportMetadataInput
+
+Metadata-only pairing input. CaptureID must already be a non-nil UUID on the committed capture.
+
+```ts
+export interface CaptureExportMetadataInput {
+  capture: SimulatedCapture;
+  workflow: CaptureExportWorkflow;
+  /** Explicit capture-event UTC timestamp, exactly YYYY-MM-DDTHH:mm:ss.sssZ; never scene time. */
+  capturedAtUtc: string;
+  raw: CaptureExportArtifactIdentity;
+  jpeg: CaptureExportArtifactIdentity;
+}
+```
+
+## CaptureExportMetadataPair
+
+Equal shared metadata and distinct resource IDs do not prove RAW/JPEG pixel derivation.
+
+```ts
+export interface CaptureExportMetadataPair {
+  schemaVersion: typeof CAPTURE_EXPORT_METADATA_SCHEMA_VERSION;
+  shared: CaptureExportSharedMetadata;
+  raw: CaptureExportArtifactIdentity & { outputRole: "raw" };
+  jpeg: CaptureExportArtifactIdentity & { outputRole: "jpeg" };
+  imageDataPairing: "not-verified";
+}
+```
+
+## CaptureExportSharedMetadata
+
+Shared semantic values, not packed EXIF/DNG tags or an XMP packet.
+
+```ts
+export interface CaptureExportSharedMetadata {
+  captureId: string;
+  capturedAtUtc: string;
+  workflow: CaptureExportWorkflow;
+  digitalSourceTypeUri: string;
+  simulatedCapture: true;
+  make: "Photivra";
+  model: "Photivra Virtual Camera";
+  /** Explicitly the captured engine API version, not a claim of an npm distribution version. */
+  software: string;
+  creatorTool: string;
+  engineApiVersion: string;
+  captureContractVersion: SimulatedCapture["schemaVersion"];
+  sceneStateId: string;
+  sceneTimeSeconds: number;
+  exposure: SimulatedCapture["exposure"];
+  focus: SimulatedCapture["focus"];
+  equivalentFocalLength35Mm: number;
+  geometry: SimulatedCapture["geometry"];
+  resolvedGeometry: SimulatedCapture["resolvedGeometry"];
+  noise: SimulatedCapture["noise"];
+  whiteBalanceIntent: SimulatedCapture["whiteBalanceIntent"];
+  models: SimulatedCapture["models"];
+}
+```
+
+## CaptureExportWorkflow
+
+Non-generative workflows only; sampled/AI/composite media need a separate reviewed policy.
+
+```ts
+export type CaptureExportWorkflow = "human-directed-non-generative" | "fully-procedural-non-generative";
+```
+
+## createCaptureExportMetadataPair
+
+Projects known capture metadata once for both future writers; never encodes or verifies image data.
+
+```ts
+export function createCaptureExportMetadataPair(input: CaptureExportMetadataInput): CaptureExportMetadataPair;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseCaptureExportMetadataInput
+
+Fail-closed parser; no default workflow, time, creator, physical-device or file lineage claims.
+
+```ts
+export function parseCaptureExportMetadataInput(value: unknown): CaptureExportMetadataInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.