@photivra/engine 0.5.1 → 1.0.0

package/docs/PSF_FOUNDATION.md

@@ -1,133 +1,155 @@
 # PSF and Pupil Foundation
 
-Photivra's PSF/pupil foundation keeps optical blur contributions **separate and explicitly contextualized** until a defensible composition model exists.
+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).
 
-Use:
+Photivra has two complementary PSF layers.
 
-```ts
-import {
-  calculatePsfFoundationComponents,
-  getPsfFoundationContract
-} from "@photivra/engine";
+The legacy foundation keeps the ideal **geometric defocus-circle** and **circular Airy first-zero** diagnostics separately named and independently testable. The #113 real-lens framework adds explicitly profiled or pupil-derived **combined primary-optical PSFs** without converting those older diagnostics into a synthetic blur score.
 
-const contract = getPsfFoundationContract();
+## Legacy diagnostics
 
-const components = calculatePsfFoundationComponents({
-  focalLengthMm: 85,
-  aperture: 2.8,
-  focusDistanceM: 10,
-  subjectDistanceM: 20,
-  fieldPointMm: { x: 12, y: 8 },
-  fieldNormalizationRadiusMm: 21.6,
-  spectralBasis: {
-    kind: "monochromatic",
-    wavelengthNm: 550
-  }
-});
-```
+Use `getPsfFoundationContract()` and `calculatePsfFoundationComponents()` for the established diagnostics and common field/depth/wavelength/pupil context.
 
-## What is implemented
+The foundation contract is version `0.3.0`.
 
-The current foundation evaluates two existing diagnostics in one explicit context:
+Implemented diagnostic contributions:
 
-- **geometric defocus circle** — the existing thin-lens defocus-circle diameter;
-- **circular diffraction first-zero diameter** — the existing ideal circular-pupil Airy diagnostic.
+- geometric defocus circle;
+- circular diffraction first-zero diameter.
 
-Each contribution retains the provenance of its underlying primitive.
+Implemented framework contributions:
 
-The foundation records:
+- ideal regular-polygon diffraction density (on-axis, in focus);
+- mechanical pupil clipping / cat-eye PSF shape;
+- field curvature;
+- field-dependent aberration;
+- field-dependent bokeh / signed-defocus response.
 
-- physical image-plane field position;
-- normalized field radius for comparison;
-- focus and subject depth;
-- monochromatic wavelength basis;
-- ideal circular f-number-derived pupil diameter.
+Arbitrary curved-blade, off-axis and clipped-pupil diffraction is not inferred by the ideal polygon API.
 
-## What is deliberately not calculated
+The legacy component calculator still returns no combined PSF. That is intentional: a combined PSF is available only when an explicit #113 profile or complex pupil supplies the information needed to justify one.
 
-The foundation does **not** currently calculate:
+## Ideal polygon diffraction
 
-- a combined PSF;
-- a convolution kernel;
-- MTF;
-- one combined blur diameter;
-- a lens-sharpness score.
+`calculateIdealPolygonDiffractionPsf()` reuses the regular-polygon geometry and image-plane conventions, but evaluates its continuous Fourier transform analytically rather than rasterizing the pupil into the bounded #113 DFT grid. This avoids a second sampled approximation of the same ideal aperture; #113 still owns arbitrary complex sampled pupils and aberration phase.
 
-Defocus and diffraction are independent diagnostics. A future combined PSF must document the mathematical composition method and assumptions rather than adding their diameters or scores ad hoc.
+Inputs are explicit: equal-area physical pupil diameter, pupil-to-image propagation distance, wavelength and resolved air/vacuum basis, blade count/orientation, and image-plane displacements in micrometres (+X right, +Y up). A nonzero displacement is a location within the **on-axis PSF**, not an off-axis source field position. There is no implicit wavelength conversion or focus-to-propagation-distance conversion.
 
-## Reserved contributions
+For unit-circumradius area `A_unit = n sin(2π/n)/2`, the physical radius is `sqrt(A/A_unit)`, with `A = π(D_equal_area/2)²`. This fixes equal area, not equal circumradius/inradius. Under a declared nominal-area convention, a caller may use `D_equal_area = f/N`; that convention is not an inferred real-lens pupil calibration.
 
-The public contract reserves ownership for:
+For dimensionless pupil coordinates `u`, the independently derived boundary integral follows the divergence theorem:
 
