@photivra/engine 1.4.0 → 2.0.0

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

@@ -1,33 +1,179 @@
 // SPDX-License-Identifier: Apache-2.0
-/** Bounded source-radiance → optical/EQE → native packed RAW execution. */
-import { calculateNativeRawPlan, createNativeRawTask } from "./native-raw.js";
-import { planEnvironmentRawSite } from "./environment-raw-producer.js";
-import { executeEnvironmentSensorPhotoSignal } from "../sensor/environment-photo-signal.js";
-import { calculateSensorDarkCurrentCharge } from "../sensor/dark-current.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 { calculateNativeRawPlan, createNativeRawTaskWithCadence } from "./native-raw.js";
+import { createPhaseWhiteLevelAccumulator } from "./raw-white-level.js";
+import { createEnvironmentRawFrameCanonicalMemo, planEnvironmentRawSite } from "./environment-raw-producer.js";
+import { DEFAULT_HOST_YIELD_CADENCE, createHostYieldGate } from "./host-yield-cadence.js";
+import { executeEnvironmentSensorPhotoSignal, prebuildApertureRadianceQuery } from "../sensor/environment-photo-signal.js";
+import { composeNativeEnvironmentSensorSite, createNativeEnvironmentOpticalStageRecorder, createSensorStageRawTask, parseNativeEnvironmentOpticalStageRetention } from "./native-environment-optical-stage.js";
 import { parseEvidenceList } from "../core/evidence-provenance.js";
-import { requireAllowlistedRecord, requirePublicOpaqueId } from "../core/record-validation.js";
+import { rejectUnknownFields, requireAllowlistedRecord, requirePublicOpaqueId } 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";
+import { createNativeEnvironmentLeanExecutor, createNativeEnvironmentSensorLean, isLeanEnvironmentPlan } from "./native-environment-lean.js";
+import { prepareCaptureExposureWindowSampler } from "../sensor/exposure-window.js";
 function canonical(value) {
     return stringifyCanonicalJson(value, { undefinedObjectProperties: "omit", nonFiniteNumberMessage: "Invalid native scene binding.", unsupportedValueMessage: "Invalid native scene binding." });
 }
