@photivra/engine 1.5.0 → 2.0.0

package/docs/NATIVE_CAPTURE_SDR_REVIEW.md

@@ -1,37 +0,0 @@
-# Native capture SDR candidate review
-
-Technical review date: 2026-10-03. Initial PR #216 head: `1bfdb87c6111299dda4649b03d787e6aff60cf15`; base: `a57bdecd73e1b64ab404415ae95494423756286a`. This record and its follow-up tests are AI-assisted draft material. They support, but do not supply, the substantive human review required by [repository instructions](../AGENTS.md) and [provenance policy](PROVENANCE.md#ai-assisted-work).
-
-## Scientific and execution assessment
-
-The new executor calls the existing `calculateSdrRendering` for every tile. Its supported exposure normalization, tone curve, gamut policy, transfer and quantization are component-local; no operation needs neighboring pixels or full-frame statistics. Consequently a tile partition preserves the reference arithmetic. The reference implementation and its 262,144-component guard are unchanged. New parity tests compare every integer component and aggregate diagnostics across 256-column/32-row boundaries using both declared float precisions, both bit depths, both tone curves and both gamut policies. Float32 comparisons use the actual float32-rounded source values; they do not assert float64 fidelity. Independent endpoint/tie and megapixel-coordinate tests supplement shared-implementation parity.
-
-The source parser enforces RGB channel order, plane dimensions/binding, transform history, external layout, finite positive reference white and capture identities. Planning adds the exact linear-sRGB/D65 profile/reference white, completed WB state, fresh output state, representable rendering scale, raster caps and output admission. A valid capture containing pending WB intent is deliberately rejected. Four oriented off-center active-capture cases now compare actual reference pixels as well as retained geometry. Later output crop intent stays in the capture; this API does not execute that crop on an active-capture plane.
-
-The [ICC sRGB registry](https://registry.color.org/rgb-registry/srgb), checked on the review date, supports the unchanged transfer constants, primary/white coordinates and 80 cd/m² encoding reference. These are mathematical/encoding facts, not a calibrated camera, perceptual gamut mapping or a display measurement. Exposure is post-capture rendering scale; positive per-channel Reinhard can alter chromaticity. Capture saturation, noise, source range history and physical exposure are retained separately from output clipping. No new physical equation, WB estimator, serializer, correction/resampler or production stage is introduced.
-
-## Source and resource assessment
-
-The change introduces no runtime dependency or copied third-party image, profile binary, calibration dataset or implementation. The benchmark generates a coordinate ramp directly into bounded tiles. Its source SHA declarations are explicitly synthetic placeholders. The ICC reference is used to check numerical facts; no reference prose/code/data is incorporated by this review. These observations do not certify original authorship, rights to distribute or absence of patent claims. Contributor review and DCO remain required.
-
-Admission precedes retained output allocation and tile acquisition. Provider backing storage is bounded, not just its visible view. Precision/rectangle/source identifiers and exact stride length are checked; padding is ignored and nonfinite image values fail. SharedArrayBuffer rejection now has a regression. Logical scratch is provider storage plus packed input, parser copy and four reference output arrays: `32768 × 8 + 256 × 32 × 3 × 8 × 6 = 1,441,792` bytes. JS allocation/GC overhead and provider/device memory are excluded. Retained output limits are 72 MB at 8 bits and 144 MB at 16 bits.
-
-The task keeps partial output private, clears it on failure/cancel/dispose, and transfers it once. Activity is checked after both acquisition and host yield. Added tests cover disposal while a yield is pending, late settlement, and real timer cancellation. A provider that ignores abort can still delay settlement; caller resource reuse requires draining the pending run. Host scheduling, artifact authentication and source/device admission remain caller responsibilities. Identity declarations do not authenticate supplied samples.
-
-## Compatibility and release assessment
-
-Package, lock root, citation and engine API are aligned at 1.2.0. Schema, model, POC and plan identities remain independent. The runtime diff adds a root module/export and version increment; it does not alter existing rendering equations or API contracts. Archived JPEG fixtures, manifest bytes/hashes and independent decoder evidence are unchanged. Golden replay uses the recorded creator, while a separate current-creator regression checks current exports and identical integer pixels.
-
-The follow-up corrects 49 current release-context headers to 1.2.0 and links them to the current release procedure. Historical introduction/measurement values are retained. The additional 24 MP/16-bit benchmark measures the maximum retained code buffer; see [validation evidence](NATIVE_CAPTURE_SDR_VALIDATION.md). No universal performance threshold follows from those measurements.
-
-Full local check and coverage passed with 1,739 tests on Node 26.8.1. Coverage: statements 91.94%, branches 88.36%, functions 99.62%, lines 91.89%. Build, generated reference/docs, packed typed consumers, package surface and image-formation benchmark passed. Local HTTP tests required port access outside the sandbox; package dry-run used a writable temporary npm cache. The original head passed all four Node CI jobs. Follow-up-head CI must also pass before merge. Repository search found no other open engine PR requiring version reconciliation. Public npm lists 1.1.0 as its newest version and no 1.2.0; the remote `v1.2.0` tag is absent as of this review.
-
-## Remaining owner gates
-
-- Substantive human scientific/source review of the final diff, supported domains, provider obligations and evidence. No human review submission was present during the initial inspection.
-- Contribution-specific DCO certification. Neither original PR commit contains `Signed-off-by`; this AI-assisted follow-up does not assert the contributor's certification. Resolve the complete candidate's certification before inclusion, without fabricating or silently rewriting sign-offs.
-- Green supported Node CI at the final reviewed head, then mark ready and merge through repository protections.
-- Verify final-main CI/tree, main/tag protections and npm trusted-publishing configuration before separately approved tagging/publication. Repository workflow checks those release prerequisites; this review does not verify account-side configuration.
-- Keep #215 publication acceptance and downstream producer/device activation pending until the reviewed distribution exists and their separate evidence is supplied.
-
-No merge, tag or publication is authorized by this review record. Follow [the release procedure](RELEASE_1_2_0.md) after the required owner gates.

package/docs/NATIVE_CAPTURE_SDR_VALIDATION.md

@@ -1,34 +0,0 @@
-# Native capture SDR validation
-
-This is owned synthetic mathematical/resource evidence for schema 0.1.0. It is not device/backend qualification, calibrated camera accuracy, source artifact authentication or human review. Public contract and limitations are in [bounded native SDR](NATIVE_CAPTURE_SDR.md).
-
-On 2026-10-03, Node 24.19.0 on darwin/arm64, the repository benchmark produced these sampled values. It yields with setImmediate and evaluates an analytic RGB ramp directly into bounded float64 tiles, so it does not allocate a full-size linear source. Source/digest declarations are synthetic placeholders. Baseline process memory is sampled before each raster; GC runs between cases but does not necessarily return resident memory to the OS. These are sequential runs in one process, not clean-start comparisons.
-
-| Raster | Codes | Elapsed | Output payload | Largest provider tile | Sampled peak RSS | Sampled peak heap |
-| --- | --- | --- | --- | --- | --- | --- |
-| 3000 × 2000 | 8-bit | 2.310 s | 18.0 MB | 196,608 bytes | 229.49 MB | 84.28 MB |
-| 6000 × 4000 | 8-bit | 9.120 s | 72.0 MB | 196,608 bytes | 317.54 MB | 93.44 MB |
-| 3000 × 2000 | 16-bit | 2.335 s | 36.0 MB | 196,608 bytes | 312.49 MB | 83.21 MB |
-
-Raw measurements, baseline values and output hashes are retained in [the machine-readable record](validation/native-capture-sdr-darwin-arm64.jsonl). Earlier development-candidate runs produced the same 8/16-bit output hashes; the retained record is from the aligned 1.2.0 candidate. The 16-bit hash describes typed-array backing bytes in this host's endian order, not a portable serialized format. No peak-allocation guarantee or CPU/device threshold is inferred from sampling. The 1,441,792-byte logical tile scratch bound excludes JS object/array/GC overhead; the measurements visibly exceed it. Provider/master/GPU/encoder retained costs remain external caller obligations.
-
-Regression acceptance compares exact integer pixels, encoding and aggregate clipping diagnostics against the unchanged reference for 259 × 33 rasters crossing all tile boundaries, at 8/16 bits. Additional tests cover upstream engine-resolved WB, all four oriented off-center capture geometries, ignored stride padding, float32/float64, Reinhard, independent sRGB rounding/tie endpoints, 1.2 MP global pixel coordinates, rejected source/color/state/resource inputs, stale rectangles/identities, oversized backing buffers and nonfinite image samples. Lifecycle tests cover pending-read and between-tile aborts, late completion, explicit output transfer, failed host yield, cancellation/disposal of ready/completed tasks, immutable setup/callback commitments and fresh-task recovery.
-
-Initial candidate validation: 1,735 tests passed under full coverage; statements 91.94%, branches 88.36%, functions 99.62%, lines 91.89%. Static/security/license/SPDX/identity/browser gates, build, generated documentation and packed consumer acceptance passed. The packed acceptance executes the new typed root-import example independently of the source checkout. Package dry-run passed with root exports only. CI repeats standard acceptance on Node 22.13/22/24/26 and the native-raster benchmark on Node 24.
-
-## Technical review follow-up
-
-The [review record](NATIVE_CAPTURE_SDR_REVIEW.md) documents scientific/source/execution assessment and outstanding human/DCO gates. The follow-up adds exact float32/float64 parity across both tone/gamut policies and code depths, reference pixels for all four off-center orientations, valid-container pending WB rejection, shared backing-buffer rejection, pending-yield disposal and actual timer cancellation. Full local checks and coverage passed with 1,739 tests on Node 26.8.1; the coverage percentages above are unchanged.
-
-On 2026-10-03, Node 26.8.1 on the same darwin/arm64 host, a sequential benchmark run after the test/consumer checks completed produced:
-
-| Raster | Codes | Elapsed | Output payload | Largest provider tile | Sampled peak RSS | Sampled peak heap |
-| --- | --- | --- | --- | --- | --- | --- |
-| 3000 × 2000 | 8-bit | 2.346 s | 18.0 MB | 196,608 bytes | 190.64 MB | 90.03 MB |
-| 6000 × 4000 | 8-bit | 9.114 s | 72.0 MB | 196,608 bytes | 258.82 MB | 80.96 MB |
-| 3000 × 2000 | 16-bit | 2.294 s | 36.0 MB | 196,608 bytes | 280.15 MB | 93.14 MB |
-| 6000 × 4000 | 16-bit | 9.167 s | 144.0 MB | 196,608 bytes | 412.14 MB | 80.92 MB |
-
-The [follow-up machine-readable record](validation/native-capture-sdr-darwin-arm64-node26-review.jsonl) preserves baselines, sampled peaks and hashes. All three earlier raster/code-depth hashes agree with the original Node 24 record. The new maximum 24 MP/16-bit backing-byte hash is `b4ab10fe9f6b8f083c5637561aa2a61fe447774b86504a8551b8cc784c815626`. Its host-endian interpretation and all earlier resource/source qualification limitations apply. Earlier measurements are retained; differences across runtimes/runs do not establish a performance improvement.
-
-The package/root candidate identity is 1.2.0, aligned with lock/citation and regenerated references. npm registry verification on 2026-10-03 found 1.1.0 as the latest published version and no 1.2.0 distribution. Follow [the 1.2.0 release procedure](RELEASE_1_2_0.md) after human review to run exact tag/publish gates. No existing published version is overwritten; implementation, human review, merge and publication are separate. #215's publication acceptance remains pending until that reviewed distribution exists. A consumer still requires a qualified authoritative RGB producer and measured device budgets before production activation.

package/docs/NATIVE_RAW_AND_PRINT.md

@@ -1,54 +0,0 @@
-# Native RAW and Print candidate contracts
-
-These native RAW and Print contracts are part of version 1.4.0. The optional execution chunk control described below is an unreleased additive change and is not available in the published 1.4.0 package. Production adoption requires separate downstream qualification.
-
-The separate `createNativeRawTask` contract accepts metadata without an inline image plane, then produces exact owned native codes, black levels, digital saturation codes and independent physical/pre-ADC/digital flags. Admission is limited to 24 million sites, 16,384 pixels per dimension, 256 sites per tile, and an explicitly admitted seven-byte-per-site payload. The reference 4,096-site RAW path is unchanged. Absolute CFA coordinates and absolute-index charge/read-noise seeds preserve reference arithmetic across tile boundaries.
-
-`createNativeEnvironmentRawTask` invokes actual source radiance callbacks through shared projection, shutter, optical throughput, pupil/PSF and EQE calculations. It admits no more than 100,000 source evaluations per tile and requires a whole-event budget no greater than two billion. Source visibility, measured radiometry, convergence and physical transport remain provider responsibilities. The optional immutable photo-tile observer exposes bounded expectation values before noise or clipping. Observers receive the event AbortSignal for pending resource work. Source callbacks stop immediately when the event is aborted; observer failures and cancellation withhold output. `productionPlanActivated` and transport verification remain false.
-
-`createNativeRawDevelopmentTask` snapshots one exact packed RAW and applies the shared reconstruction kernels, declared camera RGB-to-XYZ approximation, white balance exactly once, and shared SDR rendering. Every used phase and kernel halo must lie inside actual native support: no padding or weight renormalization. Output crop and orientation are bound to the capture geometry; this stage supports 1:1 output sampling. Retained payload admission counts the owned RAW copy and integer output, not caller buffers, JavaScript heap or GPU storage.
-
-All tasks require host yields, publish only whole successful outputs, distinguish failure/cancellation/disposal, and transfer output ownership once. Typed storage must have an exact owned ArrayBuffer; shared buffers and hidden larger parent allocations are rejected. Metadata provenance and declared hashes do not establish producer authenticity.
-
-
-### Optional smaller execution chunks (unreleased)
-
-`NativeRawInput.tileWidth` may explicitly select an integer from 1 through 256 native sites. Omission retains the original 256-site execution and original plan shape. An explicit width is copied into the immutable plan and changes only tile count, provider request widths and yield frequency. Absolute native CFA coordinates, noise seeds, rolling exposure windows and all output codes/flags are unchanged. This control does not change physical sampling or quadrature.
-
-Smaller chunks can admit an unchanged high-query-per-site optical event under the existing 100,000-query tile cap. The two-billion whole-event cap and 24-million-site/output-byte limits remain unchanged; a smaller tile never establishes convergence, qualified source transport or production activation. For example, 64 sites with 1,024 source queries per site need 65,536 queries in a tile, while 256 sites would exceed the tile cap. The caller must still satisfy the full-event budget and qualify the source and result independently.
-
-## Print stage
-
-`createPrintJpegTask` accepts explicitly encoded sRGB 8-bit RGB in an already oriented output raster. It crops only within actual source support and rejects enlargement, stretching and unsupported aspect ratios. Original area filtering decodes this declared post-SDR stage to linear values, integrates exact pixel overlap, then encodes and quantizes sRGB. This does not recover sensor headroom or reprocess RAW. Source reads are bounded to 256 × 32 pixels; JPEG coding uses 8 × 8 blocks. Edge replication is restricted to final JPEG coding blocks, not reconstruction or crop support.
-
-The original baseline JPEG encoder embeds an original ICC v4.3 sRGB matrix/TRC profile, EXIF orientation 1, sRGB ColorSpace and final pixel dimensions. Its XMP records the immutable Print plan and declares source bytes unverified. Encoded output is explicitly budgeted to at most 256 MB and provider reads to one million. The caller owns the final file and must separately qualify browser save/share, byte-size requirements and printer/substrate appearance.
-
-The ICC serializer uses the existing engine sRGB primaries and transfer function, standard numerical Bradford adaptation to D50 PCS and original ICC tag serialization. This profile adaptation does not introduce a shooting white-balance model. Numerical facts and format references: [ICC sRGB interpretation](https://registry.color.org/rgb-registry/files/sRGB.pdf), [ICC profile specification](https://www.color.org/icc34.pdf). No third-party ICC profile bytes or implementation were redistributed.
-
-## Reproducible validation
-
-`test/native-raw.test.ts`, `test/native-environment-raw.test.ts`, `test/native-raw-development.test.ts` and `test/print-jpeg.test.ts` cover small-reference parity, absolute odd-width phase/seed boundaries, orientation, signed below-black noise, whole-output budgets, corrupt providers, support halos and cancellation/ownership.
-
-Run the optional actual megapixel test with `PHOTIVRA_VALIDATE_MEGAPIXEL_RAW=1 PHOTIVRA_RAW_REPORT=/tmp/native-raw-report.json npx vitest run test/native-raw-megapixel.test.ts`. It executes every one of a million native sites, develops that exact RAW and downsamples to a 500 × 500 ICC JPEG. The constructed count inputs are not a qualified megapixel scene-radiance capture.
-
-Generate the separate original color, checker, asymmetric fractional crop, gray ramp and one-megapixel JPEG controls with `node scripts/generate-native-print-jpeg.mjs /tmp/native-print`. Validate actual bytes using `python scripts/verify-native-print-jpeg.py /tmp/native-print /tmp/native-print/validation.json` in an environment with NumPy and Pillow/LittleCMS. The independent area oracle expects 188 for a half-black/half-white sRGB checker reduction, rather than an encoded-value average. JPEG tolerance is four encoded codes; the original ICC is compared against LittleCMS sRGB over a 17³ color cube with a one-code budget.
-
-These controls do not qualify all product fixtures, calibrated sensor/lens behavior, diffraction, full production depth composition, physical phone/tablet resources, printer appearance, platform save/share or substantive human review. See the application qualification record for its separate source and deployment gates.
-
-## Standalone bounded Print example
-
-This executable control declares a constant encoded RGB source. The zero digest is a placeholder declaration and is not authenticated by the engine; a product should bind its actual retained artifact and enforce qualification before offering export.
-
-```ts
-import { createPrintJpegTask, createSrgbIccProfile } from '@photivra/engine';
-const source = { captureId: 'owned-control', imageStateId: 'encoded-control', artifactId: 'constant-gray',
-  sha256: '0'.repeat(64), width: 16, height: 16, encoding: 'encoded-srgb-8-rgb' as const };
-const task = createPrintJpegTask({ source, crop: { x: 0, y: 0, width: 16, height: 16 },
-  outputWidth: 8, outputHeight: 8, quantizationStep: 1, maximumEncodedBytes: 16000, maximumProviderReads: 100 }, {
-  readTile: async request => ({ ...request, samples: new Uint8Array(request.width * request.height * 3).fill(128) }),
-  yieldControl: async () => { await new Promise<void>(resolve => setTimeout(resolve, 0)); }
-});
-await task.run();
-const jpeg = task.takeOutput();
-if (jpeg.bytes.length === 0 || jpeg.width !== 8 || createSrgbIccProfile().length === 0) throw new Error('Control failed');
-```

package/docs/NUMERICAL_CORRECTNESS.md

@@ -1,191 +0,0 @@
-# Numerical Correctness and Physical Units
-
-Release context: **package 1.2.0 candidate / root API 1.2.0**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_2_0.md).
-
-Photivra is a scientific engine. Numerical behavior and physical-unit meaning are public-contract concerns, not implementation details.
-
-This document defines the repository-wide numerical policy used by public calculations, parsers, schemas, tests, and composed image-formation work.
-
-## Core rules
-
-- Public physical quantities must use explicit units in field names unless the type itself unambiguously owns the unit.
-- The same physical concept should use the same unit and property name across modules.
-- Coordinate-system identity is part of the quantity definition. A number is not interchangeable merely because it has the same dimensional unit.
-- Public calculation results must remain JSON-safe. `NaN` and numeric infinities are not valid calculation outputs.
-- Invalid scientific inputs fail explicitly rather than being silently clamped, coerced, defaulted, or reinterpreted.
-- Unknown, unbounded, absent, and unsupported states must be represented semantically rather than by magic numeric sentinels.
-- Unit conversion happens exactly once at an explicit boundary.
-- Mathematical simplifications must not erase axis dependence, sign conventions, physical stage, provenance, or applicability.
-
-These rules supplement `docs/API_STYLE.md` and the coordinate/model rules in `docs/PHYSICS_FOUNDATION.md`.
-
-## Canonical public units
-
-Photivra does not require one internal SI-only representation. It does require explicit, stable units at public boundaries.
-
-Common conventions include:
-
-| Quantity | Public convention |
-| --- | --- |
-| focal/image/sensor distances | millimetres when named `*Mm` |
-| scene/object/focus distance | metres when named `*M` |
-| sampling pitch | micrometres when named `*Micrometers` |
-| time / exposure duration | seconds when named `*Seconds` |
-| wavelength | nanometres when named `*Nanometers` / `*Nm` |
-| angle | explicit radians/degrees fields, never an unlabeled angle |
-| ISO / exposure index | dimensionless named camera setting |
-| normalized factors / weights | dimensionless; document normalization and valid range |
-| spectral irradiance | explicit radiometric unit including wavelength-density basis |
-| irradiance | W/m² when physically calibrated |
-| radiance | W/m²/sr, with /nm when spectrally resolved |
-| electrons / photons / RAW codes | explicit domain-specific counts/codes; do not interchange |
-
-Do not infer units from neighboring fields or documentation when the public field name/type is ambiguous.
-
-## Coordinate identity
-
-A physical unit alone does not identify a coordinate.
-
-For example, these are different domains even when expressed in millimetres or pixels:
-
-- native sensor raster coordinates;
-- oriented capture raster coordinates;
-- output raster coordinates;
-- optical image-plane coordinates;
-- sensor physical coordinates;
-- scene/world coordinates.
-
-Crossing coordinate systems requires an explicit exported transform or a documented model boundary. Do not implement ad-hoc sign changes, axis swaps, recentering, or crop-local reinterpretation.
-
-## Finite-number policy
-
-Public calculation envelopes must not contain non-finite numbers.
-
-The existing `CalculationResult<T>` constructors recursively validate returned numeric values. If a calculation would emit `NaN`, `Infinity`, or `-Infinity`, it fails with `InvalidScientificResultError`.
-
-Inputs that are required to be finite must fail with a typed/domain validation error before the calculation proceeds.
-
-When the scientific state is genuinely unbounded, represent that state semantically. Example: depth of field uses `null` for an infinite far limit rather than numeric `Infinity`.
-
-Do not rely on JSON serialization to convert or erase non-finite numbers.
-
-## Domains and ranges
-
-Validation should distinguish:
-
-1. **structural validity** — correct type/shape/discriminant;
-2. **numeric validity** — finite, integer, nonnegative, positive, bounded fraction, etc.;
-3. **scientific applicability** — value lies inside the model/profile/calibration operating range;
-4. **composition compatibility** — independently valid inputs are valid together.
-
-Do not silently widen a model's operating envelope to accept a caller value.
-
-For reusable bounded ranges:
-
-- state units;
-- state whether endpoints are inclusive;
-- reject reversed ranges;
-- preserve exact evidence/applicability when calibrated;
-- do not extrapolate unless the model explicitly defines and labels extrapolation.
-
-## Exact equality vs tolerance
-
-Photivra does not use one global epsilon.
-
-Use exact equality when the contract is exact, including:
-
-- IDs, versions, enum/discriminant values;
-- integer/raster identities;
-- explicit zero/no-op states when represented exactly;
-- deterministic serialized/canonical structures where bitwise identity is part of the contract;
-- algebraic results whose implementation is expected to be exact in the represented arithmetic.
-
-Use a documented tolerance when floating-point evaluation is inherently approximate, including:
-
-- transcendental functions;
-- iterative numerical methods;
-- quadrature/integration;
-- interpolated calibration data;
-- numerically conditioned inverse mappings.
-
-Tolerance selection must be tied to the quantity, numerical scale, conditioning, algorithm, and scientific claim. A looser tolerance must never be used merely to hide an unexplained regression.
-
-Prefer:
-
-- absolute tolerance near a known scale/zero;
-- relative tolerance for scale-proportional quantities;
-- convergence/refinement tests for sampled numerical methods;
-- independently derived analytical/reference values where available.
-
-## Rounding and quantization
-
-Rounding is a scientific/output operation when it changes represented data.
-
-- Keep calculations in the highest practical deterministic precision until a defined output boundary.
-- Pixel/raster integer rounding rules must be explicit.
-- RAW/export quantization must define scale, offset/black level, clipping, rounding/tie behavior, and code range.
-- Do not round intermediate physical values for display convenience.
-- Do not let serializer/container limitations redefine the authoritative scientific value.
-
-## Signed zero and tiny values
-
-Do not use `-0` as a semantic state.
-
-When a public result is mathematically zero, normalize or test it according to the owning model if signed zero could leak into serialization/identity. Do not indiscriminately clamp small nonzero values to zero; that requires a documented model/tolerance decision.
-
-## Overflow, underflow, and extreme inputs
-
-Public functions must fail safely when arithmetic leaves the valid numerical/scientific domain.
-
-- A finite input does not guarantee a finite computed result.
-- Check derived values where overflow or invalid denominators can occur.
-- Avoid transformations that turn a detectable invalid state into an apparently plausible finite number.
-- Extreme-value tests should target the model boundary, not arbitrary machine limits alone.
-
-If a stable reformulation is needed for numerical conditioning, it must preserve the documented scientific model and provenance.
-
-## Determinism and runtime expectations
-
-For identical validated inputs and fixed stochastic seeds, the engine should produce deterministic scientific results within the documented contract.
-
-Do not depend on:
-
-- object iteration order that is not part of the serialized contract;
-- current wall-clock time;
-- random state without an explicit seed;
-- network/service responses;
-- renderer/UI state;
-- machine-specific hidden calibration.
-
-Browser-safe public code and supported Node runtimes must share the same semantic result contract. If an implementation permits small runtime-dependent floating-point differences, acceptance tolerances must be explicit and scientifically harmless.
-
-## Testing requirements
-
-Numerical tests should use the strongest applicable form:
-
-1. exact identity/invariant;
-2. independently derived analytical constant;
-3. dimensional/unit relation;
-4. monotonic/bounded behavior;
-5. round-trip/inverse invariant;
-6. numerical convergence/refinement;
-7. calibrated/reference tolerance with provenance.
-
-The canonical `test/fixtures/basic-reference-scene.json` fixture is the preferred shared reference for cross-domain deterministic cases once available.
-
-Do not generate the only expected value by calling the same production function under test.
-
-## Changes to numerical behavior
-
-A change that alters public numerical meaning must document:
-
-- equation/model change;
-- units and coordinate system;
-- assumptions/applicability;
-- old vs new behavior;
-- tolerance/precision impact;
-- API/schema/version impact;
-- provenance/uncertainty consequences;
-- migration implications when relevant.
-
-A pure implementation optimization must preserve the same scientific result semantics and provenance within the existing contract.

package/docs/PERFORMANCE_BASELINE.md

@@ -1,56 +0,0 @@
-# Measured-performance baseline: #43 / #45
-
-Release context: **package 1.2.0 candidate / root API 1.2.0**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_2_0.md).
-
-This independent first slice records merged main `83a99a4c1ec525fd1add7cccff134fcee0f5159b`, root API 0.93.0, POC API 0.20.0, in `docs/benchmarks/2026-10-01-main-baseline.json`. No pending capture/output/correction/preset implementation is consumed. It does not close either issue or justify an optimization by itself.
-
-## Context and method
-
-Measurements used Node 24.19.0/V8 13.6.233.17-node.51 on shared Linux x64 execution infrastructure reporting AMD EPYC 9V74 and 9 logical CPUs. This is not the user's Mac, a browser frame-time result or a dedicated machine. Local source was restored to the recorded main snapshot and transpiled with Node's type stripper because canonical TypeScript tooling is unavailable locally; this build method is explicit in the artifact. The script's source commit/build label is operator-attested, not independently verified by the script. CI separately verifies the canonical build/gates.
-
-The existing #43 sampling benchmark retains its 33x33 field and 5 temporal samples, alternating scalar/batch pairs, nine measured repeats and five inner repeats. It is reused unchanged. New `scripts/benchmark-composed-baseline.mjs` measures four whole POC request shapes against #130: base, 16 defocus samples, 16 samples each of defocus/size/motion, and the same mixed set with portrait/off-center staged capture. Each scenario has 200 warmup requests and nine 100-request blocks; scenario order rotates. Both ordinary and forced-GC-assisted runs are recorded, not combined. Net post-GC retained heap is **not** allocation count or GC-pause evidence.
-
-| POC scenario | Ordinary median µs/request | Forced-GC-assisted median µs/request |
-| --- | ---: | ---: |
-| Base | 13.17 | 16.88 |
-| Defocus 16 | 29.20 | 36.77 |
-| Mixed 16 per kind | 62.46 | 76.05 |
-| Staged portrait mixed | 124.76 | 130.16 |
-
-These distributions establish reproducible request shapes, not portable speed constants or ordinary-vs-GC causality. Raw timing/heap samples are retained in the artifact.
-
-## Findings and disposition
-
-For #43, existing lateral-CA batch/scalar median ratio was 0.628 (about 37% shorter in this run); radial batch ratio 1.019 showed no benefit in this run. Vignetting and temporal rotation remain recorded microbenchmark candidates, not demonstrated consumer hotspots. This supports retaining the existing narrow CA batch surface, not adding a generic prepared engine abstraction now.
-
-For #45, a separate ordinary V8 CPU-profile run had 250 sampled stacks inside `simulatePocCamera`; 83 included `calculateThinLensImageDistance` (33.2%). 157 included recursive finite-result validation (62.8%). These are **overlapping inclusive sampled stacks** and cannot be summed or equated to exact time/savings. Zero samples attributed to `requirePositiveFinite` do not imply zero validation work; sampling/inlining can hide frames. Startup/outside-call samples are excluded from the fraction denominator. The profiled run's timings are not used in the unprofiled timing table.
-
-Repeated projection/result validation is therefore a plausible bounded investigation target, but no reuse candidate, amortization break-even, retained prepared-state cost, exact equivalence corpus, actual consumer frequency or browser behavior has been demonstrated. **No runtime optimization is implemented and neither issue receives a final no-change closure.** After representative V1 composition/output paths merge, repeat profiling with those paths and relevant browser/worker consumers; then compare the smallest internal request-scoped reuse candidate, or record a supported no-change decision. No public context/cache or API/version change is justified here.
-
-## Reproduction
-
-Use a checkout of the commit being measured and build it before measuring; retain runtime/hardware/commit context for every comparison. The new script is developer tooling, not the browser root. Example after `npm ci` / `npm run build`, replacing the commit with the exact source revision used:
-
-```sh
-node scripts/benchmark-composed-baseline.mjs --commit=83a99a4c1ec525fd1add7cccff134fcee0f5159b --build-method=tsc
-node --expose-gc scripts/benchmark-composed-baseline.mjs --commit=83a99a4c1ec525fd1add7cccff134fcee0f5159b --build-method=tsc
-node --expose-gc scripts/benchmark-image-formation.mjs
-node --cpu-prof --cpu-prof-name=poc.cpuprofile scripts/benchmark-composed-baseline.mjs --commit=83a99a4c1ec525fd1add7cccff134fcee0f5159b --build-method=tsc
-node scripts/summarize-composed-cpu-profile.mjs poc.cpuprofile
-```
-
-To reproduce this historical engine baseline after the tooling lands, use the recorded engine checkout plus these tooling scripts, rather than labeling a newer engine build with the old SHA. Do not commit raw CPU profiles: they can contain private local paths. The summary emits fixed public function categories only. The archived artifact contains no raw profile/path or source-private metadata.
-
-Scripts and scenarios are independently authored using the owned canonical fixture and existing benchmark. No third-party code/data or dependency is incorporated. AI-assisted draft remains subject to human review and DCO certification; performance evidence is not scientific/provenance certification.
-
-## Subsequent bounded #45 experiment
-
-The baseline conclusions above are historical. [POC_PROJECTION_REUSE.md](POC_PROJECTION_REUSE.md) records the main 0.103.0 request-local defocus candidate, paired whole-request timing, preparation, separate allocation sampling and complete-response equivalence. It advances #45 independently; it does not change #43's disposition or establish browser performance.
-
-## Subsequent bounded #43 experiment
-
-The baseline conclusions above are historical. [GEOMETRIC_PREPARATION_REUSE.md](GEOMETRIC_PREPARATION_REUSE.md) records the main 0.103.0 call-local geometry-preparation candidate, real merged sampling/correction consumers, separate CPU/allocation evidence and scalar/copy-safety tests. It advances #43 independently and does not establish browser performance or #45's conclusion.
-
-## Final V1 remeasurement
-
-[Final V1 performance disposition](V1_PERFORMANCE_DISPOSITION.md) records current main #204, fresh paired timing/equivalence, preparation/memory profiles and dense executed environment-to-RAW evidence. PR #205 merged the final reviewed/signed no-further-change disposition; PR #206 merged final conformance. The measured engine commit remains the historical benchmark identity. Earlier candidate and pending-remeasurement statements above are historical.

