@photivra/engine 1.5.0 → 2.1.0

package/dist/capture/native-environment-optical-stage.js

@@ -0,0 +1,340 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Keeps (retains) the result of the optical stage of a native environment capture, so the sensor stage
+ * can be re-run with new post-optics settings without calling the radiance callbacks again.
+ *
+ * Optical stage: scene radiance → optics, PSF (point-spread function) and pupil → expected photo signal
+ * via EQE (external quantum efficiency). Sensor stage: dark charge → charge realization → readout.
+ *
+ * Reuse is exact, not approximate: the sensor stage receives a photo signal whose every number is the
+ * float64 value the optical stage produced, and the same charge/noise/ADC code runs on it. Reuse is
+ * refused unless the capture's optical binding and every site's environment input are strictly equal
+ * to those the stage was produced from.
+ * @see docs/NATIVE_RAW_AND_PRINT.md for the invariance analysis, memory bound and limits.
+ */
+import { createNativeRawTask } from "./native-raw.js";
+import { parseSensorEqeTemporalPhotoSignal } from "../sensor/temporal-photo-signal.js";
+import { calculateSensorDarkCurrentCharge } from "../sensor/dark-current.js";
+import { requireAllowlistedRecord } from "../core/record-validation.js";
+import { stringifyCanonicalJson } from "../core/canonical-json.js";
+import { freezeOwnedData } from "../core/owned-data.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+/**
+ * Fixed retention limits. The per-site footprint of a retained optical stage is
+ * `fixedBytesPerSite + bytesPerTemporalSamplePerSite × temporalSampleCount` bytes of typed-array storage;
+ * distinct environment and photo templates (each about one site's input size) are capped separately.
+ */
+export const NATIVE_ENVIRONMENT_OPTICAL_STAGE_LIMITS = Object.freeze({
+    /** Two one-byte template indices plus seven float64 values (site x/y, window start/end/duration, photon/electron counts). */
+    fixedBytesPerSite: 58,
+    /** Three float64 values per temporal midpoint: time, incident-photon rate, generated-electron rate. */
+    bytesPerTemporalSamplePerSite: 24,
+    /** Distinct per-site environment inputs once the site index and integration ID are removed. */
+    maximumEnvironmentTemplates: 256,
+    /** Distinct photo-signal identity/evidence records once per-site numbers are removed. */
+    maximumPhotoTemplates: 256
+});
+const FIXED_VALUES = 7;
+const ENVIRONMENT_SHARED_KEYS = ["sceneBindings", "optics", "motion", "psf", "pupil", "fieldThroughput"];
+function canonical(value) {
+    return stringifyCanonicalJson(value, { undefinedObjectProperties: "omit", nonFiniteNumberMessage: "Invalid native scene binding.",
+        unsupportedValueMessage: "Invalid native scene binding." });
+}
+function isPlainRecord(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Strict structural equality of plain data: Object.is for primitives (so 0 and -0 differ), identical own
+ * key sets, arrays element by element. Anything that is not a plain record or array is unequal unless it is
+ * the same reference, so an unexpected value refuses reuse instead of being treated as equal.
+ */
+function strictlyEqual(a, b, verified, skip) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+        return false;
+    if (!skip && verified.get(a)?.has(b))
+        return true;
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b) || a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (!(i in a) || !(i in b) || !strictlyEqual(a[i], b[i], verified))
+                return false;
+        }
+    }
+    else {
+        if (Array.isArray(b) || !isPlainRecord(a) || !isPlainRecord(b))
+            return false;
+        const ak = Object.keys(a), bk = Object.keys(b);
+        if (ak.length !== bk.length || Object.getOwnPropertySymbols(a).length !== 0 || Object.getOwnPropertySymbols(b).length !== 0)
+            return false;
+        for (const key of ak) {
+            if (!Object.prototype.hasOwnProperty.call(b, key))
+                return false;
+            if (skip?.has(key))
+                continue;
+            if (!strictlyEqual(a[key], b[key], verified))
+                return false;
+        }
+    }
+    if (!skip) {
+        let set = verified.get(a);
+        if (!set)
+            verified.set(a, set = new WeakSet());
+        set.add(b);
+    }
+    return true;
+}
+/**
+ * Environment equality except the two per-site fields that are bound to the absolute native index and
+ * checked separately: temporalIntegrationId and sensor.spatialSampling.site.
+ */
+function environmentMatches(e, t, verified) {
+    if (typeof e !== "object" || e === null || typeof e.sensor !== "object" || e.sensor === null ||
+        typeof e.sensor.spatialSampling !== "object" || e.sensor.spatialSampling === null)
+        return false;
+    return strictlyEqual(e, t, verified, new Set(["temporalIntegrationId", "sensor"])) &&
+        strictlyEqual(e.sensor, t.sensor, verified, new Set(["spatialSampling"])) &&
+        strictlyEqual(e.sensor.spatialSampling, t.sensor.spatialSampling, verified, new Set(["site"]));
+}
+/**
+ * Post-optics capture fields: noise seed/realization/model, ISO metadata, white-balance intent, adopted white,
+ * capture identity, source artifact metadata and declared models. The optical stage never reads them.
+ * Everything else in the normalized plan (scene state/time, geometry including orientation, focal length,
+ * aperture, shutter, focus, frame/mode/CFA/binding profiles and the exposure window) is part of the binding.
+ */
+function opticalBinding(plan, sceneBinding) {
+    const { captureId, noise, source, whiteBalanceIntent, adoptedWhiteXyz, models, exposure, ...capture } = plan.exposure;
+    void captureId;
+    void noise;
+    void source;
+    void whiteBalanceIntent;
+    void adoptedWhiteXyz;
+    void models;
+    const { iso, ...opticalExposure } = exposure;
+    void iso;
+    const { capture: frameCapture, ...frame } = plan.frame;
+    void frameCapture;
+    return { capture: { ...capture, exposure: opticalExposure }, frame, exposureWindow: plan.exposureWindow ?? null, sceneBinding };
+}
+const STAGES = new WeakMap();
+function release(state) {
+    state.values.fill(0);
+    state.environmentIndex.fill(0);
+    state.photoIndex.fill(0);
+    state.values = new Float64Array(0);
+    state.environmentIndex = new Uint8Array(0);
+    state.photoIndex = new Uint8Array(0);
+    state.environments = [];
+    state.photoTemplates = [];
+    state.disposed = true;
+}
+function photoTemplate(p) {
+    const { temporalIntegrationId, site, startOffsetSecondsFromOpeningReference, endOffsetSecondsFromOpeningReference, localExposureDurationSeconds, expectedIncidentPhotonCount, expectedGeneratedElectronCount, temporalSamples, ...rest } = p;
+    void temporalIntegrationId;
+    void site;
+    void startOffsetSecondsFromOpeningReference;
+    void endOffsetSecondsFromOpeningReference;
+    void localExposureDurationSeconds;
+    void expectedIncidentPhotonCount;
+    void expectedGeneratedElectronCount;
+    void temporalSamples;
+    return rest;
+}
+/** Shared by full acquisition and reuse so the sensor stage receives an identical site record either way. */
+export function composeNativeEnvironmentSensorSite(site, photoSignal) {
+    const darkCharge = calculateSensorDarkCurrentCharge({ exposure: photoSignal, darkCurrentProfile: site.darkCurrentProfile,
+        operatingTemperatureC: site.operatingTemperatureC }).value;
+    return { ...site.readout, charge: { ...site.charge, photoSignal, darkCharge } };
+}
+/** Validates the optional retention request before any provider work. */
+export function parseNativeEnvironmentOpticalStageRetention(value) {
+    const r = requireAllowlistedRecord(value, ["maximumRetainedBytes"], "Invalid optical-stage retention request.");
+    if (typeof r.maximumRetainedBytes !== "number" || !Number.isSafeInteger(r.maximumRetainedBytes) || r.maximumRetainedBytes < 1) {
+        throw new InvalidConfigurationError("Optical-stage retention requires a positive safe-integer byte budget.");
+    }
+    return { maximumRetainedBytes: r.maximumRetainedBytes };
+}
+export function createNativeEnvironmentOpticalStageRecorder(plan, sceneBinding, retention) {
+    const L = NATIVE_ENVIRONMENT_OPTICAL_STAGE_LIMITS;
+    const state = { pixelCount: plan.pixelCount, nativeWidth: plan.exposure.geometry.nativeRaster.pixelWidth,
+        frameId: plan.frame.frameId, stride: 0, temporalSampleCount: 0, binding: freezeOwnedData(structuredClone(opticalBinding(plan, sceneBinding))),
+        values: new Float64Array(0), environmentIndex: new Uint8Array(0), photoIndex: new Uint8Array(0), environments: [], photoTemplates: [],
+        providerEvaluationCount: 0, disposed: false };
+    const environmentKeys = new Map(), photoKeys = new Map(), verified = new WeakMap();
+    const admitted = new Uint8Array(plan.pixelCount);
+    let recorded = 0;
+    function residualKey(e, sharedCanonical) {
+        const rest = { ...e, temporalIntegrationId: undefined,
+            sensor: { ...e.sensor, spatialSampling: { ...e.sensor.spatialSampling, site: undefined } } };
+        for (const key of ENVIRONMENT_SHARED_KEYS)
+            rest[key] = undefined;
+        return sharedCanonical + "\u0000" + canonical(rest);
+    }
+    return {
+        admit(index, environment, sharedCanonical) {
+            if (state.disposed)
+                throw new InvalidConfigurationError("Optical-stage retention was released.");
+            const n = environment.temporalSampleCount;
+            if (state.stride === 0) {
+                const bytes = plan.pixelCount * (L.fixedBytesPerSite + L.bytesPerTemporalSamplePerSite * n);
+                if (!Number.isSafeInteger(bytes) || bytes > retention.maximumRetainedBytes)
+                    throw new InvalidConfigurationError("Optical-stage retention exceeds its byte budget.");
+                state.temporalSampleCount = n;
+                state.stride = FIXED_VALUES + 3 * n;
+                state.values = new Float64Array(plan.pixelCount * state.stride);
+                state.environmentIndex = new Uint8Array(plan.pixelCount);
+                state.photoIndex = new Uint8Array(plan.pixelCount);
+            }
+            else if (n !== state.temporalSampleCount)
+                throw new InvalidConfigurationError("Optical-stage retention requires one temporal sample count per event.");
+            const key = residualKey(environment, sharedCanonical), candidates = environmentKeys.get(key) ?? [];
+            let found = candidates.find(i => environmentMatches(environment, state.environments[i], verified));
+            if (found === undefined) {
+                if (state.environments.length >= L.maximumEnvironmentTemplates)
+                    throw new InvalidConfigurationError("Optical-stage retention exceeds its distinct site-environment limit.");
+                found = state.environments.length;
+                state.environments.push(environment);
+                candidates.push(found);
+                environmentKeys.set(key, candidates);
+            }
+            state.environmentIndex[index] = found;
+            admitted[index] = 1;
+        },
+        record(index, p) {
+            if (state.disposed || admitted[index] !== 1)
+                throw new InvalidConfigurationError("Optical-stage retention was released or not admitted.");
+            const samples = p.temporalSamples;
+            if (samples.length !== state.temporalSampleCount)
+                throw new InvalidConfigurationError("Optical-stage temporal sample count changed.");
+            const template = photoTemplate(p), key = canonical(template), candidates = photoKeys.get(key) ?? [];
+            let found = candidates.find(i => strictlyEqual(template, state.photoTemplates[i], verified));
+            if (found === undefined) {
+                if (state.photoTemplates.length >= L.maximumPhotoTemplates)
+                    throw new InvalidConfigurationError("Optical-stage retention exceeds its distinct photo-identity limit.");
+                found = state.photoTemplates.length;
+                state.photoTemplates.push(freezeOwnedData(structuredClone(template)));
+                candidates.push(found);
+                photoKeys.set(key, candidates);
+            }
+            state.photoIndex[index] = found;
+            const v = state.values, o = index * state.stride;
+            v[o] = p.site.x;
+            v[o + 1] = p.site.y;
+            v[o + 2] = p.startOffsetSecondsFromOpeningReference;
+            v[o + 3] = p.endOffsetSecondsFromOpeningReference;
+            v[o + 4] = p.localExposureDurationSeconds;
+            v[o + 5] = p.expectedIncidentPhotonCount;
+            v[o + 6] = p.expectedGeneratedElectronCount;
+            for (let t = 0; t < samples.length; t++) {
+                const s = samples[t], q = o + FIXED_VALUES + 3 * t;
+                v[q] = s.timeSecondsFromOpeningReference;
+                v[q + 1] = s.incidentPhotonRatePerSecond;
+                v[q + 2] = s.expectedGeneratedElectronRatePerSecond;
+            }
+            admitted[index] = 2;
+            recorded++;
+        },
+        finish(providerEvaluationCount) {
+            if (state.disposed || recorded !== plan.pixelCount)
+                throw new InvalidConfigurationError("Optical-stage retention is incomplete.");
+            for (const environment of state.environments)
+                freezeOwnedData(environment);
+            state.providerEvaluationCount = providerEvaluationCount;
+            const handle = Object.freeze({ kind: "native-environment-optical-stage",
+                pixelCount: state.pixelCount, temporalSampleCount: state.temporalSampleCount,
+                retainedBytes: state.pixelCount * (L.fixedBytesPerSite + L.bytesPerTemporalSamplePerSite * state.temporalSampleCount),
+                providerEvaluationCount, get disposed() { return state.disposed; },
+                dispose() { if (!state.disposed)
+                    release(state); } });
+            STAGES.set(handle, state);
+            return handle;
+        },
+        discard() { if (!state.disposed)
+            release(state); }
+    };
+}
+/**
+ * Internal: re-runs only the sensor stage (dark charge, charge realization, capacity, seeded noise and ADC) from a retained
+ * optical stage. The capture may change post-optics settings only: noise seed/realization, ISO metadata, readout
+ * regime/gain, charge sampling/capacity/completeness, dark-current profile and temperature, white-balance intent,
+ * capture identity and tile width. Every optical input must be strictly equal, otherwise this refuses before
+ * output: the capture binding is checked here, each site's environment as its tile is read.
+ */
+export function createSensorStageRawTask(input, opticalStage, provider, parseSceneBinding) {
+    const state = typeof opticalStage === "object" && opticalStage !== null ? STAGES.get(opticalStage) : undefined;
+    if (!state)
+        throw new InvalidConfigurationError("Optical-stage reuse requires an engine-produced optical stage.");
+    if (state.disposed)
+        throw new InvalidConfigurationError("Optical stage was disposed.");
+    const r = requireAllowlistedRecord(input, ["raw", "sceneBinding"], "Invalid native sensor-stage input.");
+    const sceneBinding = parseSceneBinding(r.sceneBinding);
+    if (!provider || typeof provider.readTile !== "function" || typeof provider.yieldControl !== "function") {
+        throw new InvalidConfigurationError("Sensor-stage reuse requires physical site input and host yields.");
+    }
+    const read = provider.readTile.bind(provider), yieldControl = provider.yieldControl.bind(provider);
+    const width = state.nativeWidth, frameId = state.frameId;
+    const task = createNativeRawTask(input.raw, {
+        async readTile(request, signal) {
+            const supplied = await read(request, signal);
+            if (signal.aborted)
+                throw new InvalidConfigurationError("Native sensor-stage acquisition aborted.");
+            if (state.disposed)
+                throw new InvalidConfigurationError("Optical stage was disposed.");
+            const tile = requireAllowlistedRecord(supplied, ["captureId", "frameId", "x", "y", "width", "height", "sites"], "Invalid physical source tile.");
+            for (const key of Object.keys(request))
+                if (tile[key] !== request[key])
+                    throw new InvalidConfigurationError("Physical source tile identity mismatch.");
+            if (!Array.isArray(tile.sites) || tile.sites.length !== request.width || Array.from({ length: request.width }, (_, i) => i in tile.sites).includes(false)) {
+                throw new InvalidConfigurationError("Physical source tile needs exact native coverage.");
+            }
+            // The supplied environment is only compared, in one synchronous pass, and never used: execution uses the
+            // retained stage. Only the post-optics parts the sensor stage uses are cloned. The equality cache is per
+            // tile, so a caller object changed between tiles is compared again.
+            const tileVerified = new WeakMap();
+            const suppliedSites = tile.sites;
+            const sites = structuredClone(suppliedSites.map((value, j) => {
+                const site = requireAllowlistedRecord(value, ["environment", "darkCurrentProfile", "operatingTemperatureC", "charge", "readout"], "Invalid physical site input.");
+                const index = request.y * width + request.x + j, e = site.environment;
+                if (typeof e !== "object" || e === null || !environmentMatches(e, state.environments[state.environmentIndex[index]], tileVerified) ||
+                    e.temporalIntegrationId !== frameId + ":native:" + index || typeof e.sensor.spatialSampling.site !== "object" || e.sensor.spatialSampling.site === null ||
+                    !strictlyEqual(e.sensor.spatialSampling.site, { x: index % width, y: Math.floor(index / width) }, tileVerified)) {
+                    throw new InvalidConfigurationError("Site environment differs from the retained optical stage; recompute the optical stage.");
+                }
+                return { temporalIntegrationId: e.temporalIntegrationId, darkCurrentProfile: site.darkCurrentProfile, operatingTemperatureC: site.operatingTemperatureC,
+                    charge: site.charge, readout: site.readout };
+            }));
+            const photos = sites.map((site, j) => {
+                const index = request.y * width + request.x + j;
+                if (site.temporalIntegrationId !== frameId + ":native:" + index) {
+                    throw new InvalidConfigurationError("Site environment differs from the retained optical stage; recompute the optical stage.");
+                }
+                const v = state.values, o = index * state.stride, template = state.photoTemplates[state.photoIndex[index]];
+                const temporalSamples = Array.from({ length: state.temporalSampleCount }, (_, t) => {
+                    const q = o + FIXED_VALUES + 3 * t;
+                    return { timeSecondsFromOpeningReference: v[q], incidentPhotonRatePerSecond: v[q + 1], expectedGeneratedElectronRatePerSecond: v[q + 2] };
+                });
+                return freezeOwnedData(parseSensorEqeTemporalPhotoSignal({ ...template, temporalIntegrationId: site.temporalIntegrationId, site: { x: v[o], y: v[o + 1] },
+                    startOffsetSecondsFromOpeningReference: v[o + 2], endOffsetSecondsFromOpeningReference: v[o + 3], localExposureDurationSeconds: v[o + 4],
+                    expectedIncidentPhotonCount: v[o + 5], expectedGeneratedElectronCount: v[o + 6], temporalSamples }));
+            });
+            return { ...request, sites: sites.map((site, j) => composeNativeEnvironmentSensorSite(site, photos[j])) };
+        },
+        // Host yields are time-budgeted and always follow the final tile, so a stage disposed
+        // while the host runs is caught here even when no further tile would be read.
+        async yieldControl(signal) {
+            await yieldControl(signal);
+            if (state.disposed)
+                throw new InvalidConfigurationError("Optical stage was disposed.");
+        }
+    });
+    // The task's own accepted plan is the one compared, so nothing is planned twice and no callback has run yet.
+    if (!strictlyEqual(opticalBinding(task.plan, sceneBinding), state.binding, new WeakMap())) {
+        task.dispose();
+        throw new InvalidConfigurationError("Optical stage does not match this capture's optical inputs; recompute the optical stage.");
+    }
+    return { task, sceneBinding };
+}
+//# sourceMappingURL=native-environment-optical-stage.js.map