-/** Every tile is planned and admission-checked before its radiance callbacks; no partial output escapes. */
+/** Site-environment fields that one native event shares across every site (same set as the optical-stage binding). */
+const SHARED_STATE_KEYS = ["sceneBindings", "optics", "motion", "psf", "pupil", "fieldThroughput"];
+/**
+ * Strict structural equality of structured-clone output against the reference: Object.is for primitives (0 and
+ * -0 differ), identical prototypes limited to plain records and arrays, identical own keys in identical order,
+ * and arrays with no holes or non-index properties. Anything else is unequal unless it is the same reference.
+ * Equal values therefore serialize to the same canonical string and are interchangeable for every reader, so a
+ * site may adopt the reference values. Recursion is bounded by the reference, which serialized without error.
+ */
+function samePlainData(value, reference, cleanArrays) {
+    if (Object.is(value, reference))
+        return true;
+    if (typeof value !== "object" || typeof reference !== "object" || value === null || reference === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.getPrototypeOf(reference))
+        return false;
+    if (prototype === Array.prototype) {
+        const a = value, b = reference, length = a.length;
+        if (length !== b.length)
+            return false;
+        for (let index = 0; index < length; index++)
+            if (!(index in a) || !(index in b) || !samePlainData(a[index], b[index], cleanArrays))
+                return false;
+        // Holes are excluded above, so equal key counts exclude non-index properties as well.
+        if (Object.keys(a).length !== length)
+            return false;
+        if (!cleanArrays.has(b)) {
+            if (Object.keys(b).length !== length)
+                return false;
+            cleanArrays.add(b);
+        }
+        return true;
+    }
+    if (prototype !== Object.prototype && prototype !== null)
+        return false;
+    const a = value, b = reference, keys = Object.keys(a), referenceKeys = Object.keys(b);
+    if (keys.length !== referenceKeys.length)
+        return false;
+    for (let index = 0; index < keys.length; index++)
+        if (keys[index] !== referenceKeys[index])
+            return false;
+    for (let index = 0; index < keys.length; index++)
+        if (!samePlainData(a[keys[index]], b[keys[index]], cleanArrays))
+            return false;
+    return true;
+}
+/**
+ * Replaces a site's private copy of the shared state with the frame's reference values when every field is
+ * strictly equal (a 2.0 performance change). All sites then share one engine-owned shared state, so its sampled
+ * PSF is parsed and frozen once per frame and duplicate copies can be garbage-collected at once. `verified`
+ * holds copies in the current tile already shown equal, so sites the supplier built from one object compare in
+ * O(1). Returns false, changing nothing, when any field differs; the caller then serializes as before.
+ */
+function adoptSharedState(environment, reference, verified) {
+    const record = environment;
+    for (let index = 0; index < SHARED_STATE_KEYS.length; index++) {
+        const value = record[SHARED_STATE_KEYS[index]];
+        if (!(typeof value === "object" && value !== null && value === verified[index]) && !samePlainData(value, reference.values[index], reference.cleanArrays))
+            return false;
+    }
+    for (let index = 0; index < SHARED_STATE_KEYS.length; index++) {
+        const key = SHARED_STATE_KEYS[index], value = record[key];
+        if (value !== reference.values[index]) {
+            verified[index] = value;
+            record[key] = reference.values[index];
+        }
+    }
+    return true;
+}
+/**
+ * Every radiance query the executors will make for these site plans, in their callback order: per site, per instant,
+ * per group (spectral-major, spatial-minor), per tap, then per pupil ray. Pupil queries come from the executors' own
+ * apertureRadianceQuery, which then hands the executor the same objects.
+ */
+function tileQueries(plans) {
+    const queries = [];
+    const add = (tap) => {
+        if (tap.apertureRays === undefined) {
+            queries.push({ request: tap.request });
+            return;
+        }
+        // The executor later receives these same objects (apertureRadianceQuery), so they are built once.
+        for (const ray of tap.apertureRays)
+            queries.push(prebuildApertureRadianceQuery(tap.request, ray));
+    };
+    for (const p of plans) {
+        if (isLeanEnvironmentPlan(p)) {
+            for (const instant of p.instants)
+                for (const tap of instant.taps)
+                    add(tap);
+        }
+        else
+            for (const instant of p.instants)
+                for (const group of instant.groups)
+                    for (const tap of group.taps)
+                        add(tap);
+    }
+    return queries;
+}
+function parseSceneBinding(value) {
+    const binding = requireAllowlistedRecord(value, ["sceneStateId", "providerSceneId", "evidence"], "Invalid native scene binding.");
+    return freezeOwnedData({ sceneStateId: requirePublicOpaqueId(binding.sceneStateId, "Invalid scene-state ID."), providerSceneId: requirePublicOpaqueId(binding.providerSceneId, "Invalid provider-scene ID."), evidence: parseEvidenceList(binding.evidence, "nativeEnvironmentSceneBinding.evidence") });
+}
+/**
+ * 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 function createNativeEnvironmentRawTask(input, provider) {
-    const r = requireAllowlistedRecord(input, ["raw", "sceneBinding", "maximumProviderEvaluations"], "Invalid native environment input.");
-    const plan = calculateNativeRawPlan(input.raw), binding = requireAllowlistedRecord(r.sceneBinding, ["sceneStateId", "providerSceneId", "evidence"], "Invalid native scene binding.");
-    const sceneBinding = freezeOwnedData({ sceneStateId: requirePublicOpaqueId(binding.sceneStateId, "Invalid scene-state ID."), providerSceneId: requirePublicOpaqueId(binding.providerSceneId, "Invalid provider-scene ID."), evidence: parseEvidenceList(binding.evidence, "nativeEnvironmentSceneBinding.evidence") });
+    return createNativeEnvironmentRawTaskWithCadence(input, provider, DEFAULT_HOST_YIELD_CADENCE);
+}
+/** Internal: the same task with an explicit host-yield timing. Timing never changes tiles, callbacks or output. Not exported from the package. */
+/** Validates a native environment input exactly as task creation does, before any callback. */
+function admitNativeEnvironmentInput(input) {
+    const r = requireAllowlistedRecord(input, ["raw", "sceneBinding", "maximumProviderEvaluations", "opticalStage"], "Invalid native environment input.");
+    const plan = calculateNativeRawPlan(input.raw), sceneBinding = parseSceneBinding(r.sceneBinding);
+    const retention = r.opticalStage === undefined ? undefined : parseNativeEnvironmentOpticalStageRetention(r.opticalStage);
     if (sceneBinding.sceneStateId !== plan.exposure.sceneStateId || plan.exposure.sceneTimeSeconds !== 0 || !plan.exposureWindow ||
         typeof r.maximumProviderEvaluations !== "number" || !Number.isSafeInteger(r.maximumProviderEvaluations) || r.maximumProviderEvaluations < plan.pixelCount || r.maximumProviderEvaluations > 2_000_000_000)
         throw new InvalidConfigurationError("Native environment requires opening-reference scene binding, an explicit shutter event and bounded full-event query budget.");
+    return { plan, sceneBinding, retention, maximum: r.maximumProviderEvaluations };
+}
+export function createNativeEnvironmentRawTaskWithCadence(input, provider, cadence, partition) {
+    const { plan, sceneBinding, retention, maximum } = admitNativeEnvironmentInput(input);
+    if (partition && retention)
+        throw new InvalidConfigurationError("A native environment partition cannot retain the optical stage.");
     if (!provider || typeof provider.readTile !== "function" || typeof provider.evaluateRadiance !== "function" || typeof provider.yieldControl !== "function" ||
         (provider.evaluateApertureRadiance !== undefined && typeof provider.evaluateApertureRadiance !== "function") ||
-        (provider.observePhotoTile !== undefined && typeof provider.observePhotoTile !== "function"))
+        (provider.observePhotoTile !== undefined && typeof provider.observePhotoTile !== "function") ||
+        (provider.evaluateRadianceBatch !== undefined && typeof provider.evaluateRadianceBatch !== "function"))
         throw new InvalidConfigurationError("Native environment requires physical source callbacks and host yields.");
     const read = provider.readTile.bind(provider), evaluate = provider.evaluateRadiance.bind(provider), aperture = provider.evaluateApertureRadiance?.bind(provider), yieldControl = provider.yieldControl.bind(provider);
