@photivra/engine 1.5.0 → 2.0.0

package/docs/POC_API.md

@@ -1,278 +0,0 @@
-# Local POC Simulation API
-
-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 includes a minimal Node HTTP transport for proof-of-concept development and integration testing.
-
-It is **not** the recommended production runtime. Browser applications can consume the root `@photivra/engine` scientific surface directly; the production Photivra architecture is intended to keep the simulation math client-side rather than expose this unauthenticated POC server to the public internet.
-
-## Repository and package boundary
-
-`@photivra/engine` publishes only the runtime-neutral scientific/calculation surface.
-
-The Node HTTP transport remains in this GitHub repository under `src/api` as contributor/development tooling. It is **not** exported by the package and `dist/api` is explicitly excluded from the npm tarball.
-
-The HTTP layer adds request parsing, CORS response headers, routing, and serialization. It does not add camera-science equations.
-
-## Build and run from a repository checkout
-
-```sh
-npm ci
-npm run build
-node dist/api/poc-api-cli.js
-```
-
-This command is a repository-development workflow. Installing `@photivra/engine` from npm does not install or expose the POC HTTP server.
-
-Defaults:
-
-- bind host: `localhost` (loopback only);
-- API URL: `http://localhost:8787`;
-- CORS allowed origin value: `http://localhost:5173`.
-
-Overrides:
-
-- `PHOTIVRA_API_HOST`;
-- `PHOTIVRA_API_PORT`;
-- `PHOTIVRA_ALLOWED_ORIGIN`.
-
-The server is unauthenticated and therefore binds only to loopback by default. Setting `PHOTIVRA_API_HOST` to a non-loopback address exposes it beyond the local machine and is outside the security model supplied by this repository.
-
-CORS is a browser policy, **not** authentication or authorization. Non-browser clients can call an exposed endpoint regardless of its CORS header.
-
-The server accepts request bodies up to 64 KiB. It does not provide production rate limiting, authentication, quotas, reverse-proxy hardening, or abuse controls.
-
-## Health
-
-`GET /health`
-
-Example:
-
-```json
-{
-  "ok": true,
-  "service": "photivra-engine",
-  "apiVersion": "0.20.0"
-}
-```
-
-## Simulate
-
-`POST /v1/poc/simulate`
-
-Requests must use `Content-Type: application/json`.
-
-All physical quantities use explicit units in their property names.
-
-The POC transport reports the composed simulation contract version, not the root library `ENGINE_API_VERSION`. The current composed contract is exposed as `POC_SIMULATION_API_VERSION`.
-
-POC simulation API 0.20 composes projection using the selected focus plane. The response includes a `projection` block with ideal thin-lens image distance, scale relative to the infinity-focus approximation, and model provenance. Full-sensor field of view, crop field of view, object sampling, subject motion, and camera-shake projection use that same selected projection plane.
-
-### Sensor/capture composition in POC API 0.20
-
-POC simulation API 0.20 begins composing the standalone sensor/capture foundation **additively**.
-
-The existing request remains valid. New callers may opt into staged capture geometry with a `capture` object containing:
-
-- physical `orientation`;
-- optional native `activeCaptureRect`;
-- optional oriented `outputCropRect`;
-- optional final `outputRaster`.
-
-Compatibility rules are intentionally strict:
-
-- legacy `crop.factor` remains available for existing callers;
-- when `capture` is supplied, legacy `crop.factor` must be `1` so two crop models are not silently stacked;
-- legacy top-level `subjectCrop` response semantics remain unchanged when staged capture is absent;
-- with staged capture, subject framing is reported under `capture.subjectFraming` and is applied after declared output crop/resampling;
-- equivalent-viewing CoC in staged capture is based on the final retained physical image region used for viewing, including subject framing when present; output pixel count alone does not change it.
-
-The response keeps existing full-sensor/native-vector fields intact and adds an optional `capture` block with:
-
-- resolved native/active/oriented/output geometry, including final retained physical bounds;
-- active-capture and final-output FOV, including asymmetric bounds for off-center capture/output crop;
-- physical actual focal length plus active-capture diagonal-based 35 mm equivalence;
-- explicit oriented-capture→output pixel scaling;
-- optional capture-specific subject framing with final retained physical area and effective FOV;
-- explicit native-raster, oriented-capture, and final-output motion-vector diagnostics;
-- corresponding native-raster/oriented/output camera-shake vectors when camera shake is requested.
-
-Final digital/output crop does not redefine physical focal length or active-capture 35 mm equivalence. Physical `lens.focalLengthMm` remains the optical input.
-
-Sensor architecture metadata and radiometry-readiness profiles remain standalone foundations and are not yet composed into the POC.
-
-### Required request groups
-
-The request includes:
-
-- sensor physical imaging dimensions and native effective raster;
-- focal length and aperture;
-- shutter duration and ISO;
-- focus distance;
-- exactly one circle-of-confusion criterion:
-  - explicit target `circleOfConfusionMm`, or
-  - an equivalent-viewing reference sensor/CoC convention;
-- crop factor;
-- diffraction wavelength;
-- one representative object position and velocity.
-
-### Optional request groups
-
-The request may also include:
-
-- physical subject dimensions/distance for pixels-on-subject calculation;
-- named scene-plane distances for defocus sampling;
-- named physical objects for projected pixel sampling;
-- named object motion samples with explicit position/velocity vectors;
-- target subject-height fraction for framing crop;
-- controlled yaw/pitch camera-shake profile plus equivalent stabilization-stop attenuation;
-- ideal regular-polygon aperture blade count/orientation;
-- primary-subject diagnostics selecting a named motion sample.
-
-Named sample IDs must be non-empty and unique within their respective arrays.
-
-## Response semantics
-
-### Projection and field of view
-
-The top-level `fieldOfView` always describes the full sensor before digital cropping.
-
-`projection` reports:
-
-- selected focus distance;
-- ideal Gaussian thin-lens image distance;
-- scale relative to the infinity-focus `f` projection;
-- calculated model provenance.
-
-This remains ideal paraxial geometry, not a real-lens focus-breathing calibration.
-
-### Sensor and staged capture geometry
-
-The `sensor` response now includes the shared `SensorGeometryMetrics` result in addition to the backwards-compatible representative pitch fields. This exposes physical imaging-area crop factor, exact native-raster megapixels, and independent X/Y geometric sample pitch without treating sample pitch as photosite collection area.
-
-When the opt-in `capture` request is present, the response additionally exposes the staged geometry pipeline:
-
-```text
-native physical imaging area + native raster
-                ↓
-native active-capture rectangle
-                ↓
-physical camera orientation
-                ↓
-oriented active capture
-                ↓
-digital/output crop
-                ↓
-final output raster
-```
-
-Native sensor coordinates remain invariant under orientation. Active-capture FOV is calculated from the physical retained area, including off-center asymmetric angular bounds.
-
-Legacy projected-motion/camera-shake X/Y values use the existing image-plane basis (+X right, +Y up). Capture raster coordinates use +X right, +Y down. The capture diagnostics therefore expose the explicit conversion to `nativeRasterDeltaPixels` before rotating to `orientedCaptureDeltaPixels` and scaling to `outputDeltaPixels`; legacy fields remain unchanged.
-
-### Legacy crop
-
-`crop` reports the requested legacy centered crop factor, retained pixel dimensions/area, megapixels, and its effective field of view.
-
-If `subjectCrop` is requested, subject framing is composed **after** the fixed crop. The response distinguishes:
-
-- `additionalCropFactor`: framing crop relative to the fixed crop;
-- `totalCropFactor`: total linear crop relative to the full sensor.
-
-`subjectHeightFraction` is not clamped to 1. A value above 1 with `subjectClipped: true` means the projected subject is taller than the output frame.
-
-The framing calculation assumes the crop can be positioned around the subject; it does not validate subject position against source-image edges.
-
-### Sensor sampling
-
-The response exposes horizontal and vertical geometric sampling pitch plus their relative difference. The composed POC still uses the backwards-compatible horizontal pitch as its representative scalar for blur/sampling calculations and therefore rejects sensor geometry whose X/Y pitch differs by more than 1%. This prevents silent directional error until the composed POC becomes fully axis-aware.
-
-### Subject/object sampling
-
-
-When physical subject/object dimensions are supplied, projected dimensions are returned in sensor millimetres and pixels using the focus-aware projection plane.
-
-These values can drive pre-authored asset/detail selection without moving projection math into a renderer.
-
-### Defocus
-
-Named defocus samples return ideal geometric blur-circle diameters in sensor millimetres and pixels.
-
-### Subject motion
-
-Primary and named motion samples return representative-point sensor-plane displacement in millimetres and pixels, including signed x/y components.
-
-The model assumes constant world-space linear velocity. It can represent depth-direction motion of the representative point but does not model extended-object scale blur, rotation, acceleration, deformation, or occlusion changes.
-
-### Camera shake
-
-When supplied, camera shake returns unstabilized and stabilized global image-plane vectors.
-
-Yaw/pitch projection uses the selected focus-aware projection distance. Equivalent stabilization stops attenuate angular displacement by `2^-stops` and are explicitly labeled an approximation.
-
-The result is not a CIPA DC-011 measurement, real-camera stabilization rating, or spatially varying rotational optical-flow model.
-
-### Aperture and diffraction
-
-The optional aperture-shape response contains regular-polygon vertices plus idealized sunstar direction symmetry. Blade count is bounded to 1024.
-
-The separate diffraction result remains the ideal **circular-pupil** first-zero Airy diagnostic and reports `pupilModel: "ideal-circular"`.
-
-Polygon aperture geometry does not convert the circular Airy result into a polygon-aperture diffraction PSF.
-
-### Focus criterion
-
-For cross-format comparisons, the equivalent-viewing helper scales a caller-supplied reference CoC by the diagonal of the physical image region assumed to be enlarged to the final viewing size.
-
-Legacy requests continue to use the full physical sensor. In staged capture mode the target is the final physical region retained by active capture + output crop and, when requested, centered subject framing. Changing only the encoded output raster does not change this viewing criterion.
-
-This remains explicitly a viewing approximation, not a physical lens/sensor blur threshold. An explicit caller-supplied `circleOfConfusionMm` is never changed by crop or output geometry.
-
-### Primary-subject diagnostics
-
-When requested with the needed subject inputs, diagnostics report sampling, defocus, circular-pupil diffraction, optional named subject-motion path, and optional stabilized camera-shake path side by side.
-
-They are intentionally **not** collapsed into one sharpness score because these quantities describe different physical effects.
-
-### Provenance
-
-Aggregate response provenance is:
-
-- `calculated` when all included components are calculated models;
-- `mixed` when an equivalent-viewing focus criterion and/or camera-shake approximation is present.
-
-Component provenance identifies which parts are calculated versus approximate.
-
-## Validation and errors
-
-Decoded HTTP JSON is structurally checked for required object/array/string/finite-number/vector shapes before simulation.
-
-That parser does not duplicate every scientific domain/range rule. Scientific modules remain responsible for constraints such as positive dimensions, physically valid distances, blade-count bounds, and crop limits.
-
-Current transport responses include:
-
-- `200`: successful simulation;
-- `204`: CORS preflight;
-- `400`: malformed JSON/shape or invalid scientific request;
-- `404`: unknown route;
-- `415`: simulation POST without `application/json`.
-
-Error messages are intended for local development diagnostics and should not be treated as a hardened public error contract.
-
-## Reusable repository module
-
-Within this repository, `src/api/server.ts` exports an unbound `createPocApiServer` constructor for tests and trusted development composition.
-
-It is repository-internal development tooling rather than a supported npm subpath. Importing the module in repository tests does not start a listener; the CLI entrypoint is responsible for binding the configured host/port.
-
-## Important limitations
-
-- Local POC transport only.
-- No authentication or authorization.
-- No rate limiting or public-service abuse protection.
-- No persistence.
-- No scene uploads.
-- No calibration database.
-- No real-camera/lens claims.
-- ISO is an exposure/gain setting, not a noise shortcut.
-- Photon/noise primitives exist in the root library, but calibrated photon/noise output is intentionally absent from the composed POC until the radiometric/spectral/optical/sensor prerequisites are defensible.