package/dist/capture/native-environment-optical-stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-environment-optical-stage.js","sourceRoot":"","sources":["../../src/capture/native-environment-optical-stage.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Keeps (retains) the result of the optical stage of a native environment capture, so the sensor stage\n * can be re-run with new post-optics settings without calling the radiance callbacks again.\n *\n * Optical stage: scene radiance → optics, PSF (point-spread function) and pupil → expected photo signal\n * via EQE (external quantum efficiency). Sensor stage: dark charge → charge realization → readout.\n *\n * Reuse is exact, not approximate: the sensor stage receives a photo signal whose every number is the\n * float64 value the optical stage produced, and the same charge/noise/ADC code runs on it. Reuse is\n * refused unless the capture's optical binding and every site's environment input are strictly equal\n * to those the stage was produced from.\n * @see docs/NATIVE_RAW_AND_PRINT.md for the invariance analysis, memory bound and limits.\n */\n\nimport { createNativeRawTask, type NativeRawInput, type NativeRawPlan, type NativeRawTileRequest } from \"./native-raw.js\";\nimport type { SimulateEnvironmentSensorRawFrameInput } from \"./environment-raw-producer.js\";\nimport type { SensorRawProducerSiteInput } from \"./sensor-raw-producer.js\";\nimport { parseSensorEqeTemporalPhotoSignal, type SensorEqeTemporalPhotoSignal } from \"../sensor/temporal-photo-signal.js\";\nimport { calculateSensorDarkCurrentCharge } from \"../sensor/dark-current.js\";\nimport { requireAllowlistedRecord } from \"../core/record-validation.js\";\nimport { stringifyCanonicalJson } from \"../core/canonical-json.js\";\nimport { freezeOwnedData } from \"../core/owned-data.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\ntype EnvironmentSite = SimulateEnvironmentSensorRawFrameInput[\"sites\"][number];\ntype SiteEnvironment = EnvironmentSite[\"environment\"];\n\n/**\n * Fixed retention limits. The per-site footprint of a retained optical stage is\n * `fixedBytesPerSite + bytesPerTemporalSamplePerSite × temporalSampleCount` bytes of typed-array storage;\n * distinct environment and photo templates (each about one site's input size) are capped separately.\n */\nexport const NATIVE_ENVIRONMENT_OPTICAL_STAGE_LIMITS = Object.freeze({\n  /** Two one-byte template indices plus seven float64 values (site x/y, window start/end/duration, photon/electron counts). */\n  fixedBytesPerSite: 58,\n  /** Three float64 values per temporal midpoint: time, incident-photon rate, generated-electron rate. */\n  bytesPerTemporalSamplePerSite: 24,\n  /** Distinct per-site environment inputs once the site index and integration ID are removed. */\n  maximumEnvironmentTemplates: 256,\n  /** Distinct photo-signal identity/evidence records once per-site numbers are removed. */\n  maximumPhotoTemplates: 256\n});\n\n/** Optional request on NativeEnvironmentRawInput to keep the optical stage. The byte budget covers the typed-array storage described by the limits. */\nexport interface NativeEnvironmentOpticalStageRetention {\n  maximumRetainedBytes: number;\n}\n\n/**\n * Opaque, engine-owned optical-stage result. It is valid only for captures whose optical binding and every\n * site's environment input are strictly equal to those that produced it. dispose() zeroes and releases the\n * storage; a disposed stage refuses every later use.\n */\nexport interface NativeEnvironmentOpticalStage {\n  readonly kind: \"native-environment-optical-stage\";\n  readonly pixelCount: number;\n  readonly temporalSampleCount: number;\n  /** Typed-array bytes held: pixelCount × (fixedBytesPerSite + bytesPerTemporalSamplePerSite × temporalSampleCount). */\n  readonly retainedBytes: number;\n  /** Radiance callbacks the producing task executed; reuse executes none. */\n  readonly providerEvaluationCount: number;\n  readonly disposed: boolean;\n  dispose(): void;\n}\n\n/** Input for a post-optics re-run. `raw` may differ from the original capture only in post-optics fields. */\nexport interface NativeEnvironmentSensorStageInput {\n  raw: NativeRawInput;\n  sceneBinding: SimulateEnvironmentSensorRawFrameInput[\"sceneBinding\"];\n}\n/** Supplies the same physical site inputs as the original capture. Environments must equal the retained ones exactly. */\nexport interface NativeEnvironmentSensorStageProvider {\n  readTile(request: Readonly<NativeRawTileRequest>, signal: AbortSignal): Promise<{ captureId: string; frameId: string; x: number; y: number;\n    width: number; height: number; sites: SimulateEnvironmentSensorRawFrameInput[\"sites\"] }>;\n  yieldControl(signal: AbortSignal): Promise<void>;\n}\n\nconst FIXED_VALUES = 7;\nconst ENVIRONMENT_SHARED_KEYS = [\"sceneBindings\", \"optics\", \"motion\", \"psf\", \"pupil\", \"fieldThroughput\"] as const;\n\nfunction canonical(value: unknown): string {\n  return stringifyCanonicalJson(value, { undefinedObjectProperties: \"omit\", nonFiniteNumberMessage: \"Invalid native scene binding.\",\n    unsupportedValueMessage: \"Invalid native scene binding.\" });\n}\n\nfunction isPlainRecord(value: object): boolean {\n  const prototype = Object.getPrototypeOf(value);\n  return prototype === Object.prototype || prototype === null;\n}\n\n/**\n * Strict structural equality of plain data: Object.is for primitives (so 0 and -0 differ), identical own\n * key sets, arrays element by element. Anything that is not a plain record or array is unequal unless it is\n * the same reference, so an unexpected value refuses reuse instead of being treated as equal.\n */\nfunction strictlyEqual(a: unknown, b: unknown, verified: WeakMap<object, WeakSet<object>>, skip?: ReadonlySet<string>): boolean {\n  if (Object.is(a, b)) return true;\n  if (typeof a !== \"object\" || typeof b !== \"object\" || a === null || b === null) return false;\n  if (!skip && verified.get(a)?.has(b)) return true;\n  if (Array.isArray(a)) {\n    if (!Array.isArray(b) || a.length !== b.length) return false;\n    for (let i = 0; i < a.length; i++) {\n      if (!(i in a) || !(i in b) || !strictlyEqual(a[i], b[i], verified)) return false;\n    }\n  } else {\n    if (Array.isArray(b) || !isPlainRecord(a) || !isPlainRecord(b)) return false;\n    const ak = Object.keys(a), bk = Object.keys(b);\n    if (ak.length !== bk.length || Object.getOwnPropertySymbols(a).length !== 0 || Object.getOwnPropertySymbols(b).length !== 0) return false;\n    for (const key of ak) {\n      if (!Object.prototype.hasOwnProperty.call(b, key)) return false;\n      if (skip?.has(key)) continue;\n      if (!strictlyEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key], verified)) return false;\n    }\n  }\n  if (!skip) {\n    let set = verified.get(a);\n    if (!set) verified.set(a, set = new WeakSet());\n    set.add(b);\n  }\n  return true;\n}\n\n/**\n * Environment equality except the two per-site fields that are bound to the absolute native index and\n * checked separately: temporalIntegrationId and sensor.spatialSampling.site.\n */\nfunction environmentMatches(e: SiteEnvironment, t: SiteEnvironment, verified: WeakMap<object, WeakSet<object>>): boolean {\n  if (typeof e !== \"object\" || e === null || typeof e.sensor !== \"object\" || e.sensor === null ||\n    typeof e.sensor.spatialSampling !== \"object\" || e.sensor.spatialSampling === null) return false;\n  return strictlyEqual(e, t, verified, new Set([\"temporalIntegrationId\", \"sensor\"])) &&\n    strictlyEqual(e.sensor, t.sensor, verified, new Set([\"spatialSampling\"])) &&\n    strictlyEqual(e.sensor.spatialSampling, t.sensor.spatialSampling, verified, new Set([\"site\"]));\n}\n\n/**\n * Post-optics capture fields: noise seed/realization/model, ISO metadata, white-balance intent, adopted white,\n * capture identity, source artifact metadata and declared models. The optical stage never reads them.\n * Everything else in the normalized plan (scene state/time, geometry including orientation, focal length,\n * aperture, shutter, focus, frame/mode/CFA/binding profiles and the exposure window) is part of the binding.\n */\nfunction opticalBinding(plan: NativeRawPlan, sceneBinding: unknown): unknown {\n  const { captureId, noise, source, whiteBalanceIntent, adoptedWhiteXyz, models, exposure, ...capture } = plan.exposure;\n  void captureId; void noise; void source; void whiteBalanceIntent; void adoptedWhiteXyz; void models;\n  const { iso, ...opticalExposure } = exposure; void iso;\n  const { capture: frameCapture, ...frame } = plan.frame; void frameCapture;\n  return { capture: { ...capture, exposure: opticalExposure }, frame, exposureWindow: plan.exposureWindow ?? null, sceneBinding };\n}\n\ninterface OpticalStageState {\n  pixelCount: number;\n  nativeWidth: number;\n  frameId: string;\n  stride: number;\n  temporalSampleCount: number;\n  binding: unknown;\n  values: Float64Array;\n  environmentIndex: Uint8Array;\n  photoIndex: Uint8Array;\n  environments: SiteEnvironment[];\n  photoTemplates: Record<string, unknown>[];\n  providerEvaluationCount: number;\n  disposed: boolean;\n}\nconst STAGES = new WeakMap<object, OpticalStageState>();\n\nfunction release(state: OpticalStageState): void {\n  state.values.fill(0); state.environmentIndex.fill(0); state.photoIndex.fill(0);\n  state.values = new Float64Array(0); state.environmentIndex = new Uint8Array(0); state.photoIndex = new Uint8Array(0);\n  state.environments = []; state.photoTemplates = []; state.disposed = true;\n}\n\nfunction photoTemplate(p: SensorEqeTemporalPhotoSignal): Record<string, unknown> {\n  const { temporalIntegrationId, site, startOffsetSecondsFromOpeningReference, endOffsetSecondsFromOpeningReference,\n    localExposureDurationSeconds, expectedIncidentPhotonCount, expectedGeneratedElectronCount, temporalSamples, ...rest } = p;\n  void temporalIntegrationId; void site; void startOffsetSecondsFromOpeningReference; void endOffsetSecondsFromOpeningReference;\n  void localExposureDurationSeconds; void expectedIncidentPhotonCount; void expectedGeneratedElectronCount; void temporalSamples;\n  return rest;\n}\n\n/** Shared by full acquisition and reuse so the sensor stage receives an identical site record either way. */\nexport function composeNativeEnvironmentSensorSite(site: Omit<EnvironmentSite, \"environment\">, photoSignal: SensorEqeTemporalPhotoSignal): SensorRawProducerSiteInput {\n  const darkCharge = calculateSensorDarkCurrentCharge({ exposure: photoSignal, darkCurrentProfile: site.darkCurrentProfile,\n    operatingTemperatureC: site.operatingTemperatureC }).value;\n  return { ...site.readout, charge: { ...site.charge, photoSignal, darkCharge } } as SensorRawProducerSiteInput;\n}\n\n/** Validates the optional retention request before any provider work. */\nexport function parseNativeEnvironmentOpticalStageRetention(value: unknown): NativeEnvironmentOpticalStageRetention {\n  const r = requireAllowlistedRecord(value, [\"maximumRetainedBytes\"], \"Invalid optical-stage retention request.\");\n  if (typeof r.maximumRetainedBytes !== \"number\" || !Number.isSafeInteger(r.maximumRetainedBytes) || r.maximumRetainedBytes < 1) {\n    throw new InvalidConfigurationError(\"Optical-stage retention requires a positive safe-integer byte budget.\");\n  }\n  return { maximumRetainedBytes: r.maximumRetainedBytes };\n}\n\n/** Internal recorder used by createNativeEnvironmentRawTask when retention is requested. */\nexport interface NativeEnvironmentOpticalStageRecorder {\n  /** Interns one planned site before any radiance callback; throws if a limit or the byte budget would be exceeded. */\n  admit(index: number, environment: SiteEnvironment, sharedCanonical: string): void;\n  record(index: number, photoSignal: SensorEqeTemporalPhotoSignal): void;\n  finish(providerEvaluationCount: number): NativeEnvironmentOpticalStage;\n  discard(): void;\n}\n\nexport function createNativeEnvironmentOpticalStageRecorder(plan: NativeRawPlan, sceneBinding: unknown,\n  retention: NativeEnvironmentOpticalStageRetention): NativeEnvironmentOpticalStageRecorder {\n  const L = NATIVE_ENVIRONMENT_OPTICAL_STAGE_LIMITS;\n  const state: OpticalStageState = { pixelCount: plan.pixelCount, nativeWidth: plan.exposure.geometry.nativeRaster.pixelWidth,\n    frameId: plan.frame.frameId, stride: 0, temporalSampleCount: 0, binding: freezeOwnedData(structuredClone(opticalBinding(plan, sceneBinding))),\n    values: new Float64Array(0), environmentIndex: new Uint8Array(0), photoIndex: new Uint8Array(0), environments: [], photoTemplates: [],\n    providerEvaluationCount: 0, disposed: false };\n  const environmentKeys = new Map<string, number[]>(), photoKeys = new Map<string, number[]>(), verified = new WeakMap<object, WeakSet<object>>();\n  const admitted = new Uint8Array(plan.pixelCount);\n  let recorded = 0;\n  function residualKey(e: SiteEnvironment, sharedCanonical: string): string {\n    const rest: Record<string, unknown> = { ...e, temporalIntegrationId: undefined,\n      sensor: { ...e.sensor, spatialSampling: { ...e.sensor.spatialSampling, site: undefined } } };\n    for (const key of ENVIRONMENT_SHARED_KEYS) rest[key] = undefined;\n    return sharedCanonical+\"\\u0000\"+canonical(rest);\n  }\n  return {\n    admit(index, environment, sharedCanonical): void {\n      if (state.disposed) throw new InvalidConfigurationError(\"Optical-stage retention was released.\");\n      const n = environment.temporalSampleCount;\n      if (state.stride === 0) {\n        const bytes = plan.pixelCount*(L.fixedBytesPerSite+L.bytesPerTemporalSamplePerSite*n);\n        if (!Number.isSafeInteger(bytes) || bytes > retention.maximumRetainedBytes) throw new InvalidConfigurationError(\"Optical-stage retention exceeds its byte budget.\");\n        state.temporalSampleCount = n; state.stride = FIXED_VALUES+3*n;\n        state.values = new Float64Array(plan.pixelCount*state.stride);\n        state.environmentIndex = new Uint8Array(plan.pixelCount); state.photoIndex = new Uint8Array(plan.pixelCount);\n      } else if (n !== state.temporalSampleCount) throw new InvalidConfigurationError(\"Optical-stage retention requires one temporal sample count per event.\");\n      const key = residualKey(environment, sharedCanonical), candidates = environmentKeys.get(key) ?? [];\n      let found = candidates.find(i => environmentMatches(environment, state.environments[i]!, verified));\n      if (found === undefined) {\n        if (state.environments.length >= L.maximumEnvironmentTemplates) throw new InvalidConfigurationError(\"Optical-stage retention exceeds its distinct site-environment limit.\");\n        found = state.environments.length;\n        state.environments.push(environment);\n        candidates.push(found); environmentKeys.set(key, candidates);\n      }\n      state.environmentIndex[index] = found; admitted[index] = 1;\n    },\n    record(index, p): void {\n      if (state.disposed || admitted[index] !== 1) throw new InvalidConfigurationError(\"Optical-stage retention was released or not admitted.\");\n      const samples = p.temporalSamples;\n      if (samples.length !== state.temporalSampleCount) throw new InvalidConfigurationError(\"Optical-stage temporal sample count changed.\");\n      const template = photoTemplate(p), key = canonical(template), candidates = photoKeys.get(key) ?? [];\n      let found = candidates.find(i => strictlyEqual(template, state.photoTemplates[i]!, verified));\n      if (found === undefined) {\n        if (state.photoTemplates.length >= L.maximumPhotoTemplates) throw new InvalidConfigurationError(\"Optical-stage retention exceeds its distinct photo-identity limit.\");\n        found = state.photoTemplates.length;\n        state.photoTemplates.push(freezeOwnedData(structuredClone(template)));\n        candidates.push(found); photoKeys.set(key, candidates);\n      }\n      state.photoIndex[index] = found;\n      const v = state.values, o = index*state.stride;\n      v[o] = p.site.x; v[o+1] = p.site.y; v[o+2] = p.startOffsetSecondsFromOpeningReference; v[o+3] = p.endOffsetSecondsFromOpeningReference;\n      v[o+4] = p.localExposureDurationSeconds; v[o+5] = p.expectedIncidentPhotonCount; v[o+6] = p.expectedGeneratedElectronCount;\n      for (let t = 0; t < samples.length; t++) {\n        const s = samples[t]!, q = o+FIXED_VALUES+3*t;\n        v[q] = s.timeSecondsFromOpeningReference; v[q+1] = s.incidentPhotonRatePerSecond; v[q+2] = s.expectedGeneratedElectronRatePerSecond;\n      }\n      admitted[index] = 2; recorded++;\n    },\n    finish(providerEvaluationCount): NativeEnvironmentOpticalStage {\n      if (state.disposed || recorded !== plan.pixelCount) throw new InvalidConfigurationError(\"Optical-stage retention is incomplete.\");\n      for (const environment of state.environments) freezeOwnedData(environment);\n      state.providerEvaluationCount = providerEvaluationCount;\n      const handle: NativeEnvironmentOpticalStage = Object.freeze({ kind: \"native-environment-optical-stage\" as const,\n        pixelCount: state.pixelCount, temporalSampleCount: state.temporalSampleCount,\n        retainedBytes: state.pixelCount*(L.fixedBytesPerSite+L.bytesPerTemporalSamplePerSite*state.temporalSampleCount),\n        providerEvaluationCount, get disposed(): boolean { return state.disposed; },\n        dispose(): void { if (!state.disposed) release(state); } });\n      STAGES.set(handle, state);\n      return handle;\n    },\n    discard(): void { if (!state.disposed) release(state); }\n  };\n}\n\n/**\n * Internal: re-runs only the sensor stage (dark charge, charge realization, capacity, seeded noise and ADC) from a retained\n * optical stage. The capture may change post-optics settings only: noise seed/realization, ISO metadata, readout\n * regime/gain, charge sampling/capacity/completeness, dark-current profile and temperature, white-balance intent,\n * capture identity and tile width. Every optical input must be strictly equal, otherwise this refuses before\n * output: the capture binding is checked here, each site's environment as its tile is read.\n */\nexport function createSensorStageRawTask<B>(input: NativeEnvironmentSensorStageInput, opticalStage: NativeEnvironmentOpticalStage,\n  provider: NativeEnvironmentSensorStageProvider, parseSceneBinding: (value: unknown) => B):\n  { task: ReturnType<typeof createNativeRawTask>; sceneBinding: B } {\n  const state = typeof opticalStage === \"object\" && opticalStage !== null ? STAGES.get(opticalStage) : undefined;\n  if (!state) throw new InvalidConfigurationError(\"Optical-stage reuse requires an engine-produced optical stage.\");\n  if (state.disposed) throw new InvalidConfigurationError(\"Optical stage was disposed.\");\n  const r = requireAllowlistedRecord(input, [\"raw\", \"sceneBinding\"], \"Invalid native sensor-stage input.\");\n  const sceneBinding = parseSceneBinding(r.sceneBinding);\n  if (!provider || typeof provider.readTile !== \"function\" || typeof provider.yieldControl !== \"function\") {\n    throw new InvalidConfigurationError(\"Sensor-stage reuse requires physical site input and host yields.\");\n  }\n  const read = provider.readTile.bind(provider), yieldControl = provider.yieldControl.bind(provider);\n  const width = state.nativeWidth, frameId = state.frameId;\n  const task = createNativeRawTask(input.raw, {\n    async readTile(request, signal) {\n      const supplied = await read(request, signal);\n      if (signal.aborted) throw new InvalidConfigurationError(\"Native sensor-stage acquisition aborted.\");\n      if (state.disposed) throw new InvalidConfigurationError(\"Optical stage was disposed.\");\n      const tile = requireAllowlistedRecord(supplied, [\"captureId\", \"frameId\", \"x\", \"y\", \"width\", \"height\", \"sites\"], \"Invalid physical source tile.\");\n      for (const key of Object.keys(request) as (keyof NativeRawTileRequest)[]) if (tile[key] !== request[key]) throw new InvalidConfigurationError(\"Physical source tile identity mismatch.\");\n      if (!Array.isArray(tile.sites) || tile.sites.length !== request.width || Array.from({ length: request.width }, (_, i) => i in (tile.sites as unknown[])).includes(false)) {\n        throw new InvalidConfigurationError(\"Physical source tile needs exact native coverage.\");\n      }\n      // The supplied environment is only compared, in one synchronous pass, and never used: execution uses the\n      // retained stage. Only the post-optics parts the sensor stage uses are cloned. The equality cache is per\n      // tile, so a caller object changed between tiles is compared again.\n      const tileVerified = new WeakMap<object, WeakSet<object>>();\n      const suppliedSites = tile.sites as unknown[];\n      const sites = structuredClone(suppliedSites.map((value, j) => {\n        const site = requireAllowlistedRecord(value, [\"environment\", \"darkCurrentProfile\", \"operatingTemperatureC\", \"charge\", \"readout\"], \"Invalid physical site input.\");\n        const index = request.y*width+request.x+j, e = site.environment as SiteEnvironment;\n        if (typeof e !== \"object\" || e === null || !environmentMatches(e, state.environments[state.environmentIndex[index]!]!, tileVerified) ||\n          e.temporalIntegrationId !== frameId+\":native:\"+index || typeof e.sensor.spatialSampling.site !== \"object\" || e.sensor.spatialSampling.site === null ||\n          !strictlyEqual(e.sensor.spatialSampling.site, { x: index%width, y: Math.floor(index/width) }, tileVerified)) {\n          throw new InvalidConfigurationError(\"Site environment differs from the retained optical stage; recompute the optical stage.\");\n        }\n        return { temporalIntegrationId: e.temporalIntegrationId, darkCurrentProfile: site.darkCurrentProfile, operatingTemperatureC: site.operatingTemperatureC,\n          charge: site.charge, readout: site.readout };\n      })) as (Omit<EnvironmentSite, \"environment\"> & { temporalIntegrationId: string })[];\n      const photos = sites.map((site, j) => {\n        const index = request.y*width+request.x+j;\n        if (site.temporalIntegrationId !== frameId+\":native:\"+index) {\n          throw new InvalidConfigurationError(\"Site environment differs from the retained optical stage; recompute the optical stage.\");\n        }\n        const v = state.values, o = index*state.stride, template = state.photoTemplates[state.photoIndex[index]!]!;\n        const temporalSamples = Array.from({ length: state.temporalSampleCount }, (_, t) => {\n          const q = o+FIXED_VALUES+3*t;\n          return { timeSecondsFromOpeningReference: v[q]!, incidentPhotonRatePerSecond: v[q+1]!, expectedGeneratedElectronRatePerSecond: v[q+2]! };\n        });\n        return freezeOwnedData(parseSensorEqeTemporalPhotoSignal({ ...template, temporalIntegrationId: site.temporalIntegrationId, site: { x: v[o]!, y: v[o+1]! },\n          startOffsetSecondsFromOpeningReference: v[o+2]!, endOffsetSecondsFromOpeningReference: v[o+3]!, localExposureDurationSeconds: v[o+4]!,\n          expectedIncidentPhotonCount: v[o+5]!, expectedGeneratedElectronCount: v[o+6]!, temporalSamples }));\n      });\n      return { ...request, sites: sites.map((site, j) => composeNativeEnvironmentSensorSite(site, photos[j]!)) };\n    },\n    // Host yields are time-budgeted and always follow the final tile, so a stage disposed\n    // while the host runs is caught here even when no further tile would be read.\n    async yieldControl(signal) {\n      await yieldControl(signal);\n      if (state.disposed) throw new InvalidConfigurationError(\"Optical stage was disposed.\");\n    }\n  });\n  // The task's own accepted plan is the one compared, so nothing is planned twice and no callback has run yet.\n  if (!strictlyEqual(opticalBinding(task.plan, sceneBinding), state.binding, new WeakMap())) {\n    task.dispose();\n    throw new InvalidConfigurationError(\"Optical stage does not match this capture's optical inputs; recompute the optical stage.\");\n  }\n  return { task, sceneBinding };\n}\n"]}

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

