@photivra/engine 1.5.0 → 2.0.0

package/docs/CAPTURE_CORRECTED_SDR.md

@@ -1,25 +0,0 @@
-# Capture-bound corrections and SDR: #112 integration slice
-
-Release context: **package 1.2.0 candidate / root API 1.2.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_2_0.md).
-
-`calculateCaptureCorrectedSdr()` consumes the same immutable `SimulatedCapture` and explicit source/color/WB choice as `calculateCaptureSdr()`, then executes existing #117/#118 corrections before the existing SDR renderer. This bounded reference bridge does not replace the #111 composer, activate production stages, or complete #112/V1.
-
-Order: validated inline source → existing color/WB → native-optical reconstructed-linear geometry/CA → illumination gain → exact orientation permutation → explicit support crop → SDR. Profiles must be authored for **post-color/WB linear-sRGB/D65**, not assumed interchangeable with sensor-channel CA calibration. Raw-domain components and geometry across gain fail through the existing executor. No WB estimator, optical equation, noise generator or tier-based strength is introduced.
-
-The strict `correction` contract requires exact generic profile/independently declared optical state, `coordinateFrame: "native-optical-linear-srgb-d65"`, selections/selection kind, resampler, positive finite clipping level, local `frameTimeSeconds`, support policy and unique public output state ID. Unknown/private fields fail. Profile/state match and committed focal length/aperture/finite focus/native output dimensions are checked. Infinity focus remains unsupported by the profile schema. Body/lens/version, acquisition mode/frame rate/stabilization and profile accuracy remain **producer declarations**, not independently established by the capture container or upgraded to calibration.
-
-Metric rasters derive from committed physical bounds via the capture coordinate bridge; no caller-supplied pitch/center is accepted. All four orientation corner UVs map to native optical +X-right/+Y-up. Sample quarter-turn permutations reuse the existing raster point transform without extra interpolation. Profile output dimensions are **native optical output dimensions**, swapped relative to final oriented width/height for portrait capture. Square physical pixel pitch is required for source and destination (relative tolerance 1e-12); anisotropic lattices fail rather than stretch. Off-center capture/output retain optical-axis offsets.
-
-Local frame time must fall within the exposure interval; capture scene-clock time is preserved separately. Focus-aware projection reuses the field-of-view calculator, whose child result is returned. Conventional active-capture focal equivalence and physical geometry are never rewritten by correction/output crop.
-
-Source/destination are bounded to 65,536 sites each. Inline co-sited three-channel RGB is required after color/WB. No external loading/streaming/prefilter generation occurs. `source-prefiltered` remains a caller obligation, not verification of adequacy. Child sampling plans preserve native optical coordinates, full Jacobians, per-channel support, resampler identity and prefilter diagnostics. Top-level support uses the full **oriented output** lattice.
-
-Support policy `reject` requires all requested output pixels. `joint-valid-crop` uses the existing largest all-valid rectangle after orientation; empty support fails. No missing channel is padded, mirrored or replaced with black. `outputView.rect` is within the declared oriented output raster; cropped samples/dimensions are a derived view, not a replacement capture plane or new physical capture. A later file adapter must deliberately map this view/crop metadata; the paired DNG/JPEG exporter is unchanged.
-
-Original source/capture/noise IDs, source dynamic-range history and upstream saturation remain separate from optional color, correction and SDR child provenance. Aggregate provenance is approximation because corrections are generic-parametric. `illuminationClippingEventCount` counts channel/stage clipping events **before joint support/crop**, including repeated gain stages; it is not an output-pixel or capture-saturation count. SDR gamut diagnostics describe the retained view. Signed/headroom values survive until explicit gain clipping/SDR handling. Noise covariance/SNR is not regenerated or inferred.
-
-Any existing digital correction history rejects a second invocation; staged recorrection needs a future explicit contract. The view must not be relabeled untreated RAW. Mandatory/automatic camera states and educational reference bypass remain distinct; bypass still honors committed output crop/resampling.
-
-Compatibility: root API 0.100.0 → 0.101.0; adapter schema 0.1.0; package/POC/capture/production unchanged. Existing capture-SDR shares an internal source validator and preserves its behavior. Independently authored tests cover quarter turns/native-direction shifts, nonmutation/determinism, crop/support, history/clocks, clipping separation and unsupported boundaries. No runtime dependency, third-party implementation/data/calibration or new cost is added. Human science/provenance review and contribution-specific DCO are required before inclusion.
-
-Remaining V1 work: authoritative sensor RAW producer, explicit production composition, corrected-view/file wiring, end-to-end production capture→RAW→processed-file acceptance and external Adobe/open RAW editor checks. None is marked complete by this bridge.

package/docs/CAPTURE_EXPORT_METADATA.md