package/docs/POC_PROJECTION_PLATFORM_REFERENCE.md

@@ -1,12 +0,0 @@
-# POC projection reference on macOS ARM64
-
-The unchanged historical 64-case response-hash corpus has one mismatch on macOS ARM64 with Node 24.19.0 and 26.8.1: `equivalence-38`. This mismatch also occurs when executing the original pre-optimization source at `c1374c31473f893310d1ce4f0d5a737aaba43ab5`. All 64 serialized responses are byte-for-byte identical between that original source, the released 1.0.1 baseline `c89e6e83eb7d4b625e12d496bcd51c58d6c7447b`, and the Print candidate `12f304f087d5cbe41266e2a81be2d6a1d521e692` on the verified host. The difference is therefore present in the archived reference on this platform; it is not introduced by projection reuse or the Print changes. The specific floating-point operation responsible has not been isolated.
-
-The separate `test/fixtures/poc-projection-reuse-darwin-arm64-reference.json` records the original executable's one differing SHA-256. The test selects this exact reference only for darwin/arm64 on the verified Node major lines 24 and 26. All other cases and environments retain the historical hashes. No tolerance, ignored field, regenerated candidate oracle, scientific implementation change, or historical fixture edit is introduced. A new mismatch still fails the test.
-
-To independently reproduce the reference, check out the original commit in an isolated directory, compile its original source with TypeScript 6.0.3, and run its built `simulatePocCamera()` over the unchanged inputs in `test/fixtures/poc-projection-reuse-reference.json` under each recorded Node runtime. Compute SHA-256 over `JSON.stringify(response)` using Node crypto. Compare all outputs with the baseline and candidate on the same host. The original build used the reviewed 1.0.1 development dependency set; no runtime dependencies are added. Only `equivalence-38` differs from the historical corpus:
-
-- Historical hash: `1135d7b57b528cbba1c1af98cd09de94d3b2dc3251ed66dcb62ea7ea8d3d32af`.
-- Original-source macOS hash: `02688bd713afea5ae82da9d53675a4e63738aa45bb5f33abca1b2cfeade3d52c`.
-
-This is test equivalence evidence, not renewed optical calibration or physical accuracy evidence. Other macOS architectures and Node lines have not been qualified by this record. Human source/scientific review and DCO certification remain pending for this AI-assisted corrective draft.

