@photivra/engine 1.3.0 → 1.5.0

package/docs/NATIVE_RAW_AND_PRINT.md

@@ -0,0 +1,54 @@
+# 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/RELEASE_1_4_0.md

@@ -0,0 +1,23 @@
+# Engine 1.4.0 candidate release review
+
+This additive candidate aligns package, lockfile, citation and root engine identity at 1.4.0. It is not tagged or published. The application's production dependency remains the published 1.2.0 package until an approved release and explicit consumer migration.
+
+Changes include the previously merged ideal pupil support and the separate metadata-only packed native RAW, source-to-RAW, same-RAW development and bounded post-SDR Print JPEG/ICC APIs. Independent schema versions remain 0.1.0. Reference inline plane, RAW and photographic export caps remain unchanged. Shared scalar helpers preserve the existing charge/noise/ADC, reconstruction, color and SDR equations. Reference JPEG byte controls cover eighteen original encoder cases including odd padding, three quantization steps and empty metadata.
+
+See [native contracts and reproducible evidence](NATIVE_RAW_AND_PRINT.md), [pupil contract](SENSOR_APERTURE_RAYS.md), and [recorded controls](validation/native-raw-print-2026-10-04/validation.json).
+
+## Review boundaries
+
+The new tasks execute complete constructed capture inputs; they do not authenticate caller-owned artifact hashes or calibrate arbitrary source callbacks. Source radiometry/visibility, quadrature convergence, device resources, production stage composition, printer appearance and platform delivery remain separate contracts. Full production depth composition remains closed. The new native event records are deliberately separate from bounded `SensorRawFrame` and cannot be inserted into it as fabricated small frames.
+
+The public engine contains original Apache-licensed math, serialization and synthetic controls only. Private application scene sources, fixture assets and proprietary adapters are retained in the application repository. The original ICC profile uses standard format/color facts, not a redistributed profile or encoder implementation.
+
+## Owner handoff
+
+1. Review the exact candidate code and public source provenance, scientific domains, unit/frame/phase/seed binding, resource limits and disposal behavior. AI-assisted changes remain draft until substantive human review under AGENTS.md.
+2. Require green exact-head CI on Node 22.13, 22, 24 and 26, plus the package, documentation and isolated consumer gates. The optional actual megapixel run is separately recorded; its ordinary-suite skip is explicit.
+3. Approve merge and the concrete 1.4.0 release only after review. Merge must not silently publish a tag. Check final main/commit/version identity and unchanged package consumer acceptance.
+4. With explicit publication approval, use the repository release procedure/workflow for GitHub and npm. Confirm the published tarball, root export, version and provenance before migrating the application. Do not treat local candidate tooling as a published production import.
+5. Finish the application’s independently retained source, output, platform and human/device acceptance at the adopted published version, then approve the concrete production deployment.
+
+No tag, publication, production activation, credential change or deployment is authorized by this document.

package/docs/RELEASE_1_5_0.md