@@ -1,27 +0,0 @@
-# Capture export metadata foundation (#16B)
-
-Release context: **package 1.2.0 candidate / root API 1.2.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_2_0.md).
-
-`createCaptureExportMetadataPair()` is a browser-safe, deterministic **semantic metadata projection**, not an image exporter or proof of RAW/JPEG pixel derivation. Both future writers consume its single shared object; each resource has a distinct caller-owned document UUID and saved-incarnation UUID. `imageDataPairing = "not-verified"` prevents metadata agreement being mistaken for image agreement.
-
-The existing committed capture must already have a non-nil RFC-variant UUID CaptureID. Existing opaque-ID captures remain valid for all earlier APIs, but must be created with a UUID to enter this new export boundary; the exporter does not silently replace their identity. UUIDs normalize to lowercase. All five IDs (capture, two resources, two incarnations) must differ, including after case normalization. The engine neither creates randomness nor proves global uniqueness. Preserve document IDs across reserialization of a resource; give a new saved incarnation its own instance ID. Reuse the capture's ID for the same shutter event. New shutter events require caller-owned new capture IDs.
-
-The input contains `capture`, `workflow`, `capturedAtUtc`, `raw: { documentId, instanceId }`, and `jpeg: { documentId, instanceId }`. The event time is a supplied valid canonical UTC timestamp with three millisecond digits, e.g. `2026-10-01T19:00:00.123Z`. Missing time is rejected: no wall-clock read occurs. The existing scene-clock seconds remain a separate semantic value; file-save/metadata-edit timestamps are not supplied or inferred here.
-
-Only two explicit non-generative workflows are supported:
-
-- `human-directed-non-generative` maps to the IPTC `digitalCreation` concept URI.
-- `fully-procedural-non-generative` maps to `algorithmicMedia`.
-
-Classification is caller-declared workflow metadata, not an independent investigation of upstream media. AI-generated, sampled-source, or composite workflows are outside this first policy and require reviewed expansion; do not silently label them with these choices. No `digitalCapture`, AI-specific fields or physical camera claims are emitted. IPTC is the primary semantic reference: [Digital Source Type vocabulary](https://cv.iptc.org/newscodes/digitalsourcetype/), [digitalCreation](https://cv.iptc.org/newscodes/digitalsourcetype/digitalCreation), [algorithmicMedia](https://cv.iptc.org/newscodes/digitalsourcetype/algorithmicMedia). These are references to concept identifiers, not incorporated third-party implementation or calibration data.
-
-Known exposure settings, finite/infinity focus, active-area diagonal 35-mm focal equivalence, native/oriented/output geometry, scene-state identity/time, noise seed/model, resolved WB intent, and model provenance are projected from the parsed immutable capture. Models retain their existing scientific status and public evidence. No model is inferred to be a sensor/lens calibration profile simply because it appears in this list.
-
-Software/creator-tool identity is `Photivra <captured engine API version>`, with explicit `engineApiVersion`; this is not an npm-distribution-version claim. Make/model are `Photivra` / `Photivra Virtual Camera`. Photivra is not automatically the human creator or rights holder. The result omits source bytes and float planes, private paths/hostnames/GPS/serials, invented lens identity, creator/rights, commercial IDs, RAW-data digests, simulation hashes, format calibration and false physical FileSource/SceneType claims.
-
-Geometry is preserved semantically, not packed into EXIF orientation. DNG native samples versus an already-oriented JPEG require different format-specific orientation handling; writers must not rotate twice. This slice does not serialize timestamps, ISO rational/integer tags, focal equivalence rounding, XMP namespace packets, or EXIF identifier representations.
-
-The result is copied/frozen without freezing caller-owned IDs. Repeated projection of identical capture/workflow/time/IDs is identical. It has no runtime dependencies, external I/O or mutable-clock/randomness dependency.
-
-Historical foundation-only gates (current implementation/evidence and external
-gates are mapped in [Export acceptance](EXPORT_ACCEPTANCE.md)): authoritative same-RAW reconstruction/pairing through #112, stable virtual-sensor DNG interpretation/model identity, canonical reproducibility representation + SHA-256, distinct RAW-data identity/digests, complete Photivra XMP 1.0 mapping, optional DNG/JPEG writers, independently decoded samples/metadata, external editor interoperability, and supported-resolution/memory evidence. C2PA #165 consumes the future complete metadata contract and remains post-V1.

package/docs/CAPTURE_SDR.md

@@ -1,22 +0,0 @@
-# Capture-to-SDR adapter
-
-Release context: **package 1.2.0 candidate / root API 1.2.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_2_0.md).
-
-Current integration: [processed camera output](PROCESSED_OUTPUT.md) documents
-the shared preview/export path and explicit plan 0.6.0 post-RAW activation.
-The historical slice descriptions below retain their original scope.
-
-
-`calculateCaptureSdr()` connects the authoritative SimulatedCapture/color contracts to the existing SDR renderer. Adapter schema is `0.1.0`; root API advances to `0.98.0`. Existing capture/color/SDR schemas, production plan, package and POC versions are unchanged.
-
-Choose `already-transformed` for an exact `linear-srgb-d65` profile/version, RGB channel order and D65 encoding white. Choose `transform` to delegate an explicitly selected XYZ/ideal-camera color and WB operation to `calculateCaptureColorTransform()`. Derived plane/state IDs must be new. No WB estimator runs. Intent-only WB is rejected; an already applied state cannot be transformed again. Applied RGB gains and adopted-white adaptation remain distinct; XYZ diagonal adaptation remains approximation, including the adapter envelope.
-
-Input is an inline co-sited three-channel plane, no more than 262,144 samples. Its raster binding, dimensions, reference-white value and source identity are retained. External/oversized planes fail rather than being loaded, truncated, downsampled or silently tiled. The adapter performs no geometric resampling.
-
-The result exposes optional color and SDR calculation envelopes separately, with original capture saturation, dynamic-range history and noise realization identity. Rendering exposure/tone/gamut clipping cannot rewrite physical capture. SDR's own saturation field remains `not-consumed`; original capture saturation is a separate upstream diagnostic, never an output-code inference. Display adaptation remains external/unknown.
-
-This is #112B, not full #112 closure. It does not execute correction profiles or activate production stages. Corrected planes may retain their explicit upstream transform history; no correction is inferred. #117/#118 execution and #111 ordered production integration require their own bound handoff. #16 remains the serializer owner and must not invent color/WB/quantization semantics.
-
-Implementation and fixtures are independently authored orchestration of existing Photivra APIs; no new equation, calibration, third-party material, dependency, service, IO or cost is introduced.
-
-For external megapixel masters already in resolved linear sRGB/D65, see the separate [bounded native SDR contract](NATIVE_CAPTURE_SDR.md). The reference limits above remain unchanged.

package/docs/DENSE_PUPIL_QUALIFICATION.md