@@ -1,21 +1,48 @@
-/** Bounded source-radiance → optical/EQE → native packed RAW execution. */
-import { type NativeRawInput, type NativeRawOutput, type NativeRawTask, type NativeRawTileRequest } from "./native-raw.js";
+/**
+ * Native RAW capture from a scene-radiance provider: source radiance → optics → EQE (external quantum
+ * efficiency) → packed RAW codes for the full native sensor, within fixed work limits.
+ */
+import { type NativeRawInput, type NativeRawOutput, type NativeRawPlan, type NativeRawTask, type NativeRawTileRequest } from "./native-raw.js";
+import type { SensorRawProducerSiteInput } from "./sensor-raw-producer.js";
 import { type SimulateEnvironmentSensorRawFrameInput } from "./environment-raw-producer.js";
+import { type HostYieldCadence } from "./host-yield-cadence.js";
+import { type NativeEnvironmentOpticalStage, type NativeEnvironmentOpticalStageRetention, type NativeEnvironmentSensorStageInput, type NativeEnvironmentSensorStageProvider } from "./native-environment-optical-stage.js";
+import type { SceneRadianceEvaluationRequest, SceneRadianceEvaluationResult } from "../schema/scene-radiance.js";
+import type { SensorApertureRay } from "../optics/sensor-aperture-rays.js";
 export interface NativeEnvironmentRawInput {
     raw: NativeRawInput;
     sceneBinding: SimulateEnvironmentSensorRawFrameInput["sceneBinding"];
-    /** Full-event admission budget; maximum 2 billion calls. No convergence is inferred. */
+    /** Budget of provider calls for the whole capture, checked before work starts; at most 2 billion. Staying within it does not imply convergence. */
     maximumProviderEvaluations: number;
+    /**
+     * Optional: keep the optical stage (per-site expected photo signal, tied to every optical input) on the
+     * output, for createNativeEnvironmentSensorStageTask. If omitted, behaviour and output shape are unchanged.
+     */
+    opticalStage?: NativeEnvironmentOpticalStageRetention;
 }
 export interface NativeEnvironmentRawTile extends NativeRawTileRequest {
     sites: SimulateEnvironmentSensorRawFrameInput["sites"];
 }
