@photivra/engine 0.5.1 → 1.0.0

package/docs/CAPTURE_COLOR.md

@@ -0,0 +1,25 @@
+# Virtual-camera linear color: #15B
+
+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).
+
+`resolveCaptureColorModel()` defines an ideal CIE 1931 2-degree colorimetric camera: co-sited red/green/blue channels are an invertible encoding of XYZ in the linear-sRGB primary basis, with D65 reference white. They are relative linear values, not electrons, spectral response measurements or commercial-camera RGB. Choosing this profile is an upstream producer assertion about sample meaning; naming arbitrary sensor data with its ID does not establish validity.
+
+The primary chromaticities are red (0.64,0.33), green (0.30,0.60), blue (0.15,0.06), and D65 (0.3127,0.3290). Matrices are independently derived: form each primary column `(x/y,1,(1-x-y)/y)`, solve its scale against normalized D65 XYZ, scale columns, then invert the resulting 3x3 matrix. Model `0.1.0` exposes both row-major matrices, observer, reference illuminant/white, evidence identity and valid conditions. No transfer curve, gamut mapping or nominal [0,1] clamp is applied. Mathematical conversion is calculated, not calibrated.
+
+`calculateCaptureColorTransform()` consumes a validated `SimulatedCapture` and one untreated inline XYZ or exact `photivra-colorimetric-rgb-d65` virtual-camera plane. It returns a new immutable transformed RGB plane, model data, source plane/state IDs and the selected WB policy. It leaves the capture/exposure/focus/noise/source manifest unchanged. Consumers use the same API for preview/export; no renderer or file-format dependence is introduced.
+
+| Explicit policy | Meaning |
+| --- | --- |
+| preserve-intent | Convert the color basis only; retain resolved WB as intent without applying it. XYZ reference white must match the documented D65 convention exactly. |
+| apply-resolved-rgb-gains | Convert XYZ to the camera RGB basis, then multiply the resolved #108 red/green/blue gains. Caller must bind gains to the exact camera profile/version. No AWB estimator or implicit adopted-white adaptation runs. |
+| adopted-white-xyz-scaling | In XYZ, multiply X and Z by target-D65/adopted-white ratios, leave Y unchanged, then convert to linear RGB. Requires explicit adopted white; consumes no RGB gains. Reports approximation provenance. |
+
+XYZ diagonal scaling is intentionally a limited adaptation approximation, not Bradford, a physiological cone model or a full color-appearance model. It maps the chosen normalized adopted white to D65 while preserving its Y; this invariant does not prove perceptual accuracy for other colors. Ratios must lie in [1e-6,1e6] for the supported numerical domain; no validated physical accuracy envelope is claimed. Under mixed illumination, the selected adopted white remains a camera/photographer choice. The result always states `claimsUniqueSceneWhite:false`. Encoding white and adopted white are separate records; RGB gains do not derive/update the adopted white.
+
+Signed samples, above-white headroom and the source reference-value normalization are retained; non-finite arithmetic fails with the scientific-result error. Source saturation is retained as **upstream capture history in the original source-channel domain**, not an output clipping threshold or transformed RGB white level. The result performs no clipping and creates no new saturation count. Existing digital-lens-correction history is retained; color/adaptation/gain history rejects a second color invocation. Missing/wrong profile versions, unsupported spectral channel identities, transformed input, external storage, reused output IDs and malformed policies fail closed. External data must be independently loaded/verified before a future streaming color executor; this API does no IO.
+
+To commit the returned plane into a new container, carry the original source manifest and capture settings, add the returned model/evidence to `models` as appropriate, and include the derived plane. `createSimulatedCapture()` revalidates the aggregate inline budget; callers decide whether to retain both master and derived planes. A transform result does not assert an external artifact checksum for newly generated bytes. Schema `0.2.0` explicitly records applied-chromatic-adaptation; `0.1.0` archives migrate without inventing adaptation.
+
+The fixed ideal basis has no illumination-dependent sensor calibration. Future measured/spectral sensor models need their own versioned channel→XYZ profiles with explicit reference illumination/validity and approximation/calibration evidence; this implementation rejects them instead of inventing a universal matrix or interpolating undocumented illuminants. #15C owns quantization, #112 tone/look/gamut/transfer/display, #16 file mapping and #111 production ordering. No stage is activated here.
+
+Factual research: [W3C CSS Color 4 linear sRGB definition](https://www.w3.org/TR/css-color-4/#predefined-sRGB) documents primary/white chromaticities and distinguishes linear-light values from the transfer-encoded space. Only these public numerical facts and color-space distinctions are used; source code, published conversion matrices, protected prose and calibration/color tables were not incorporated. Reference coefficient tests check independently stated numerical values to absolute tolerance about 5e-14; invariants check primary chromaticities, black and D65 white. AI-assisted draft remains subject to substantive human science/provenance review and DCO certification.

package/docs/CAPTURE_CORRECTED_SDR.md

@@ -0,0 +1,25 @@
+# Capture-bound corrections and SDR: #112 integration slice
+
+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).
+
+`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

@@ -0,0 +1,27 @@
+# Capture export metadata foundation (#16B)
+
+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).
+
+`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