package/docs/POC_PROJECTION_REUSE.md

@@ -1,124 +0,0 @@
-# Request-local defocus projection reuse: #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).
-
-The measured candidate reuses the focus-plane image distance already calculated
-inside `simulatePocCamera()` for its subject and defocus sweep. It is a small
-private optimization against merged main
-`c1374c31473f893310d1ce4f0d5a737aaba43ab5`. It consumes no pending tier/export draft.
-Root API 0.103.0, POC API 0.20.0 and public scalar signatures/semantics stay unchanged.
-
-## Measurement and decision
-
-[Recorded evidence](benchmarks/2026-10-02-poc-projection-reuse.json) contains two
-independent ordinary paired runs and one GC-assisted paired run, all built with
-`tsc`. Each path/scenario has 500 warmup calls and nine blocks of 1,000 whole
-requests. Reference/candidate order alternates, scenario order rotates, and the
-final recorded runs were performed after local tests finished, without concurrent
-task benchmarks. Shared host activity remains uncontrolled.
-
-Runtime was Node 24.19.0/V8 13.6.233.17-node.51 on Linux x64, reporting AMD EPYC 9V74
-and 9 logical CPUs. Every run records runtime/hardware, baseline commit and SHA-256
-fingerprints of both candidate runtime source files. The source identity is
-operator-attested; fingerprints allow verification after commit. These are
-public POC developer-consumer request shapes, not observed product traffic or
-browser frame-time evidence.
-
-| Whole request | Ordinary reference µs, run 1 | Candidate µs, run 1 | Candidate/reference, run 1 | Ratio, run 2 | GC-assisted ratio |
-| --- | ---: | ---: | ---: | ---: | ---: |
-| Base, no sweep | 11.11 | 11.29 | 1.017 | 1.014 | 0.989 |
-| 1 defocus sample | 12.16 | 11.89 | 0.978 | 0.942 | 0.974 |
-| 2 defocus samples | 13.20 | 11.85 | 0.897 | 0.950 | 0.980 |
-| 4 defocus samples | 14.69 | 13.50 | 0.919 | 0.906 | 0.941 |
-| 8 defocus samples | 18.37 | 16.67 | 0.907 | 0.856 | 0.952 |
-| 16 defocus samples | 27.10 | 19.97 | 0.737 | 0.819 | 0.857 |
-| 16 each defocus/size/motion | 56.33 | 50.52 | 0.897 | 0.902 | 0.880 |
-| Portrait/off-center staged mixed | 95.54 | 90.79 | 0.950 | 0.924 | 0.970 |
-
-A ratio below one means a shorter measured request. The two ordinary runs show
-18–26% improvement on the 16-defocus shape, about 10% on mixed samples and 5–8%
-on staged capture. The base shape is about 0.16–0.18 µs slower (1.4–1.7%) in those
-runs; no universal speedup or zero overhead is claimed. GC-assisted timings are
-separate distributions and do not establish ordinary-vs-GC causality. Earlier
-exploratory runs are excluded from the final evidence.
-
-The decision is to retain this bounded private reuse candidate for human review.
-The repeatable sweep/mixed improvement justifies it, with the small base-path
-tradeoff explicitly visible. Further FOV/motion/sampling reuse or a generic
-prepared public API is not justified by this experiment. #43 retains its separate
-measurement/decision gate; this result does not establish its conclusion.
-
-## Preparation and memory
-
-Context creation copies three scalar numbers into a frozen object only when a
-non-empty defocus sweep is present. It adds no new thin-lens resolution: it borrows
-the same request's existing calculated projection. It cannot survive the request,
-is not returned in the response and has no global cache or cross-input lifetime.
-No-sweep requests allocate no context. An isolated object/freeze probe measured
-about 42–46 ns per preparation; its JIT/escape behavior can differ inside the
-whole call, so it is not an independent cost/error bound.
-
-Short sweeps are explicitly measured above; benefits increase enough at 16
-samples to amortize the context in these workloads. A single sample is close to
-noise, so no portable break-even count is asserted. Raw net retained-heap deltas
-are preserved but are not allocation counts or persistent-context size estimates.
-
-A separate V8 Inspector allocation-sampling pass measured 2,000 staged requests
-per path at 32 KiB sampling intervals, requesting inclusion of objects collected
-by both major and minor GC. Estimated sampled bytes were 593,837,880 for reference
-and 551,945,312 for candidate (about 7% lower); inclusive thin-lens sampled bytes
-were 177,301,960 and 138,224,096 (about 22% lower). These are statistical sampling
-estimates, not exact allocation counters, GC-pause measurements or latency
-attribution. Instrumented allocations are separate from all timing comparisons.
-No raw inspector profile/private path is stored.
-
-The sensor dimensions are an explicit 36×24 mm, 6000×4000 raster. This POC computes
-analytical diagnostics; it does not execute 24 million image samples. Raster
-size is therefore context, not a claim of full image-rendering throughput. The
-canonical tiny #130 fixture is used only for correctness, never as the runtime
-performance basis.
-
-## Correctness and boundary
-
-The public scalar `calculateDefocusCircle()` uses the same shared implementation
-without a borrowed projection. Its validation, arithmetic, result model,
-assumptions and provenance remain authoritative. The internal borrowed context
-requires exact physical focal/focus identity and positive finite projection.
-The POC constructs it from its already validated thin-lens result, never from
-serialized user projection values. Subject-plane projection still uses the
-ordinary thin-lens calculation; no equation or scientific stage is replaced.
-
-`test/fixtures/poc-projection-reuse-reference.json` stores 64 owned deterministic
-inputs and complete response/provenance SHA-256 commitments generated from the
-unchanged main reference build. The corpus includes all four orientations,
-off-center captures, legacy crops, varied focal/focus/aperture state and sample
-counts. Seed is `0x45c1374c`. Do not regenerate expectations from the candidate to
-hide drift. #130 remains unchanged. Additional tests compare the scalar oracle,
-invalid-input errors, stale context rejection and alternating request identities.
-
-Browser-surface and package gates remain required. This is a Node-measured POC
-optimization, not a browser-motivated public API; no browser performance or private
-application claim is made. It does not activate production rendering/radiometry
-or change capture/output/version contracts. Scientific/provenance review and
-contribution-specific DCO certification remain required before merge.
-
-## Reproduction
-
-Create an independent checkout of the recorded reference commit and build it with
-`npm ci` / `npm run build`. Build the candidate checkout too. Run only the
-benchmark during timing; replace the example reference-root with that checkout.
-The tooling consumes the reference's `dist/index.js` and first verifies complete
-response equivalence for every measured scenario.
-
-```sh
-node scripts/benchmark-poc-projection-reuse.mjs --reference-root=/path/to/reference --reference-commit=c1374c31473f893310d1ce4f0d5a737aaba43ab5
-node --expose-gc scripts/benchmark-poc-projection-reuse.mjs --reference-root=/path/to/reference --reference-commit=c1374c31473f893310d1ce4f0d5a737aaba43ab5 --allocation=sample
-```
-
-Repeat ordinary runs separately. Build labels are not independently attested by
-the script. There is no timing CI threshold, paid service, runtime dependency or
-new third-party material. This tooling is Node-only and outside the public root.
-
-## 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/PRINT_195_196_REVIEW.md