+/** One radiance query of a batch: the frozen provider request and, for an ideal-pupil ray, its frozen aperture ray. */
+export interface NativeEnvironmentRadianceQuery {
+    request: Readonly<SceneRadianceEvaluationRequest>;
+    apertureRay?: Readonly<SensorApertureRay>;
+}
 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. */
+    /**
+     * Optional batched light sampling (2.0, additive). When present, the engine makes one call per tile instead of one
+     * evaluateRadiance or evaluateApertureRadiance call per query. `queries` holds every query of the tile's sites, in
+     * exactly the order the per-query callbacks would be made, each with the same frozen request (and aperture ray).
+     * Return one result per query, in the same order; a promise is allowed (for example a GPU readback). Each result
+     * is validated by the same parser and binding checks as a per-query result, so for the same results the output is
+     * byte-identical. The per-query evaluators stay required as the reference contract, but are not called.
+     */
+    evaluateRadianceBatch?(queries: readonly NativeEnvironmentRadianceQuery[], signal: AbortSignal): readonly SceneRadianceEvaluationResult[] | Promise<readonly SceneRadianceEvaluationResult[]>;
+    /** Optional, bounded diagnostic callback. Counts are expected values before any noise, clipping or ADC (analogue-to-digital conversion). */
     observePhotoTile?(tile: Readonly<NativeEnvironmentPhotoTile>, signal: AbortSignal): void | Promise<void>;
     yieldControl(signal: AbortSignal): Promise<void>;
 }