@@ -0,0 +1,105 @@
+# 1.5.0 release candidate
+
+Review snapshot: 2026-10-05. This document records the 1.5.0 engine release candidate. It does not tag, publish or activate a downstream application.
+
+**Proposed version:** `@photivra/engine@1.5.0`, with `ENGINE_API_VERSION = "1.5.0"`. The backward-compatible public `NativeRawInput.tileWidth` option warrants a minor release rather than describing the entire change as a patch-only fix. This is an engine release identity, not the separate application's public Beta label.
+
+**Candidate metadata is aligned to 1.5.0 on the release branch.** Generated references, exact-candidate CI/package validation, final review and owner publication authorization remain gates below.
+
+## Current integration and owner review — 2026-10-06
+
+The owner substantively reviewed and approved PRs #230 and #232, certified DCO 1.1 for those contributions and authorized contributor sign-off and merge after remaining checks. #232 merged with authorized sign-off as `7106fb90d8351cb769c2c01b0f10ebf1a437aea8`; its reviewed head `0d414b3f942c65f42a1a86f26c073a83093cd004` passed exact-head CI. The 1.5.0 candidate includes that bounded qualification checkpoint and preserves the reviewed #230 release changes at `7f33e4e39f94893ee93f87d90e7153d80ebd6f08`.
+
+The checkpoint adds independent SI photon/electron tests and complete 2×2 resource pilots, not complete native Focus qualification or a public experimental API. #224 remains open. Historical draft/input-review statements below describe the October 5 preparation snapshot; they do not reopen completed contribution review/DCO. Generated API references were regenerated on the combined candidate with no file drift. Combined-candidate local validation passed: 2,184 tests / one existing skip, existing coverage thresholds, build, docs, packed consumers, package surface and configured image-formation benchmark. The actual 1.5.0 archive was inspected: 867 entries, root-only export, matching emitted version declarations and no repository-only API implementation/test/source/script/workflow tree. Final combined-candidate GitHub CI remains required before merge; publication remains separately authorized.
+
+## Published baseline and exact candidate inputs
+
+- Published GitHub release: [v1.4.0](https://github.com/Photivra/photivra/releases/tag/v1.4.0), published on 2026-10-04.
+- At this review, `main` and `v1.4.0` both identify commit `240340ec9e23ef79b6a0d729f494b2a531dd6df4`; their comparison contains no new commits or changed files.
+- [PR #223](https://github.com/Photivra/photivra/pull/223), head `04baece1a8d1a133db3e7a2f0c9daa0d662bb826`: optional native RAW execution chunks and preservation of the exact acquisition plan during same-RAW development.
+- [PR #225](https://github.com/Photivra/photivra/pull/225), head `70f55f5e27795d2fa51d112fbee1b14ee097b6ce`: experimental separable ideal-emission work, stacked on #223.
+- This preparation branch starts at the #225 snapshot so neither draft is silently omitted from the review. That ancestry is not approval to ship either change. Reconcile this document whenever a source PR changes, is excluded, or is rebased.
+
+The v1.4.0 GitHub release is verified here. A fresh direct npm-registry check was unavailable in this review; do not infer current registry dist-tags or integrity values from the GitHub release alone.
+
+## Proposed release notes, subject to the gates below
+
+### Bounded native RAW execution and development
+
+Add an explicit integer `NativeRawInput.tileWidth` from 1 through 256 native sites. Omission preserves the existing 256-site execution and the original plan shape. The option controls provider request width, tile count and host-yield frequency; it is not a physical sampling or quality control.
+
+Preserve that acquisition width when validating and developing an owned native RAW result. Reject invalid widths, inconsistent tile counts and stale plans rather than silently reconstructing the default-width plan. Existing CFA coordinates, absolute-index noise seeds, shutter timing and RAW/developed values remain the intended invariant.
+
+The existing 100,000 logical-query tile bound, two-billion arbitrary-provider event bound and native raster/output-byte limits remain in force. Smaller chunks can solve a tile-admission problem; they do not solve an over-budget whole event or establish optical convergence.
+
+### Experimental source work is not a supported release feature
+
+#225 explores an explicit uniform-spectrum, achromatic ideal-emission factorization with separately counted geometry evaluations and spectral compositions. It does not establish that an external source satisfies separability, that a full native fixture is qualified, or that a device meets time/memory requirements. See [the draft contract](SEPARABLE_EMISSION_DRAFT.md).
+
+Do not advertise or expose this as a supported public API. At the current #225 head the prototype lives under `src/api/`, which is built for repository checks but excluded by the npm package manifest and unreachable from the root browser/package graph. Promotion out of that repository-only boundary would be a separate reviewed public-contract change. A successful test suite alone remains insufficient for scientific or production qualification.
+
+## Blocking findings
+
+### Resolved prerequisite: experimental distribution boundary
+
+#225 now restores the published `src/capture/native-environment-raw.ts` implementation unchanged and moves the separable-emission prototype under `src/api/`. The repository's existing package-surface check excludes `dist/api/`, and the browser/root reachability check does not traverse the prototype. The 128-ray correctness regression also carries an explicit 15-second test budget so Node 24 timing variance is not misreported as a scientific failure.
+
+This boundary must remain verified on the final candidate. Moving the prototype into a published module or root dependency graph would reopen the release blocker.
+
+### 1. Scientific/source and resource qualification remain unresolved
+
+[Issue #224](https://github.com/Photivra/photivra/issues/224) requires bounded full-event evidence and no hidden source assumption or raised safety ceiling. #225 proposes a distinct, four-billion scalar spectral-composition ceiling while preserving the two-billion legacy provider ceiling. Review whether this new source/work domain satisfies the approved scope; do not treat preserving the old ceiling as automatic approval of the new one.
+
+Full-native depth/visibility/refinement results, independently checked output and measured resource evidence remain prerequisites for any newly claimed full-native capability. Keep source separability and transport unverified until evidence establishes them. Excluding the prototype from this release is valid; silently presenting partial-tile or synthetic controls as full-event qualification is not.
+
+### 2. Substantive human review and contribution-specific DCO
+
+The input PRs #223/#225/#226 received substantive human review and DCO approval before candidate preparation. The owner subsequently reviewed and certified #230/#232 on 2026-10-06, as recorded above. Follow [CONTRIBUTING](../CONTRIBUTING.md); use the authorized contributor sign-off for inclusion. This review does not establish the unresolved full-native/source/resource qualification under #224 or authorize public promotion of the experimental API.
+
+## Validation already available for the code snapshots
+
+- #223 records 2,151 passing tests and one existing skip at `04baece`, with CI [37216829043](https://github.com/Photivra/photivra/actions/runs/37216829043).
+- #225's corrected package-isolated head `70f55f5` passed CI [37384286949](https://github.com/Photivra/photivra/actions/runs/37384286949). The prior Node 24 timeout was addressed by an explicit correctness-test budget rather than changing scientific assertions or resource limits.
+- The test counts above are taken from the source PR records, not a new local test execution. The inspected CI job outcomes establish those jobs' success, not review approval or scientific qualification.
+- Neither snapshot is the final version-bumped release candidate. These results must not be reported as final 1.5.0 release verification. This preparation branch must rerun the matrix after every stacked-base or release-document change.
+
+## Remaining release checklist
+
+- [x] Isolate the experimental implementation from the published package/root dependency graph; keep package/browser-surface checks green on the final candidate.
+- [x] Keep #225 experimental source/work-budget behavior repository-only and outside the public 1.5.0 package/API; #224 retains scientific qualification ownership.
+- [x] #223/#225/#226 inclusion, substantive human review and DCO are recorded complete on engine main before this candidate branch; release-candidate changes still require final owner review.
+- [x] Reconcile included stacked PRs in dependency order on engine main; retain any branches still needed by open work.
+- [x] Set `package.json`, both root version fields in `package-lock.json`, `src/core/version.ts` and `CITATION.cff` to 1.5.0. No citation release date is asserted before publication.
+- [x] Add the 1.5.0 changelog/release-context entry while preserving historical release records and independently versioned POC/schema/model identities.
+- [x] Regenerate API documentation/`docs/api/exports.json` on the combined candidate; no generated drift.
+- [x] Run local checks/coverage/build/docs/packed consumers/package gate/image-formation benchmark on the combined candidate and inspect the actual npm tarball and emitted root/declaration import graph. Final remote CI and final-main CI remain separate gates.
+- [x] Owner scientific/source review and contribution-specific DCO certification cover the included contributions; final integration diff preserves the approved scope.
+- [ ] Require green final-candidate CI before the signed merge and verify final-main CI before separate publication authorization.
+- [ ] Verify protected main/tag configuration and trusted publishing, confirm the next npm version is absent, then authorize the separate tag/publish step. Never move v1.4.0 or attempt to overwrite its package.
+- [ ] After publication, independently verify the npm version, dist-tag, tarball integrity and provenance, and publish matching GitHub release notes. Downstream dependency adoption and application qualification remain separate.
+
+## Candidate preparation and verification
+
+After resolving the inclusion/review decisions, use a clean checkout of the approved candidate. The existing release contract remains authoritative for guarded owner publication; see [release procedure](RELEASE_1_0_1.md#owner-release-procedure). The commands below perform preparation and checks only, not a tag or publication:
+
+```sh
+npm version 1.5.0 --no-git-tag-version --ignore-scripts
+# Align src/core/version.ts and CITATION.cff, finalize CHANGELOG.md and
+# current release-context prose; do not rewrite historical evidence.
+npm ci --ignore-scripts
+node scripts/generate-api-reference.mjs
+node --test .github/test-node-lts-policy.mjs
+node .github/node-lts-policy.mjs
+npm run check
+npm run coverage
+npm run build
+npm run docs:check
+npm run release:consumer-check
+npm run pack:check
+npm run bench:image-formation:built
+npm pack --ignore-scripts --json
+```
+
+Inspect the resulting tarball, its emitted declarations/imports and its recorded hashes. Keep temporary archives/build evidence untracked unless an existing evidence policy explicitly requires them. Review current [Node support](../NODE_SUPPORT.md); do not reuse a dated runtime snapshot as proof of future support. Any source, version, documentation, exclusion or generated-file change requires checks against that changed candidate.
+
+**Stop before tagging or publishing until exact-candidate CI/package/tarball verification and owner authorization are complete.** No release tag, npm publication, GitHub release, application dependency change, automation or safety-cap change is performed by this preparation.

package/docs/SENSOR_APERTURE_RAYS.md

@@ -0,0 +1,23 @@
+# Ideal pupil rays for bounded capture
+
+`calculateSensorApertureRays()` generates origin-aware rays for an explicitly declared ideal symmetric thin lens. Native sensor coordinates use +Y down; camera look directions use +Y up and +Z forward. Origins lie in the lens principal plane and use metres. Pupil sample points use millimetres.
+
+For focal length f and nominal f-number N, the circular pupil radius is f/(2N). The shared focus contract determines image distance v. For finite object-plane distance D, every unrotated ray intersects (xD/v, -yD/v, D). At infinity the rays remain parallel. The existing constant-axis camera rotation rotates both origin and direction about the principal-plane origin at the actual local shutter time.
+
+Uniform-area polar midpoints use r = R sqrt((i + 1/2)/Nr) and theta = 2 pi (j + 1/2)/Na. Each ray has normalized weight 1/(Nr Na). Counts are bounded to 1..32 radial and 4..64 angular samples, with at most 256 rays. These are integration samples, not a convergence guarantee.
+
+## Capture integration
+
+A caller may supply `pupil` and the separate `evaluateApertureRadiance(request, ray)` callback to `calculateEnvironmentSensorPhotoSignal()` or `simulateEnvironmentSensorRawFrame()`. The callback receives the actual pupil origin and look direction. It owns scene intersection, visibility and emitted/transported wavelength-resolved radiance; the engine owns focus, rotation, local shutter timing, sensor response and RAW production. The old single-argument environment callback remains compatible and unchanged when pupil sampling is omitted.
+
+The engine averages physical irradiances over normalized pupil weights before sensor integration. The existing working-f-number radiometric factor is applied once. Pupil area is not multiplied again. A sampled local PSF and pupil integration are rejected together: neither an implicit second defocus nor an unreviewed optical composition is permitted. Every ray and the total provider budget are preflighted before provider execution. Full-frame site completeness, seeds and 4,096-site/100,000-query limits remain unchanged.
+
+Diagnostics retain the original central `query`, plus `apertureRequest` and `apertureRay` for the actual evaluated ray. `pupilIntegrationApplied` and `pupilIntegrationProfile` report the declared integration. Provider transport and scene visibility remain unverified. The production composer rejects this standalone route until depth/visibility fidelity has an explicit composition contract; this API does not activate a production stage.
+
+## Limits and evidence
+
+This is an ideal paraxial approximation with unity pupil magnification. It does not model diffraction, aberrations, pupil clipping, lens housing, calibrated lens transmission, camera translation, scattering or physically measured sensor response. Existing separately declared field and spectral transmission remain separate. No megapixel RAW capability or physical device acceptance is established.
+
+Tests independently intersect finite rays with the focus plane, check pupil moments, through-focus footprints, infinity parallelism, coordinate signs and camera rotation. Capture tests check uniform radiance against the unchanged no-pupil path, origin-dependent visibility averages, exact seeded replay, callback ownership and rejection before provider work. These synthetic controls do not qualify arbitrary scene providers.
+
+Conceptual references: [PBRT projective camera models](https://www.pbr-book.org/4ed/Cameras_and_Film/Projective_Camera_Models) describes ideal lens sampling; [PBRT realistic cameras](https://www.pbr-book.org/3ed-2018/Camera_Models/Realistic_Cameras) distinguishes full lens geometry. Implementation and tests are original Photivra work using existing engine helpers; no reference code, data or prose is incorporated. AI-assisted work remains draft pending substantive human scientific/source review.

package/docs/SEPARABLE_EMISSION_DRAFT.md

@@ -0,0 +1,103 @@
+# Explicit separable ideal emission — draft for issue #224
+
+This repository-only prototype is AI-assisted draft material requiring substantive
+human scientific/source review and contributor certification. Its implementation
+lives under `src/api/`, the repository-only boundary that is built for contributor
+checks but excluded from the npm package and unreachable from the public root API.
+The published `src/capture` and `src/sensor` modules are unchanged by this draft.
+It includes an experimental native task, not a qualified release or production plan.
+No private scene geometry, assets or provider implementation are included.
+
+`calculateSeparableEmissionPhotoSignal` composes the existing bounded single-site
+optical/EQE executor with an explicit `uniform-spectrum-achromatic-ideal-emission`
+contract. Outgoing spectral radiance is `G(origin, direction, time) × S(wavelength)`.
+`G` is a finite nonnegative dimensionless multiplier supplied by caller-owned
+ideal-emission geometry. `S` is an explicit, uniform, linear-interpolated spectrum
+in W/m²/sr/nm. This declaration excludes wavelength-dependent visibility, surface
+spectra and material transport. It does not establish that an external source
+actually satisfies those assumptions. Source separability remains unverified.
+
+The geometry callback receives no wavelength or spectral sample identity. All
+scene/provider/illumination/material IDs, opening-reference time, outgoing
+query direction, pupil origin and ray remain exact. The contract is owned before
+callbacks. All original spatial, pupil, temporal and wavelength nodes, normalized
+weights, optical throughput, spectral response and photon/EQE calculations execute
+unchanged. Only identical geometry requests are reused across wavelengths. No
+cross-site/event cache persists. This cache is bounded by the existing 100,000
+single-site work cap, and checks cancellation before every spectral composition
+and after each caller callback. A synchronous callback cannot be forcibly
+interrupted; the host still owns its responsiveness.
+
+The prototype records actual `geometryEvaluationCount` separately from
+`spectralCompositionCount`. The existing photo output's `providerEvaluationCount`
+continues to mean original logical wavelength/ray evaluations. It must never be
+presented as the geometry callback count, or as evidence of calibrated transport.
+
+## Experimental native task and proposed budgets
+
+`createExperimentalNativeSeparableEmissionTask` is a repository-only additive
+route. It shares the original native RAW scheduler, noise/ADC executor and photo
+observer. The original public task still applies its two-billion provider-event
+and 100,000 logical tile limits unchanged. The experimental route separately
+requires caller-supplied `maximumGeometryEvaluations` (at most two billion) and
+`maximumSpectralCompositions` (draft ceiling four billion). These names are not
+interchangeable; the output omits the legacy provider count and records both
+actual attempted geometry calls and executed spectral compositions. Failure or
+cancellation exposes no partial RAW output. Conservative per-tile geometric
+support and complete scalar spectral support are admission-checked before any
+geometry callback. The 100,000 logical spectral/ray tile-work cap still applies.
+All sites in a tile preflight binding and complete original wavelength coverage
+before execution. The host yields at existing RAW tile boundaries; each site's
+cache is released before the next site rather than retained for the event.
+
+Full 2048 × 1366 Focus with four spatial nodes, two spectral nodes and 128 pupil
+rays has 2,864,709,632 spectral compositions and at most 1,432,354,816 geometry
+calls under this exact declaration. A 32-site tile has 32,768 logical spectral
+compositions and at most 16,384 geometry calls. The draft four-billion scalar
+ceiling is a finite separately named admission bound above that specific event;
+it is **not** a measured performance/memory policy or scientific convergence
+claim. Callers should declare the tighter exact projected budget, rather than
+use the ceiling by default. It adds no nodes, hides no scalar optical/sensor work
+and does not widen arbitrary-provider support. A source with wavelength-dependent
+visibility or materials remains incompatible. The source owner must establish
+this declaration; runtime typing cannot prove an external callback is truthful.
+
+This draft proposes different work domains for a new source model, rather than
+raising the existing legacy provider cap. Human review must decide whether this
+source assumption and the new spectral budget are appropriate before root API
+export, adoption or a full-native fixture qualification run. Current app source
+and acquisition queues continue using their recorded legacy/candidate paths.
+
+Tests compare original photon/electron results and every pupil ray at 32/64/128
+support using a synthetic origin-dependent occlusion edge. They reject malformed
+contract, identity, basis, insufficient spectral coverage, unsupported PSF,
+missing pupil, invalid callback factors and cancellation. A wavelength-dependent
+visibility negative control deliberately disagrees with this separable source;
+it demonstrates why declaration is a scientific requirement rather than proof.
+It cannot detect a dishonest or mistaken caller declaration automatically.
+
+Package-boundary acceptance is explicit: `npm pack` must exclude `dist/api/`,
+and the browser/root reachability check must not traverse this prototype. Promotion
+out of `src/api/` would therefore be a separate reviewed public-contract change.
+
+Still required: independently decoded full-native depth/visibility/refinement,
+measured memory/time evidence, a deliberate public API/version decision if this
+prototype is ever promoted, and substantive human source/scientific review. No
+production admission flag, native fixture qualification or DCO is cleared here.
+
+Native regression tests additionally compare seeded RAW and independently computed
+legacy per-site photons/electrons for global and rolling shutters at 32/64/128
+pupil support, test separate budgets, unchanged tile/legacy caps, attempted failing
+work counts, immutable contract ownership and cancellation at a host yield.
+No full native source/event results or physical-device memory evidence are claimed.
+
+## Qualification checkpoint — 2026-10-06
+
+[DENSE_PUPIL_QUALIFICATION.md](DENSE_PUPIL_QUALIFICATION.md) records independent
+SI photon/electron checks and complete-small-event resource pilots. It supersedes
+any inference that the proposed four-billion scalar ceiling alone resolves #224:
+base native spectral work remains above two billion, simple pupil/time refinement
+exceeds both prototype ceilings, and no complete native/depth/device event is
+qualified. The recorded elapsed-time extrapolation is not native measurement.
+The prototype remains repository-only; exact work reduction and full-native
+scientific/resource evidence are still required before public promotion.

package/docs/api/camera-equivalent-focal-length.md

@@ -1,6 +1,6 @@
 # camera/equivalent-focal-length.ts public contracts
 
-Package **1.3.0**, root API **1.3.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateEquivalentFocalLength35Mm
 

package/docs/api/camera-field-of-view.md

@@ -1,6 +1,6 @@
 # camera/field-of-view.ts public contracts
 
-Package **1.3.0**, root API **1.3.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateFieldOfView
 

package/docs/api/camera-projected-object-size.md

@@ -1,6 +1,6 @@
 # camera/projected-object-size.ts public contracts
 
-Package **1.3.0**, root API **1.3.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateProjectedObjectSize
 

package/docs/api/capture-capture-export-metadata.md

@@ -1,6 +1,6 @@
 # capture/capture-export-metadata.ts public contracts
 
-Package **1.3.0**, root API **1.3.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## CAPTURE_EXPORT_METADATA_SCHEMA_VERSION
 

package/docs/api/capture-environment-raw-producer.md

@@ -1,6 +1,6 @@
 # capture/environment-raw-producer.ts public contracts
 
-Package **1.3.0**, root API **1.3.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## EnvironmentSensorRawFrame
 
@@ -45,12 +45,13 @@ export interface SimulateEnvironmentSensorRawFrameInput {
   /** Shared shutter schedule is bound to the committed frame duration. */
   exposureWindow: NonNullable<SensorRawProducerInput["exposureWindow"]>;
   sites: readonly {
-    environment: Omit<CalculateEnvironmentSensorPhotoSignalInput, "evaluateRadiance">;
+    environment: Omit<CalculateEnvironmentSensorPhotoSignalInput, "evaluateRadiance" | "evaluateApertureRadiance">;
     darkCurrentProfile: SensorDarkCurrentProfile;
     operatingTemperatureC: number;
     charge: Omit<SensorRawProducerSiteInput["charge"], "photoSignal" | "darkCharge">;
     readout: Omit<SensorRawProducerSiteInput, "charge">;
   }[];
   evaluateRadiance: EnvironmentRadianceEvaluator;
+  evaluateApertureRadiance?: EnvironmentApertureRadianceEvaluator;
 }
 ```

package/docs/api/capture-focus-control.md

@@ -1,6 +1,6 @@
 # capture/focus-control.ts public contracts
 
-Package **1.3.0**, root API **1.3.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## assessFocusReleaseGate
 

package/docs/api/capture-linear-encoding.md

@@ -1,6 +1,6 @@
 # capture/linear-encoding.ts public contracts
 
-Package **1.3.0**, root API **1.3.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateLinearCaptureEncoding
 

package/docs/api/capture-native-environment-raw.md

@@ -0,0 +1,88 @@
+# capture/native-environment-raw.ts public contracts
+
+Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## createNativeEnvironmentRawTask
+
+Every tile is planned and admission-checked before its radiance callbacks; no partial output escapes.
+
+```ts
+export function createNativeEnvironmentRawTask(input:NativeEnvironmentRawInput,provider:NativeEnvironmentRawProvider):NativeEnvironmentRawTask;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## NativeEnvironmentPhotoTile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeEnvironmentPhotoTile extends NativeRawTileRequest {
+  sites:readonly {nativeIndex:number;expectedIncidentPhotonCount:number;expectedGeneratedElectronCount:number}[];
+}
+```
+
+## NativeEnvironmentRawInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeEnvironmentRawInput {
+  raw: NativeRawInput;
+  sceneBinding: SimulateEnvironmentSensorRawFrameInput["sceneBinding"];
+  /** Full-event admission budget; maximum 2 billion calls. No convergence is inferred. */
+  maximumProviderEvaluations: number;
+}
+```
+
+## NativeEnvironmentRawOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeEnvironmentRawOutput {
+  raw: NativeRawOutput;
+  sceneBinding: NativeEnvironmentRawInput["sceneBinding"];
+  providerEvaluationCount: number;
+  upstreamOrigin: "executed-environment-query-provider-optics-psf-eqe";
+  providerTransportVerified: false;
+  productionPlanActivated: false;
+}
+```
+
+## NativeEnvironmentRawProvider
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeEnvironmentRawProvider {
+  /** Supplies physical site profiles, not photo counts or precomputed RAW codes. */
+  readTile(request: Readonly<NativeRawTileRequest>,signal:AbortSignal):Promise<NativeEnvironmentRawTile>;
+  evaluateRadiance: SimulateEnvironmentSensorRawFrameInput["evaluateRadiance"];
+  evaluateApertureRadiance?: SimulateEnvironmentSensorRawFrameInput["evaluateApertureRadiance"];
+  /** Optional bounded diagnostic observer; counts are expectation values before any noise/clamp/ADC. */
+  observePhotoTile?(tile:Readonly<NativeEnvironmentPhotoTile>,signal:AbortSignal):void|Promise<void>;
+  yieldControl(signal:AbortSignal):Promise<void>;
+}
+```
+
+## NativeEnvironmentRawTask
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeEnvironmentRawTask extends Omit<NativeRawTask,"takeOutput"> {
+  readonly providerEvaluationCount: number;
+  takeOutput(): NativeEnvironmentRawOutput;
+}
+```
+
+## NativeEnvironmentRawTile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeEnvironmentRawTile extends NativeRawTileRequest {
+  sites: SimulateEnvironmentSensorRawFrameInput["sites"];
+}
+```

package/docs/api/capture-native-raw-development.md

@@ -0,0 +1,70 @@
+# capture/native-raw-development.ts public contracts
+
+Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## createNativeRawDevelopmentTask
+
+Validates complete phase/halo support, snapshots RAW once, and yields between 256-pixel output tiles.
+Retains explicit acquisition tile width when reconstructing the exact packed plan. Omitted width
+preserves legacy plan shape; inconsistent tile counts or unsupported widths fail validation.
+Acquisition chunk width changes neither CFA/seed coordinates nor development pixels, and does
+not establish transport or device-resource qualification.
+
+```ts
+export function createNativeRawDevelopmentTask(input: NativeRawDevelopmentInput,
+  yieldControl: (signal:AbortSignal)=>Promise<void>): NativeRawDevelopmentTask;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## NativeRawDevelopmentInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeRawDevelopmentInput {
+  raw: NativeRawOutput;
+  phaseProfiles: readonly RawFrameReconstructionPhaseProfile[];
+  colorProfile: ExportSensorColorProfile;
+  whiteBalance: "not-required" | "apply-resolved-sensor-gains";
+  rendering: SdrRenderingProfile;
+  /** Includes one owned packed RAW copy plus integer output; not caller buffers, process heap or GPU. */
+  maximumRetainedPayloadBytes: number;
+}
+```
+
+## NativeRawDevelopmentOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeRawDevelopmentOutput {
+  raw: NativeRawOutput;
+  phaseProfiles: readonly RawFrameReconstructionPhaseProfile[];
+  colorProfile: ExportSensorColorProfile;
+  whiteBalance: NativeRawDevelopmentInput["whiteBalance"];
+  width: number;
+  height: number;
+  integerSamples: Uint8Array | Uint16Array;
+  diagnostics: SdrRenderingResult["diagnostics"];
+  outputEncoding: SdrRenderingResult["outputEncoding"];
+  rendering: SdrRenderingProfile;
+  displayAdaptation: SdrRenderingResult["displayAdaptation"];
+  imageDataPairing: "derived-from-exact-packed-native-raw";
+  producerOriginVerified: false;
+}
+```
+
+## NativeRawDevelopmentTask
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeRawDevelopmentTask {
+  readonly state: NativeRawTaskState;
+  run(): Promise<void>;
+  cancel(): void;
+  dispose(): void;
+  takeOutput(): NativeRawDevelopmentOutput;
+}
+```