-- non-circular diffraction;
-- mechanical/pupil clipping;
-- field curvature;
-- field-dependent aberration/PSF structure;
-- field-dependent bokeh.
+`F(q) = i/|q|² Σ_edges (qx Δy − qy Δx) exp(−i q·midpoint) sinc(q·edge/2)`.
+
+The phase coordinate is `q = 2π R x/(λ L)`. The center uses the exact area limit. Subtracting each edge's constant term (which sums to zero on a closed contour), a cancellation-safe sinc-minus-one series and `cos(t)−1 = −2 sin²(t/2)` keep near-origin evaluation stable. There is no FFT, pupil rasterization or hidden pupil-grid convergence parameter.
+
+Output gives both `|F/A_unit|²` (unity at center) and continuous intensity density `A |F/A_unit|²/(λ L)²`, converted from 1/mm² to **1/µm²**. Parseval's identity gives unit integral over the infinite image plane. Neither the density nor the peak-normalized intensity is a discrete probability weight. A finite point list is **not** renormalized to sum to one. Renderer quadrature must multiply density by image-plane area, measure support truncation and convergence, and explicitly own any finite-kernel normalization. Throughput stays separate.
+
+Bounds: 3–1024 blades, 1–4096 image points per request, finite positive scales and dimensionless phase radius at most `1e6` (a computational envelope, not a calibrated accuracy claim). Unsupported fields, including aberration/clipping/field inputs, fail closed. Uniform unit amplitude and zero phase are fixed ideal-model assumptions; there is no defocus, curved-blade, field, polarization, sensor, stray-light or polychromatic claim. No quantified physical uncertainty is asserted.
+
+Validation independently checks square sinc-squared response (absolute tolerance `5e-13`), rotated odd/even apertures, direct triangular-pupil quadrature refinement, the equal-area many-blade circular limit (absolute intensity tolerance `1e-7` at the tested points), and finite-support energy integration/refinement. Those tolerances describe test evidence, not universal real-lens accuracy bounds.
+
+Mathematical reference: [Sillitto, Fraunhofer diffraction at straight-edged apertures (1979)](https://doi.org/10.1364/JOSA.69.000765), whose abstract establishes analytical polygon Fourier methods. The implementation and tests are independently authored from Fourier integration, the divergence theorem and Parseval's identity; no third-party implementation, tabulated data or protected exposition is incorporated. AI-assisted draft work still requires substantive human provenance/science review under `PROVENANCE.md` and DCO certification before inclusion.
+
+The circular Airy diagnostic remains separate and unchanged. Do not convolve this diffraction PSF over a #113 kernel that already includes diffraction. This standalone API does not enable an uncomposed production-plan stage or change the POC.
+
+## Sampled real-lens PSFs
+
+`LensSampledPsfProfile` stores full 2D intensity PSFs on an explicit regular calibration/simulation grid.
+
+Profile axes:
+
+- focal length;
+- focus diopters (`0` = #103 optical infinity);
+- f-number;
+- image-plane field X/Y;
+- wavelength;
+- signed image-plane defocus.
+
+Every node declares a unit-energy PSF kernel with physical X/Y sample pitch. All nodes in one interpolated profile must share the same kernel grid geometry.
+
+`resolveLensSampledPsf()` reports either:
+
+- `exact-grid-sample`; or
+- `interpolated`.
+
+No extrapolation is permitted.
+
+The full 2D kernel preserves image-plane +X right / +Y up orientation, allowing off-axis sagittal/tangential/asymmetric structure instead of forcing radial symmetry.
+
+## Field curvature and longitudinal chromatic focus
+
+Each sampled node carries `bestFocusImagePlaneOffsetMicrometers`.
+
+That quantity may vary with:
+
+- field position — field curvature;
+- wavelength — longitudinal/axial chromatic focus;
+- focal/aperture/focus configuration.
+
+It is a focus/PSF quantity. It does not modify geometric distortion, lateral CA, or the selected camera focus-control state.
+
+## Complex pupil / wavefront reference
+
+`LensComplexPupilProfile` represents one explicit primary-optical state as:
 
-A reserved contribution is not an implemented capability.
+- relative pupil amplitude; and
+- optical-path difference in micrometres.
 
-## Field position
+`calculateLensComplexPupilPsf()` performs deterministic scalar Fraunhofer propagation of that complex pupil.
 
-Field position uses physical image-plane coordinates:
+This path evaluates diffraction and aberration in one pupil calculation. Do not stack another independent Airy or diffraction blur over its output.
 
-- optical axis at the origin;
-- +X right;
-- +Y up;
-- millimetres.
+The output intensity PSF is normalized to unit energy.
 
-`fieldNormalizationRadiusMm` exists only to make center/mid/edge/corner comparisons reproducible. It is not a real-lens calibration or model-validity limit by itself.
+## Pupil clipping and throughput
 
-The current defocus and circular Airy diagnostics are field invariant. Recording field position now gives future field-dependent contributions a stable context without changing those existing calculations.
+PSF energy normalization and optical throughput are separate.
 
-## Spectral basis
+A clipped pupil can change:
 
-The current foundation accepts an explicit monochromatic wavelength because the circular Airy diagnostic is wavelength dependent.
+1. the pupil/PSF shape; and
+2. the relative amount of transmitted light.
 
-This does not create:
+The #113 profiles therefore keep `relativePupilThroughputFactor` separate from the normalized PSF kernel. The throughput factor belongs in the optical-throughput path (including #110 integration) and must be applied exactly once.
 
-- a spectral lens model;
-- longitudinal chromatic aberration;
-- sensor spectral response;
-- CFA/color calibration.
+The existing illumination-vignetting primitive remains a separate throughput-only approximation; it does not become pupil clipping automatically.
 
-Future wavelength-dependent PSFs must declare their basis explicitly.
+## MTF boundary
 
-## Pupil boundary
+MTF magnitude is useful validation evidence, including sagittal/tangential trends.
 
-The current context records an ideal circular, f-number-derived pupil diameter because the existing defocus/Airy diagnostics use circular-pupil assumptions.
+It does **not** uniquely determine a PSF without phase.
 
-Polygon aperture geometry is not automatically a non-circular diffraction PSF.
+`assessMtfOnlyPsfRenderability()` therefore always blocks unique PSF reconstruction from magnitude-only MTF data while allowing diagnostic use.
 
-Mechanical/pupil vignetting is also separate from illumination vignetting:
+## Sensor and stray-light boundaries
 
-- illumination vignetting changes throughput only;
-- pupil clipping can change throughput **and** PSF/bokeh shape.
+V1 lens PSF profiles are `lens-primary-optical-path-only`.
 
-## Preview and reference fidelity
+They exclude:
 
-Browser preview and higher-fidelity reference implementations may use different numerical approximations or sampling budgets.
+- sensor OLPF;
+- microlens response;
+- CFA/spectral sensor response;
+- sensor crosstalk;
+- sensor sampling;
+- RAW reconstruction/demosaic;
+- sharpening/denoise;
+- ghosting, flare and veiling glare.
 
-They must preserve the same:
+A future combined camera-system response must be labeled separately rather than silently stored as a lens PSF.
 
-- contribution identities;
-- field/depth/spectral context;
-- pupil semantics;
-- engine-owned parameters;
-- scientific limitations.
+#114 owns stray light.
 
-A preview approximation must not redefine the science merely because it is cheaper to render.
+## Preview and reference use
 
-## Test Fixture relationship
+The sampled-profile contract can be consumed by both preview and reference paths.
 
-Test Fixture v0.3 provides deterministic center/mid/edge/corner detail and point-highlight targets for integration regression.
+The complex-pupil scalar Fraunhofer evaluator is a deterministic reference calculation. A preview implementation may use a validated approximation, but it must preserve the same profile semantics, field orientation, throughput ownership and limitations.
 
-It does not establish:
+## No scalar lens quality
 
-- calibrated MTF;
-- a measured real-lens PSF;
-- spectral lens behavior;
-- calibrated mechanical vignetting;
-- named-lens performance.
+Photivra does not produce a universal lens sharpness or bokeh-quality score.
 
-Engine analytical/reference tests remain the scientific source of truth.
+Real optical response remains field-, focus-, aperture-, wavelength-, pupil- and defocus-dependent. Generic equipment tiers may later choose different versioned profiles, but the tier label is not itself an optical algorithm.

package/docs/RAW_FRAME_ENVELOPE.md

@@ -0,0 +1,56 @@
+# Reference RAW frame compatibility
+
+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).
+
+A valid RAW attachment does not establish readiness for reconstruction or paired
+export. The limits below apply to the current browser-safe reference adapters,
+not a typical-camera-resolution production implementation. Count full native
+sites before cropping; a small active area or output view never reduces that
+count for producer/reconstruction admission.
+
+| Boundary | Inclusive budget | Additional conditions |
+| --- | --- | --- |
+| `parseSensorRawFrameInput()` / `createSensorRawFrame()` | 65,536 full native sites | Dense row-major uint16 attachment; single-frame native-effective periodic CFA; explicit one-site binding and consistent codes/flags |
+| `parseSensorRawProducerInput()` / `simulateSensorRawFrame()` | 4,096 full native sites | Complete per-site exposure/charge/readout declarations and existing noise/seed identities; upstream radiometry remains declared |
+| `parseRawFrameReconstructionInput()` / `resolveRawFrameReconstruction()` | 4,096 full native sites | Native in-frame region; at most 64 CFA phases, 16 output channels and 256 contributions per phase profile; complete phase dispatch |
+| `parsePhotographicExportInput()` / `createPhotographicExportPair()` | Inherits the 4,096 full-native-site reconstruction budget | Registered 2×2 RGB Bayer; ordered RGB reconstruction channels; 1:1 oriented crop/output sampling; reconstructed region covers the native final crop |
+| Corrected paired export | Same full-native budget | Reconstruction covers the entire active native area, even when the final output crop is smaller; existing correction support/selection rules still apply |
+| Internal baseline JPEG encoder | 4,096 output pixels | Its independent output/encoder budget; not the definition of native sensor coverage |
+
+The attachment and reference execution budgets have distinct internal constants
+in `src/capture/raw-frame-limits.ts`. Producer and reconstruction share the latter
+because they admit the same full-native execution envelope. The JPEG output
+budget retains its separate meaning even though its current numeric value is
+the same. No safety limit is raised to make adjacent APIs appear identical.
+
+For example, a complete 64×65 attachment can be structurally valid, but its 4,160
+native sites exceed the reference reconstruction/producer budget even with a
+2×2 active/output crop. A 64×64 frame is within the inclusive 4,096-site budget;
+that fact alone does not supply missing kernel support or calibrated color.
+
+## Preflight and compatibility
+
+Call the existing stage parser before execution to discover incompatible
+requests. Parsers revalidate untrusted data and can copy/validate native records;
+this is not a constant-time dimensions-only capability query. Reconstruction
+rejects oversized sample arrays before creating an attachment snapshot. Export
+now rejects unsupported output resampling, uncovered final crop, incomplete
+active coverage for correction, and non-Bayer topology during parsing, before
+per-pixel reconstruction, rendering, hashes or file encoding. Bayer preflight
+requires exactly one red, two green and one blue site; an extra channel is
+rejected here rather than failing later during DNG packing.
+
+These are necessary structural gates, not a promise that execution succeeds.
+Kernel edge/source-channel support, DNG repeating black/common-white metadata,
+color-neutral validity, correction support and metadata encoding constraints
+retain their execution checks. Missing edge support still fails without
+padding, clipping or renormalization.
+
+Compatibility review: previously executable requests retain the same accepted
+envelope, arithmetic, codes, hashes and bytes. The public export parser now
+rejects these already-unsupported execution combinations earlier; when several
+faults coexist, error precedence can change. Existing diagnostic text is kept.
+No serialized field, schema or root API version changes, and no saved-data
+migration is required. Package and POC versions remain independent and unchanged.
+
+Larger/streaming execution remains unsupported. #16/#112/#178 are closed for their reviewed bounded scope; current execution/editor evidence is in [production capture](PRODUCTION_ENVIRONMENT_CAPTURE.md) and [export acceptance](EXPORT_ACCEPTANCE.md). Structural attachment alone does not establish that evidence for a new frame.

package/docs/RAW_FRAME_RECONSTRUCTION.md

@@ -0,0 +1,30 @@
+# Same-RAW reconstruction handoff (#16C)
+
+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).
+
+See [Reference RAW frame compatibility](RAW_FRAME_ENVELOPE.md) for stage-specific
+limits, full-native counting and parser preflight behavior.
+
+`resolveRawFrameReconstruction()` derives a bounded contiguous native-region virtual-sensor-channel plane from a committed `SensorRawFrame`. It delegates every output pixel to the existing #14 `resolveSensorRawReconstruction()`, using only exact attached RAW samples. Independent float planes in the attached capture are retained as history/metadata and **never provide reconstructed values**.
+
+This adapter and its RAW attachment predecessor are merged. Handoff schema 0.1.0 is retained; root API 0.99.0 was its historical introduction identity. Package 1.0.0 retains current root 0.116.0 and independent capture/production/POC contracts.
+
+Inputs are `rawFrame`, `region: { x, y, width, height }`, and `phaseProfiles: [{ phaseX, phaseY, profile }]`. A region is a positive integer half-open rectangle in the full native raster, not crop-local or oriented output coordinates. RAW-frame flags, dimensions, full native coverage, exact site/channel/code normalization and IDs are revalidated through #166.
+
+Every absolute CFA repeat phase must have exactly one explicit #14 reconstruction profile, matching the frame's capture-mode and color-sampling identities. All phase profiles expose the same output channels in the same order. Dispatch uses absolute native indices modulo the declared repeat dimensions; a cropped region never restarts phase. Input profile order is canonicalized to repeat-tile row-major phase order. No Bayer/X-Trans algorithm or RGB color basis is inferred from labels.
+
+For each pixel, the adapter gathers the exact required sites from the attached frame and checks bounds/channel assignment before calling #14. Existing declared normalized kernel weights own linear reconstruction; negative weights are permitted by that existing contract. Source values are the existing signed `blackSubtractedNormalizedCode`, not raw storage codes divided by container maximum. No new black subtraction, saturation/noise/gain equation or quantization is introduced.
+
+Missing edge sites fail closed. There is no edge replication, reflection, zero fill, dropped weight or renormalization. A caller may choose a smaller explicit region with fully available neighborhoods, but must not silently change intended final framing. Supplying a profile for every phase is not proof the kernel represents a calibrated or adequate reconstruction algorithm.
+
+The result includes an immutable exact source RAW-frame snapshot, phase profiles, region, interleaved native-region row-major plane and child calculation envelopes with exact weighted source contributions. The top-level scientific status remains **approximation** even if a profile labels itself calibrated; child status and assumptions are retained. No aggregate uncertainty is fabricated.
+
+`lineage = "engine-reconstructed-from-attached-raw"` means these returned values were actually computed from that returned RAW snapshot. `producerOriginVerified = false` retains #166's caller-declared producer boundary: no assertion is made that a caller originally ran the sensor pipeline. IDs alone do not establish equality; the exact snapshot and contributions remain inspectable. This is not cryptographic provenance, a signed certificate, RAW integrity metadata or a SimulationHash.
+
+The plane's image state is `virtual-sensor-channels`, and its raster binding is `native-reconstruction-region`; it is deliberately **not** an already-oriented `CaptureLinearPlane`. No WB, color conversion, physical orientation, final crop/resampling, sharpening, denoising or JPEG pipeline is applied. Sensor-channel labels do not define calibrated RGB primaries. A downstream explicit color-profile and geometry bridge is required before #112/#164 can accept these values. Existing capture float planes must not be substituted at that boundary.
+
+Reference safety limits: at most **4,096 full-native RAW sites**, **64 repeat phases**, **16 output channels**, and **256 total contributions per phase profile**. Region size cannot exceed that native frame. The reference adapter retains source snapshots and per-pixel traces and reparses lower-level profiles; it is not a 24/45/60 MP performance or memory claim. Larger/streaming execution requires measured separately reviewed work.
+
+Tests reuse #130-derived capture metadata and the shared synthetic RAW fixture. Declared 2×2 tile-average kernels are intentionally simple regression policy, not manufacturer demosaic or calibrated sensor color. Tests independently check arithmetic, direct lower-level equivalence, RAW-code changes versus unrelated float-plane changes, native phase/orientation invariance, malformed/stale inputs, edge rejection and safety bounds.
+
+Remaining #16/#112 work: producer-bound sensor execution, a defensible sensor color interpretation/profile, reconstruction-to-oriented-active/output geometry and color/WB processing handoff, metadata/hash/format mapping, DNG/JPEG writers and decoded/editor/memory acceptance. No issue is closed by this slice.

