@photivra/engine 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -1,6 +1,91 @@
 # Changelog
 
-## 2.7.0 — unreleased (prepared October 24, 2026)
+## Unreleased
+
+### Faster, same output
+
+- **Display view: a sample's terms written in place; the clock read less often.** Each real pixel's recorded terms went through a new typed-array view (`subarray`, then `fill`) and `Date.now()` was read per display pixel. The terms are now written straight into the real pixel's memo slot (a scratch buffer only for the first sample of a one-material key), and the clock is read every 16 display pixels and at each row's end; yield timing never changes the output.
+  - **Same values:** 57 display views (Speed, a 2 × 2 box aperture and the Quality options; three presets, a caller material scene and a caller function scene; exact and stratified sizes) hash identically before and after: samples, expected values, noise and diagnostics. All hash locks pass.
+  - **Measured:** four 32-row bands of the app's 2028 × 1352 view of a 24 MP frame (a caller material scene, Speed, 2 × 2 box aperture), one thread, median of five alternating runs: 4.31 s → 4.00 s (about 7 %). A line profile puts the rest of the time in the per-real-pixel statistics and the scene's material lookups (the caller's `materialAt` with the frozen point it receives), which these changes leave as they are.
+
+## 2.8.0 — unreleased (prepared October 25, 2026)
+
+A minor release that makes full-resolution captures of chart and material scenes about 50× faster (48–84× in the regions measured), and makes the display view exact at device-pixel sizes.
+- **Faster captures, same bytes:** for chart presets and caller material scenes with a still, rectilinear camera, the RAW stage takes tabulated expected electrons and skips the per-site record pipeline. On every request tested, the samples, RAW codes and files are the bytes of 2.7.0.
+- **Exact display view at device-pixel sizes:** a display pixel covering at most 25 real pixels is the exact area mean of the real pixels instead of a stratified estimate. Those views have new values (a deliberate reference change); the 155-case validation is the same as 2.6.0's or better.
+- **Visible changes:** chart and material captures report a `raw.expectedSignal` assumption and count far fewer `providerEvaluationCount` evaluations; auto white balance no longer renders the RAW twice. Root exports are unchanged (1,727).
+- **Known limit:** the Quality noise limit of 2.6.0 remains (#379), and its fix moves to 2.9.0.
+
+Measured on one thread (24 MP frame, 6 µm, 50 mm f/8, 2 × 2 pixel averaging), with identical samples: a 512 × 512 Siemens star region takes 0.6 s instead of 31.7 s on 2.7.0 (Quality options: 2.8 s instead of 135 s); the whole frame takes 28.2 s as sRGB and 36.5 s as a JPEG.
+
+### Faster, same output
+
+- **Captures of chart and material scenes: tabulated expected electrons, 10–13× faster again; the same bytes on every frame tested (#394, step 2).**
+  - **What changes:** a capture of a chart preset or a caller material scene, with a still, rectilinear, distortion-free camera (no rotation, lens projection or distortion, vignetting, pupil sampling or caller PSF), no longer runs each native site through the environment chain. It takes each site's expected photo electrons from the display view's tabulated expected signal: the same sum over the pixel-aperture nodes, anti-aliasing spots, diffraction taps and spectral nodes, formed in another order. The sensor stage is the native one, with each site's own seeds: dark charge, both Poisson draws, read noise and the ADC.
+  - **Same result, by verification:** one site of each CFA phase still runs the full chain. Its readout must be reproduced bit for bit, and its tabulated electrons must agree with the chain's within 1e-9 relative; otherwise the capture takes the environment path. Electrons that differ in the last bit could, rarely, draw a different integer at a site; on every frame tested none did.
+  - **Measured equality:** 0 differing RAW codes and 0 differing samples:
+    - 1,052,676 native sites of a 24 MP frame in Speed, for dead leaves and for a material scene;
+    - 272,484 sites with the Quality options;
+    - every frame of the 2.0.0 hash locks.
+
+    The verification sites agreed within 2 × 10⁻¹⁵ relative.
+  - **Visible changes:**
+    - a `raw.expectedSignal` assumption names the method and the verification;
+    - `diagnostics.providerEvaluationCount` counts the verification sites' evaluator calls and the table's scene lookups (120 instead of 720 for a 6 × 6 frame);
+    - auto white balance keeps the RAW instead of rendering it again, because its codes do not depend on the white-balance intent.
+
+    The 2.0.0 hash lock's byte digests are unchanged; its assumption and diagnostics digests were re-recorded.
+  - **Measured** on a 512 × 512 centre region of a 24 MP frame (6 µm, 50 mm f/8, 2 × 2 pixel averaging), one thread, one run each, against main with step 1:
+
+    | Scene | Speed | Quality options |
+    | --- | --- | --- |
+    | Siemens star preset | 6.5 → 0.6 s | 37.5 → 2.8 s |
+    | Siemens star as a caller material scene | 7.1 → 0.7 s | 40.4 → 3.0 s |
+
+    The whole 24 MP frame on one thread now takes 28.2 s as sRGB (RAW 24.2 s, development 3.9 s), 36.5 s as a JPEG (encoding 11.2 s) and 75.7 s as a Quality PNG.
+  - **Code:**
+    - the expected signal moved to `src/facade/expected-signal.ts`, so capture-only bundles still leave out the display view;
+    - the input setup is shared with the display view in `src/facade/expected-signal-setup.ts`, and the display view's hash locks are unchanged;
+    - the RAW task is in `src/capture/native-environment-tabulated.ts`.
+
+- **Captures of chart and material scenes: 3.6–8.3× faster RAW stage, no byte changed (#394, step 1).**
+  - **Engine-built tiles without a private copy:** the native environment no longer `structuredClone`s the site records that `simulateCapture` builds for each tile. They are fresh engine records, never shown to supplied code or changed afterwards, so they are planned as engine-owned data directly. Shared records keep their identity, which also makes the template comparisons cheaper. Tiles from callers are still copied.
+  - **Key taps:** for a chart preset or a caller material scene, the engine-built evaluator's result for a query is a pure function of the material at the queried plane point and the wavelength (with object-space diffraction, of the convolved lattice site and the wavelength). A verified lean template now plans its sites' taps as those keys instead of frozen requests, and takes each radiance from the key: chart materials from a table filled once per material and spectral node, lattice sites from the convolved band. Without a PSF a tap's key is the same at every spectral node, so it is found once per spatial node. The evaluator is not called for such taps; the evaluation count is still added, and the abort check still runs.
+  - **Verified per template:** a template takes key taps only when its own site's key radiances equal every radiance of its full execution, tap by tap (`Object.is`). Key taps never apply with pupil rays, a lens field mapping, a caller reflectance or radiance function, or a batched provider. A tap that would need the full irradiance function (a non-finite or negative value, or a field throughput outside the fast path) sends its site through the full path before anything is counted. A caller `materialAt` that throws during key planning sends its site to the full path, which throws the same error.
+  - **Tests:** a new test compares lean and full captures (samples, diagnostics counts, assumptions) for chart presets and caller material scenes in Speed and Quality, with a fixed-size chart, rotation, two temporal samples, a rolling shutter, vignetting and a region, and checks that key taps ran; and that lens field mappings and caller function scenes stay on request taps. All hash locks and facade fingerprints are unchanged.
+  - **Measured** on a 512 × 512 centre region of a 24 MP frame (6 µm, 50 mm f/8, 2 × 2 pixel averaging), one thread, main before and this change after, one run each; samples identical:
+
+    | Scene | Speed | Quality options (diffraction, four-spot filter, AHD) |
+    | --- | --- | --- |
+    | Siemens star preset | 31.7 → 6.5 s (4.9×) | 135.2 → 37.5 s (3.6×) |
+    | Siemens star as a caller material scene | 58.6 → 7.1 s (8.3×) | 252.9 → 40.4 s (6.3×) |
+
+    The material scene gains more because it now also takes the engine-built evaluator's shorter result parsing that chart presets had since 2.6.
+
+### Changed
+
+- **Display view: the exact area mean where a footprint holds at most 25 real pixels (#393).** This is a deliberate reference change.
+  - **Before:** each display pixel's expected value was a stratified estimate over K × K jittered real pixels.
+  - **Now:** where a display pixel's rectangle holds at most 25 real pixels (and at most `view.samplesPerAxis`²), so views at least 1/5 of the frame's width, every real pixel it touches is evaluated once and weighted by its exact overlap, w_j / A. The expected value is then the definition itself, D_P = Σ_j (w_j/A)·E[L_j], with no sampling error.
+  - **Noise:** the linear part keeps the closed-form B_c. The independent residual becomes Σ_j (w_j/A)²·r_j, the same model written exactly.
+  - **Shared terms:** a real pixel's recorded terms are shared by the display pixels that touch it, in a ring of native rows.
+  - **Unchanged:** coarser views keep the stratified estimator and their bytes. The `view.estimation` assumption names the method, and the internal render result reports it.
+  - **Tests:** a new test checks, in Speed and with diffraction, the four-spot filter and AHD, that a half-size and a 2/3-size view of a 48 × 32 frame have exactly the overlap-weighted means of the frame-size view's per-pixel expected values (within 1e-12 relative). Two of the six display-view hash locks and both memo locks were re-recorded (their views take the exact path); the four coarser locks are unchanged.
+  - **Measured** on the 2028 × 1352 view's 8-row strips of a 24 MP frame, the app's chart as a material scene, one thread, against 2.7.0:
+
+    | Strip | Speed | Quality options |
+    | --- | --- | --- |
+    | Rows 660 / 300 / 1000 | 1.04 / 1.01 / 0.97 s → 0.84 / 0.85 / 0.77 s | 2.9 / 3.1 / 2.7 s → 2.3 / 2.8 / 2.3 s |
+
+    Samples fell 3–9× and site evaluations 3–10×. The time fell less, because the 2.7 memos had already made repeated samples cheap: at device-pixel sizes the view now does about one real pixel's work per real pixel.
+  - **Why 25:** measured on 8-row strips of a 24 MP view (Siemens star and dead leaves, f/2.8, one thread, one run each), the exact path took the stratified estimator's time within run-to-run spread up to 25 real pixels per display pixel and longer above: 1.1–1.2× at 36, 1.4–1.5× at 64, 1.5–2.4× at 144, because it evaluates every real pixel while the estimator takes a quarter of its samples per axis where the pilot finds no detail.
+  - **Validation:** the 155-case validation was re-run on October 25 (`de77074`, [record](https://github.com/Photivra/photivra/blob/main/docs/validation/display-view-2026-10-25/README.md)): 145 cases are identical to the 2.6.0 record, and the 10 cases on the exact area mean (the phone at 800 wide) are the same or better (Siemens star: expected-value RMS 1.78 → 1.35 codes, SSIM 0.9931 → 0.9966). The known Quality noise miss of case 138 (#379) remains: 1.165 against the 1.15 limit.
+
+### Known limit
+
+- **Quality noise at small footprints (#379), unchanged from 2.6.0.** With `output.demosaic: "ahd"` the display view's noise has too much colour where a display pixel covers few sensor pixels; validation case 138 is outside its limit (1.165 against 1.15). The exact covariance through AHD's two linear candidates was measured and makes it worse (1.351), because AHD's direction choice reacts to the noise; the remaining fix is a Monte Carlo model of the real AHD output's noise covariance, moved to 2.9.0 by the owner's decision of October 25, 2026. Speed (bilinear) is exact, and the Photivra site offers Speed only.
+
+## 2.7.0 — published October 24, 2026
 
 A minor release that makes the display view much faster at device-pixel sizes and adds two APIs for it.
 - **API for regions:** `prepareDisplayView` resolves a request once for many regions.

package/CITATION.cff

@@ -9,7 +9,7 @@ abstract: "An open TypeScript engine for the science and mathematics of photogra
 repository-code: "https://github.com/photivra/photivra"
 url: "https://photivra.com"
 license: "Apache-2.0"
-version: "2.7.0"
+version: "2.8.0"
 keywords:
   - photography
   - camera optics

package/README.md

@@ -32,10 +32,10 @@ The source is licensed under Apache-2.0.
 
 ## Quick start
 
-Install the published ESM package below. The [2.7.0 release record](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_2_7_0.md) and [changelog](https://github.com/Photivra/photivra/blob/main/CHANGELOG.md) describe the current release:
+Install the published ESM package below. The [2.8.0 release record](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_2_8_0.md) and [changelog](https://github.com/Photivra/photivra/blob/main/CHANGELOG.md) describe the current release:
 
 ```sh
-npm install @photivra/engine@2.7.0
+npm install @photivra/engine@2.8.0
 ```
 
 Simulate a photograph of a test chart with a generic camera, then read the developed sRGB pixels:
@@ -75,7 +75,7 @@ console.log(horizontal.provenance);
 
 Start with the [Developer Guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Then use the [Usage Guide](https://github.com/Photivra/photivra/blob/main/docs/USAGE.md) and the [API reference](https://github.com/Photivra/photivra/blob/main/docs/API_REFERENCE.md), which is generated from the package exports.
 
-Repository `main` may describe newer, unreleased work. For the stable contract, use the docs bundled in the published package, or the exact `v2.7.0` tag.
+Repository `main` may describe newer, unreleased work. For the stable contract, use the docs bundled in the published package, or the exact `v2.8.0` tag.
 
 ## Documentation
 
@@ -363,13 +363,13 @@ The application can then use those results, while the photography calculations t
 
 ## Status
 
-- Repository package version: `2.7.0` (release candidate prepared October 24, 2026; publication is separate)
-- Engine API contract: `2.7.0`
+- Repository package version: `2.8.0` (release candidate prepared October 25, 2026; publication is separate)
+- Engine API contract: `2.8.0`
 - Versioned generic tier reference assets: [GENERIC_TIER_PRESETS.md](https://github.com/Photivra/photivra/blob/main/docs/GENERIC_TIER_PRESETS.md).
 - Composed POC simulation API contract: `1.0.0`
 - Stability: 1.0 root-package compatibility policy; bounded scientific models and independent POC contract
 
-From 1.0.1, the package version and `ENGINE_API_VERSION` are equal. New captures/plans record 2.7.0; existing archives keep their original creator identities. Schema, model and POC contract versions stay independent.
+From 1.0.1, the package version and `ENGINE_API_VERSION` are equal. New captures/plans record 2.8.0; existing archives keep their original creator identities. Schema, model and POC contract versions stay independent.
 
 A breaking change to the root contracts now needs a new package major version. Additive and corrective changes follow [compatibility and migration](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_1_3_0.md). A 1.0 package is not a claim of calibrated physical accuracy.
 

package/SECURITY.md

@@ -4,7 +4,7 @@ Please do not open a public issue that contains vulnerability details.
 
 ## Supported versions
 
-The published 1.0.0 release started the 1.x root-package compatibility line, and 2.0.0 started the 2.x line. The current release is **2.6.0**, published on October 20, 2026 (see [CHANGELOG.md](CHANGELOG.md)).
+The published 1.0.0 release started the 1.x root-package compatibility line, and 2.0.0 started the 2.x line. The current release is **2.7.0**, published on October 24, 2026 (see [CHANGELOG.md](CHANGELOG.md)).
 
 Security fixes target the current maintained development and release line. Do not assume that older 1.x releases, snapshots or pre-1.0 releases will receive fixes.
 

package/dist/capture/native-environment-lean.d.ts

@@ -32,14 +32,15 @@
 import type { SimulateEnvironmentSensorRawFrameInput } from "./environment-raw-producer.js";
 import type { planEnvironmentSensorPhotoSignal, executeEnvironmentSensorPhotoSignal, EnvironmentRadianceEvaluator, EnvironmentApertureRadianceEvaluator } from "../sensor/environment-photo-signal.js";
 import type { SensorEqeTemporalPhotoSignal } from "../sensor/temporal-photo-signal.js";
+import { type InternalRadianceAccess } from "../core/internal-radiance-evaluator.js";
 import { type SceneRadianceEvaluationRequest } from "../schema/scene-radiance.js";
 import { type PreparedEnvironmentLensFieldMapping } from "../optics/sensor-environment-query.js";
 import { type ResolveLensSampledPsfInput } from "../optics/lens-psf-profile.js";
 import { type SensorApertureRay } from "../optics/sensor-aperture-rays.js";
 import { parseFocusPlane } from "../optics/focus-state.js";
 import { prepareCaptureExposureWindowSampler } from "../sensor/exposure-window.js";
-import { type NativeRawProducerFrameContext } from "./sensor-raw-producer.js";
-import type { NativeRawLeanSensorHook } from "./native-raw.js";
+import { calculateNativeRawSite, type NativeRawProducerFrameContext, type SensorRawProducerSiteInput } from "./sensor-raw-producer.js";
+import type { NativeRawLeanOutput, NativeRawLeanSensorHook } from "./native-raw.js";
 type Site = SimulateEnvironmentSensorRawFrameInput["sites"][number];
 type Env = Site["environment"];
 type FullPlan = ReturnType<typeof planEnvironmentSensorPhotoSignal>;
@@ -51,6 +52,7 @@ export declare const nativeEnvironmentLeanStatistics: {
     executedSites: number;
     sensorSites: number;
     psfFallbacks: number;
+    keySites: number;
 };
 export declare function setNativeEnvironmentLeanExecutionEnabled(enabled: boolean): void;
 interface SpatialNode {
@@ -86,6 +88,13 @@ interface Template {
     execution?: ExecutionConstants;
     /** undefined until the template site executed through the full path. */
     executionVerified?: boolean;
+    /**
+     * #394: true when an engine-built evaluator's key lookup reproduced every radiance of the template's own full execution; its
+     * sites are then planned as key taps and their radiances taken from the lookup instead of the evaluator (tabulated keys, chart
+     * materials, from `radiance`: per key, per spectral node, NaN until first needed).
+     */
+    keyMode?: boolean;
+    radiance?: Float64Array[];
 }
 interface PlanConstants {
     spectralCount: number;
@@ -131,7 +140,10 @@ interface PlanConstants {
     sceneBindings: FullPlan["sceneBindings"];
 }
 interface LeanTap {
-    request: SceneRadianceEvaluationRequest;
+    /** The provider request; absent for a key tap (#394), whose radiance comes from the evaluator's key lookup. */
+    request?: SceneRadianceEvaluationRequest;
+    /** #394: the key (chart material or lattice site) the request would read (key taps only). */
+    key?: number;
     sourcePointImagePlaneMm: {
         x: number;
         y: number;
@@ -167,6 +179,8 @@ export interface LeanEnvironmentPlan {
     }[];
     /** Per group: the resolved PSF kernel weights. Present only with a sampled PSF. */
     readonly kernels?: readonly (readonly number[])[];
+    /** #394: true when the taps are key taps (no requests). */
+    readonly keyTaps?: true;
 }
 export declare function isLeanEnvironmentPlan(plan: unknown): plan is LeanEnvironmentPlan;
 export interface NativeEnvironmentLeanFrame {
@@ -197,9 +211,25 @@ export interface NativeEnvironmentLeanExecutor {
      * caller then plans and executes this site in full. `fullPlan` builds the site's full plan without callbacks;
      * it is called only when a sampled-PSF check fails and the full PSF quadrature must decide.
      */
-    execute(plan: LeanEnvironmentPlan, evaluate: EnvironmentRadianceEvaluator, aperture: EnvironmentApertureRadianceEvaluator | undefined, fullPlan: () => FullPlan, internalEvaluator?: boolean): SensorEqeTemporalPhotoSignal | undefined;
+    execute(plan: LeanEnvironmentPlan, evaluate: EnvironmentRadianceEvaluator, aperture: EnvironmentApertureRadianceEvaluator | undefined, fullPlan: () => FullPlan, internalEvaluator?: boolean, countEvaluations?: (count: number) => void): SensorEqeTemporalPhotoSignal | undefined;
 }
-export declare function createNativeEnvironmentLeanExecutor(frame: NativeEnvironmentLeanFrame): NativeEnvironmentLeanExecutor;
+/**
+ * Creates the per-event lean executor. With `access` (#394: the key lookup of an engine-built evaluator), a template whose own
+ * site verifies it plans its sites as key taps and takes their radiances from the lookup.
+ */
+export declare function createNativeEnvironmentLeanExecutor(frame: NativeEnvironmentLeanFrame, access?: InternalRadianceAccess): NativeEnvironmentLeanExecutor;
+/** #394: the sensor stage of one CFA phase for given expected photo electrons, verified against a full site computation. */
+export interface NativeSiteReadout {
+    /** The site's RAW outputs for expected photo electrons `photoE` over a local exposure of `duration` seconds; undefined where a check of the full path would throw. */
+    compute(photoE: number, duration: number, x: number, y: number, index: number, seed: number): NativeRawLeanOutput | undefined;
+}
+/**
+ * #394: a sensor template from one fully parsed and computed site (`calculateNativeRawSite`), as the lean sensor stage builds
+ * its templates; undefined unless the lean arithmetic reproduces that site's dark and total charge, both charge realizations,
+ * its codes and its flags bit for bit. Its `compute` then gives `calculateNativeRawSite`'s outputs for any site of the same
+ * readout inputs (same CFA channel, dark current, capacity, readout regime and fixed-pattern profile).
+ */
+export declare function createVerifiedNativeSiteReadout(parsed: SensorRawProducerSiteInput, result: ReturnType<typeof calculateNativeRawSite>, whiteCode: number, photo: SensorEqeTemporalPhotoSignal, x: number, y: number, index: number, seed: number): NativeSiteReadout | undefined;
 /**
  * Lean sensor stage for createNativeEnvironmentRawTask.
  *

package/dist/capture/native-environment-lean.js

@@ -30,7 +30,7 @@ const REDUCTION_TOLERANCE = 1e-10;
 /** Disables the lean executor process-wide (internal; tests compare both paths). */
 let leanDisabled = false;
 /** Internal counters of lean work (tests assert the lean path actually runs). Not exported from the package. */
-export const nativeEnvironmentLeanStatistics = { plannedSites: 0, executedSites: 0, sensorSites: 0, psfFallbacks: 0 };
+export const nativeEnvironmentLeanStatistics = { plannedSites: 0, executedSites: 0, sensorSites: 0, psfFallbacks: 0, keySites: 0 };
 export function setNativeEnvironmentLeanExecutionEnabled(enabled) { leanDisabled = !enabled; }
 function isPlainRecord(value) {
     const prototype = Object.getPrototypeOf(value);
@@ -137,8 +137,12 @@ function siteOf(environment) {
     const site = plainChild(plainChild(plainChild(environment, "sensor"), "spatialSampling"), "site");
     return site;
 }
-/** Plans the site-dependent parts with the full planner's arithmetic. Returns undefined on any doubt, and the caller plans in full. */
-function geometry(t, k, frame, environment, index) {
+/**
+ * Plans the site-dependent parts with the full planner's arithmetic. Returns undefined on any doubt, and the caller plans in full.
+ * With `access` (#394: a verified key-mode template, no pupil or lens mapping), each tap keeps the key its request would read
+ * instead of the request.
+ */
+function geometry(t, k, frame, environment, index, access) {
     try {
         const x = index % frame.nativeWidth, y = Math.floor(index / frame.nativeWidth), site = siteOf(environment);
         // Object.is: a -0 coordinate would flow into the full path's outputs, so it takes the full path.
@@ -233,14 +237,22 @@ function geometry(t, k, frame, environment, index) {
             const displacement = { pitch: omega.pitch * time, yaw: omega.yaw * time, roll: omega.roll * time };
             const taps = [];
             for (let gi = 0; gi < S * P; gi++) {
+                // #394: without a PSF a key tap depends only on its spatial node (same point, direction, field and key at
+                // every spectral node), so groups after the first spectral node share the first one's tap.
+                if (access !== undefined && destinationFields !== undefined && gi >= P) {
+                    taps.push(taps[gi % P]);
+                    continue;
+                }
                 const s = Math.floor(gi / P), points = destinationFields === undefined ? tapPoints[gi] : undefined;
                 const tapCount = points === undefined ? 1 : points.length;
                 for (let pi = 0; pi < tapCount; pi++) {
-                    const point = points === undefined ? sources[gi % P] : points[pi], sampleId = `${id}-t${ti}-n${gi}-p${pi}`;
+                    const point = points === undefined ? sources[gi % P] : points[pi], sampleId = access === undefined ? `${id}-t${ti}-n${gi}-p${pi}` : "";
                     const apertureRays = pupil === undefined ? undefined : sensorApertureRayValues({ sourcePointNativeSensorMm: point, focalLengthMm,
                         nominalFNumber, angularVelocityRadPerSec: omega, timeSecondsFromOpeningReference: time }, pupil, k.parsedFocus).rays;
-                    let request, imagePointMm, distortionAreaFactor;
+                    let request, key, imagePointMm, distortionAreaFactor;
                     if (k.lensMapping !== undefined) {
+                        if (access !== undefined)
+                            return undefined;
                         // The full planner's own mapped query, with the same input; only its result envelope is not kept.
                         const query = calculateMappedSensorEnvironmentRadianceQuery({ ...motion, sourcePointNativeSensorMm: point, focalLengthMm, focus: k.focus,
                             timeSecondsFromOpeningReference: time, request: { schemaVersion: "0.1.0", sampleId, providerProfileId: base.providerProfileId, sceneId: base.sceneId,
@@ -272,15 +284,26 @@ function geometry(t, k, frame, environment, index) {
                         const norm = Math.hypot(direction.x, direction.y, direction.z);
                         if (!Number.isFinite(norm) || Math.abs(norm - 1) > 1e-9)
                             return undefined;
-                        request = Object.freeze({ schemaVersion: "0.1.0", sampleId, providerProfileId: base.providerProfileId,
-                            sceneId: base.sceneId, illuminationProfileId: base.illuminationProfileId, materialResponseProfileId: base.materialResponseProfileId,
-                            target: Object.freeze({ kind: "environment-direction", outgoingDirectionUnitVector: Object.freeze(direction) }),
-                            timeSecondsFromExposureStart: time, wavelengthNanometers: k.wavelengths[s],
-                            wavelengthBasis: base.wavelengthBasis });
+                        // #394: the key the evaluator would read for this request (undefined where it would throw: the full path decides).
+                        if (access !== undefined) {
+                            key = access.keyOfDirection(direction);
+                            if (key === undefined)
+                                return undefined;
+                        }
+                        else
+                            request = Object.freeze({ schemaVersion: "0.1.0", sampleId, providerProfileId: base.providerProfileId,
+                                sceneId: base.sceneId, illuminationProfileId: base.illuminationProfileId, materialResponseProfileId: base.materialResponseProfileId,
+                                target: Object.freeze({ kind: "environment-direction", outgoingDirectionUnitVector: Object.freeze(direction) }),
+                                timeSecondsFromExposureStart: time, wavelengthNanometers: k.wavelengths[s],
+                                wavelengthBasis: base.wavelengthBasis });
                     }
                     const f = destinationFields === undefined ? tapFields[gi][pi] : destinationFields[gi % P];
                     // Built without object spread (cheaper per tap); optional fields are added only when present.
-                    const leanTap = { request, sourcePointImagePlaneMm: imagePointMm, fieldThroughput: f.value, fieldFactor: f.factor, fieldValid: f.valid };
+                    const leanTap = { sourcePointImagePlaneMm: imagePointMm, fieldThroughput: f.value, fieldFactor: f.factor, fieldValid: f.valid };
+                    if (request !== undefined)
+                        leanTap.request = request;
+                    else
+                        leanTap.key = key;
                     if (apertureRays !== undefined)
                         leanTap.apertureRays = apertureRays;
                     if (distortionAreaFactor !== undefined)
@@ -291,7 +314,7 @@ function geometry(t, k, frame, environment, index) {
             instants.push({ time, taps });
         }
         return { lean: true, template: t, index, owned: environment, count: k.count, site: { x, y }, start, end, duration, instants,
-            ...(k.psf === undefined ? {} : { kernels }) };
+            ...(k.psf === undefined ? {} : { kernels }), ...(access === undefined ? {} : { keyTaps: true }) };
     }
     catch {
         return undefined;
@@ -610,7 +633,45 @@ function executionConstants(k, environment, plan, result, self) {
     const mine = photo(k, c, values, environment, full.site, full.startOffsetSecondsFromOpeningReference, full.endOffsetSecondsFromOpeningReference, full.localExposureDurationSeconds, plan.instants.map(i => i.time));
     return mine && sameData(mine, full, new WeakMap()) ? c : undefined;
 }
-export function createNativeEnvironmentLeanExecutor(frame) {
+/** #394: the evaluator's radiance for a key at spectral node s (tabulated keys from the template's table, computed once). */
+function keyRadiance(t, k, access, key, s) {
+    // Untabulated keys (lattice sites) are read from the evaluator's own lookup on each use.
+    if (!access.tabulated)
+        return access.radianceOfKey(key, k.wavelengths[s]);
+    const table = t.radiance, row = table[key] ??= new Float64Array(k.spectralCount).fill(NaN);
+    let value = row[s];
+    if (Number.isNaN(value)) {
+        value = access.radianceOfKey(key, k.wavelengths[s]);
+        row[s] = value;
+    }
+    return value;
+}
+/**
+ * #394: true when the key taps of the template's own site give, tap by tap in callback order, exactly the radiance of each
+ * evaluation of its full execution. Only then do its sites take radiances from the key lookup.
+ */
+function keyModeReproduced(t, k, access, self, result) {
+    if (!self || self.keyTaps !== true || k.pupilCount !== 1 || self.instants.length !== result.value.instants.length)
+        return false;
+    const S = k.spectralCount, P = k.spatialCount;
+    for (let ti = 0; ti < self.instants.length; ti++) {
+        const evaluations = result.value.instants[ti].evaluations, taps = self.instants[ti].taps;
+        if (evaluations.length !== taps.length)
+            return false;
+        for (let gi = 0; gi < S * P; gi++)
+            for (let i = k.tapOffsets[gi]; i < k.tapOffsets[gi + 1]; i++) {
+                const key = taps[i].key;
+                if (key === undefined || !Object.is(keyRadiance(t, k, access, key, Math.floor(gi / P)), evaluations[i].result.spectralRadianceWattsPerSquareMeterSteradianNanometer))
+                    return false;
+            }
+    }
+    return true;
+}
+/**
+ * Creates the per-event lean executor. With `access` (#394: the key lookup of an engine-built evaluator), a template whose own
+ * site verifies it plans its sites as key taps and takes their radiances from the lookup.
+ */
+export function createNativeEnvironmentLeanExecutor(frame, access) {
     const templates = [];
     const candidates = new Map();
     const memo = new WeakMap();
@@ -651,7 +712,7 @@ export function createNativeEnvironmentLeanExecutor(frame) {
                 return templates.length < MAXIMUM_TEMPLATES ? "candidate" : undefined;
             if (t.disabled || !t.consts || t.executionVerified === false)
                 return undefined;
-            const leanPlan = geometry(t, t.consts, frame, environment, index);
+            const leanPlan = geometry(t, t.consts, frame, environment, index, t.keyMode === true ? access : undefined);
             if (leanPlan)
                 nativeEnvironmentLeanStatistics.plannedSites++;
             return leanPlan;
@@ -688,19 +749,81 @@ export function createNativeEnvironmentLeanExecutor(frame) {
                     return;
                 t.execution = c;
                 t.executionVerified = true;
+                // #394: key taps need no pupil and no lens mapping (the evaluator then reads one plane point per tap).
+                if (access !== undefined && t.consts.lensMapping === undefined && t.environment.pupil === undefined) {
+                    t.radiance = [];
+                    t.keyMode = keyModeReproduced(t, t.consts, access, geometry(t, t.consts, frame, t.environment, index, access), result);
+                    if (!t.keyMode)
+                        delete t.radiance;
+                }
             }
             catch {
                 // Unverified: sites of this template run the full path.
             }
         },
-        execute(plan, evaluate, aperture, fullPlan, internalEvaluator = false) {
+        execute(plan, evaluate, aperture, fullPlan, internalEvaluator = false, countEvaluations) {
             const t = plan.template, c = t.execution, k = t.consts;
             if (t.executionVerified !== true || !c || !k)
                 return undefined;
             const environment = plan.owned, optics = environment.optics;
             const S = k.spectralCount, P = k.spatialCount, kernels = plan.kernels;
+            if (plan.keyTaps === true) {
+                // #394: every tap's radiance from the evaluator's key lookup, with tapIrradiance's arithmetic. A tap that would
+                // need the full irradiance function returns undefined before anything is counted: the caller runs the site in full.
+                if (t.keyMode !== true || !access || !countEvaluations)
+                    return undefined;
+                const values = [], times = [], instantTaps = [];
+                for (const instant of plan.instants) {
+                    const v = new Float64Array(S * P), tapValues = [];
+                    if (kernels === undefined) {
+                        // One tap per group.
+                        for (let gi = 0; gi < S * P; gi++) {
+                            const tap = instant.taps[gi], s = Math.floor(gi / P);
+                            const irradiance = keyRadiance(t, k, access, tap.key, s) * (c.acceptance[s] * tap.fieldFactor);
+                            if (!tap.fieldValid || !Number.isFinite(irradiance) || irradiance < 0)
+                                return undefined;
+                            let integrated = 0;
+                            integrated += irradiance * 1;
+                            v[gi] = integrated;
+                        }
+                        values.push(v);
+                        times.push(instant.time);
+                        continue;
+                    }
+                    for (let gi = 0; gi < S * P; gi++) {
+                        const first = k.tapOffsets[gi], s = Math.floor(gi / P), groupValues = new Float64Array(k.tapOffsets[gi + 1] - first);
+                        for (let pi = 0; pi < groupValues.length; pi++) {
+                            const tap = instant.taps[first + pi];
+                            const irradiance = keyRadiance(t, k, access, tap.key, s) * (c.acceptance[s] * tap.fieldFactor);
+                            if (!tap.fieldValid || !Number.isFinite(irradiance) || irradiance < 0)
+                                return undefined;
+                            let integrated = 0;
+                            integrated += irradiance * 1;
+                            groupValues[pi] = integrated;
+                        }
+                        tapValues.push(groupValues);
+                        v[gi] = kernels === undefined ? groupValues[0] : psfSum(kernels[gi], groupValues);
+                    }
+                    values.push(v);
+                    instantTaps.push(tapValues);
+                    times.push(instant.time);
+                }
+                // The evaluations the full path would count (and its abort check), then the PSF checks after each instant's taps.
+                countEvaluations(plan.count);
+                let full;
+                if (kernels !== undefined)
+                    for (let ti = 0; ti < values.length; ti++) {
+                        if (!psfChecksPass(k, c, instantTaps[ti], values[ti]))
+                            values[ti] = fullPsfInstant(full ??= fullPlan(), ti, instantTaps[ti]);
+                    }
+                nativeEnvironmentLeanStatistics.executedSites++;
+                nativeEnvironmentLeanStatistics.keySites++;
+                return photo(k, c, values, environment, plan.site, plan.start, plan.end, plan.duration, times) ??
+                    createSensorEqeTemporalPhotoSignal(fullPhotoInput(k, values, environment, times)).value.photoSignal;
+            }
             /** One tap: its callbacks in order, each result validated, the pupil sum, then the distortion area factor once. */
-            const tapIrradiance = (tap, s) => {
+            const tapIrradiance = (leanTap, s) => {
+                const tap = leanTap;
                 let integrated = 0;
                 const support = tap.apertureRays ?? [undefined];
                 for (const ray of support) {
@@ -888,6 +1011,42 @@ function chargeTotal(photoE, darkE) {
     }
     return sum;
 }
+/**
+ * #394: a sensor template from one fully parsed and computed site (`calculateNativeRawSite`), as the lean sensor stage builds
+ * its templates; undefined unless the lean arithmetic reproduces that site's dark and total charge, both charge realizations,
+ * its codes and its flags bit for bit. Its `compute` then gives `calculateNativeRawSite`'s outputs for any site of the same
+ * readout inputs (same CFA channel, dark current, capacity, readout regime and fixed-pattern profile).
+ */
+export function createVerifiedNativeSiteReadout(parsed, result, whiteCode, photo, x, y, index, seed) {
+    try {
+        const readout = resolveSensorReadoutRegime({ profile: parsed.readoutProfile, regimeId: parsed.regimeId });
+        const t = { darkRate: parsed.charge.darkCharge.darkCurrentElectronsPerSecond,
+            capacity: result.capacity.value.physicalChargeCapacityElectrons, readout, pattern: parsed.fixedPatternNoise, whiteCode };
+        const darkE = t.darkRate * photo.localExposureDurationSeconds, total = chargeTotal(photo.expectedGeneratedElectronCount, darkE);
+        const r = result.readout.value, realization = result.realization.value, out = leanSensorSite(t, { photo, darkE, total, x, y }, index, seed);
+        if (!out || !Object.is(darkE, parsed.charge.darkCharge.expectedDarkElectronCount) || !Object.is(total, result.accumulatedCharge.value.totalExpectedStoredElectronCount) ||
+            !Object.is(out.photoRealized, realization.photoRealizedElectronCount) || !Object.is(out.darkRealized, realization.darkRealizedElectronCount) ||
+            realization.additionalComponents.length !== 0 || out.rawCode !== r.rawCode || out.blackLevelCode !== r.blackLevelCode || out.digitalSaturationCode !== r.digitalSaturationCode ||
+            out.flags !== (Number(r.physicalScalarSaturationApplied) | Number(r.preAdcSaturationApplied) << 1 | Number(r.digitalSaturationApplied) << 2))
+            return undefined;
+        return {
+            compute(photoE, duration, sx, sy, siteIndex, siteSeed) {
+                // The parse-phase predicates of the full path (claim()): finite non-negative dark and total charge.
+                const siteDark = t.darkRate * duration;
+                if (!Number.isFinite(photoE) || photoE < 0 || !Number.isFinite(siteDark) || siteDark < 0)
+                    return undefined;
+                const siteTotal = chargeTotal(photoE, siteDark);
+                if (!Number.isFinite(siteTotal) || siteTotal < 0)
+                    return undefined;
+                const o = leanSensorSite(t, { photo: { expectedGeneratedElectronCount: photoE }, darkE: siteDark, total: siteTotal, x: sx, y: sy }, siteIndex, siteSeed);
+                return o && { rawCode: o.rawCode, blackLevelCode: o.blackLevelCode, digitalSaturationCode: o.digitalSaturationCode, flags: o.flags, whiteCode: o.whiteCode };
+            }
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 export function createNativeEnvironmentSensorLean(frame, producerFrame, nativeWindow) {
     const enabled = !leanDisabled && nativeWindow !== undefined && frame.identityBinding && frame.repeatWidth > 0 && frame.repeatHeight > 0;
     const templates = [], handles = new WeakMap(), memo = new WeakMap();