@@ -0,0 +1,20 @@
+# Capture-to-SDR adapter
+
+Release context: **package 1.0.0 candidate / root API 0.116.0**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_0.md).
+
+Current 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.

package/docs/DEVELOPERS.md

@@ -0,0 +1,60 @@
+# Developer guide
+
+This is the entry point for **@photivra/engine 1.0.0 candidate**, root API contract **0.116.0**. The candidate becomes an installable 1.0.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_0.md) explain the version distinction.
+
+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.0.0`. During candidate review, use the verified tarball described in [release preparation](RELEASE_1_0.md).
+
+```ts
+import { calculateFieldOfView, ENGINE_API_VERSION } from "@photivra/engine";
+
+const horizontal = calculateFieldOfView({ focalLengthMm: 50, sensorDimensionMm: 36 });
+console.log(ENGINE_API_VERSION); // 0.116.0: independent root contract identity
+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 and the maintained 24 line; prefer patched Node 24. The broad manifest minimum does not qualify Node Current/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 1.0.0/root 0.116.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 eventual verified npm 1.0.0 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.

package/docs/DIGITAL_OPTICS_FOUNDATION.md

@@ -0,0 +1,69 @@
+# Stray light and digital lens correction foundations
+
+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).
+
+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

@@ -0,0 +1,187 @@
+# Executed environment capture to native RAW
+
+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).
+
+`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 field throughput with evidence and a limitation. Spatial
+  vignetting is not silently synthesized. Existing lens transmission/front-filter
+  inputs remain upstream of normalized PSF shape.
+- 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.

package/docs/EXPORT_ACCEPTANCE.md

@@ -0,0 +1,133 @@
+# Simulated Sensor RAW DNG / JPEG acceptance
+
+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 record separates implemented export behavior, reproducible independent
+checks and external application acceptance for #16. The files are synthetic
+Photivra captures, never photographs from a physical commercial camera.
+
+## Current implemented boundary
+
+`simulateEnvironmentSensorRawFrame()` executes supplied analytic environment
+queries through the existing optics, wavelength/EQE, local temporal exposure,
+dark/charge/capacity, seeded shot/read noise and ADC pipeline. Its exact native
+post-ADC CFA frame feeds `createPhotographicExportPair()` and the shared #112
+processed path. The serializer does not reconstruct the sensor simulation.
+Attached manual RAW fixtures remain valid low-level serializer inputs, but are
+not the evidence used here for producer-origin acceptance.
+
+Provider transport, visibility, calibration and complete production-stage
+activation are explicitly unverified. Source evaluation and authoritative
+sensor-code production are executed; these are different claims. Bounded production integration is now merged in #178; provider transport and unsupported combinations remain explicit limits, not properties established by a DNG file. Child diagnostics remain accessible in the engine result.
+
+The public export API requires explicit profiles, WB/rendering policy, identity,
+workflow and event time. It copies validated data before asynchronous hashing.
+The commercial app and calling runtime own file downloads. There is no file IO,
+wall-clock sampling, service, new runtime dependency, Adobe SDK or competing
+writer in the engine.
+
+## Reproduce the acceptance files
+
+```sh
+node scripts/generate-producer-export-acceptance.mjs OUTPUT_DIRECTORY
+python scripts/verify-producer-export-acceptance.py OUTPUT_DIRECTORY
+```
+
+The generator uses the existing repository dev compiler to compile only its
+entry point and imported engine/owned fixture modules in a disposable directory.
+It cleans that directory on success or failure. It is not an engine dependency
+or package export. Run from a checkout with its normal dev dependencies installed.
+The Python verifier requires independently installed Pillow, lxml and LibRaw.
+Missing required independent tooling is a failure, not a passing skipped check.
+
+Five 72×48 native pairs are committed in
+`test/fixtures/producer-export-acceptance/`: landscape, both portrait directions,
+inverted landscape and manual WB. Each represents an explicitly identified
+shutter event with distinct artifact IDs; the controlled cases use the same seed
+and physical/noise inputs, so orientation and metadata-WB variations preserve
+all native codes and RAW-data identity. Portrait JPEGs are 48×72, upright JPEG
+orientation is 1, and DNG retains native 72×48 pixels with its orientation tag.
+
+These are explicit #130-derived camera/exposure/seed/units variants. The source
+is an owned three-zone analytic angular environment at 400–500 nm, not the
+canonical Lambertian target or a measured calibration. Optical transmission,
+EQE, uniform aperture response, absent AA/PSF and direct noiseless source
+radiance remain named approximations. Physical sampling uses square 500 µm
+pitch, a declared 0.8×0.6-pitch sensitive aperture, one aperture midpoint and
+one shutter midpoint, with two spectral nodes. Each capture executes 6,912
+provider queries. This is bounded reference evidence, not native camera pixel
+pitch, high-resolution output, measured accuracy or convergence evidence.
+
+The actual generated samples include signed-noise shadows below BlackLevel 64,
+physical clipping and ADC clipping at WhiteLevel 1023. Original RAW integers,
+not an RGB screenshot or later tone curve, supply the DNG. The manual-WB case
+changes AsShotNeutral and JPEG development, while preserving those RAW codes.
+The manifest records exact file SHA-256, RAW-data identity, expected codes/RGB,
+producer model/version/query count, clipping counts and bounded elapsed/heap
+observations. Regeneration can change incidental measurement fields; image
+samples/file hashes remain deterministic for the pinned engine/policy.
+
+## Independent checks
+
+The optional verifier uses Pillow's TIFF directory reader and independent strip
+unpacking for exact RAW codes; Pillow decodes JPEG and standard EXIF. DOM/Expat
+and lxml/libxml2 independently agree on XMP attributes. LibRaw's documented
+opaque-handle C API opens, unpacks and renders every DNG, independently verifies
+native dimensions/white code and reads camera-neutral WB gains. Its emitted
+PPM is decoded by Pillow to verify all oriented output dimensions.
+
+LibRaw API reference: https://www.libraw.org/docs/API-C.html. No LibRaw source,
+private structure layout or version-dependent pointer offset is incorporated.
+Its version is recorded in `independent-validation.json`. Different demosaic,
+tone or display algorithms are not expected to produce pixel-identical images.
+
+Standard capture metadata agree across DNG/JPEG; shared CaptureID/hash remain
+separate from per-resource IDs and native RAW-data identity. Privacy checks
+reject false camera/GPS/serial/host/creator/AI assertions through the existing
+strict metadata contract and verify selected forbidden tags are absent in files.
+Advanced noise hints, calibration matrices/signatures, rights fields and original
+RAW-resource lineage are omitted when no justified mapping exists. See
+[photographic export](PHOTOGRAPHIC_EXPORT.md) and
+[capture metadata](CAPTURE_EXPORT_METADATA.md) for the existing field contract.
+
+## Supported sizes and memory semantics
+
+All existing stage limits remain unchanged: the reference producer,
+reconstruction and full-native export path permit at most **4,096 native sites**.
+The structural attachment ceiling alone does not authorize image execution.
+No 24/45/60 MP export, streaming or resampling is claimed. A tiny output crop
+cannot evade full-native counting. See [RAW frame envelope](RAW_FRAME_ENVELOPE.md)
+and its complete-edge regression tests.
+
+The generator also records 24/45/60 MP unsupported-size preflight requests with
+an empty site payload. They reject before any provider invocation or large image
+allocation. These are measured rejections with deliberately unsupported/missing
+coverage, not typical-resolution memory/performance benchmarks. Before/after
+heap is not peak memory; measured timings are informational. The explicit
+bounded support declaration satisfies #16's supported-limit option without
+claiming high-resolution processing or silently raising safety budgets.
+
+## Closure map
+
+| Requirement | Implementation / evidence | Status |
+| --- | --- | --- |
+| True native post-ADC CFA RAW; exact lossless codes; effective ADC/black/white consistency; no baked processing | `sensor-raw-producer.test.ts`, `raw-output-conformance.test.ts`, producer-derived files and independent verifier | Implemented / independently checked |
+| RAW directly from simulated capture; ISO/gain upstream; same-capture standalone JPEG | `environment-raw-integration.test.ts`, `raw-output-conformance.test.ts`, generated producer pairs | Implemented / bounded origin evidence |
+| Shared capture/provenance/hash; distinct resource/RAW IDs; truthful Photivra EXIF/XMP/IPTC | `capture-export-metadata.test.ts`, `photographic-export.test.ts`, independent file inspection | Implemented / checked |
+| No generative-AI, real-camera, GPS/serial/host/path or fabricated creator/rights claims | Strict input projection and existing negative tests; generated file inspection | Implemented / checked |
+| Native CFA phase, active/default crop, aspect and all orientations | `photographic-export.test.ts`, four generated orientations and LibRaw rendered dimensions | Implemented / checked |
+| As-shot WB metadata does not rewrite RAW; virtual color interpretation is explicit | `photographic-export-correction.test.ts`, same-code manual-WB case and LibRaw neutral-gain interpretation | Implemented / approximate color basis |
+| Deterministic fixture/code/critical metadata acceptance | Committed manifests, hashes and independent TIFF/JPEG/XML/LibRaw verification | Checked |
+| Size/memory boundary and optional runtime/package surface | Existing 4,096-native-site envelope, unsupported-size records, browser/package gates | Explicit supported limits |
+| Adobe RAW interpretation plus independent RAW reader | LibRaw all five pairs; owner Lightroom 9.6 screenshots cover four orientations/as-shot and usable exposure/WB | Reviewed bounded acceptance |
+| JPEG independent decoder/editor/browser acceptance | Pillow all five pairs; owner Photoshop 2026/Chrome landscape screenshots | Reviewed bounded acceptance |
+| Provenance/license review | Existing Apache/DNG notices, owned fixtures and no new dependency; AI-assisted contribution | Owner approved and signed PR #201 |
+| Accurate simulated-RAW documentation | This record and existing metadata/export/frame documentation | Reviewed and merged; reconciled for 1.0 |
+
+## Recorded owner external acceptance — 2026-10-02
+
+[Reviewed PR #201](https://github.com/Photivra/photivra/pull/201) records owner-supplied screenshots: Lightroom 9.6 (build 20260923-1659-a32d844) opens landscape DNG at 72×48, both portraits at 48×72 and inverted landscape at 72×48. Exposure +2.34 brightens the landscape; WB at 6500 K/Tint −78 visibly changes the midtone band. The manual-WB thumbnail uses As Shot and shows a distinct warm band; Adobe's displayed 50,000 K/Tint +28 is its interpretation of synthetic gains, not measured color-temperature accuracy. Photoshop 2026 and Chrome render the landscape JPEG at 72×48.
+
+Independent automated decoding covers all five pairs. User-Mac file hashes and exact Photoshop/Chrome builds were not supplied/reverified; editor/browser screenshots cover the landscape JPEG, not every JPEG variant. These limits are preserved. The committed independent report and `external-review.template.json` describe the earlier automated-only checkpoint; template booleans are not new acceptance evidence. PR #201 merged as `8f5259c4d6b40746173d7842554d416f0138ee27` after owner review/DCO and merge authorization, closing #16. The release audit does not regenerate scientific fixtures, claim additional editor tests or install/buy commercial tooling.
+
+For a future export/model change, rerun the independent reader and relevant Adobe/editor/browser checks against that exact candidate and record hashes/builds. Runtime arithmetic/export schemas remain unchanged in this release preparation.