-    const maximum = r.maximumProviderEvaluations, observe = provider.observePhotoTile?.bind(provider);
-    let evaluations = 0, shared;
-    const task = createNativeRawTask(input.raw, {
+    const observe = provider.observePhotoTile?.bind(provider), batch = provider.evaluateRadianceBatch?.bind(provider);
+    let evaluations = 0, shared, reference;
+    const recorder = retention ? createNativeEnvironmentOpticalStageRecorder(plan, sceneBinding, retention) : undefined;
+    const memo = createEnvironmentRawFrameCanonicalMemo(plan.frame, plan.exposureWindow), gate = createHostYieldGate(cadence);
+    const layout = plan.frame.colorSamplingProfile.layout, relationship = plan.frame.bindingProfile.relationship;
+    const leanFrame = { frameId: plan.frame.frameId, nativeWidth: plan.exposure.geometry.nativeRaster.pixelWidth,
+        nativeHeight: plan.exposure.geometry.nativeRaster.pixelHeight, repeatWidth: layout.kind === "periodic-mosaic" ? layout.repeatWidthSites : 0,
+        repeatHeight: layout.kind === "periodic-mosaic" ? layout.repeatHeightSites : 0,
+        identityBinding: relationship.sitesPerNativeSampleX === 1 && relationship.sitesPerNativeSampleY === 1 && relationship.anchor === "shared-native-top-left" };
+    const lean = createNativeEnvironmentLeanExecutor(leanFrame);
+    let nativeWindow;
+    try {
+        nativeWindow = prepareCaptureExposureWindowSampler({ ...plan.exposureWindow, nativeRaster: plan.exposure.geometry.nativeRaster });
+    }
+    catch {
+        nativeWindow = undefined;
+    }
+    const sensorLean = createNativeEnvironmentSensorLean(leanFrame, plan.frame, nativeWindow);
+    const task = createNativeRawTaskWithCadence(input.raw, {
         async readTile(request, signal) {
             const supplied = await read(request, signal);
             if (signal.aborted)
@@ -38,44 +184,299 @@ export function createNativeEnvironmentRawTask(input, provider) {
                     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.");
+            // Private copy: planning takes each site environment as engine-owned plan data without copying it again.
             const sites = structuredClone(tile.sites);
+            // Yield to the host between sites on the shared time budget. Cancellation is honoured right after it.
+            const pause = async () => {
+                if (!gate.due())
+                    return;
+                await yieldControl(signal);
+                if (signal.aborted)
+                    throw new InvalidConfigurationError("Native environment acquisition aborted.");
+                gate.restart();
+            };
             let tileCount = 0;
-            const plans = sites.map((site, j) => {
+            const plans = [], verified = [];
+            for (let j = 0; j < sites.length; j++) {
+                if (j > 0)
+                    await pause();
+                const site = sites[j];
                 requireAllowlistedRecord(site, ["environment", "darkCurrentProfile", "operatingTemperatureC", "charge", "readout"], "Invalid physical site input.");
                 const e = site.environment, index = request.y * plan.exposure.geometry.nativeRaster.pixelWidth + request.x + j;
                 if (e.temporalIntegrationId !== plan.frame.frameId + ":native:" + index)
                     throw new InvalidConfigurationError("Native environment IDs must bind the absolute native index.");
-                const state = canonical({ sceneBindings: e.sceneBindings, optics: e.optics, motion: e.motion, psf: e.psf, pupil: e.pupil, fieldThroughput: e.fieldThroughput });
-                shared ??= state;
-                if (state !== shared)
-                    throw new InvalidConfigurationError("Native event requires one shared source/optical/motion state.");
-                const p = planEnvironmentRawSite(site, request.y * plan.exposure.geometry.nativeRaster.pixelWidth + request.x + j, plan.frame, sceneBinding, plan.exposureWindow);
+                // A site strictly equal to the frame's first shared state adopts it and skips serialization; otherwise the
+                // canonical comparison runs exactly as before and decides acceptance or the same error.
+                let state;
+                if (reference !== undefined && adoptSharedState(e, reference, verified))
+                    state = reference.canonical;
+                else {
+                    state = canonical({ sceneBindings: e.sceneBindings, optics: e.optics, motion: e.motion, psf: e.psf, pupil: e.pupil, fieldThroughput: e.fieldThroughput });
+                    shared ??= state;
+                    if (partition)
+                        partition.shared ??= shared;
+                    if (state !== shared)
+                        throw new InvalidConfigurationError("Native event requires one shared source/optical/motion state.");
+                    reference ??= { canonical: state, values: SHARED_STATE_KEYS.map(key => e[key]), cleanArrays: new WeakSet() };
+                }
+                // A site matching a verified template gets a lean plan (identical requests and limit checks; see
+                // native-environment-lean.ts). A template candidate keeps full query records for its self-check.
+                // Otherwise only the photo signal is needed, so the plan keeps just each query's frozen request and image-plane point.
+                const leanPlan = lean.plan(e, index);
+                let p;
+                if (typeof leanPlan === "object")
+                    p = leanPlan;
+                else {
+                    p = planEnvironmentRawSite(site, index, plan.frame, sceneBinding, plan.exposureWindow, "engine-owned", memo, leanPlan === "candidate" ? "full" : "photo-only");
+                    if (leanPlan === "candidate")
+                        lean.admitCandidate(e, index, p);
+                }
                 if (p.owned.pupil && !aperture)
                     throw new InvalidConfigurationError("Pupil capture requires origin-aware source visibility.");
+                recorder?.admit(index, e, state);
                 tileCount += p.count;
                 if (tileCount > 100_000 || evaluations + tileCount > maximum)
                     throw new InvalidConfigurationError("Native environment exceeds tile or full-event query budget.");
-                return p;
-            });
-            const rawSites = sites.map((site, j) => {
-                const result = executeEnvironmentSensorPhotoSignal(plans[j], q => { if (signal.aborted)
-                    throw new InvalidConfigurationError("Native source evaluation aborted."); evaluations++; return evaluate(q); }, aperture ? (q, ray) => { if (signal.aborted)
-                    throw new InvalidConfigurationError("Native aperture evaluation aborted."); evaluations++; return aperture(q, ray); } : undefined);
-                const photoSignal = result.value.photo.value.photoSignal;
-                const darkCharge = calculateSensorDarkCurrentCharge({ exposure: photoSignal, darkCurrentProfile: site.darkCurrentProfile, operatingTemperatureC: site.operatingTemperatureC }).value;
-                return { ...site.readout, charge: { ...site.charge, photoSignal, darkCharge } };
-            });
+                plans.push(p);
+            }
+            // Only value.photo is consumed, so per-evaluation diagnostics are not retained.
+            const rawSites = [], photos = [];
+            sensorLean.beginTile();
+            let evaluateCounted = (q) => { if (signal.aborted)
+                throw new InvalidConfigurationError("Native source evaluation aborted."); evaluations++; return evaluate(q); };
+            let apertureCounted = aperture ? (q, ray) => { if (signal.aborted)
+                throw new InvalidConfigurationError("Native aperture evaluation aborted."); evaluations++; return aperture(q, ray); } : undefined;
+            let batched;
+            if (batch) {
+                // One call for the whole tile, with every planned query in per-query callback order (see tileQueries).
+                const queries = tileQueries(plans);
+                if (signal.aborted)
+                    throw new InvalidConfigurationError("Native source evaluation aborted.");
+                const results = await batch(Object.freeze(queries), signal);
+                if (signal.aborted)
+                    throw new InvalidConfigurationError("Native source evaluation aborted.");
+                if (!Array.isArray(results) || results.length !== queries.length || Array.from({ length: queries.length }, (_, i) => i in results).includes(false))
+                    throw new InvalidConfigurationError("Batched radiance must return one result per query, in query order.");
+                const current = { queries, results: results, next: 0 };
+                batched = current;
+                // The executors ask for each query in the same order; every step is checked against the planned query.
+                const take = (q, ray) => {
+                    const k = current.next++, planned = current.queries[k];
+                    if (planned === undefined || planned.request.sampleId !== q.sampleId || (planned.apertureRay === undefined) !== (ray === undefined))
+                        throw new InvalidConfigurationError("Batched radiance results are out of step with the planned queries.");
+                    evaluations++;
+                    return current.results[k];
+                };
+                evaluateCounted = (q) => take(q, undefined);
+                apertureCounted = aperture ? (q, ray) => take(q, ray) : undefined;
+            }
+            for (let j = 0; j < sites.length; j++) {
+                await pause();
+                const index = request.y * plan.exposure.geometry.nativeRaster.pixelWidth + request.x + j;
+                let p = plans[j], photoSignal;
+                if (isLeanEnvironmentPlan(p)) {
+                    // The full plan (deterministic, no callbacks) is built only when the lean path needs it.
+                    const fullPlan = () => planEnvironmentRawSite(sites[j], index, plan.frame, sceneBinding, plan.exposureWindow, "engine-owned", memo, "photo-only");
+                    photoSignal = lean.execute(p, evaluateCounted, apertureCounted, fullPlan);
+                    // An unverified template: plan this site in full now and execute it in full.
+                    if (photoSignal === undefined)
+                        p = fullPlan();
+                }
+                if (photoSignal === undefined) {
+                    const full = p, candidate = lean.isCandidate(index);
+                    const result = executeEnvironmentSensorPhotoSignal(full, evaluateCounted, apertureCounted, candidate ? "full" : "photo-only");
+                    if (candidate)
+                        lean.verifyCandidate(index, full, result);
+                    photoSignal = result.value.photo.value.photoSignal;
+                }
+                recorder?.record(index, photoSignal);
+                photos.push(photoSignal);
+                // A site matching a verified sensor template becomes a lean entry: every check its composition and RAW
+                // parse would run has been evaluated (see native-environment-lean.ts). Otherwise compose it in full.
+                const claimed = sensorLean.claim(sites[j], photoSignal, index);
+                if (claimed)
+                    rawSites.push(claimed);
+                else {
+                    rawSites.push(composeNativeEnvironmentSensorSite(sites[j], photoSignal));
+                    sensorLean.remember(index, sites[j], photoSignal);
+                }
+            }
+            if (batched && batched.next !== batched.queries.length)
+                throw new InvalidConfigurationError("Batched radiance results are out of step with the planned queries.");
             if (signal.aborted)
                 throw new InvalidConfigurationError("Native photo observation aborted.");
             if (observe)
-                await observe(freezeOwnedData({ ...request, sites: rawSites.map((s, j) => ({ nativeIndex: request.y * plan.exposure.geometry.nativeRaster.pixelWidth + request.x + j,
-                        expectedIncidentPhotonCount: s.charge.photoSignal.expectedIncidentPhotonCount, expectedGeneratedElectronCount: s.charge.photoSignal.expectedGeneratedElectronCount })) }), signal);
+                await observe(freezeOwnedData({ ...request, sites: photos.map((s, j) => ({ nativeIndex: request.y * plan.exposure.geometry.nativeRaster.pixelWidth + request.x + j,
+                        expectedIncidentPhotonCount: s.expectedIncidentPhotonCount, expectedGeneratedElectronCount: s.expectedGeneratedElectronCount })) }), signal);
             return { ...request, sites: rawSites };
         }, yieldControl
-    });
+    }, cadence, gate, sensorLean.hook, partition ? { y: partition.rows.y, height: partition.rows.height, firstSite: (site) => { partition.firstSite = site; } } : undefined);
+    // The frame reference is needed only while tiles are read; release it once the event settles.
+    const settle = () => { reference = undefined; };
     return { plan: task.plan, get state() { return task.state; }, get completedTileCount() { return task.completedTileCount; }, get providerEvaluationCount() { return evaluations; },
+        run: () => (recorder ? task.run().catch((error) => { if (task.state === "failed" || task.state === "cancelled" || task.state === "disposed")
+            recorder.discard(); throw error; }) : task.run()).finally(settle),
+        cancel: () => { if (task.state !== "transferred")
+            recorder?.discard(); task.cancel(); }, dispose: () => { if (task.state !== "transferred")
+            recorder?.discard(); task.dispose(); },
+        takeOutput() {
+            // Finish retention first so a retention failure never strands the transferred RAW.
+            const opticalStage = recorder && task.state === "completed" ? recorder.finish(evaluations) : undefined;
+            const raw = task.takeOutput();
+            const base = { raw, sceneBinding, providerEvaluationCount: evaluations, upstreamOrigin: "executed-environment-query-provider-optics-psf-eqe", providerTransportVerified: false, productionPlanActivated: false };
+            return opticalStage ? { ...base, opticalStage } : base;
+        }
+    };
+}
+/**
+ * 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 function calculateNativeRawRowBands(plan, count) {
+    if (plan !== null && typeof plan === "object")
+        rejectUnknownFields(plan, ["schemaVersion", "exposure", "frame", "exposureWindow", "pixelCount", "outputBytes", "tileCount",
+            "tileWidth", "upstreamRadiometryVerified", "seedSchedule"], "Native RAW plan");
+    const height = plan?.exposure?.geometry?.nativeRaster?.pixelHeight;
+    if (typeof height !== "number" || !Number.isSafeInteger(height) || height < 1)
+        throw new InvalidConfigurationError("Native RAW partitioning requires a native RAW plan.");
+    if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 1 || count > 1024)
+        throw new InvalidConfigurationError("Native RAW partition count must be an integer from 1 to 1024.");
+    const bands = Math.min(count, height), base = Math.floor(height / bands), extra = height % bands, result = [];
+    for (let i = 0, y = 0; i < bands; i++) {
+        const h = base + (i < extra ? 1 : 0);
+        result.push({ y, height: h });
+        y += h;
+    }
+    return result;
+}
+function inputCanonical(input) {
+    return canonical({ raw: input.raw, sceneBinding: input.sceneBinding, maximumProviderEvaluations: input.maximumProviderEvaluations });
+}
+function parseRowBand(value, height) {
+    const band = requireAllowlistedRecord(value, ["y", "height"], "Invalid native RAW row band.");
+    if (typeof band.y !== "number" || typeof band.height !== "number" || !Number.isSafeInteger(band.y) || !Number.isSafeInteger(band.height) ||
+        band.y < 0 || band.height < 1 || band.y + band.height > height)
+        throw new InvalidConfigurationError("Native RAW row band must lie inside the native raster.");
+    return { y: band.y, height: band.height };
+}
+/**
+ * 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 function createNativeEnvironmentRawPartitionTask(input, rows, provider) {
+    const plan = calculateNativeRawPlan(input?.raw), band = parseRowBand(rows, plan.exposure.geometry.nativeRaster.pixelHeight);
+    const probe = { rows: band };
+    const task = createNativeEnvironmentRawTaskWithCadence(input, provider, DEFAULT_HOST_YIELD_CADENCE, probe), text = inputCanonical(input);
+    return { plan: task.plan, rows: band, get state() { return task.state; }, get completedTileCount() { return task.completedTileCount; },
+        get providerEvaluationCount() { return task.providerEvaluationCount; }, run: () => task.run(), cancel: () => task.cancel(), dispose: () => task.dispose(),
+        takeOutput() {
+            if (task.state !== "completed" || probe.shared === undefined || probe.firstSite === undefined)
+                throw new InvalidConfigurationError("Native RAW output unavailable.");
+            const site = probe.firstSite, sharedStateCanonical = probe.shared, output = task.takeOutput(), raw = output.raw;
+            return { rows: { ...band }, inputCanonical: text, sharedStateCanonical, readoutIdentity: { readoutProfileId: site.readoutProfile.profileId, regimeId: site.regimeId,
+                    fixedPatternProfileId: site.fixedPatternNoise?.profileId ?? null, fixedPatternSeedUint32: site.fixedPatternNoise?.sensorInstanceSeedUint32 ?? null },
+                codes: raw.codes, blackLevels: raw.blackLevels, digitalSaturationCodes: raw.digitalSaturationCodes, saturationFlags: raw.saturationFlags,
+                effectiveSaturationCodes: raw.effectiveSaturationCodes, providerEvaluationCount: output.providerEvaluationCount };
+        }
+    };
+}
+/**
+ * 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 function composeNativeEnvironmentRawPartitions(input, partitions) {
+    const { plan, sceneBinding, retention, maximum } = admitNativeEnvironmentInput(input);
+    if (retention)
+        throw new InvalidConfigurationError("A native environment partition cannot retain the optical stage.");
+    const native = plan.exposure.geometry.nativeRaster, width = native.pixelWidth, layout = plan.frame.colorSamplingProfile.layout;
+    if (layout.kind !== "periodic-mosaic")
+        throw new InvalidConfigurationError("Native RAW requires periodic CFA.");
+    const phases = layout.repeatWidthSites * layout.repeatHeightSites, text = inputCanonical(input);
+    if (!Array.isArray(partitions) || partitions.length < 1 || partitions.length > native.pixelHeight || Array.from({ length: partitions.length }, (_, i) => i in partitions).includes(false))
+        throw new InvalidConfigurationError("Native RAW merge requires a dense list of partitions.");
+    const codes = new Uint16Array(plan.pixelCount), blackLevels = new Uint16Array(plan.pixelCount), digitalSaturationCodes = new Uint16Array(plan.pixelCount), saturationFlags = new Uint8Array(plan.pixelCount);
+    const white = createPhaseWhiteLevelAccumulator(width, layout.repeatWidthSites, layout.repeatHeightSites);
+    let y = 0, total = 0, shared, identity;
+    for (const value of partitions) {
+        const p = requireAllowlistedRecord(value, ["rows", "inputCanonical", "sharedStateCanonical", "readoutIdentity", "codes", "blackLevels", "digitalSaturationCodes",
+            "saturationFlags", "effectiveSaturationCodes", "providerEvaluationCount"], "Invalid native RAW partition.");
+        const band = parseRowBand(p.rows, native.pixelHeight), length = band.height * width;
+        if (band.y !== y)
+            throw new InvalidConfigurationError("Native RAW partitions must cover every row once, in row order.");
+        if (p.inputCanonical !== text)
+            throw new InvalidConfigurationError("Native RAW partition was computed from a different input.");
+        if (!(p.codes instanceof Uint16Array) || !(p.blackLevels instanceof Uint16Array) || !(p.digitalSaturationCodes instanceof Uint16Array) ||
+            !(p.saturationFlags instanceof Uint8Array) || !(p.effectiveSaturationCodes instanceof Uint16Array) || p.codes.length !== length || p.blackLevels.length !== length ||
+            p.digitalSaturationCodes.length !== length || p.saturationFlags.length !== length || p.effectiveSaturationCodes.length !== phases ||
+            typeof p.providerEvaluationCount !== "number" || !Number.isSafeInteger(p.providerEvaluationCount) || p.providerEvaluationCount < 0 || typeof p.sharedStateCanonical !== "string")
+            throw new InvalidConfigurationError("Invalid native RAW partition arrays.");
+        const id = requireAllowlistedRecord(p.readoutIdentity, ["readoutProfileId", "regimeId", "fixedPatternProfileId", "fixedPatternSeedUint32"], "Invalid native RAW partition identity.");
+        const idText = canonical(id);
+        shared ??= p.sharedStateCanonical;
+        identity ??= idText;
+        if (p.sharedStateCanonical !== shared)
+            throw new InvalidConfigurationError("Native event requires one shared source/optical/motion state.");
+        if (idText !== identity)
+            throw new InvalidConfigurationError("Frame requires one readout identity/regime, one fixed-pattern identity and a positive uint16 RAW code span.");
+        const offset = band.y * width;
+        codes.set(p.codes, offset);
+        blackLevels.set(p.blackLevels, offset);
+        digitalSaturationCodes.set(p.digitalSaturationCodes, offset);
+        saturationFlags.set(p.saturationFlags, offset);
+        for (let phase = 0; phase < phases; phase++)
+            white.recordPhase(phase, p.effectiveSaturationCodes[phase]);
+        total += p.providerEvaluationCount;
+        y += band.height;
+    }
+    if (y !== native.pixelHeight)
+        throw new InvalidConfigurationError("Native RAW partitions must cover every row once, in row order.");
+    if (total > maximum)
+        throw new InvalidConfigurationError("Native environment exceeds tile or full-event query budget.");
+    const raw = { plan, codes, blackLevels, digitalSaturationCodes, saturationFlags, effectiveSaturationCodes: white.finish() };
+    return { raw, sceneBinding, providerEvaluationCount: total, upstreamOrigin: "executed-environment-query-provider-optics-psf-eqe", providerTransportVerified: false, productionPlanActivated: false };
+}
+/**
+ * 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 function createNativeEnvironmentSensorStageTask(input, opticalStage, provider) {
+    const { task, sceneBinding } = createSensorStageRawTask(input, opticalStage, provider, parseSceneBinding);
+    return { plan: task.plan, get state() { return task.state; }, get completedTileCount() { return task.completedTileCount; }, get providerEvaluationCount() { return 0; },
         run: () => task.run(), cancel: () => task.cancel(), dispose: () => task.dispose(),
-        takeOutput() { return { raw: task.takeOutput(), sceneBinding, providerEvaluationCount: evaluations, upstreamOrigin: "executed-environment-query-provider-optics-psf-eqe", providerTransportVerified: false, productionPlanActivated: false }; }
+        takeOutput() { return { raw: task.takeOutput(), sceneBinding, providerEvaluationCount: 0, upstreamOrigin: "executed-environment-query-provider-optics-psf-eqe", providerTransportVerified: false, productionPlanActivated: false }; }
     };
 }
 //# sourceMappingURL=native-environment-raw.js.map