@@ -1,93 +0,0 @@
-# Print #195 / #196 candidate evidence and release review
-
-Historical candidate record, retained without relabeling its original evidence. PR #217 subsequently received owner approval and was merged; see the [current engine acceptance audit](PRINT_196_ENGINE_ACCEPTANCE.md) for approval identity, additional native-capture evidence and engine/app gate ownership.
-
-This record accompanies the 1.2.0 candidate. It preserves the full #196 acceptance gate: bounded computational conformance does not close the device/backend, proof UI or natural-image perception obligations of the full new-UI release. Engine publication precedes dependent app integration; app acceptance is not treated as an engine dependency cycle. No tag or distribution is created. Historical 1.1.0 diagnostic ledgers and JPEG artifacts remain unchanged.
-
-## Planning acceptance (#195)
-
-The existing public planner is tested against an independent exhaustive sample-count search for stamp, book, home, gallery, billboard and distant large-sign conditions on one immutable retained source. Heavy off-center crops expose insufficient native sampling. Smaller-size alternatives recover only within the original exact integer aspect family. Zero physical dimensions are rejected and a corrected request recovers. Enlarged delivery dimensions do not create native sampling. These are planning checks, not source-quality claims. See `test/print-plan-acceptance.test.ts` and [the planning contract](PRINT_PLANNING.md).
-
-## New diagnostics and independent references
-
-The [linear statistics protocol](PRINT_REGION_STATISTICS.md) separates paired processing changes from independent-repeat temporal sample variance. The [contrast reference](PRINT_CONTRAST_REFERENCE.md) exposes a restricted static neutral D65 Gabor model estimate with explicit luminance and reference-observer conditions. It does not label a photograph visible, sharp or printable.
-
-| Experiment | Executed backend | Independent reference | Supported meaning |
-| --- | --- | --- | --- |
-| Registered differences and repeats | New bounded scalar statistics | Exact binary64 rational arithmetic / high precision RMS | Finite arithmetic and sample statistics, not acquisition calibration |
-| PSF/aperture detail | Public local PSF + spatial/spectral quadrature | Sparse complex transfer, midpoint aperture sum and continuous sinc | Owned neutral periodic signal; finite kernels; all orientations; off-center ROIs |
-| Photocharge noise | Public accumulated-charge / seeded realization | Poisson mean and variance-of-sample-variance moments | Independent seeded ideal photocharge, 4 sites, 32–256 repeats; no ADC/read noise |
-| Electronic noise and clipping stages | Public native RAW producer, including dark/photo Poisson, storage capacity, read noise and 12-bit ADC | Exact rational charge-injection stage predictions; compound Poisson/Gaussian moments; deterministic half-code error bound | Owned 2×2 electronic reference; independent repeats at 32–256 counts; signed pre-ADC signal and unsigned code clamp; no source radiometry or device calibration |
-| Source-to-capture handoff | Public production environment capture + native RAW + processed-output path | Independent 80-digit SI radiance-to-photoelectron arithmetic | Owned uniform 540–560 nm band; QE 0.4; transmission 0.85; 8 ms; 2×2 native; four radiance scales; no real source/device calibration |
-| JPEG processing changes | Public SDR/JPEG exporter, archived independent Pillow/libjpeg decode | Exact decoded neutral scalar paired differences | Exact preserved JPEG bytes, orientation, stage and source hashes; no automatic artifact classifier |
-| Subject depth / intentional defocus | Shared thin-lens geometry + public complex-pupil propagation + owned visible-plane provider | Separate finite complex DFT and ray-plane reference | 2/5/10 m overlapping static planes; 5 m focus; f/8,16,32; 500 nm; 9×9 ideal pupil; interior ROIs |
-| Pupil sampling pilot | Public finite complex-pupil propagation with separately varied pupil resolution and padding | Independently factored finite DFT; continuous shifted-pupil overlap integral; analytic focused circular-pupil transfer | 25 cycles/mm; 500 nm; 2/5/10 m; f/8,16,32; final padded 61×61 grid below 0.01 absolute transfer error; no all-frequency or device certificate |
-| Translation motion | Public local exposure timing + translation/parallax nodes + owned periodic plane accumulation | Closed finite geometric transfer and continuous exposure sinc | Constant depth/visibility; 2/5/10 m; camera/subject velocity 0/1 m/s; 20 ms; 2–32 nodes |
-| Changing source visibility | Public production environment capture + native RAW + processed-output path, with owned moving two-plane provider | Exact rational ray/interval occupancy and continuous-exposure visibility fraction | Foreground 2 m / background 10 m; static camera; point optics; 8 ms; native X/Y motion; 2–128 midpoint nodes; no PSF/depth-edge blur or device qualification |
-| Physical proof reference | Owned PDF wrapper around exact archived JPEG streams; existing public Print planner | Exact Fraction physical-unit/ROI reference; separate pypdf graphics-state/DCT inspection; rendered visual inspection | Same retained crop at two enlargements and same-scale q1/q32 comparison; nominal A4 geometry/ruler only; no actual printer/UI/device or perception qualification |
-| Static contrast reference | Restricted castleCSF equation adapter | Independent 80-digit Decimal arithmetic | Numerical model conformance only; no new psychophysics or individual observer calibration |
-
-All generator inputs and JSON expected outputs are committed under `test/fixtures/print-detail/`; tests pin reference SHA-256. References never import the engine or derive expected values from its output. Every new scene/provider is owned draft material, not a private app fixture or camera dataset. These test adapters execute the named public backend; they do not qualify an unnamed renderer or device by association.
-
-## Finite-focus propagation correction
-
-The depth experiment exposed that the complex-pupil reference used nominal focal length for image sample pitch even when finite focus metadata was present. Model 1.1.0 adds explicit `propagationDistanceMm` and returns the distance/source. Omission preserves all legacy kernel values. The owned principal-plane fixture explicitly passes the shared thin-lens image distance. Real exit-pupil geometry needs separate evidence. No blur-diameter-to-PSF approximation or duplicate camera equation is introduced. See [PSF foundation](PSF_FOUNDATION.md).
-
-The new depth test is a finite scalar pupil conformance test. Its 9×9 pupil grid is **not** a continuum convergence certificate. The new independent pilot demonstrates intensity aliasing in that unpadded reference, including absolute transfer errors above 0.14 at f/32. A separately padded 61×61 grid satisfies a candidate 0.01 transfer-error criterion only at the declared 25 cycles/mm frequency and nine depth/aperture combinations; see [the pupil sampling pilot](PSF_FOUNDATION.md). Existing 9×9 outputs are not retrospectively certified. All finite taps for every selected ROI must hit the same visible surface. Depth-edge diffraction/occlusion composition, moving visibility, lens distortion and corrections are unsupported by that experiment. A background explicitly marked intentional defocus never becomes failed source quality.
-
-The motion reference checks continuous-exposure convergence and separately composes camera and subject velocities. It does not use an endpoint chord as a PSF, change exposure from readout duration, or authorize one homography across depths. PSF/aperture tests independently check spatial quadrature convergence. Stochastic repeat-count checks use predeclared broad moment bands; random sample estimates need not converge monotonically and these bands are not confidence intervals for a photograph.
-
-### Linear/high-bit electronic readout qualification
-
-`test/print-region-readout-backend.test.ts` invokes `simulateSensorRawFrame()` with an owned 2×2 native reference and 12-bit ADC in the existing 16-bit container. Exact deterministic charge-injection experiments independently isolate storage saturation, pre-ADC upper saturation, final digital saturation and rounding without clipping. The Python rational oracle includes threshold contact and half-code ties; successful output at a boundary alone is not interpreted as an unknown clipping mechanism. Backend flags and exact stage values must match the independent declared experiment. Source radiometry stays explicitly unverified.
-
-The stochastic experiment uses photo mean 200 electrons, dark mean 8 electrons and read-noise RMS 0 or 2 electrons, with predeclared 32/64/128/256 repeats and independent capture/representation/realization IDs. For unclipped pre-ADC signal, the independent compound variance is `photoMean + darkMean + readRms²`; the fourth central moment is `photoMean + darkMean + 3 variance²`. Those moments determine the broad sample-mean/sample-variance conformance bands. After the 12-bit ADC, each decoded sample's rounding error is bounded by half a code times the declared gain; the RMS change is bounded deterministically without assuming independent uniform quantization noise. All observed upper/lower clipping flags must be false for that unclipped experiment.
-
-A separate zero-photo/zero-dark, 8-electron read-noise experiment verifies that negative electronic signal survives the pre-ADC stage. With zero black pedestal, the final unsigned code clamp produces a positive bias consistent with independent rectified-normal mean `sigma/sqrt(2 pi)`. The before/after comparison uses the same immutable capture and noise realization. Changing draws cannot stand in for a processing effect.
-
-The scalar diagnostic encoding is an explicit ideal neutral relative signal scaled by electrons per reference unit. It is conditional electronic model conformance, not a calibrated radiance/luminance transform or a claim that charge injection photographed a scene. Spatial texture, CFA color interpretation, real sensor read noise, temporal correlations, actual photo-source transport and display/render clipping remain separately unassessed. The native RAW producer's `upstreamRadiometryVerified: false` is preserved. This extends the public model evidence; it does not close actual capture/device qualification or certify the private app noise fixture.
-
-### Source-to-capture qualification and artifact identity
-
-`test/print-region-capture-backend.test.ts` executes the actual public production environment-capture plan, rather than injecting all photocharge directly. An owned uniform-radiance variant of the existing basic reference supplies a constant 540–560 nm spectral band. The independent Decimal SI oracle predicts generated photoelectrons from declared radiance, working f-number, transmission, native geometric aperture, wavelength, QE and duration at four radiance scales. The plan executes 32 frozen provider queries, binds actual RAW to processed output, preserves source transport/radiometry as unverified, and deterministically replays the same capture. A paired pre-ADC/decoded-16-bit diagnostic checks the half-code rounding bound with the same noise realization. Changing physical print dimensions leaves captured samples unchanged. This is bounded public computational backend qualification; it does not establish physical calibration, a megapixel producer, source headroom, or actual visibility transport.
-
-The PSF orientation references now hash the complete actual oriented scalar raster and give each orientation a distinct representation identity. Depth references hash a complete 200×200 Float64LE scalar artifact and extract the tested ROI from it. That artifact continues the selected ideal plane outside its qualified interior region; no depth-edge or other-surface rendering claim is made for those pixels. Every finite PSF tap for the selected ROI must still resolve to its declared visible surface. The ideal field-invariant pupil records the selected field coordinate explicitly. These are owned analytic references, not a reconstructed full 3D photograph or an actual-device calibration.
-
-### Changing-visibility source qualification
-
-`test/print-region-visibility-backend.test.ts` drives the actual public production capture path with an owned nearest-surface provider. A foreground half-plane at 2 m translates along world X or Y; its edge starts at −0.5 m and moves at 125 m/s during the 8 ms exposure. A uniform farther plane at 10 m supplies radiance wherever the near plane is absent. The two spectral radiance levels are 0.5 and 1.5 times the previously independently predicted flat-band source. Engine-owned outgoing rays drive metric near-plane intersections; the provider does not introduce a second camera projection or an endpoint blur kernel.
-
-A separate exact Fraction oracle derives source-aperture ray slopes, native-Y inversion, visibility transition times, finite midpoint occupancies and continuous-exposure source means. Tests use 2/4/8/16/32/64/128 time nodes and both motion axes. The 128-node cases exposed a Node 24 coverage timeout. Every query is checked with direct fail-fast conditions, and replay compares a SHA-256 digest of all finite serializable scientific results. After those harness improvements, both full capture/replay cases still took 6.5–6.7 seconds in CI coverage; the fixture therefore has an explicit 15-second deadline. It is a numerical qualification fixture, not a performance gate. All cases, independent bounds and replay checks remain; the regular suite retains its default five-second deadline. The finite/continuous source-scale error is bounded by the unit radiance step divided by node count; it need not decrease monotonically for a discontinuous edge. All 16N callbacks per complete native 2×2 capture must execute. Actual photoelectron expectations, RAW/processed-output binding and deterministic replay are checked. Each execution has an explicit capture identity, and its snapshot commits the selected time-node count.
-
-This qualifies only this owned moving-source provider and the named public integration path. The engine's `sceneVisibilityCalculated: false`, `providerTransportVerified: false` and `upstreamRadiometryVerified: false` remain unchanged: the engine has not acquired a general scene/transport solver. Point optics and the stated rectangular aperture are explicit. PSF/defocus at moving depth edges, rolling readout, camera translation/rotation, corrections, edge-grazing semantics, other geometry, source calibration and private renderer/device behavior require separate evidence. It does not certify full #196 or a printable depth proof.
-
-### Physical proof artifact and independent inspection
-
-The committed [two-page physical proof reference](../output/pdf/print-proof-reference.pdf) reuses the exact existing post-encoding JPEG streams and selected native 16×8 crop. Page 1 prints the same JPEG/crop at full-source widths of 1 and 4 inches. Page 2 compares quantizer-step 1 and 32 representations of the same capture and crop at identical physical scale. No fixture family, new source per print size, resampling or interpolation uplift is introduced. The older JPEG bytes, hashes, capture IDs and 1.1.0 creator identity remain unchanged.
-
-An offline ReportLab generator derives millimeters/PDF points using exact Fraction arithmetic. A separate pypdf inspector reads actual MediaBox, graphics transforms, clip rectangles, embedded image dimensions, original DCT bytes, default interpolation policy and the nominal 100 mm calibration line. It maps native top-down ROI corners through the actual PDF transform and compares independent physical-unit expectations at less than 0.0001 PDF point serialization tolerance. Public-root tests bind the pinned PDF/inspection/manifest hashes and compare the existing Print planner's retained raster, crop geometry and PPI to the independently inspected reference. The 16×8 crop remains 16×8 at both enlargements. Generator reproduction is deterministic, with image resources based on byte content rather than checkout paths. Both final pages were rendered and visually inspected.
-
-This is public artifact/geometry evidence, not a new runtime PDF exporter or a qualified product proof workflow. The source is the existing owned post-ADC grating, not physical source/optics qualification. PDF DeviceRGB appearance, viewing luminance, substrate, actual printer scale and user/device handling remain unqualified. The calibration line's actual printed length must be measured. There is no embedded font program, added runtime dependency or private code/asset. The independent inspector is an optional offline pypdf tool; normal Node CI verifies committed artifact/record integrity and engine geometry without requiring Python packages. Human/source review and full #196/#307 physical proof integration remain open.
-
-## Source and reuse review
-
-The castleCSF numeric model material is pinned to upstream `f4b0b722af83001d7af979281e06ca642d36e4e8`. MIT notices are retained in [the license](licenses/castleCSF-MIT.txt), `NOTICE` and `THIRD_PARTY.md`. No observational CSV or separately licensed dataset is incorporated. The public [primary paper](https://pmc.ncbi.nlm.nih.gov/articles/PMC10996938/) supplies scientific context; upstream numerical conformance does not supply a new observer experiment. Quadratic paraxial pupil phase and finite propagation are consistent with the scalar diffraction framework described by [Braat and colleagues](https://nijboerzernike.nl/_PDF/BraatProgOpt2007OwnVersion20080515.pdf); no text, figures, tables or implementation from that source are copied.
-
-Substantive human scientific/source and contribution-specific DCO review remains pending for this new change. Approval of PR #216 does not certify these new coefficients, adapter, protocols or owned test material.
-
-## Candidate checks
-
-On Node 26.8.1, all 2,065 tests in 159 files pass; the full suite also passes with coverage on Node 24.19.0. Coverage is 92.04% statements, 88.55% branches, 99.63% functions and 92.04% lines. Build, static/license/SPDX/identity/browser checks, generated references, documentation links, 67 strict packed documentation consumers and the 810-file package surface pass. The [evidence inventory](validation/print-196-candidate-evidence.json) pins generator/artifact and reviewed upstream source hashes. These observations do not replace supported Node CI or substantive human review of the exact candidate commit.
-
-## Engine and full new-UI release gates
-
-The [candidate capability ledger](validation/print-196-candidate-capabilities.json) records bounded support and missing qualification separately. The engine owns the bounded interpretation contract and publicly runnable qualification. The app owns production capture, physical proof, accessibility and device integration and consumes published engine APIs. The full new-UI acceptance below remains in scope, but cannot logically precede publication of its required engine contract. The requested release after completion still requires resolving the engine acceptance and human review gates; product gates remain explicitly outstanding:
-
-- Independently qualified active capture/backend evidence for the claimed source detail domain, including lens/field, source headroom and continuum/support convergence. Owned finite reference execution cannot certify a private production renderer or actual capture device.
-- Qualified actual-source high-bit/linear evidence for the claimed physical noise and tonal domain. The public electronic reference now covers modeled photo/dark/read noise, storage/pre-ADC/digital saturation, signed shadows and 12-bit rounding. Actual source transport, physical calibration and display/render clipping remain unassessed.
-- Backend evidence for subject/depth/occlusion across the actual supported coordinate/correction/viewpoint domain, and temporal visibility changes where claimed. Interior finite-plane references exclude depth-boundary composition.
-- A perception application whose actual stimulus, luminance, contrast, area and observer conditions match the supported model. A rectangular coherent grating or natural-image ROI is not automatically a Gaussian-envelope Gabor stimulus. Color, aliasing, halos and natural-image visibility remain independently unassessed.
-- Exact physical proof/comparison scale and immutable capture/region/output binding in the product integration required by #196/#307. The standalone engine tests cannot certify private UI scale, accessibility or device rendering.
-- Human scientific/source review, contribution DCO certification, exact-head CI, final-main release gates and explicit publication approval.
-
-Do not close #196, downgrade these gates, or describe the release as ready because computational tests pass. #195 can be closed on acceptance of its planning audit. #215 remains open until the approved distribution is published.

package/docs/PRINT_196_ENGINE_ACCEPTANCE.md

@@ -1,45 +0,0 @@
-# Engine #196 acceptance audit
-
-This audit follows merged [PR #217](https://github.com/Photivra/photivra/pull/217), commit `c58d9eb9dcba807f020df45be1ed5ec4f6c081e4`. Owner approval of that contribution's scientific/source and DCO gate is recorded in its squash commit and PR. The old candidate ledgers retain their historical pending-review observations; they are not current approval records. The additional patterned-source reference below requires its own substantive human review and contribution-specific DCO certification.
-
-## Engine contract and full product scope
-
-[Engine #196](https://github.com/Photivra/photivra/issues/196) requires documented, independently supported bounded assessment, with other dimensions explicitly qualified or unassessed. It does not require a universal quality score, automatic natural-image visibility verdict, named-device calibration or printer ICC/substrate simulation. The engine APIs preserve those exclusions. Their scientific meaning remains conditional on a declared source, registration, model and stage; successful parsing never authenticates a supplied artifact.
-
-The issue also requires the full new-UI print feature. Its app acquisition, proof workflow, accessibility and actual-device gates remain required under [app #307](https://github.com/Photivra/photivra-apps/issues/307) and its linked owners. They consume the published engine contract. They cannot be prerequisites for publishing that same prerequisite contract. Engine acceptance does not close those tickets, certify a private renderer, or make the complete new-UI release ready. The earlier candidate's combined `fullAssessmentAcceptance: blocked` remains true for that complete product scope; it must not be mistaken for proof that every engine requirement lacks evidence.
-
-## Requirement-to-evidence audit
-
-| Engine requirement | Authoritative evidence | Qualified scope / retained limit |
-| --- | --- | --- |
-| Model, supported domain, independent protocol and reuse review before implementation | `PRINT_DETAIL_ASSESSMENT.md`, `PRINT_DETAIL_VALIDATION.md`, `PRINT_REGION_STATISTICS.md`, `PRINT_CONTRAST_REFERENCE.md`, retained MIT license/NOTICE/THIRD_PARTY, #217 owner review | Bounded coherent scalar and linear-statistic models; separate population contrast reference; no general photograph classifier |
-| Reuse optics, sampling and processing; no second diffraction/defocus/motion stack | `print-detail-psf-backend.test.ts`, `print-detail-depth-backend.test.ts`, `print-depth-pupil-convergence.test.ts`, `print-detail-motion-backend.test.ts`; shared public functions | Finite local kernels, declared pupil grid and support, supported temporal nodes; no blur-diameter-to-PSF conversion or named-lens calibration |
-| Exact source stage, region, field, subject/focus, print/viewing geometry and contrast assumptions | `print-detail.test.ts`, `print-region-statistics.test.ts`, model/input contracts | Explicit selected ROI, orientation/crop and relative-linear domain; absolute print luminance is not inferred; unqualified correction/warp blocked |
-| Directional versus isotropic blur and equal-PPI/different-detail sources | `print-detail.test.ts`, `print-detail-psf-backend.test.ts`, new `print-detail-native-capture.test.ts` | Owned periodic sources and named public backend; no universal MTF or real-camera claim |
-| Actual capture backend, target truth and independently predicted source response | New `print-detail-native-capture.test.ts` and `native-detail-reference.json`; existing `print-region-capture-backend.test.ts` | Complete 4×4 native provider→optics→EQE→photo/dark/noise→ADC execution, two axes/phases and four aperture node counts; declared angular source, point optics, no private renderer/device calibration |
-| Selected subject, intentional background defocus, visible depth/occlusion | `print-detail-depth-backend.test.ts`, `print-region-visibility-backend.test.ts` | Known metric nearest-surface provider; finite PSF support restricted to one visible plane; point-optics changing visibility; depth-edge PSF and unqualified viewpoint/corrections unsupported |
-| Directional subject/camera motion | `print-detail-motion-backend.test.ts`, `print-region-visibility-backend.test.ts` | Independently predicted finite/continuous exposure on declared trajectories; no single homography across depths or endpoint chord substituted for a PSF |
-| Noise, clipping and processing halos tested separately | `print-region-statistics.test.ts`, `print-region-noise-backend.test.ts`, `print-region-readout-backend.test.ts`, new native-capture test | Same-realization paired differences versus independent-repeat temporal variance; known range overshoot/undershoot; explicit electronic clipping stages; no automatic halo attribution or physical sensor calibration |
-| Post-encode assessment bound to exact representation | `print-detail-jpeg-integration.test.ts`, committed JPEG/decoder manifests and independent references | Actual archived JPEG bytes, independent decoded neutral samples and exact capture/ROI identity; pre-encode does not certify post-encode; no automatic compression-quality verdict |
-| Physical enlargement distinct from resampling; same-scale proof binding | `print-proof-reference.test.ts`, separate pypdf inspection and committed PDF; native-capture enlargement check | Actual PDF operators, original DCT streams, retained crop, physical-unit reference and nominal ruler; actual printer and product proof workflow remain app gates |
-| Contrast/perception only through an evidence-backed model | `print-contrast-reference.test.ts`, 80-digit independent reference, pinned castleCSF revision and exact MIT terms | Declared static D65 Gabor population-model estimate only; measured rectangular ROI is not a matched Gabor; natural-image visibility, individual observer, physical print stimulus and uncertainty remain unassessed |
-| Aliasing, halos, compression and color independently inspectable; no overall score | Public result contracts and unsupported/unknown-state tests | These dimensions are unassessed unless an explicit bounded protocol supplies a numerical quantity; no combined quality uplift, pass/fail or interpolation claim |
-| Identity/version compatibility and independent public usefulness | Source/ROI/hash tests; historical JPEG replay; root-only browser/package/docs/packed consumers | Explicit engine/model/protocol identity; no private scene, device dataset, runtime dependency or changed historical creator identity |
-
-## Patterned-source native capture qualification
-
-The additional reference extends the existing owned flat-band scene variant; it adds no chart family or target per print size. A declared angular neutral sinusoid has modulation 0.5 and one cycle across the native 4×4 raster. At the stipulated ideal image distance, the two angular periods are `36 × 0.0198` and `24 × 0.0198` in look-ray slope. The source definition consumes engine-generated outgoing rays. It does not calculate a replacement camera projection. All sites use the explicit existing 800×600 µm geometric aperture, 540–560 nm band, equal effective QE 0.4, f/4 transmission 0.85 and 8 ms exposure.
-
-An independently authored 80-digit Decimal cosine series predicts every native photo expectation, fundamental modulation and continuous rectangular-aperture response for both axes, phases 0 and 0.37, and 1/2/4/8 midpoint aperture nodes. The midpoint-rule absolute modulation error bound is `0.5 (2 pi apertureWidth / imageExtent)^2 / (24 nodeCount^2)`, declared from the second-derivative bound before evaluating runtime output. Expected photoelectron units reuse the independently derived SI reference from `generate_capture_reference.py`. Neither generator imports the engine or reads observed samples. Tests pin both source artifact hashes and require every expected provider callback.
-
-The named `simulateEnvironmentSensorRawFrame()` path executes the complete native raster, including source optics/EQE, actual seeded noise and ADC. The reference first qualifies expected photo transfer, then separately binds and assesses the actual noisy, quantized relative scalar representation. Same-realization pre/post-ADC differences must satisfy half-code rounding bounds. A photo expectation is never relabeled as measured noisy captured-system MTF. Complete scalar artifacts are hashed, and physical enlargement changes print geometry without changing captured measurements.
-
-This is conditional modeled neutral signal, not measured cd/m², a photographic observer experiment, CFA color calibration, private renderer qualification or actual hardware evidence. Existing transport/radiometry verification flags remain false. The reference's point-optics domain is explicit. The older finite-pupil pilot's one-frequency convergence limits remain unchanged.
-
-The [new evidence record](validation/print-196-engine-acceptance.json) pins these additional artifacts and records local test/package observations separately from scientific approval. The generator was replayed against its pinned SHA-256; normal CI uses the committed reference without requiring Python.
-
-## Acceptance decision and remaining gates
-
-The requirement audit is review material, not self-issued scientific certification. The existing #217 contribution was approved and merged. The new generator, artifact, tests and this ownership audit must receive substantive human scientific/source review and DCO certification, with green exact-head checks, before engine #196 is accepted. Acceptance must explicitly retain the supported domains above and the complete new-UI obligations; it must not be described as natural-image or device calibration.
-
-After engine acceptance, the requested engine release still requires final-main checks, version/distribution availability checks, configured publishing protections and explicit tagging/publication approval. No tag or package is created by this work. Full new-UI release readiness remains blocked until its acquisition, source/target headroom, physical proof, accessibility and device gates have qualified evidence in the app owners. This audit neither defers nor removes them.