@@ -33,11 +60,118 @@ export interface NativeEnvironmentRawOutput {
     upstreamOrigin: "executed-environment-query-provider-optics-psf-eqe";
     providerTransportVerified: false;
     productionPlanActivated: false;
+    /** Present only when NativeEnvironmentRawInput.opticalStage was requested. The caller owns and disposes it. */
+    opticalStage?: NativeEnvironmentOpticalStage;
 }
 export interface NativeEnvironmentRawTask extends Omit<NativeRawTask, "takeOutput"> {
     readonly providerEvaluationCount: number;
     takeOutput(): NativeEnvironmentRawOutput;
 }
-/** Every tile is planned and admission-checked before its radiance callbacks; no partial output escapes. */
+/**
+ * Creates the native RAW task. Every tile is planned and checked against the limits before its radiance
+ * callbacks run, and no partial output is ever returned.
+ *
+ * The task also yields to the host between sites inside a tile once about 8 ms of work has passed (one budget
+ * shared with the tile loop). Cancellation is checked after each such yield, so cancel() takes effect within
+ * about one site's work. Yield timing never changes tile requests, limit checks, callbacks or output.
+ */
 export declare function createNativeEnvironmentRawTask(input: NativeEnvironmentRawInput, provider: NativeEnvironmentRawProvider): NativeEnvironmentRawTask;