@@ -1,121 +0,0 @@
-# Dense-pupil qualification — issue #224
-
-## Decision at this checkpoint
-
-The merged repository-only separable-emission prototype is **not qualified for
-public promotion or the complete native Focus event**. This checkpoint adds
-independent arithmetic oracles and reproducible complete-small-event resource
-measurements. It does not close #224, qualify downstream scenes/devices, change
-any resource ceiling, or export an experimental function from the package.
-
-The 4-billion spectral-composition ceiling in #225 remains a draft proposal.
-Preserving the old arbitrary-provider ceiling while introducing a larger scalar
-work ceiling does not meet #224's no-raised-safety-ceiling requirement by itself.
-The prototype also has no demonstrated full-native refinement envelope.
-
-## Work and allocation boundaries
-
-For the declared no-PSF source, the original logical support is
-`native sites × spatial nodes × temporal nodes × pupil rays × spectral nodes`.
-An explicit uniform spectrum and achromatic geometry permit wavelength reuse
-only for an identical origin/direction/time request. The geometry upper bound
-removes the spectral factor; scalar spectral compositions remain unchanged.
-No cross-site, cross-time or cross-event reuse is authorized by that declaration.
-
-| Complete event support | Geometry calls (upper bound) | Scalar spectral compositions |
-| --- | ---: | ---: |
-| 2048×1366, 4 spatial, 1 temporal, 128 pupil, 2 spectral | 1,432,354,816 | 2,864,709,632 |
-| Same support, 256 pupil | 2,864,709,632 | 5,729,419,264 |
-| Same 128-pupil support, 2 temporal | 2,864,709,632 | 5,729,419,264 |
-
-The base event is below 2 billion geometry calls but above 2 billion spectral
-compositions. Either listed refinement is above both prototype ceilings.
-Refinement events retain their own complete support and cannot be divided to
-bypass admission. Actual downstream convergence may require other refinements;
-these counts do not establish which refinement is scientifically sufficient.
-
-The native output commits seven bytes per site: three uint16 planes and one
-uint8 flag plane, or 19,582,976 bytes at 2048×1366. This excludes source profiles,
-plans, query/result objects, per-site cache and all runtime overhead. Plans are
-bounded by 100,000 logical evaluations per tile; geometric caches by the
-single-site support. Object-count bounds are not byte/memory guarantees.
-
-## Independent checks
-
-`test/separable-emission-qualification.test.ts` derives expected photon and
-electron counts directly from SI h/c, paraxial `pi/(4*N²)` acceptance, explicit
-geometric area, two specified wavelength midpoints, independently evaluated
-transmission/QE curves, and the exact integral of a linear time ramp. It uses no
-engine reducer or plan to generate the expected answer. It checks 32/64/128 pupil
-rays and two/four time nodes for a uniform source and a symmetric origin-dependent
-half-pupil edge. This checks normalized weights and response/optical/time ordering
-in those constructed cases, not arbitrary 3D depth/occlusion or convergence.
-
-The existing native regressions reuse a shared owned fixture and retain their
-original global/native-scan photon and every-code RAW parity, absolute site
-identities/seed scheduling, tile/event admission, callback failure, ownership and
-cancellation assertions. Legacy parity is an additional implementation comparison,
-not an independent oracle for all RAW physics.
-
-## Measured pilot
-
-Run from the repository root after `npm ci`:
-
-```sh
-node --expose-gc scripts/qualify-separable-emission.mjs
-```
-
-The script compiles source and owned test helpers into a temporary directory,
-copies required owned fixtures, executes complete 2×2 events at 32/64/128 pupil
-rays for both global and right-to-left native-scan shutters, compares every RAW
-code to the reference and records canonical little-endian code hashes. It removes
-temporary compilation files on completion/failure. No new dependency is added.
-
-Recorded results: [pilot.jsonl](validation/dense-pupil-2026-10-06/pilot.jsonl).
-The evidence identifies base revision and modified source content hashes; it was
-measured on Linux x64 / Node 24.19.0. Each event uses four spatial nodes, two
-spectral nodes, two temporal nodes and one-site chunks. All four tiles complete,
-produce 28 output bytes and yield four times. At 128 pupil rays the events execute
-4,096 geometry calls and 8,192 spectral compositions each.
-
-| Pupil rays | Shutter | Complete 2×2 time (ms) | Longest tile interval (ms) | Sampled process RSS peak (MiB) |
-| --- | --- | ---: | ---: | ---: |
-| 32 | global | 159.23 | 45.08 | 132.0 |
-| 32 | native scan | 189.34 | 53.55 | 172.4 |
-| 64 | global | 257.49 | 70.51 | 219.2 |
-| 64 | native scan | 359.62 | 112.23 | 234.2 |
-| 128 | global | 527.75 | 143.34 | 267.1 |
-| 128 | native scan | 561.69 | 180.42 | 299.0 |
-
-RSS is the entire process, including retained reference results, compiled helper
-execution and heap/allocator history. Sampling can miss transient peaks; these
-numbers are neither allocation guarantees nor mobile/browser/device evidence.
-One-site chunks do not ensure a responsive host when synchronous planning and
-callbacks take this long. No maximum host latency was previously approved here.
-
-Scaling the 128-ray pilots by site count and halving temporal support projects
-51.3–54.6 hours at 2048×1366. **This is an extrapolation, not a measured native
-runtime or admission guarantee.** Different geometry, allocation, GC, profiles
-and device behavior can change it. No complete native event was executed or
-independently decoded in this checkpoint. No depth/refinement/source qualification
-is established by the matching small-event code hashes.
-
-## Remaining work and decision needed
-
-1. Develop and independently qualify an exact reduction of scalar optical/spectral
-   work under explicit supported linearity and source assumptions, preserving all
-   committed quadrature measures and operating-range gates. Merely renaming counts
-   or increasing the scalar-work ceiling is insufficient.
-2. Measure planning/execution/allocation and cancellation/host responsiveness for
-   that implementation. Preserve truthful attempted-work counts and fail-closed
-   output. Do not infer mobile usability from this contributor host.
-3. Demonstrate complete native events with independent photon, packed RAW,
-   origin-aware depth/occlusion and refinement evidence within unchanged limits.
-4. Separately review a browser-safe public contract and version/API documentation,
-   compatibility, package surface and full checks before downstream adoption.
-5. Complete substantive human scientific/source review and contribution-specific
-   DCO. AI-assisted tests and measurements do not satisfy human review.
-
-Until those steps pass, the experimental route stays under `src/api/`, outside
-npm/root exports; #224 and downstream Focus/Depth remain blocked for production.
-UI implementation and authenticated staging can continue independently.

package/docs/DEVELOPERS.md

