@photivra/engine 1.5.0 → 2.0.0

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

@@ -1,16 +1,11 @@
 # capture/focus-control.ts public contracts
 
-Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## assessFocusReleaseGate
 
-Report whether release may proceed under focus-priority or release-priority policy; this does not
-operate a shutter.
-
-Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
-actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
-scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
-separate state transitions.
+Reports whether the shutter may be released under the focus-priority or release-priority
+policy. It does not operate the shutter.
 
 ```ts
 export function assessFocusReleaseGate(
@@ -38,13 +33,8 @@ export interface AssessFocusReleaseGateInput {
 
 ## createFocusControlState
 
-Create the initial ideal focus-controller state from an explicit profile, focus plane and public
-state identity.
-
-Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
-actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
-scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
-separate state transitions.
+Creates the initial ideal focus-controller state from a profile, a focus plane and a public
+state ID.
 
 ```ts
 export function createFocusControlState(
@@ -144,11 +134,12 @@ export interface FocusControlProfile {
 
 ## FocusControlState
 
-Immutable logical MF/single-AF/continuous-AF state. Resolved focus remains a
-finite longitudinal distance in metres or explicit infinity. Acquisition, loss,
-reacquisition and lock records explain why a target is usable; a focus-release
-gate remains separate from shutter sequencing. The ideal actuator does not model
-commercial AF measurement accuracy or physical acquisition time.
+Immutable focus-controller state for MF, AF-S or AF-C.
+
+The resolved focus is a finite distance along the optical axis in metres, or infinity.
+Acquisition, loss, reacquisition and lock records explain why a target can be used. The
+focus-release check is separate from shutter sequencing. The ideal actuator does not model
+real AF accuracy or the physical time focusing takes.
 
 ```ts
 export interface FocusControlState {
@@ -262,8 +253,8 @@ export type FocusTargetObservation =
   | (FocusTargetObservationBase & {
       kind: "finite-surface";
       /**
-       * Longitudinal camera-space/conjugate distance from #103, not renderer
-       * ray length.
+       * Distance along the camera's optical axis (the same convention as
+       * FocusPlane), not the renderer's ray length to the point.
        */
       longitudinalDistanceM: number;
     })
@@ -300,13 +291,12 @@ export interface FocusTargetResolution {
 
 ## parseFocusControlProfile
 
-Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
-missing required fields and incompatible scientific data fail at this boundary.
+Validates an untrusted focus-control profile and returns it normalized. Unknown enum values,
+missing required fields and inconsistent scientific data are rejected.
 
-Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
-actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
-scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
-separate state transitions.
+Focus is a distance along the optical axis or infinity, never a distance on screen. The ideal
+actuator focuses on the target observations it is given. It does not model a real AF sensor, a
+focus-ring scale or focusing time.
 
 ```ts
 export function parseFocusControlProfile(
@@ -318,13 +308,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## resolveFocusTargetObservation
 
-Resolve an explicit available/lost target observation under the selected single/continuous AF
-policy, retaining acquisition and reacquisition disposition.
+Applies one target observation (target available or lost) under the selected AF-S or AF-C
+policy, and records whether the target was acquired or reacquired.
 
-Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
-actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
-scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
-separate state transitions.
+The ideal actuator focuses on the observation as given. Target loss, reacquisition, focus
+lock and release priority are separate state changes.
 
 ```ts
 export function resolveFocusTargetObservation(
@@ -353,12 +341,7 @@ export interface ResolveFocusTargetObservationInput {
 
 ## setFocusLock
 
-Return an explicit lock/unlock transition without changing the underlying physical focus plane.
-
-Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
-actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
-scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
-separate state transitions.
+Locks or unlocks focus. The physical focus plane does not change.
 
 ```ts
 export function setFocusLock(
@@ -385,13 +368,8 @@ export interface SetFocusLockInput {
 
 ## setManualFocusState
 
-Return a manual focus transition to the supplied finite/infinity plane without inventing a lens
-actuator or focus-ring conversion.
-
-Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
-actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
-scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
-separate state transitions.
+Returns the state after manually focusing on the given finite or infinity plane. No lens
+actuator or focus-ring conversion is modelled.
 
 ```ts
 export function setManualFocusState(

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

@@ -1,12 +1,13 @@
 # capture/linear-encoding.ts public contracts
 
-Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateLinearCaptureEncoding
 
-Quantizes one immutable inline float plane without changing its capture data.
+Converts one inline float plane to integer codes. The capture data is not changed.
+
 Mapping: blackCode + (sample-blackValue)/(referenceWhiteValue-blackValue)
-* (referenceWhiteCode-blackCode). Clips only under explicit policy, then rounds.
+* (referenceWhiteCode-blackCode). It clips only when the policy says so, then rounds.
 
 ```ts
 export function calculateLinearCaptureEncoding(input: LinearCaptureEncodingInput): CalculationResult<EncodedLinearCapture>;
@@ -16,13 +17,13 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## EncodedLinearCapture
 
-Format-neutral 16-bit unsigned codes; metadata retains color/WB/saturation meaning.
+16-bit unsigned codes, not tied to a file format. The metadata keeps their colour, white-balance (WB) and saturation meaning.
 
 ```ts
 export interface EncodedLinearCapture {
   schemaVersion: typeof LINEAR_CAPTURE_ENCODING_SCHEMA_VERSION;
   captureId: string;
-  /** Sanitized geometry/settings/WB/adopted-white/model provenance without float planes. */
+  /** Cleaned-up copy of the capture's geometry, settings, WB, adopted white and model provenance, without the float planes. */
   captureMetadata: Omit<SimulatedCapture, "planes">;
   sourcePlane: Omit<CaptureLinearPlane, "storage">;
   encoding: LinearCaptureEncoding;
@@ -35,18 +36,26 @@ export interface EncodedLinearCapture {
   scale: number;
   minimumRepresentableValue: number;
   maximumRepresentableValue: number;
-  /** Maximum above-black value / reference-white above-black value. */
+  /** Headroom: (maximum value − black) / (reference white − black). */
   headroomFactor: number;
-  /** 0.5/scale for in-range samples; excludes clipping error. */
+  /** Largest rounding error for in-range samples, 0.5/scale. Clipping error is not included. */
   maximumRoundingError: number;
   clippedLowSampleCount: number;
   clippedHighSampleCount: number;
-  /** No default rendering exposure/display white is chosen by linear encoding. */
+  /** Linear encoding never picks a default rendering exposure or display white. */
   defaultRenderingExposureEv: null;
   samples: readonly number[];
 }
 ```
 
+## LINEAR_CAPTURE_ENCODING_MODEL_VERSION
+
+Version of the `uniform-linear-capture-uint16` model. 0.2.0 made rounding exact: nearest, ties up (Math.round).
+
+```ts
+LINEAR_CAPTURE_ENCODING_MODEL_VERSION = "0.2.0" as const
+```
+
 ## LINEAR_CAPTURE_ENCODING_SCHEMA_VERSION
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -57,14 +66,14 @@ LINEAR_CAPTURE_ENCODING_SCHEMA_VERSION = "0.1.0" as const
 
 ## LinearCaptureEncoding
 
-Uniform channel mapping; capture reference white comes from the source plane.
+The same linear mapping for every channel. The reference white value comes from the source plane.
 
 ```ts
 export interface LinearCaptureEncoding {
   schemaVersion: typeof LINEAR_CAPTURE_ENCODING_SCHEMA_VERSION;
   /** Relative source sample value assigned blackCode; may be negative. */
   blackValue: number;
-  /** Integer code at blackValue, 0..65534. An offset can preserve negative samples. */
+  /** Integer code for blackValue, 0..65534. A nonzero offset can keep negative samples. */
   blackCode: number;
   /** Code at the plane's referenceWhiteValue, strictly above blackCode, at most 65535. */
   referenceWhiteCode: number;
@@ -82,7 +91,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface LinearCaptureEncodingInput {
   capture: SimulatedCapture;
   planeId: string;
-  /** Prevents substituting a differently interpreted linear plane. */
+  /** Identifies the exact source plane, so a plane with a different meaning cannot be swapped in. */
   requiredImageState: CaptureLinearImageState;
   encoding: LinearCaptureEncoding;
 }
@@ -90,7 +99,7 @@ export interface LinearCaptureEncodingInput {
 
 ## parseLinearCaptureEncoding
 
-Strict allowlisted encoding parser; no default clipping/rounding policy is invented.
+Strictly parses an encoding profile. It never fills in a default clipping or rounding policy.
 
 ```ts
 export function parseLinearCaptureEncoding(value: unknown): LinearCaptureEncoding;

package/docs/api/capture-lossless-jpeg.md

@@ -0,0 +1,49 @@
+# capture/lossless-jpeg.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## LosslessJpegImage
+
+Decoded lossless JPEG samples, interleaved by component within each line (line, x, component).
+
+```ts
+export interface LosslessJpegImage {
+  /** Samples per line (X in the frame header). */
+  width: number;
+  /** Lines (Y in the frame header). */
+  height: number;
+  components: number;
+  /** Sample precision P in bits, 2..16. */
+  precision: number;
+  predictor: number;
+  pointTransform: number;
+  samples: Uint16Array;
+}
+```
+
+## LosslessJpegLimits
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LosslessJpegLimits {
+  /** Largest width x height x components accepted. Checked before output is allocated. */
+  maximumSamples: number;
+  /**
+   * DNG files with DNGVersion below 1.1.0.0 store 16 extra bits after the SSSS = 16 difference category
+   * (DNG 1.7.1.0 specification, Compatibility Issue 2). Standard streams store none.
+   */
+  legacySixteenBitDifference?: boolean;
+}
+```
+
+## parseLosslessJpeg
+
+Decodes one lossless JPEG stream. Every length, count and table index is checked against the
+buffer. Output is allocated only after the declared size passes `limits.maximumSamples`.
+
+```ts
+export function parseLosslessJpeg(bytes: Uint8Array, limits: LosslessJpegLimits): LosslessJpegImage;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/capture-native-environment-optical-stage.md

@@ -0,0 +1,75 @@
+# capture/native-environment-optical-stage.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## NATIVE_ENVIRONMENT_OPTICAL_STAGE_LIMITS
+
+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.
+
+```ts
+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
+})
+```
+
+## NativeEnvironmentOpticalStage
+
+Opaque, engine-owned optical-stage result. It is valid only for captures whose optical binding and every
+site's environment input are strictly equal to those that produced it. dispose() zeroes and releases the
+storage; a disposed stage refuses every later use.
+
+```ts
+export interface NativeEnvironmentOpticalStage {
+  readonly kind: "native-environment-optical-stage";
+  readonly pixelCount: number;
+  readonly temporalSampleCount: number;
+  /** Typed-array bytes held: pixelCount × (fixedBytesPerSite + bytesPerTemporalSamplePerSite × temporalSampleCount). */
+  readonly retainedBytes: number;
+  /** Radiance callbacks the producing task executed; reuse executes none. */
+  readonly providerEvaluationCount: number;
+  readonly disposed: boolean;
+  dispose(): void;
+}
+```
+
+## NativeEnvironmentOpticalStageRetention
+
+Optional request on NativeEnvironmentRawInput to keep the optical stage. The byte budget covers the typed-array storage described by the limits.
+
+```ts
+export interface NativeEnvironmentOpticalStageRetention {
+  maximumRetainedBytes: number;
+}
+```
+
+## NativeEnvironmentSensorStageInput
+
+Input for a post-optics re-run. `raw` may differ from the original capture only in post-optics fields.
+
+```ts
+export interface NativeEnvironmentSensorStageInput {
+  raw: NativeRawInput;
+  sceneBinding: SimulateEnvironmentSensorRawFrameInput["sceneBinding"];
+}
+```
+
+## NativeEnvironmentSensorStageProvider
+
+Supplies the same physical site inputs as the original capture. Environments must equal the retained ones exactly.
+
+```ts
+export interface NativeEnvironmentSensorStageProvider {
+  readTile(request: Readonly<NativeRawTileRequest>, signal: AbortSignal): Promise<{ captureId: string; frameId: string; x: number; y: number;
+    width: number; height: number; sites: SimulateEnvironmentSensorRawFrameInput["sites"] }>;
+  yieldControl(signal: AbortSignal): Promise<void>;
+}
+```

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

@@ -1,10 +1,69 @@
 # capture/native-environment-raw.ts public contracts
 
-Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculateNativeRawRowBands
+
+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.
+
+```ts
+export function calculateNativeRawRowBands(plan:Pick<NativeRawPlan,"exposure">,count:number):NativeRawRowBand[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## composeNativeEnvironmentRawPartitions
+
+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.
+
+```ts
+export function composeNativeEnvironmentRawPartitions(input:NativeEnvironmentRawInput,partitions:readonly NativeEnvironmentRawPartition[]):NativeEnvironmentRawOutput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createNativeEnvironmentRawPartitionTask
+
+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.
+
+```ts
+export function createNativeEnvironmentRawPartitionTask(input:NativeEnvironmentRawInput,rows:NativeRawRowBand,
+  provider:NativeEnvironmentRawProvider):NativeEnvironmentRawPartitionTask;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
 ## createNativeEnvironmentRawTask
 
-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.
 
 ```ts
 export function createNativeEnvironmentRawTask(input:NativeEnvironmentRawInput,provider:NativeEnvironmentRawProvider):NativeEnvironmentRawTask;
@@ -12,6 +71,31 @@ export function createNativeEnvironmentRawTask(input:NativeEnvironmentRawInput,p
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## createNativeEnvironmentSensorStageTask
+
+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.
+
+```ts
+export function createNativeEnvironmentSensorStageTask(input:NativeEnvironmentSensorStageInput,opticalStage:NativeEnvironmentOpticalStage,
+  provider:NativeEnvironmentSensorStageProvider):NativeEnvironmentRawTask;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
 ## NativeEnvironmentPhotoTile
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -22,6 +106,17 @@ export interface NativeEnvironmentPhotoTile extends NativeRawTileRequest {
 }
 ```
 
+## NativeEnvironmentRadianceQuery
+
+One radiance query of a batch: the frozen provider request and, for an ideal-pupil ray, its frozen aperture ray.
+
+```ts
+export interface NativeEnvironmentRadianceQuery {
+  request: Readonly<SceneRadianceEvaluationRequest>;
+  apertureRay?: Readonly<SensorApertureRay>;
+}
+```
+
 ## NativeEnvironmentRawInput
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -30,8 +125,13 @@ The exact contract is declared below; use the domain guide for assumptions and s
 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;
 }
 ```
 
@@ -47,6 +147,45 @@ 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;
+}
+```
+
+## NativeEnvironmentRawPartition
+
+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.
+
+```ts
+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;
+}
+```
+
+## NativeEnvironmentRawPartitionTask
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeEnvironmentRawPartitionTask extends Omit<NativeRawTask,"takeOutput"> {
+  readonly rows: NativeRawRowBand;
+  readonly providerEvaluationCount: number;
+  takeOutput(): NativeEnvironmentRawPartition;
 }
 ```
 
@@ -60,7 +199,17 @@ export interface NativeEnvironmentRawProvider {
   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>;
 }
@@ -86,3 +235,11 @@ export interface NativeEnvironmentRawTile extends NativeRawTileRequest {
   sites: SimulateEnvironmentSensorRawFrameInput["sites"];
 }
 ```
+
+## NativeRawRowBand
+
+A band of whole native rows, [y, y + height), in absolute full-sensor coordinates.
+
+```ts
+export interface NativeRawRowBand { y: number; height: number }
+```