-//# sourceMappingURL=native-environment-raw.d.ts.map
+/** Internal: a partition's row band, and the facts it records while running for the merge step. */
+interface NativeEnvironmentPartitionProbe {
+    readonly rows: NativeRawRowBand;
+    /** Canonical string of the band's shared source/optical/motion state (the first site's). */
+    shared?: string;
+    /** The band's first parsed RAW site (its readout identity). */
+    firstSite?: SensorRawProducerSiteInput;
+}
+export declare function createNativeEnvironmentRawTaskWithCadence(input: NativeEnvironmentRawInput, provider: NativeEnvironmentRawProvider, cadence: HostYieldCadence, partition?: NativeEnvironmentPartitionProbe): NativeEnvironmentRawTask;
+/** A band of whole native rows, [y, y + height), in absolute full-sensor coordinates. */
+export interface NativeRawRowBand {
+    y: number;
+    height: number;
+}
+/**
+ * Splits a plan's native rows into at most `count` contiguous bands of nearly equal height (the first
+ * `height % count` bands are one row taller), in row order. Deterministic: it depends only on the raster height and
+ * `count`. Use one band per worker with createNativeEnvironmentRawPartitionTask.
+ */
+export declare function calculateNativeRawRowBands(plan: Pick<NativeRawPlan, "exposure">, count: number): NativeRawRowBand[];
+/**
+ * One partition's result: plain data and typed arrays only, so it can be posted from a worker (transfer the four
+ * arrays' buffers). Merge every partition of a capture with composeNativeEnvironmentRawPartitions.
+ */
+export interface NativeEnvironmentRawPartition {
+    rows: NativeRawRowBand;
+    /** Canonical JSON of the capture input (raw, sceneBinding, maximumProviderEvaluations); the merge requires it to match. */
+    inputCanonical: string;
+    /** Canonical JSON of the band's shared source/optical/motion state; every partition must match. */
+    sharedStateCanonical: string;
+    /** Readout identity of the band's first site; every partition must match (one readout identity per frame). */
+    readoutIdentity: {
+        readoutProfileId: string;
+        regimeId: string;
+        fixedPatternProfileId: string | null;
+        fixedPatternSeedUint32: number | null;
+    };
+    /** The band's rows only, row-major, as in NativeRawOutput. */
+    codes: Uint16Array;
+    blackLevels: Uint16Array;
+    digitalSaturationCodes: Uint16Array;
+    saturationFlags: Uint8Array;
+    /** Effective white code per CFA phase; 0 for a phase the band does not contain. */
+    effectiveSaturationCodes: Uint16Array;
+    providerEvaluationCount: number;
+}
+export interface NativeEnvironmentRawPartitionTask extends Omit<NativeRawTask, "takeOutput"> {
+    readonly rows: NativeRawRowBand;
+    readonly providerEvaluationCount: number;
+    takeOutput(): NativeEnvironmentRawPartition;
+}
+/**
+ * Creates the task for one row band of a native environment capture (opt-in parallel execution, 2.0).
+ *
+ * Run one partition per worker (or one after another) with the same input, each worker using its own provider, then
+ * merge them with composeNativeEnvironmentRawPartitions. The merged output is byte-identical to the single
+ * createNativeEnvironmentRawTask output for the same input and a deterministic provider: noise seeds use absolute
+ * native indices, and tiles, plans and per-site values are those of the whole-frame task.
+ *
+ * Each partition checks the same inputs and limits before its callbacks. maximumProviderEvaluations bounds each
+ * partition's own work; the merge also rejects a total above it. Frame-wide checks that span sites (one shared
+ * state, one readout identity, one white level per CFA phase) run inside each band and again across bands in the
+ * merge. Callbacks are split across partitions, and when several partitions fail, which error is seen first depends
+ * on the caller's scheduling. Optical-stage retention is not supported in a partition.
+ *
+ * The package bundles no worker code: the caller creates workers (Web Workers or Node worker threads), runs this
+ * task inside each and posts the partition back.
+ */
+export declare function createNativeEnvironmentRawPartitionTask(input: NativeEnvironmentRawInput, rows: NativeRawRowBand, provider: NativeEnvironmentRawProvider): NativeEnvironmentRawPartitionTask;
+/**
+ * Assembles the partitions of one capture into the output createNativeEnvironmentRawTask would have returned for
+ * the same input (byte-identical RAW arrays and white levels, the summed provider evaluation count).
+ *
+ * The partitions must be in row order and cover every native row exactly once, and each must come from
+ * createNativeEnvironmentRawPartitionTask with this same input. It rejects, with InvalidConfigurationError, a
+ * different input, a gap or overlap, wrong array types or lengths, a second shared state or readout identity, two
+ * white levels for one CFA phase, a missing phase, or a total evaluation count above the input's budget. It cannot
+ * verify how a partition was computed: posted partitions are the caller's own data.
+ */
+export declare function composeNativeEnvironmentRawPartitions(input: NativeEnvironmentRawInput, partitions: readonly NativeEnvironmentRawPartition[]): NativeEnvironmentRawOutput;
+/**
+ * Re-runs only the sensor stage from a retained optical stage. No radiance callback is called.
+ *
+ * Use it when only post-optics settings change: noise seed, ISO and its readout regime and gain,
+ * fixed-pattern noise, charge, dark-current and capacity profiles, white-balance intent, capture identity
+ * or tile width. White balance and rendering are then applied by createNativeRawDevelopmentTask as usual.
+ *
+ * RAW codes are bit-identical to a full createNativeEnvironmentRawTask with the same final inputs, as long
+ * as the radiance provider is a deterministic function of its request.
+ *
+ * Any optical difference is rejected with InvalidConfigurationError before output. That includes scene
+ * binding, geometry or orientation, focal length, aperture, shutter or exposure window, focus,
+ * frame/CFA/binding profiles, and any site environment field such as PSF, field throughput, pupil, motion,
+ * spectral or temporal sampling and provider profiles.
+ *
+ * providerEvaluationCount is 0. The caller still owns the stage; it is not used up.
+ */
+export declare function createNativeEnvironmentSensorStageTask(input: NativeEnvironmentSensorStageInput, opticalStage: NativeEnvironmentOpticalStage, provider: NativeEnvironmentSensorStageProvider): NativeEnvironmentRawTask;
+export {};