@@ -1,68 +0,0 @@
-# Developer guide
-
-This is the entry point for **@photivra/engine 1.3.0 candidate**, root API contract **1.3.0**. The candidate becomes an installable 1.3.0 distribution only after the owner tags and publishes it. Repository `main` may later describe newer development; use a published release's packaged docs or its exact tag for the stable contract. [Release notes and migration](RELEASE_1_3_0.md) explain the transition to aligned package/root versions.
-
-Photivra is an Apache-2.0 ESM TypeScript calculation library with no runtime npm dependencies. It exposes explicit units, deterministic data, provenance and bounded scientific approximations. The package supplies no hosted API, renderer installation, UI, commercial camera calibration or automatic agent service. [Photivra's public site](https://photivra.com) is separate from the engine's license; public engine documentation is available here without an application account.
-
-## Install and calculate
-
-After publication, install `npm install @photivra/engine@1.3.0`. During candidate review, use the verified tarball described in [release preparation](RELEASE_1_3_0.md).
-
-```ts
-import { calculateFieldOfView, ENGINE_API_VERSION } from "@photivra/engine";
-
-const horizontal = calculateFieldOfView({ focalLengthMm: 50, sensorDimensionMm: 36 });
-console.log(ENGINE_API_VERSION); // 1.3.0: matches the package version
-console.log(horizontal.value.degrees); // approximately 39.60, ideal infinity-focus geometry
-console.log(horizontal.provenance); // read assumptions/status with the value
-```
-
-The root is browser-safe. Supported Node execution/tooling is Node 22.13+ within the maintained 22 line, the maintained 24 line, and Node 26 Current; prefer patched Node 24. The broad manifest minimum does not qualify untested or EOL lines. A browser backend must supply the documented ES APIs (including `structuredClone`, typed arrays and Web Crypto where used); a browser-safe import graph is not a promise about every browser version or rendering speed. See [runtime policy](../NODE_SUPPORT.md).
-
-Primitive calculations normally return `CalculationResult<T>` with `value`, `provenance` and optional `quality`. Parsers return validated values; plans/snapshots return their independently versioned records; assessments return explicit blockers; paired export returns a Promise because hashing is asynchronous. Do not infer calibrated accuracy from successful parsing, a complete stage graph, a generic tier name or deterministic replay.
-
-## Find the operation by scientific task
-
-Every row applies to package/root API 1.3.0. Direct calculations are synchronous/browser-safe unless the row says otherwise. A listed primitive is not automatically an app feature or supported in every production combination. The [API reference](API_REFERENCE.md) resolves all root exports and exact signatures; the linked guides own equations, inputs, defaults, errors and limits.
-
-| Task | Start here / executable evidence | Qualified boundary |
-| --- | --- | --- |
-| FOV, focus, depth of field, subject size | [Usage: field of view](USAGE.md#field-of-view), [physics](PHYSICS_FOUNDATION.md), [quick start](examples/quick-start.mjs) | Ideal paraxial/thin-lens geometry; explicit mm/metres/axes |
-| Aperture, diffraction, sampled PSF | [PSF foundation](PSF_FOUNDATION.md), [usage](USAGE.md#real-lens-psf-profiles-and-complex-pupil-reference) | Shape and throughput separate; explicit support; no inferred commercial calibration |
-| Metering and exposure modes | [Usage: relative metering](USAGE.md#relative-pre-exposure-metering), [API conventions](API_STYLE.md) | Relative pre-exposure linear signal; compensated target before control; ISO does not create photons |
-| Rigid/depth motion and stabilization | [Motion](MOTION_AND_SIGNAL.md), [stabilization](STABILIZATION.md) | Declared constant-motion/generic control models; visibility remains external |
-| Continuous or discrete spectral measures | [Scene/illumination](SCENE_RADIANCE_AND_ILLUMINATION.md) | Continuous dλ in nm versus wavelength-integrated line fractions; `distribute*` preserves quantity domain |
-| Sampling, response validity, photon/electron expectations | [Usage](USAGE.md#sensor-spectral-response), [temporal EQE](SENSOR_EQE_TEMPORAL_EXPOSURE.md) | Exact source-plane/area/profile/wavelength/time bindings; no implicit QE/collection area |
-| Execute declared environment → production RAW → output | [Production envelope](PRODUCTION_ENVIRONMENT_CAPTURE.md), [complete packed example](examples/production-capture.mjs) | Node example loads owned data; engine callback is synchronous; 4,096 native sites / 100,000 provider evaluations |
-| Preserve/reconstruct RAW and develop preview | [RAW envelope](RAW_FRAME_ENVELOPE.md), [processed output](PROCESSED_OUTPUT.md) | Signed shadows, absolute CFA phase, explicit sensor-channel color/WB; rendering does not redraw noise |
-| Pair native CFA DNG with processed JPEG | [Photographic export](PHOTOGRAPHIC_EXPORT.md), [acceptance](EXPORT_ACCEPTANCE.md) | Async Web Crypto; registered Bayer reference; 1:1 output crop; caller saves bytes |
-| Commit capture, ideal virtual-camera color, linear encoding | [Capture](SIMULATED_CAPTURE.md), [ideal color](CAPTURE_COLOR.md), [encoding](LINEAR_CAPTURE_ENCODING.md) | Ideal XYZ encoding differs from approximate sensor-channel development |
-| Generic tiers and correction cost | [Presets](GENERIC_TIER_PRESETS.md), [tier acceptance](TIER_ACCEPTANCE.md), [correction](DIGITAL_OPTICS_FOUNDATION.md) | Versioned owned synthetic assets; no universal quality ranking |
-| Reproduce conformance/performance | [Scientific suite](SCIENTIFIC_CONFORMANCE.md), [performance disposition](V1_PERFORMANCE_DISPOSITION.md) | CI science gates; Node measurements do not establish browser or megapixel performance |
-| Optional local HTTP development transport | [Repository POC](POC_API.md) | Node-only checkout tooling, excluded from root/package; unauthenticated loopback |
-
-## Complete packed examples
-
-The package includes `docs/examples/quick-start.mjs` and `production-capture.mjs`. In a Node ESM consumer directory with the candidate installed, copy these files and `production-request.json` from `node_modules/@photivra/engine/docs/examples/` into that directory and run them. The quick start asserts independent geometry/exposure invariants. The production example executes the same owned 2×2 narrow-band synthetic fixture used in final conformance through all fourteen production stages and paired byte export, retaining the exact RAW codes and deterministic replay. It writes no files and installs no renderer.
-
-The JSON data is explicitly synthetic: uniform angular radiance `1e-9 * (1 + 200t)` W/m²/sr/nm; 540–560 nm band; independently declared 800×600 µm sensitive aperture and package-incident EQE 0.4; registered opening-reference time; fixed seed and generic consumer profiles. This is a controlled regression laboratory, not a real scene, native camera pixel pitch, calibrated color/visibility, PSF transport proof or convergence bound. Production supports only the envelope linked above. The tiny DNG demonstrates byte serialization/lineage; external-reader acceptance uses separate larger fixtures.
-
-The [Usage Guide](USAGE.md) includes both complete snippets and clearly marked composition fragments that require earlier validated bindings. The release checker typechecks and executes complete importing snippets against the packed artifact; it inventories fragment dependencies without pretending missing calibration data exists.
-
-## Contracts and support
-
-Use only `import ... from "@photivra/engine"`. Deep paths and repository transport/scripts/test helpers are unsupported. TypeScript declarations describe shape; parse untrusted JSON before scientific execution. Keep native +Y-down, optical +Y-up and half-open raster rectangles explicit. Preserve domain distinctions between radiance, irradiance, rates, expected counts, realized charge, RAW codes and processed SDR.
-
-Malformed configurations/non-finite values throw the established domain errors. Scientifically incomplete but well-formed assessments/plans expose structured blockers. Trusted provider callback exceptions propagate; no silent fallback renderer runs. The exact return contract and independent model versions are visible in the reference and declarations.
-
-See [provenance](PROVENANCE.md), [license](../LICENSE), [NOTICE](../NOTICE), [third-party inventory](../THIRD_PARTY.md), [contributing](../CONTRIBUTING.md) and [security reporting](../SECURITY.md). Engine code/docs do not license the commercial application or its private assets. Report reproducible engine defects through [public issues](https://github.com/Photivra/photivra/issues).
-
-Website navigation/documentation hosting belongs to [the app-side discovery ticket #45](https://github.com/Photivra/photivra-apps/issues/45), with navigation #298 and environments #300. Handoff: link the public engine repository, this developer guide, the verified npm release package and capability examples from the public site. No unpublished `/developers` destination is linked here. Website launch is not an engine release prerequisite; access to the site returned HTTP 403 during this audit, so its content/navigation was not verified.
-
-## Print planning
-
-The published 1.2.0 release added [registered linear statistics](PRINT_REGION_STATISTICS.md) and a separate [static contrast model reference](PRINT_CONTRAST_REFERENCE.md). The [combined #195/#196 review](PRINT_195_196_REVIEW.md) and [candidate ledger](validation/print-196-candidate-capabilities.json) list executed public-backend experiments and the remaining full release gates. None of these diagnostics supplies a universal quality score.
-
-Use [native-only Print planning](PRINT_PLANNING.md) for independently specified image size/viewing distance, explicit angular conventions, confirmed native crop and lab constraints. It returns no upscale recommendation and does not certify perceived quality or activate an exporter.
-
-The [regional Print detail diagnostic](PRINT_DETAIL_ASSESSMENT.md) measures one declared coherent sinusoidal fundamental in a selected linear-luminance ROI and records its exact source stage. Its [validation protocol](PRINT_DETAIL_VALIDATION.md) and [capability ledger](validation/print-detail-capabilities.json) distinguish mathematical conformance from blocked acquired-image, renderer and perceived-quality qualification.

package/docs/DIGITAL_OPTICS_FOUNDATION.md

@@ -1,69 +0,0 @@
-# Stray light and digital lens correction foundations
-
-Release context: **package 1.2.0 candidate / root API 1.2.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_2_0.md).
-
-Issues #114, #118 and #117 add standalone browser-safe primitives. They do not enable a production-plan stage, change the POC, or supply a calibrated camera/lens preset. The public root API advances from 0.94.0 to 0.95.0; each new profile/prepared-map schema is 0.1.0. Package, POC, production-plan and PSF versions are unchanged. This branch incorporates merged polygon-diffraction PR #157 and reconciles the root API increment with that predecessor.
-
-## Applicability and evidence
-
-Stray-light and correction profiles bind an exact generic body/lens identity/version, focal length, aperture, finite focus distance, still/video mode, output dimensions, frame rate and stabilization mode. A mismatch fails; no interpolation or extrapolation is inferred. Still frameRateHz is zero; video is positive. Infinity focus, interpolated zoom/focus states and temporal crop trajectories require future schemas.
-
-Only generic-parametric evidence is accepted. Its source records use the existing EvidenceProvenance parser, and its basis and residualNote must be explicit. Parameters can be independently authored synthetic approximations; source metadata does not establish measured accuracy. Calibrated profiles and invented quantified uncertainty are not accepted by these first parsers. No tier or manufacturer identity determines coefficients.
-
-## Additive stray-light irradiance
-
-calculateLensStrayLightIrradiance() evaluates one instant, image-plane point and exact air/vacuum wavelength slice. Source field angles use +X right, +Y up, in degrees; the declared domain is the Euclidean norm of these two field-angle coordinates, not a spherical great-circle angle. The image plane uses millimetres about the optical axis. Off-frame sources remain inputs even when their primary images lie outside the active crop.
-
-Each source provides incident spectral power in W/nm integrated over the profile's declared reference entrance area. The caller must derive this power from source illumination and that area; it is neither pixel brightness nor W/m². admittedFraction is an explicit per-source/path admission result. A future physical hood/flag solver may provide it, but a global hood slider is not inferred.
-
-Ghost and veil responses have separate identities and outputs. Both use independently parameterized, infinite-plane normalized Gaussian templates. Centroids are explicit affine responses to source field angles; sigma is in mm. A response's power fraction is F(0) × (1 + angularSlope × rho²), with rho equal to source coordinate norm divided by the declared maximum. Nonnegative fractions and total response fractions at both angular endpoints are validated. Since their sum is affine in rho², this bounds the whole envelope. This bounds stray paths only; the caller must budget primary transmission and stray power together when asserting whole-system energy conservation.
-
-The normalized template density is exp(−distance²/(2 sigma²))/(2π sigma²), in 1/mm². Multiplying by 10⁶ converts to 1/m². Source power times admitted fraction times response fraction times this density gives W/m²/nm. A finite frame never renormalizes it. This does not trace lens surfaces or infer a branded ghost signature.
-
-The returned totalSpectralIrradianceWPerM2PerNm is primary plus ghost plus veil, ready for the same downstream spectral/spatial/exposure integration as other incident light. Saturation and sensor noise occur after addition. The integration test uses the existing photon-energy, photoelectron and Poisson/read-noise primitives with declared exposure/area/QE; it does not establish radiometry-readiness for a real device. meterDomain explicitly selects primary-only or primary-plus-stray.
-
-Disabled evaluation preserves the primary irradiance exactly. Profiles remain validated even when disabled. Diffraction, primary PSFs and contamination are excluded. A sensor-lens-reflections declaration binds the combined body/lens state explicitly. One static instant does not approximate an exposure average: callers must evaluate time and wavelength quadrature separately. No display/cosmetic flare mode is supplied.
-
-## One mapping and honest sampling
-
-prepareGeometricMapping() stores canonical transforms, a deterministic semantic key and contiguous image-domain groups. It clones parsed transform data. The returned record is serializable and is revalidated/reprepared on consumption, so callers cannot bypass validation by mutating a cache record.
-
-Transforms are listed in destination-to-source order. Affine maps represent breathing, rotation, crop and digital stabilization with a full matrix and offset. Radial maps reuse the existing monotonic radial-distortion evaluator; for correction the destination ideal coordinate maps to physical distorted source data. A declared correction polynomial is independent from a physical optical polynomial and can intentionally leave residual distortion. No implicit correction strength or ideal-lens inversion is assumed.
-
-Raw-channel, reconstructed-linear and processed-output domains are barriers. Compatible contiguous transforms can share a resampling pass; incompatible groups are retained by the prepared mapping but a fused pixel pass rejects them. Prepared maps are frame/time specific in seconds from exposure start; no trajectory averaging or full-video crop guarantee is implied.
-
-calculateComposedGeometricMapping() emits each component's local Jacobian and the full product d(source mm)/d(destination mm), determinant, singular values and anisotropy. calculateForwardGeometricMapping() reverses the same authoritative mapping for focus, meter and overlay coordinates. No app should independently reverse-engineer the warp.
-
-GeometricRaster describes square-pitch pixel centers on an optical plane: +X right, +Y up, row order down. Raster orientation/crop is an explicit affine transform rather than an implicit axis swap. The maximum raster is 65,536 samples, maximum composed transform count 32. This is a bounded foundation, not a megapixel production renderer.
-
-calculateGeometricSamplingPlan() builds exact support at every destination pixel center for the declared nearest/bilinear filter. It preserves a mask and finds the largest all-valid axis-aligned pixel rectangle using one composed map, with deterministic row/stack tie-breaking. Opposing transforms therefore do not spend the crop margin twice. These claims concern this sampling lattice/filter; the mask does not certify continuous between-pixel support. Each component's intermediate source point and derivative remain available for feature-specific margin inspection; intermediate points are not separately cropped.
-
-The plan reports physical captured edge FOV from the declared physical projection distance and source bounds. It separately reports the angular envelope of retained mapped pixel-center rays. That envelope is deliberately not a continuous retained edge FOV. Off-center capture is preserved.
-
-Singular values multiplied by destination/source pixel pitch diagnose local sampling compression. Any value above one requires declared source-prefiltered data. With antialias=none the plan remains inspectable but cannot execute a compressing resample. The caller owns the prefilter and must provide data appropriate to the maximum footprint; this module does not implement or certify that prefilter. The filter/profile ID remains separate from mapping identity.
-
-calculateGeometricResampling() performs one nearest or bilinear scalar pass, emits null for invalid support, and never extends/clones/mirrors edges. Exact boundary centers do not require nonexistent bilinear neighbors. It warps already-formed blur/bokeh and noise. Stretching cannot create optical detail or recalculate a better PSF. The full Jacobian explains local transformed blur and sampling density.
-
-## Generic camera correction profiles
-
-resolveLensCorrectionPlan() resolves each component independently in profile application order. It records toggled/default, mandatory, stabilization-required and component-dependency reasons. Dependencies refer only to earlier components, preventing cycles. Required components may override a dependent component's requested Off with an explicit component-dependency reason. Mandatory camera corrections cannot be turned Off through a camera setting; reference-bypass is a separately labeled educational comparison.
-
-Each component declares its image domain, identity/version, residual limits, availability and dependencies. Supported families are geometry, lateral channel registration and scalar peripheral illumination. Color shading, longitudinal CA and diffraction/deconvolution restoration are distinct unsupported families. RAW-like output preserves metadata/intent without baking; processed output bakes supported downstream operations.
-
-calculatePeripheralIlluminationCorrection() uses the existing positive bounded illumination profile and gain = throughput^(−strength), with strength in [0,1]. Its signal and variance gains are g and g²; variance is explicitly pre-clip. This does not restore photons or authoritative capture SNR. Clipping is reported. Residual gain strength does not change physical lens throughput.
-
-calculateLensCorrectedCapture() is a bounded reconstructed-linear RGB executor. The capture carries its camera/lens/acquisition state and must match the profile binding. Capture ID, time and noise realization ID are retained; physical source arrays are not mutated. Common geometry and per-channel lateral CA are composed in inverse application order and sampled once per channel. All channel masks intersect before output, so a missing channel never fabricates a valid color. A joint crop is resolved over that intersection, with per-channel sampling/crop diagnostics also inspectable.
-
-The executor supports geometry/CA followed by gain. It rejects geometry across an intervening gain, or raw/processed domains, instead of silently reordering stages. Other consumers must honor the resolved profile order through production #111/#112. Gain is defined on corrected output coordinates in this executor; it does not silently reuse an upstream physical field position. RAW-like metadata-only output preserves original capture geometry and samples. For processed output, Off/reference-bypass disables correction transforms and gains, while an explicit destination crop or sampling lattice still applies through the neutral geometric map. An identical source/destination lattice preserves samples without resampling; changed lattices expose filter/support/crop and prefilter diagnostics as usual. Output dimensions must match the exact profile binding. This revises the unmerged draft's earlier unconditional Off passthrough; no released API is changed.
-
-## Verification and provenance
-
-Tests independently check Gaussian power integration, source linearity/admission, off-frame response, sensor/noise primitive consumption, exact applicability, Jacobian centered differences, inverse/forward round trips, all quarter-turn orientations and off-center capture, anisotropy, linear-ramp interpolation, missing support, joint crop, prefilter gating, channel registration, RAW intent, mandatory/bypass/dependency resolution, residual gain/noise/clipping and already-blurred image stretch.
-
-Implementation/test parameters and equations were independently authored. No third-party source code, calibration data, numerical tables or protected prose was incorporated. Factual research:
-
-- [ZEISS, Taking care of the unwanted light](https://lenspire.zeiss.com/cine/en/article/taking-care-of-the-unwanted-light): reflection ghosts and unwanted light motivate separate stray-path ownership.
-- [Canon EOS R5 Mark II manual, Lens Aberration Correction](https://cam.start.canon/en/C017/manual/html/UG-03_Shooting-1_0220.html): peripheral correction noise and distortion crop/resolution limitations motivate downstream cost reporting.
-- [Sony ILCE-1M2 guide, Lens Compensation](https://helpguide.sony.net/ilc/2440/v1/en/contents/0414M_lens_comp.html): component controls, forced distortion and breathing angle/quality limitations motivate resolved states and explicit costs.
-
-These references justify scope and distinctions, not the synthetic coefficients. AI-assisted drafts still require substantive human scientific/provenance review and contributor DCO certification under CONTRIBUTING.md and PROVENANCE.md before inclusion.

package/docs/ENVIRONMENT_RAW_CAPTURE.md

@@ -1,208 +0,0 @@
-# Executed environment capture to native RAW
-
-Standalone follow-up: [ideal pupil rays](SENSOR_APERTURE_RAYS.md) adds an explicitly selected origin-aware evaluator. It preserves the bounds below and does not activate production depth/visibility composition.
-
-Release context: **package 1.2.0 candidate / root API 1.2.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_2_0.md).
-
-`calculateEnvironmentSensorPhotoSignal()` executes one destination site's
-bounded environment exposure. `simulateEnvironmentSensorRawFrame()` applies that
-path to a complete reference native frame and hands its photo/dark expectations
-to the existing charge, capacity, seeded noise and ADC producer. Its resulting
-RAW frame can be reconstructed and exported with the existing paired DNG/JPEG
-API. These are additive execution APIs; they do not activate the general
-production-plan capability registry or implement surface rendering.
-
-## Execution and ownership
-
-The caller supplies a synchronous `evaluateRadiance(request)` function that
-returns `SceneRadianceEvaluationResult`. The engine generates each request,
-invokes that function and validates the result. Invocation is established;
-physical correctness of the provider's transport is not. The engine performs no
-file/network access and installs no renderer or new runtime dependency.
-
-For every local shutter midpoint, spectral midpoint and pre-AA/aperture support:
-
-1. Resolve the optional sampled lens PSF at the destination/wavelength.
-2. Enumerate its complete inverse support, including zero-weight taps, or use
-   the destination point when PSF is explicitly omitted.
-3. Convert native +Y-down to image-plane +Y-up and reuse focus-aware ideal
-   projection plus analytic inverse camera rotation to derive each environment
-   look direction. Request propagation toward camera is its negative.
-4. Invoke the provider separately at each source point, wavelength and time.
-   Validate identity, units, basis, evidence and scene/profile bindings.
-5. Apply the existing paraxial radiance-to-irradiance bridge at that source point.
-   Optional normalized PSF shape redistributes those physical irradiances once.
-6. Apply sensor response applicability/range and EQE separately at each instant,
-   then integrate with seconds-valued uniform midpoint measures.
-7. Commit a temporal photo signal. Full-frame execution computes dark charge
-   for the exact same event and reuses the existing completeness, capacity,
-   Poisson, signed read-noise and ADC contracts.
-
-The destination site's channel owns every source tap; source coordinates do not
-reassign CFA phase. No crop clipping, missing-support renormalization, averaging
-of scene light before response validation, duplicated area, exposure duration or
-throughput is introduced. Source points outside active capture remain valid if
-the declared optical/provider envelope covers them.
-
-## Declared operating envelope
-
-- Environment-only scene targets; no surface intersection or occlusion solver.
-- Ideal rectilinear, focus-aware projection and constant-axis pure rotation in
-  exposure-start camera axes. The existing forward-reference-hemisphere limit
-  remains. Translation/parallax, world pose, breathing and distortion are absent.
-- Wavelength-resolved radiance with explicit air/vacuum basis. Any air photon
-  energy context remains the existing sensor contract's responsibility.
-- Explicit `unity` or `radial-illumination-vignetting` field throughput with evidence
-  and a limitation. The latter reuses the existing bounded radial profile and applies
-  attenuation once at every physical inverse-PSF source point, before normalized
-  PSF redistribution. Camera motion changes scene direction, not lens field position.
-  All taps, including zero-weight taps, must lie in the declared profile envelope
-  before any provider callback. Existing lens transmission/front-filter inputs remain
-  upstream of normalized PSF shape. This is an owned approximation, not calibrated
-  lens throughput or pupil vignetting. Production composition requires the explicit
-  `illumination-vignetting` fidelity effect, including a modeled-zero profile.
-- PSF is explicitly `not-applied` with evidence/limitation or `sampled-local`
-  with the existing evidence-backed wavelength basis and local spatial model.
-  Focal length, aperture and focus must match the optical bridge. The optional
-  PSF remains a destination-local shift-invariance approximation. Its separate
-  relative pupil throughput is reported by child diagnostics and remains
-  unapplied; no global energy-conservation proof is claimed.
-- One-to-one native/color-site timing registration and 1..256 local midpoints.
-  No temporal stationarity declaration is inferred.
-- At most 100,000 provider evaluations per site and per full frame, counted
-  before callbacks. The reference RAW producer's 4,096 native-site ceiling also
-  remains. This path does not claim 24/45/60 MP support.
-
-## Frame commitment
-
-`simulateEnvironmentSensorRawFrame()` requires full native row-major site order,
-including sites outside an active/output crop. Each site's aperture geometry,
-color profile, binding profile and complete shutter declaration must match the
-committed frame. Physical focal length, aperture and focus must match too.
-Scene/provider declarations, optical/filter state, motion, PSF selection and
-field-throughput declarations must be shared across sites; a single frame cannot
-silently combine different camera/scene models.
-Evidence/profile comparisons use canonical field ordering; object property
-insertion order does not change a binding.
-
-`sceneBinding` explicitly relates the capture's `sceneStateId` to the provider's
-`sceneId` with evidence. This first adapter supports committed `sceneTimeSeconds`
-zero at the first opening boundary. It cannot silently add an arbitrary scene
-clock offset. Every site's `temporalIntegrationId` must be distinct; generated
-request IDs append temporal/node/tap identity and pass the public-ID parser.
-
-The shared exposure schedule owns each site's actual start/end and duration.
-Rolling openings/closings are not replaced by global midpoints or readout time.
-Completeness and any additional charge declarations must already cover that exact
-event; the composer does not rewrite them to make a mismatched declaration pass.
-Readout regime and ISO remain separately declared through the existing producer.
-
-## Provider contract and failure
-
-Requests are owned, recursively frozen plain data. Their nested target cannot be
-mutated to change geometry or identity. Caller input data is snapshotted before
-execution; provider results are parsed into owned values immediately. The same
-provider and seed produce the same output only if supplied provider code is
-itself deterministic. The engine does not certify caller code determinism.
-
-Promises, malformed results, stale IDs, negative radiance, incompatible basis,
-provider exceptions and mutation attempts reject. No partial successful result
-or RAW frame is returned. This is not a transaction over arbitrary callback side
-effects: callbacks already invoked cannot be undone. Use pure local evaluators;
-no remote calls, persistence or external side effects are provided by this API.
-
-Geometric coverage, PSF evidence and aggregate work are preflighted before any
-callback. Provider result, optical validity, response range and downstream
-charge/readout validity are checked during execution. A late validation failure
-can therefore follow earlier provider calls. The API does not claim that every
-possible invalid input is rejected before supplied code runs.
-
-Temporal illumination profile bindings are preserved when declared by the
-provider. They describe source behavior; invocation and parsing do not establish
-that supplied code obeys its own transport/source declaration.
-
-## Paired export handoff
-
-Use the actual produced frame as the reconstruction input. This complete helper
-keeps reconstruction configuration explicit and feeds both outputs from the
-same realized native RAW codes:
-
-```ts
-import {
-  simulateEnvironmentSensorRawFrame,
-  createPhotographicExportPair,
-  type SimulateEnvironmentSensorRawFrameInput,
-  type PhotographicExportInput,
-  type PhotographicExportPair
-} from "@photivra/engine";
-
-type OutputConfiguration = Omit<PhotographicExportInput, "reconstruction"> & {
-  reconstruction: Omit<PhotographicExportInput["reconstruction"], "rawFrame">;
-};
-
-export async function captureEnvironmentPair(
-  input: SimulateEnvironmentSensorRawFrameInput,
-  output: OutputConfiguration
-): Promise<PhotographicExportPair> {
-  const capture = simulateEnvironmentSensorRawFrame(input);
-  return createPhotographicExportPair({
-    ...output,
-    reconstruction: {
-      ...output.reconstruction,
-      rawFrame: capture.value.raw.value.frame
-    }
-  });
-}
-```
-
-Color development, WB, correction, rendering, output crop/orientation, metadata
-and file encoding retain their existing explicit ownership. The RAW path does
-not bake JPEG processing into sensor codes. The export's independent-reader/editor
-acceptance remains unchanged.
-
-## Evidence and verification
-
-The tests use owned synthetic profiles and an explicitly declared illumination
-ramp, not licensed commercial calibration or measured scene data. Independent SI
-expectations check the optical factor, wavelength measures, geometric area,
-photon energy, EQE and temporal integral. Angular gradients exercise distinct
-rotated PSF rays and asymmetric kernel weighting. Global and rolling frame tests
-exercise optional PSF through dark/noise/ADC and deterministic paired export;
-decoded DNG strips equal the exact realized native codes.
-
-Malformed preflight, aggregate budgets, stale provider returns, callback mutation,
-Promise returns, provider errors and frame commitment drift fail closed. Existing
-PSF regressions continue using the same fixture and shared inverse-support rule.
-
-Results distinguish `providerCallbackExecuted` from `providerTransportVerified`.
-Legacy child origin flags remain conservative because their older contracts do
-not carry the new execution evidence. No calibrated accuracy, combined
-uncertainty, quadrature/support convergence, general visibility, production-plan
-activation or full-resolution/editor readiness is inferred.
-
-Root engine API **0.114.0**, new model envelopes **0.1.0**. npm/POC/schema versions
-remain independent. This is partial #16/#178 integration coordinated with #112;
-V1 remains **25/32**. #131 final science conformance and #180 documentation/1.0
-preparation remain separate closure work.
-
-## Authoritative production consumer
-
-Plan 0.7.0 can now invoke this existing adapter through an explicitly committed
-`environmentCapture` declaration. See [production environment capture](PRODUCTION_ENVIRONMENT_CAPTURE.md).
-The standalone adapter retains its conservative `productionPlanActivated: false`
-field: it cannot know whether a parent composer called it. The parent plan's
-actual stage results and executed lineage establish the bounded activation;
-no child source-truth flag is overwritten.
-
-## Additive field-throughput candidate
-
-Photo integration model 0.2.0 adds radial field-throughput input; unity arithmetic,
-provider/RAW resource limits and conservative verification flags remain unchanged.
-`test/environment-field-throughput.test.ts` independently integrates SI photon counts
-with radial attenuation, checks source-tap PSF weighting, exact unity-profile parity,
-physical field invariance under motion, profile ownership, full-frame preflight and
-replayable paired RAW/JPEG output. The production planner reports requested field
-attenuation as active or modeled-zero and blocks undeclared attenuation before callbacks.
-This candidate has not been tagged or published; the distribution version stays 1.2.0
-until the next release preparation. External chart/backend evidence belongs to its
-provider and does not become an engine calibration claim.