@photivra/engine 0.6.0 → 1.0.0

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.