package/docs/RELEASE_1_0.md

@@ -0,0 +1,65 @@
+# 1.0.0 release contract and owner handoff
+
+**Distribution:** `@photivra/engine@1.0.0` candidate. **Root API identity:** `0.116.0`. **Feature/science predecessor:** reviewed/signed main `34c6d9aca1c2e365b253c1562734d11bc8e0235f` (PR #206), tree `fa74373967843a1942206c26f5baa004e9a466fd`. Its post-merge CI 37032338620 passed Node 22.13.0/24 with 1,598 tests / 142 files. The release-preparation PR/CI identifies the exact new candidate; after signed squash merge, verify its tree equality and record final main SHA in the issue/PR handoff. A commit cannot contain its own cryptographic commit/tree identifier without a circular dependency.
+
+## What 1.0 contains
+
+The V1 feature/science checklist is 32/32 and required defect #178 is closed. The root includes explicit camera/sensor/capture geometry, optics, focus, exposure control, registered illumination, bounded motion/stabilization, spectral/response/charge/noise/readout foundations, generic tier assets, immutable production plans, linear/color/SDR processing, and same-RAW paired DNG/JPEG export. See [developer navigation](DEVELOPERS.md) and [composition/consumer map](V1_COMPOSITION_MAP.md) for actual entry points and supported combinations.
+
+The declared environment production route can execute all fourteen graph stages through native RAW and optional output. It retains a full-native 4,096-site budget and 100,000-provider-evaluation aggregate cap, exact one-to-one CFA timing, scene time zero, ideal environment projection/constant-axis rotation, explicit unity field throughput and optional destination-local sampled PSF. Paired reference export supports registered Bayer and 1:1 output cropping. Structural RAW attachment has a separate 65,536-site ceiling and does not authorize larger execution.
+
+The package does not supply a general surface renderer/visibility solution, calibrated commercial profiles, full field-dependent PSF transport, megapixel processing, HDR output, multi-frame computational image combination, C2PA, hosted API or MCP server. Generic assets and provider output remain approximations. A stable API does not establish calibrated physical accuracy, universal tier ranking, combined uncertainty, browser frame time or typical-resolution peak memory. Export/editor evidence and limits remain in [acceptance](EXPORT_ACCEPTANCE.md).
+
+## Migration and independent identities
+
+The distribution moves from 0.6.0 to 1.0.0. Root contract **0.116.0 is retained**, rather than mechanically reset to 1.0.0: no exported operation shape, scientific arithmetic, default, seed schedule or serialized capture identity changes in this preparation. This is an intentional independent contract identity under the package's new stable policy, not permission to keep making undocumented pre-1.0 breaks. Existing 0.116 callers require no code/data migration for this release preparation.
+
+Users of earlier development contracts must apply their actual intervening migrations. In particular, old producer noise model 0.1.0 cannot silently replay the signed-shadow correction: current producer noise model is 0.2.0, readout provenance model 2.0.0. Deliberate recomputation preserves historical artifacts and records new identity. Capture schema 0.1.0 archives normalize to 0.2.0 while retaining creator API identity; normalized bytes change. Production plan 0.7.0 / consumer manifest 0.2.0 add bounded environment execution fields. See the governing capture/producer/composition guides and historical changelog. Do not compare version strings from different contracts as though they form one global schema version.
+
+POC API 0.20.0, image-formation ordering 0.4.0, production capture snapshot 0.3.0, tier assets 1.0.0 and every other schema/model keep their existing independent values. Root API 0.116.0 still exports all original scientific operations. Documentation-only comments and reference generation do not authorize recomputation of historical calibrated data or fixture hashes.
+
+After 1.0, compatible additions use package minor releases, compatible fixes/docs use patches, and breaking root exports, semantics or unsupported reinterpretation of previously valid data require a documented package major transition and relevant independent contract changes. Prefer additive deprecation with an explicit migration and documented removal version. No fixed deprecation duration is promised. Necessary scientific/security corrections must be explicit even when preserving incorrect behavior would appear easier. No substantial optional public-engine feature work starts by default after V1; maintenance, corrective science, validation and security continue.
+
+## Exact candidate verification
+
+Use the lockfile and maintained Node 22/24 CI policy, preferably patched Node 24 for tooling:
+
+```sh
+npm ci
+npm run check
+npm run coverage
+npm run build
+npm run pack:check
+npm run docs:check
+npm run release:consumer-check
+npm run bench:image-formation:built
+```
+
+`docs:check` verifies reference synchronization, local/public repository links, imported symbols and explicitly recorded complete/fragment examples. The consumer check packs once into a temporary directory, installs the tarball with scripts disabled, validates declarations with strict TypeScript and executes complete examples plus the bounded production/export example without a source checkout. CI runs these release-specific checks on both supported runtimes. Existing science/license/SPDX/browser/package/coverage gates remain unchanged.
+
+Local macOS full tests retain the previously reproduced unchanged-main `equivalence-38` exact hash difference. No reference was regenerated. Linux CI is the exact-head full-suite authority; recorded cross-platform deterministic limitations must remain visible rather than weakening that assertion. Existing performance and external-editor acceptance evidence applies because runtime arithmetic and independent models are unchanged; release comments/version metadata are additionally checked against the packed artifact.
+
+## Owner-only tag and publish procedure
+
+This ticket prepares the repository; it creates no tag, npm publication or GitHub release. First substantively review the release contribution and certify DCO 1.1 for the signed merge. Merge only the tested candidate, verify final-main CI and record its commit/tree. Confirm current main still equals that final commit immediately before tagging; keep it unchanged through workflow verification.
+
+The current `.github/workflows/publish.yml` triggers on pushed `v*` tags. It requires **`v1.0.0`**, matching package/lock/citation metadata, at **current main**, with protected main and a protected tag. Public API inspection on 2026-10-02 confirmed main protected and an active tag ruleset applying to `refs/tags/v*`, blocking creation/update/deletion except authorized bypass. Only an authorized owner can create the release tag; do not weaken those controls.
+
+From a clean owner checkout, replace `FINAL_MAIN_SHA` with the verified merged commit:
+
+```sh
+git fetch origin main --tags
+git switch main
+git pull --ff-only origin main
+test "$(git rev-parse HEAD)" = "FINAL_MAIN_SHA"
+test "$(git rev-parse origin/main)" = "FINAL_MAIN_SHA"
+test "$(node -p "require('./package.json').version")" = "1.0.0"
+git tag -a v1.0.0 FINAL_MAIN_SHA -m "Photivra engine 1.0.0"
+git push origin refs/tags/v1.0.0
+```
+
+The **tag push automatically starts npm publication**; publishing a GitHub release alone does not. The workflow checks the maintained LTS policy, installs locked dependencies with scripts disabled, verifies science/coverage/static/docs/consumer/build/package gates, then packs the verified artifact. A separate minimal OIDC job downloads it, checks SHA-256 and publishes public npm only if that exact version is absent. It requires npm >=11.5.1 and the configured trusted publisher for this repository/workflow. That npm account-side configuration is not inspectable through the repository connector and is an owner account prerequisite; no credential or publishing identity is used during this ticket.
+
+Watch the publish workflow until success. Verify npm reports 1.0.0 and record the published tarball integrity. Then create the owner GitHub release at `v1.0.0`, using these release notes and the final commit/check evidence. If verification fails, retain the failure and investigate; do not force-move a protected tag or bypass science/provenance gates.
+
+The site-side handoff is in [developer navigation](DEVELOPERS.md); no website deployment or unpublished route is required. #165 remains post-V1.

package/docs/RELEASE_AUDIT.md

@@ -0,0 +1,38 @@
+# Final 1.0.0 preparation audit
+
+Package **1.0.0 candidate**, root API **0.116.0**, based on reviewed/signed main **34c6d9aca1c2e365b253c1562734d11bc8e0235f**. No tag, npm publication or GitHub release is performed by this contribution. The review PR and exact-head CI identify the candidate; the final signed squash commit/tree and post-merge CI belong in the issue/PR handoff after owner approval. [Owner release steps](RELEASE_1_0.md) specify that boundary.
+
+## Inventory and corrections
+
+[The audit inventory](validation/release-audit-inventory.json) records all **62 pre-existing human/agent Markdown documents** and **141 source modules**. It includes document hashes and normalized source-syntax hashes, not private filesystem paths. All source syntax is identical to the feature/science baseline when comments are removed. Source JSDoc grows from 814 to 1,060 blocks, including module integration notes, previously undocumented exported operations, central state records and non-obvious internal execution algorithms. Existing member unit/coordinate documentation is retained. [The generated reference](API_REFERENCE.md) resolves **1,130 root symbols across 126 modules**, including exact accepted unions, fields, signatures and independent constants; it is regenerated/checked against the compiler's actual root exports.
+
+| Reviewed surface | Findings and disposition |
+| --- | --- |
+| README, usage and onboarding | Corrected pending SDR integration, closed editor acceptance, extended-motion/stabilization scope and obsolete package/stability statements. Added one developer entry point with capabilities, qualified models/runtime and executable packed examples. |
+| Architecture, physics, stage/production contracts | Reconciled static broad foundation/reserved metadata versus route-specific plan 0.7.0 execution; preserved sample/attached-RAW blockers and all source/area/wavelength/time/calibration limits. No broader capability is inferred. |
+| Capture, RAW, processing, export, color | Corrected unmerged-draft/old issue status; preserved same native RAW lineage, signed shadows, separate ideal virtual-camera versus sensor-channel interpretation, one-time WB, correction/order and bounded export envelope. |
+| Tier/conformance/performance evidence | Reconciled reviewed/merged #116/#119/#43/#45/#131 and 32/32 status. Introduction IDs and measured commits remain historical; no fixture/golden/benchmark data is relabeled as new measurements. |
+| External export evidence | Carried forward PR #201 owner Lightroom orientation/as-shot/exposure/WB and landscape Photoshop/Chrome screenshots. User-Mac hashes/builds and JPEG-variant coverage remain explicitly limited; templates remain templates. No new commercial tool installation or external result is claimed. |
+| Source public/internal contracts | Added plain-language purpose/input/return/stage-limit explanations and non-obvious RNG/Poisson/normal, signed readout, compensated temporal sums, provider preflight, evidence composition, color conditioning and TIFF/JPEG encoding notes. 141-module comment-free syntax comparison confirms no runtime changes. |
+| AGENTS/contributing/security/support | Removed obsolete pending integration ownership, aligned 1.0 compatibility and maintained Node policy, retained human review/DCO/science/provenance/private-data boundaries and loopback-only contributor transport. |
+| Distribution/legal/provenance | Coordinated package/lock/citation 1.0.0, retained every independent contract version, kept no runtime dependencies and Apache/DNG notices, completed pinned artifact-action inventory, shipped readable policies and npm-safe README links. Existing license/SPDX/package/browser gates remain unchanged. |
+| Automation/publishing/discovery | Added docs/packed-consumer verification to existing CI/publish verification jobs; retained separate minimal OIDC publish job, protected exact-main tag and tarball checksum controls. Confirmed public protected main and active v* tag ruleset. Account-side npm trusted publisher remains an owner publication prerequisite. |
+| Site handoff | Engine repository/package/docs are public navigation destinations. Site-side discovery #45/navigation #298/environments #300 own hosting and links; no unpublished route/deployment is invented. Site content was not verified after HTTP 403. |
+
+## Examples, paths and package verification
+
+The automated documentation checker validates **2,096 repository/local links** in the current Markdown tree and generated reference synchronization. It verifies every importing snippet's actual root symbols. **63 complete importing snippets** typecheck strictly and execute in an isolated ESM consumer installed from the real packed candidate, plus quick-start and production/paired-export examples. The latter uses the existing final-conformance fixture through the actual public package, not copied runtime algorithms or test-helper imports.
+
+**26 composition fragments** have explicit prior-binding captions and [a dependency inventory](validation/documentation-fragments.json). These illustrate joining previously validated domain values; they are not claimed to run without those inputs. The public complete production example supplies actual owned synthetic data without inventing calibration or implicit defaults. Repository/local navigation is verified against actual paths/anchors, including public main-source links; external standards and archived references are citations rather than runtime fetches.
+
+Pack checks retain root-only ESM/declaration surface and exclude `src/api`, source, tests and tooling. The package includes README, docs, examples, LICENSE/NOTICE and the referenced policy files so consumer links do not require a checkout. Documentation hosting and application implementation remain outside the package license boundary.
+
+## Validation and exact candidate evidence
+
+- Exact locked dependencies; maintained Node policy unchanged, official lifecycle reviewed 2026-10-02 (22 Maintenance LTS / 24 Active LTS; 26 still Current).
+- Static/type/lint, license allowlist, SPDX, identity and browser graph pass; 138 browser-reachable modules.
+- Local full check and coverage: **1,597 passing / 1 known unchanged-main Mac `equivalence-38` exact hash failure**, 142 files. No golden, assertion, threshold, scientific tolerance or seed schedule is changed. Exact-head Linux CI on Node 22.13/24 remains the required passing full-suite authority; attach its outcome to the review PR before merge.
+- Build, root/package-content check, documentation/reference check and real packed-consumer declaration/runtime checks pass. The informational existing image-formation benchmark completes. Recorded tier/performance/independent-reader/editor acceptance remains applicable within its prior explicit limits because runtime syntax and model identities are unchanged.
+- Final diff preserves scientific execution syntax across all 141 modules. Source comments, distribution metadata, docs and release-verification tooling are the changes.
+
+Substantive owner review and contribution-specific DCO 1.1 certification are still required for this release-preparation contribution. After signed merge, final-main CI and tested-tree equality must be recorded before #180 closes and the owner tags `v1.0.0`. This audit does not certify an untested later commit or publish any artifact.