@photivra/engine 1.2.0 → 1.4.0

package/docs/API_REFERENCE.md

@@ -1,6 +1,6 @@
 # Public API reference
 
-Generated from the exact root exports for **@photivra/engine 1.2.0 / root contract 1.2.0** by `node scripts/generate-api-reference.mjs`. No module deep import is supported.
+Generated from the exact root exports for **@photivra/engine 1.4.0 / root contract 1.4.0** by `node scripts/generate-api-reference.mjs`. No module deep import is supported.
 
 Use [the developer guide](DEVELOPERS.md) for executable paths and scientific boundaries. Types are contracts, not runtime validation: parse untrusted data, preserve units/reference frames, read assessment blockers, and retain evidence/limitations. Optional properties do not imply a universal default. Model/schema IDs remain independent of the distribution.
 
@@ -105,6 +105,52 @@ Use [the developer guide](DEVELOPERS.md) for executable paths and scientific bou
 | [`LinearCaptureEncodingInput`](api/capture-linear-encoding.md#linearcaptureencodinginput) | Type |
 | [`parseLinearCaptureEncoding`](api/capture-linear-encoding.md#parselinearcaptureencoding) | Runtime |
 
+## capture/native-environment-raw.ts
+
+[Detailed contracts](api/capture-native-environment-raw.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/capture/native-environment-raw.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`createNativeEnvironmentRawTask`](api/capture-native-environment-raw.md#createnativeenvironmentrawtask) | Runtime |
+| [`NativeEnvironmentPhotoTile`](api/capture-native-environment-raw.md#nativeenvironmentphototile) | Type |
+| [`NativeEnvironmentRawInput`](api/capture-native-environment-raw.md#nativeenvironmentrawinput) | Type |
+| [`NativeEnvironmentRawOutput`](api/capture-native-environment-raw.md#nativeenvironmentrawoutput) | Type |
+| [`NativeEnvironmentRawProvider`](api/capture-native-environment-raw.md#nativeenvironmentrawprovider) | Type |
+| [`NativeEnvironmentRawTask`](api/capture-native-environment-raw.md#nativeenvironmentrawtask) | Type |
+| [`NativeEnvironmentRawTile`](api/capture-native-environment-raw.md#nativeenvironmentrawtile) | Type |
+
+## capture/native-raw-development.ts
+
+[Detailed contracts](api/capture-native-raw-development.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/capture/native-raw-development.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`createNativeRawDevelopmentTask`](api/capture-native-raw-development.md#createnativerawdevelopmenttask) | Runtime |
+| [`NativeRawDevelopmentInput`](api/capture-native-raw-development.md#nativerawdevelopmentinput) | Type |
+| [`NativeRawDevelopmentOutput`](api/capture-native-raw-development.md#nativerawdevelopmentoutput) | Type |
+| [`NativeRawDevelopmentTask`](api/capture-native-raw-development.md#nativerawdevelopmenttask) | Type |
+
+## capture/native-raw.ts
+
+[Detailed contracts](api/capture-native-raw.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/capture/native-raw.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`calculateNativeRawPlan`](api/capture-native-raw.md#calculatenativerawplan) | Runtime |
+| [`createNativeRawTask`](api/capture-native-raw.md#createnativerawtask) | Runtime |
+| [`NATIVE_RAW_LIMITS`](api/capture-native-raw.md#native_raw_limits) | Runtime |
+| [`NATIVE_RAW_SCHEMA_VERSION`](api/capture-native-raw.md#native_raw_schema_version) | Runtime |
+| [`NativeRawExposure`](api/capture-native-raw.md#nativerawexposure) | Type |
+| [`NativeRawExposureInput`](api/capture-native-raw.md#nativerawexposureinput) | Type |
+| [`NativeRawInput`](api/capture-native-raw.md#nativerawinput) | Type |
+| [`NativeRawOutput`](api/capture-native-raw.md#nativerawoutput) | Type |
+| [`NativeRawPlan`](api/capture-native-raw.md#nativerawplan) | Type |
+| [`NativeRawProvider`](api/capture-native-raw.md#nativerawprovider) | Type |
+| [`NativeRawTask`](api/capture-native-raw.md#nativerawtask) | Type |
+| [`NativeRawTaskState`](api/capture-native-raw.md#nativerawtaskstate) | Type |
+| [`NativeRawTile`](api/capture-native-raw.md#nativerawtile) | Type |
+| [`NativeRawTileRequest`](api/capture-native-raw.md#nativerawtilerequest) | Type |
+
 ## capture/photographic-export.ts
 
 [Detailed contracts](api/capture-photographic-export.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/capture/photographic-export.ts)
@@ -189,6 +235,7 @@ Use [the developer guide](DEVELOPERS.md) for executable paths and scientific bou
 
 | Export | Kind |
 | --- | --- |
+| [`CaptureExposureSource`](api/capture-simulated-capture.md#captureexposuresource) | Type |
 | [`CaptureFloatStorage`](api/capture-simulated-capture.md#capturefloatstorage) | Type |
 | [`CaptureLinearImageState`](api/capture-simulated-capture.md#capturelinearimagestate) | Type |
 | [`CaptureLinearPlane`](api/capture-simulated-capture.md#capturelinearplane) | Type |
@@ -221,6 +268,15 @@ Use [the developer guide](DEVELOPERS.md) for executable paths and scientific bou
 | [`resolveCaptureColorModel`](api/color-capture-color.md#resolvecapturecolormodel) | Runtime |
 | [`VIRTUAL_COLOR_CAMERA_PROFILE`](api/color-capture-color.md#virtual_color_camera_profile) | Runtime |
 
+## color/srgb-icc.ts
+
+[Detailed contracts](api/color-srgb-icc.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/color/srgb-icc.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`createSrgbIccProfile`](api/color-srgb-icc.md#createsrgbiccprofile) | Runtime |
+| [`SRGB_ICC_PROFILE_VERSION`](api/color-srgb-icc.md#srgb_icc_profile_version) | Runtime |
+
 ## color/white-balance.ts
 
 [Detailed contracts](api/color-white-balance.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/color/white-balance.ts)
@@ -1033,6 +1089,18 @@ Use [the developer guide](DEVELOPERS.md) for executable paths and scientific bou
 | [`SceneSensorQuadratureSample`](api/optics-scene-to-sensor-quadrature.md#scenesensorquadraturesample) | Type |
 | [`SceneToSensorIrradianceQuadrature`](api/optics-scene-to-sensor-quadrature.md#scenetosensorirradiancequadrature) | Type |
 
+## optics/sensor-aperture-rays.ts
+
+[Detailed contracts](api/optics-sensor-aperture-rays.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/optics/sensor-aperture-rays.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`calculateSensorApertureRays`](api/optics-sensor-aperture-rays.md#calculatesensoraperturerays) | Runtime |
+| [`CalculateSensorApertureRaysInput`](api/optics-sensor-aperture-rays.md#calculatesensorapertureraysinput) | Type |
+| [`IdealCircularPupil`](api/optics-sensor-aperture-rays.md#idealcircularpupil) | Type |
+| [`SensorApertureRay`](api/optics-sensor-aperture-rays.md#sensorapertureray) | Type |
+| [`SensorApertureRays`](api/optics-sensor-aperture-rays.md#sensoraperturerays) | Type |
+
 ## optics/sensor-environment-query.ts
 
 [Detailed contracts](api/optics-sensor-environment-query.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/optics/sensor-environment-query.ts)
@@ -1238,6 +1306,23 @@ Use [the developer guide](DEVELOPERS.md) for executable paths and scientific bou
 | [`PrintSinusoidalMeasurement`](api/output-print-detail.md#printsinusoidalmeasurement) | Type |
 | [`PrintSinusoidalTarget`](api/output-print-detail.md#printsinusoidaltarget) | Type |
 
+## output/print-jpeg.ts
+
+[Detailed contracts](api/output-print-jpeg.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/output/print-jpeg.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`createPrintJpegTask`](api/output-print-jpeg.md#createprintjpegtask) | Runtime |
+| [`parsePrintJpegInput`](api/output-print-jpeg.md#parseprintjpeginput) | Runtime |
+| [`PRINT_JPEG_SCHEMA_VERSION`](api/output-print-jpeg.md#print_jpeg_schema_version) | Runtime |
+| [`PrintJpegInput`](api/output-print-jpeg.md#printjpeginput) | Type |
+| [`PrintJpegOutput`](api/output-print-jpeg.md#printjpegoutput) | Type |
+| [`PrintJpegProvider`](api/output-print-jpeg.md#printjpegprovider) | Type |
+| [`PrintJpegSource`](api/output-print-jpeg.md#printjpegsource) | Type |
+| [`PrintJpegTask`](api/output-print-jpeg.md#printjpegtask) | Type |
+| [`PrintJpegTile`](api/output-print-jpeg.md#printjpegtile) | Type |
+| [`PrintJpegTileRequest`](api/output-print-jpeg.md#printjpegtilerequest) | Type |
+
 ## output/print-plan.ts
 
 [Detailed contracts](api/output-print-plan.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/output/print-plan.ts)
@@ -1607,6 +1692,7 @@ Use [the developer guide](DEVELOPERS.md) for executable paths and scientific bou
 | --- | --- |
 | [`calculateEnvironmentSensorPhotoSignal`](api/sensor-environment-photo-signal.md#calculateenvironmentsensorphotosignal) | Runtime |
 | [`CalculateEnvironmentSensorPhotoSignalInput`](api/sensor-environment-photo-signal.md#calculateenvironmentsensorphotosignalinput) | Type |
+| [`EnvironmentApertureRadianceEvaluator`](api/sensor-environment-photo-signal.md#environmentapertureradianceevaluator) | Type |
 | [`EnvironmentRadianceEvaluator`](api/sensor-environment-photo-signal.md#environmentradianceevaluator) | Type |
 | [`EnvironmentSensorPhotoSignal`](api/sensor-environment-photo-signal.md#environmentsensorphotosignal) | Type |
 

package/docs/API_STYLE.md

@@ -1,6 +1,6 @@
 # Public API Style
 
-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).
+Release context: **package 1.3.0 candidate / root API 1.3.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_3_0.md).
 
 The open engine should feel like one coherent library.
 

package/docs/DEVELOPERS.md

@@ -1,18 +1,18 @@
 # Developer guide
 
-This is the entry point for **@photivra/engine 1.2.0 candidate**, root API contract **1.2.0**. The candidate becomes an installable 1.2.0 distribution only after the owner tags and publishes it. Repository `main` may later describe newer development; use a published release's packaged docs or its exact tag for the stable contract. [Release notes and migration](RELEASE_1_2_0.md) explain the transition to aligned package/root versions.
+This is the entry point for **@photivra/engine 1.3.0 candidate**, root API contract **1.3.0**. The candidate becomes an installable 1.3.0 distribution only after the owner tags and publishes it. Repository `main` may later describe newer development; use a published release's packaged docs or its exact tag for the stable contract. [Release notes and migration](RELEASE_1_3_0.md) explain the transition to aligned package/root versions.
 
 Photivra is an Apache-2.0 ESM TypeScript calculation library with no runtime npm dependencies. It exposes explicit units, deterministic data, provenance and bounded scientific approximations. The package supplies no hosted API, renderer installation, UI, commercial camera calibration or automatic agent service. [Photivra's public site](https://photivra.com) is separate from the engine's license; public engine documentation is available here without an application account.
 
 ## Install and calculate
 
-After publication, install `npm install @photivra/engine@1.2.0`. During candidate review, use the verified tarball described in [release preparation](RELEASE_1_2_0.md).
+After publication, install `npm install @photivra/engine@1.3.0`. During candidate review, use the verified tarball described in [release preparation](RELEASE_1_3_0.md).
 
 ```ts
 import { calculateFieldOfView, ENGINE_API_VERSION } from "@photivra/engine";
 
 const horizontal = calculateFieldOfView({ focalLengthMm: 50, sensorDimensionMm: 36 });
-console.log(ENGINE_API_VERSION); // 1.2.0: matches the package version
+console.log(ENGINE_API_VERSION); // 1.3.0: matches the package version
 console.log(horizontal.value.degrees); // approximately 39.60, ideal infinity-focus geometry
 console.log(horizontal.provenance); // read assumptions/status with the value
 ```
@@ -23,7 +23,7 @@ Primitive calculations normally return `CalculationResult<T>` with `value`, `pro
 
 ## Find the operation by scientific task
 
-Every row applies to package/root API 1.2.0. Direct calculations are synchronous/browser-safe unless the row says otherwise. A listed primitive is not automatically an app feature or supported in every production combination. The [API reference](API_REFERENCE.md) resolves all root exports and exact signatures; the linked guides own equations, inputs, defaults, errors and limits.
+Every row applies to package/root API 1.3.0. Direct calculations are synchronous/browser-safe unless the row says otherwise. A listed primitive is not automatically an app feature or supported in every production combination. The [API reference](API_REFERENCE.md) resolves all root exports and exact signatures; the linked guides own equations, inputs, defaults, errors and limits.
 
 | Task | Start here / executable evidence | Qualified boundary |
 | --- | --- | --- |
@@ -61,7 +61,7 @@ Website navigation/documentation hosting belongs to [the app-side discovery tick
 
 ## Print planning
 
-The 1.2.0 candidate adds [registered linear statistics](PRINT_REGION_STATISTICS.md) and a separate [static contrast model reference](PRINT_CONTRAST_REFERENCE.md). The [combined #195/#196 review](PRINT_195_196_REVIEW.md) and [candidate ledger](validation/print-196-candidate-capabilities.json) list executed public-backend experiments and the remaining full release gates. None of these diagnostics supplies a universal quality score.
+The published 1.2.0 release added [registered linear statistics](PRINT_REGION_STATISTICS.md) and a separate [static contrast model reference](PRINT_CONTRAST_REFERENCE.md). The [combined #195/#196 review](PRINT_195_196_REVIEW.md) and [candidate ledger](validation/print-196-candidate-capabilities.json) list executed public-backend experiments and the remaining full release gates. None of these diagnostics supplies a universal quality score.
 
 Use [native-only Print planning](PRINT_PLANNING.md) for independently specified image size/viewing distance, explicit angular conventions, confirmed native crop and lab constraints. It returns no upscale recommendation and does not certify perceived quality or activate an exporter.
 

package/docs/ENVIRONMENT_RAW_CAPTURE.md

@@ -1,5 +1,7 @@
 # Executed environment capture to native RAW
 
+Standalone follow-up: [ideal pupil rays](SENSOR_APERTURE_RAYS.md) adds an explicitly selected origin-aware evaluator. It preserves the bounds below and does not activate production depth/visibility composition.
+
 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).
 
 `calculateEnvironmentSensorPhotoSignal()` executes one destination site's
@@ -50,9 +52,15 @@ the declared optical/provider envelope covers them.
   remains. Translation/parallax, world pose, breathing and distortion are absent.
 - Wavelength-resolved radiance with explicit air/vacuum basis. Any air photon
   energy context remains the existing sensor contract's responsibility.
-- Explicit unity field throughput with evidence and a limitation. Spatial
-  vignetting is not silently synthesized. Existing lens transmission/front-filter
-  inputs remain upstream of normalized PSF shape.
+- Explicit `unity` or `radial-illumination-vignetting` field throughput with evidence
+  and a limitation. The latter reuses the existing bounded radial profile and applies
+  attenuation once at every physical inverse-PSF source point, before normalized
+  PSF redistribution. Camera motion changes scene direction, not lens field position.
+  All taps, including zero-weight taps, must lie in the declared profile envelope
+  before any provider callback. Existing lens transmission/front-filter inputs remain
+  upstream of normalized PSF shape. This is an owned approximation, not calibrated
+  lens throughput or pupil vignetting. Production composition requires the explicit
+  `illumination-vignetting` fidelity effect, including a modeled-zero profile.
 - PSF is explicitly `not-applied` with evidence/limitation or `sampled-local`
   with the existing evidence-backed wavelength basis and local spatial model.
   Focal length, aperture and focus must match the optical bridge. The optional
@@ -185,3 +193,16 @@ The standalone adapter retains its conservative `productionPlanActivated: false`
 field: it cannot know whether a parent composer called it. The parent plan's
 actual stage results and executed lineage establish the bounded activation;
 no child source-truth flag is overwritten.
+
+## Additive field-throughput candidate
+
+Photo integration model 0.2.0 adds radial field-throughput input; unity arithmetic,
+provider/RAW resource limits and conservative verification flags remain unchanged.
+`test/environment-field-throughput.test.ts` independently integrates SI photon counts
+with radial attenuation, checks source-tap PSF weighting, exact unity-profile parity,
+physical field invariance under motion, profile ownership, full-frame preflight and
+replayable paired RAW/JPEG output. The production planner reports requested field
+attenuation as active or modeled-zero and blocks undeclared attenuation before callbacks.
+This candidate has not been tagged or published; the distribution version stays 1.2.0
+until the next release preparation. External chart/backend evidence belongs to its
+provider and does not become an engine calibration claim.

package/docs/NATIVE_RAW_AND_PRINT.md

@@ -0,0 +1,47 @@
+# Native RAW and Print candidate contracts
+
+Version 1.4.0 is a release candidate. It has not been published, tagged or adopted by a production application.
+
+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.
+
+## 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_3_0.md

@@ -0,0 +1,15 @@
+# Photivra engine 1.3.0 release
+
+This minor release adds evidence-bound radial illumination throughput to bounded environment photo/RAW capture, merged in PR #219. Attenuation is applied exactly once before normalized PSF redistribution; every inverse-PSF tap is validated before provider callbacks. Existing unity-throughput arithmetic and resource limits are preserved. No new dependency, calibration claim, or transport qualification is introduced.
+
+## Compatibility and migration
+
+Existing unity-throughput requests remain supported. Requests using the new non-unity field profile must explicitly request the illumination-vignetting fidelity effect in production composition. Invalid or undeclared attenuation fails before provider callbacks. The photo integration model advances independently to 0.2.0.
+
+Package, lock root, citation and ENGINE_API_VERSION are aligned at 1.3.0. New capture/plan creator identities and hashes may change; archived records retain their original creator identity. Historical fixture bytes and independent model/schema/POC/plan versions are preserved.
+
+## Validation and publication
+
+The owner requested immediate release on October 4, 2026. PR #219 already received owner scientific/source review and passed supported Node CI. This release preparation changes metadata and documentation only. Require static policy, tests/coverage, build, generated references, documentation, isolated packed consumer, package-surface and supported Node CI checks on the final release tree.
+
+After merge and successful main CI, create the unused annotated v1.3.0 tag at the verified main commit. The protected publish workflow rechecks tag/main/version and all distribution gates, verifies the tarball checksum and publishes through npm trusted publishing. Observe successful publication and then create the matching GitHub release. Never move tags or overwrite published versions.

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/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/api/camera-equivalent-focal-length.md

@@ -1,6 +1,6 @@
 # camera/equivalent-focal-length.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.4.0**, root API **1.4.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.2.0**, root API **1.2.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.4.0**, root API **1.4.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.2.0**, root API **1.2.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.4.0**, root API **1.4.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.2.0**, root API **1.2.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.4.0**, root API **1.4.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.2.0**, root API **1.2.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.4.0**, root API **1.4.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.2.0**, root API **1.2.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.4.0**, root API **1.4.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.2.0**, root API **1.2.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.4.0**, root API **1.4.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.4.0**, root API **1.4.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,66 @@
+# capture/native-raw-development.ts public contracts
+
+Package **1.4.0**, root API **1.4.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.
+
+```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;
+}
+```