package/docs/PHOTOGRAPHIC_EXPORT.md

@@ -1,206 +0,0 @@
-# Simulated Sensor RAW DNG / JPEG export
-
-Release context: **package 1.2.0 candidate / root API 1.2.0**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_2_0.md).
-
-Current producer-derived files and external closure gates are recorded in
-[Export acceptance](EXPORT_ACCEPTANCE.md). The new reproducible generator uses
-current typed fixtures; the earlier pinned serializer-only files remain historical.
-
-See [Reference RAW frame compatibility](RAW_FRAME_ENVELOPE.md) for stage-specific
-limits, full-native counting and parser preflight behavior.
-
-`createPhotographicExportPair()` is an optional browser-safe asynchronous export
-boundary. Both owned byte arrays come from one revalidated, privately copied RAW
-input. The JPEG never uses the capture's independent float planes. Web Crypto
-SHA-256 is required. No filesystem, clock, random generator, network or encoder
-dependency is added. Callers supply public identities and an explicit UTC event
-timestamp, and own saving the bytes.
-
-This is a bounded reference implementation. The entire native frame must contain
-at most **4,096 sites**, with complete single-frame, one-site-per-native-sample,
-registered 2×2 RGB Bayer coverage. RAW codes remain in native row-major CFA
-coordinates. A fixed repeating black tile and common digital white code are
-required. Below-black codes and original saturation codes are preserved without
-stretching to the 16-bit container limit. This does not support typical camera
-resolutions or establish calibrated camera behavior.
-
-## Explicit development
-
-`RawFrameReconstructionInput` supplies complete absolute CFA phase profiles and
-a native region covering the final crop. Existing reconstruction preserves
-signed black-subtracted values and exact weighted source contributions. Missing
-edge support fails; no automatic kernel, padding, sharpening or denoising runs.
-
-`ExportSensorColorProfile` explicitly declares an invertible 3×3 normalized
-camera-channel-to-XYZ/D65 matrix, owned/reusable numeric evidence, profile
-identity and limitations. Only approximation status is accepted. RGB/CFA names
-do not establish primaries, spectral response or calibration. Output kernels
-must use the declared RGB order and exact CFA profile. The reference white must
-map to positive camera-neutral coordinates.
-
-WB is explicitly `not-required` with no captured intent, or
-`apply-resolved-sensor-gains` with intent. Existing resolved camera-channel gains
-apply once before camera-to-XYZ and the existing XYZ-to-linear-sRGB transform.
-No second WB estimator runs. Existing SDR rendering handles rendering exposure,
-named tone mapping, clipping, transfer and 8-bit quantization. Rendering clipping
-is separate from RAW saturation.
-
-Only 1:1 output cropping is supported. The final oriented crop is translated
-through the active crop to exact native coordinates. JPEG pixels receive
-orientation once and EXIF Orientation=1. DNG keeps native pixels and records
-orientation, native ActiveArea and DefaultCrop. Resampling fails closed. JPEG
-coding replicates edges solely to fill partial 8×8 coding blocks; it does not
-supply missing reconstruction samples or change photograph dimensions.
-
-## Optional correction of the JPEG view
-
-The optional `correction` field reuses the choice contract documented in
-[CAPTURE_CORRECTED_SDR.md](CAPTURE_CORRECTED_SDR.md). Order is exact attached RAW
-reconstruction → resolved camera-channel WB → declared camera-to-XYZ/D65 →
-existing linear-sRGB transform → native-optical geometry/CA/gain correction →
-SDR → JPEG. The private intermediate plane contains only RAW-derived RGB; it
-replaces all independent float planes for this calculation and is never returned
-as a replacement capture. Parent `source` retains the exact RAW reconstruction,
-its provenance, site-level physical/digital saturation and source history.
-Intermediate RGB capture saturation is explicitly unmodeled; no scalar RGB white
-level is inferred from heterogeneous RAW site saturation flags.
-
-This branch requires reconstruction of the **full active native area**, square
-physical pixel pitch and 1:1 declared output crop sampling. The exporter supplies
-no prefilter, so `resampler.antialias` must be `none`; maps requiring compression
-filtering fail through the existing executor. It cannot claim a prefiltered input
-or silently create a filter. Correction state uses native output dimensions,
-exact committed optics and exposure-local time, independently of scene time.
-Profiles remain generic declarations for the post-color/WB linear-sRGB basis,
-not physical sensor-channel CA calibration. The pipeline does not redraw noise,
-blur or photons and does not activate reserved production stages.
-
-`invalidSupport` either rejects unavailable samples or chooses the existing
-largest joint-valid rectangle. `processedOutputView.rect` records that rectangle
-in the full oriented output raster, with dimensions used by JPEG SOF and EXIF.
-It is relative to the declared output crop, not the active/native sensor origin.
-The DNG's native codes, ActiveArea and original DefaultCrop remain unchanged;
-a nonlinear corrected JPEG cannot be represented by moving an uncorrected RAW
-crop. These paired files share the exact capture and source codes, while their
-processed geometry can differ. Physical focal equivalence remains capture-owned.
-
-The result exposes the processed `correction` calculation and a separate
-`rawCorrectionIntent` plan with application `metadata-only`. Custom XMP in both
-files records CorrectionProfileID/version, CorrectionSelectionKind/selections,
-ProcessedOutputRect and ProcessedIlluminationClippingEvents. CorrectionDisposition
-is `informational-intent-only` in DNG and `processed-view` in JPEG. This is
-informational metadata, not standardized DNG opcodes or a promise that editors
-apply the profile. Gain clipping events precede joint cropping and remain
-separate from RAW saturation and SDR gamut clipping. Full profile and choices
-enter SimulationHash; RawDataUniqueID still depends only on the exact RAW codes.
-Omitting correction preserves the original rendering/hash inputs and emits no
-correction XMP. The additive contract retains export schema 0.1.0.
-
-## Files and metadata
-
-DNG uses little-endian TIFF, version/backward version 1.1, one uncompressed
-16-bit CFA strip, CFA/black/white tags, inverse XYZ-to-camera ColorMatrix1,
-D65 CalibrationIlluminant1 and normalized AsShotNeutral. Rational values use
-bounded decimal approximations (maximum denominator 10^9); unsupported range
-or nonzero values rounding to zero fail. AsShotNeutral records development intent
-and does not alter RAW codes. No preview, compression, opcodes, NoiseProfile,
-calibration signature, RawImageDigest or NewRawImageDigest is claimed.
-
-JPEG is baseline sequential 8-bit YCbCr444 with an explicit constant quantization
-step 1..255, analytical DCT, custom canonical Huffman tables and byte stuffing.
-The step is not a manufacturer's quality scale. JPEG remains lossy at step 1.
-JFIF and EXIF ColorSpace=1 declare rendered sRGB; DNG is unclassified and carries
-the explicit virtual-camera matrix.
-
-EXIF records exposure, aperture, focal length, rounded 35mm equivalent when
-representable, dimensions, UTC event time/subseconds/offset, and ImageUniqueID.
-Integer selected virtual ISO ≤65535 is recorded as RecommendedExposureIndex
-with SensitivityType=REI: a simulation setting, not measured ISO speed or
-standard-output-sensitivity calibration. Make/Model identify Photivra's virtual
-camera, not a commercial device.
-
-XMP contains distinct xmpMM DocumentID/InstanceID and IPTC DigitalImageGUID per
-file, the caller-selected non-generative IPTC workflow type and the namespace
-`https://photivra.com/ns/simulation/1.0/`. SceneID/version are caller-declared
-public profiles bound to the capture's sceneStateId. SensorProfileID identifies
-the export color interpretation. SceneTime is simulation seconds, not wall-clock
-time. Finite focus distance is recorded; infinity never becomes a fake number.
-Private paths/GPS/serials and unsupported rights/calibration/AI fields are rejected.
-
-## Identity and lineage
-
-- SimulationHash is SHA-256 over sorted finite canonical JSON containing the
-  entire RAW frame, including capture identity/history/float planes, phase
-  profiles, region, color/scene profiles, WB policy, rendering, JPEG step and
-  the optional correction choice.
-  Save timestamp and artifact IDs are excluded. History changes may change the
-  hash without changing decoded pixels.
-- RawDataUniqueID is the first 128 bits of SHA-256 over versioned native
-  dimensions, CFA layout, 16-bit container declaration and exact codes. It is
-  not a standard RawImageDigest.
-- UniqueCameraModel includes public color profile identity/version and its full
-  hash; profile changes cannot silently keep the same family identity. File
-  SHA-256 fields hash exact returned bytes at creation.
-- Top-level pairing records JPEG generation from the exact attached RAW. Nested
-  metadata-only `imageDataPairing="not-verified"` retains its earlier projection
-  semantics. Upstream producer origin remains caller-declared/unverified. Hashes
-  are not signatures, C2PA or tamper-proof attestations.
-
-Returned arrays are owned and mutable; hashes describe creation-time bytes.
-Reconstruction/rendering calculation envelopes remain available for review.
-
-## Use and acceptance
-
-```ts
-import { createPhotographicExportPair, parsePhotographicExportInput,
-  type PhotographicExportInput } from "@photivra/engine";
-
-async function exportCommittedRaw(input: PhotographicExportInput) {
-  return createPhotographicExportPair(parsePhotographicExportInput(input));
-}
-```
-
-Callers supply actual committed input and explicit profile evidence. Test profiles
-are synthetic and are not suggested physical calibrations.
-
-Generate concrete acceptance files with `npm run build`, then
-`node scripts/generate-photographic-export-fixtures.mjs OUTPUT_DIRECTORY`.
-With an existing Pillow installation, run
-`python scripts/verify-photographic-export-fixtures.py OUTPUT_DIRECTORY`.
-This repository-only optional checker adds no engine dependency. It also uses
-existing lxml and LibRaw installations when available, and reports skipped
-checks explicitly. Both the 2×2 strip regression and 64×64 owned grayscale
-chart are generated with separate capture/artifact identities. The manifest
-records elapsed time and before/after heap usage for each bounded fixture;
-these are not peak-memory measurements or high-resolution evidence.
-
-Supplemental local checks use Pillow's independent TIFF-directory reader plus
-direct strip unpacking for exact RAW codes; Pillow decodes JPEG/EXIF and extracts
-XMP, and Python DOM parses both packets. Diverse 1×1, 7×8, 9×13 and 64×64 patterns
-decode at steps 1, 7 and 255; measured step-1 maximum channel error is ≤2 codes.
-Pillow cannot render the CFA photometric profile. LibRaw 0.21.2 independently
-opens, unpacks and processes the 64×64 DNG, retaining the native 64×64 size and
-WhiteLevel=1023. It rejects the 2×2 file as unsupported; that tiny file remains
-a strip/tag regression fixture, not an editor acceptance file. XMP attributes
-in both pair members are independently decoded and compared through DOM/Expat
-and lxml/libxml2. These checks do not establish Adobe acceptance, exact
-agreement between different demosaic/rendering algorithms or a complete
-schema-aware XMP implementation conformance claim.
-
-Concrete 64×64 files are checked into `test/fixtures/paired-export-acceptance/`
-for external review. Their owned synthetic ramp codes exercise the serializer,
-not the physical sensor producer. See its README for hashes and the exact
-remaining acceptance steps. No commercial-camera calibration is used.
-
-#16 is closed through reviewed/signed PR #201. [Export acceptance](EXPORT_ACCEPTANCE.md) records producer-derived pairs, independent LibRaw/TIFF/JPEG/XML checks, owner Lightroom orientation/as-shot/exposure/WB screenshots and landscape JPEG Photoshop/Chrome review, with unverified user-Mac hashes/builds explicitly preserved. The per-call API retains `independent-decode-required-editor-validation-pending`: it cannot attest that arbitrary newly generated bytes were checked in an external editor. That conservative result field is not the current issue status.
-
-Format references and DNG patent-license notice are recorded in `THIRD_PARTY.md`
-and `NOTICE`. No Adobe SDK or external encoder source is incorporated.
-
-Internal ownership: `src/color/sensor-color-development.ts` owns the declared
-sensor-channel gain → camera-to-XYZ → linear-sRGB calculation and conditioned
-inversion. Export retains profile/evidence validation, CFA binding, one-time WB
-authorization, geometry and DNG/JPEG container mapping. The adapter consumes
-validated data and does not infer sensor calibration or reuse the distinct ideal
-virtual-camera input contract. Existing arithmetic order and error policies are
-preserved; no public API or schema change is introduced.