@photivra/engine 1.5.0 → 2.1.0

package/docs/api/facade-simulate-capture.md

@@ -0,0 +1,397 @@
+# facade/simulate-capture.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.
+
+## SIMULATE_CAPTURE_COST_OPTIONS
+
+Options reported in `diagnostics.options` (2.1), in this order, when they ran: the ones that change how much work
+a capture does. `motion.rotation` is a non-zero angular velocity; `sensor.temporalSampleCount` a count above 1.
+
+```ts
+SIMULATE_CAPTURE_COST_OPTIONS = Object.freeze(["lens.pupilSampling", "lens.projection", "lens.distortion", "lens.vignetting", "lens.psf",
+  "lens.diffraction", "sensor.antiAliasing", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror",
+  "output.whiteBalance.auto", "output.demosaic.ahd", "output.highlightMode.reconstruct", "output.colorEncoding.wide-gamut", "output.gamutMapping.perceptual",
+  "output.format.jpeg", "output.format.png", "output.format.dng"] as const)
+```
+
+## SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX
+
+Default illuminance, lux: an 18 % Lambertian grey card (L = 0.18·E/π) then gets exactly the CIPA DC-004 standard
+output sensitivity reference exposure H = 10/S at f/8, 1/125 s, ISO 100:
+E = π·10·N²/(0.65·t·S·0.18) = π·80 000/11.7 ≈ 21 480.98 lux.
+
+```ts
+SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX = Math.PI * sosReferenceLuminance(DEFAULTS.fNumber, DEFAULTS.shutterSeconds, DEFAULTS.iso) /
+  GREY_CARD_REFLECTANCE
+```
+
+## SIMULATE_CAPTURE_FACADE_VERSION
+
+Version of how the facade builds requests. It changes whenever the same input would build a different request.
+
+```ts
+SIMULATE_CAPTURE_FACADE_VERSION = "1.0.0" as const
+```
+
+## simulateCapture
+
+Simulates one still capture of a planar scene and returns the developed image, the packed RAW, the full
+underlying request/plan, provenance and every assumption made. See docs/QUICK_START.md.
+
+```ts
+export async function simulateCapture(options: SimulateCaptureOptions): Promise<SimulateCaptureResult>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
+## SimulateCaptureAssumption
+
+One decision the facade made: a default, a derived value or a fixed modelling choice.
+
+```ts
+export interface SimulateCaptureAssumption {
+  /** Dotted option path or modelling topic, for example "exposure.shutterSeconds" or "model.lens-psf". */
+  id: string;
+  kind: "default" | "derived" | "model";
+  value: unknown;
+  explanation: string;
+}
+```
+
+## SimulateCaptureBorderHandling
+
+`margin` renders extra native sites around the output, as far as the kernel reaches. `mirror` renders
+exactly the output and reads mirrored (reflect-101) copies of the missing border sites. Mirroring is
+checked to keep the CFA (colour filter array) pattern consistent.
+
+```ts
+export type SimulateCaptureBorderHandling = "margin" | "mirror";
+```
+
+## SimulateCaptureColorEncoding
+
+PNG colour encoding. `srgb` is the developed sRGB output. The others take the developed linear
+colour (camera → XYZ → linear sRGB/D65, unclipped) and convert it through CIE XYZ into the target
+primaries:
+- `display-p3`: Display P3 primaries (W3C CSS Color 4 `display-p3`; also SMPTE EG 432-1) with the
+  sRGB transfer function;
+- `rec2020`: ITU-R BT.2020 primaries and OETF.
+PQ and HLG (BT.2100) are not part of 2.0; see THIRD_PARTY.md.
+
+```ts
+export type SimulateCaptureColorEncoding = "srgb" | "display-p3" | "rec2020";
+```
+
+## SimulateCaptureCostOption
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureCostOption = typeof SIMULATE_CAPTURE_COST_OPTIONS[number];
+```
+
+## SimulateCaptureDemosaic
+
+Demosaic. `bilinear`: the built-in Bayer kernels (`createBuiltInBayerDemosaicProfiles`). `ahd` (2.1): adaptive
+homogeneity-directed demosaicing (`createAhdDemosaicTask`, after Hirakawa & Parks 2005), a non-linear
+edge-directed method that reduces zipper and false colour on sharp edges.
+
+```ts
+export type SimulateCaptureDemosaic = "bilinear" | "ahd";
+```
+
+## SimulateCaptureExposureMode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureExposureMode = "manual" | "aperture-priority" | "shutter-priority" | "program";
+```
+
+## SimulateCaptureLensDistortion
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureLensDistortion =
+  | { kind: "radial"; profile: RadialDistortionProfile }
+  | { kind: "brown-conrady"; profile: BrownConradyDistortionProfile };
+```
+
+## SimulateCaptureMotion
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SimulateCaptureMotion {
+  /** Constant camera angular velocity, rad/s, in the engine's pitch/yaw/roll convention. Missing axes are 0. */
+  angularVelocityRadPerSec?: { pitch?: number; yaw?: number; roll?: number };
+  /** Default "global". `rolling` derives the exposure schedule from the body's rolling readout declaration. */
+  shutter?: "global" | "rolling";
+  /** Rolling shutter only: time from the first to the last line over the simulated frame, in s. Default: the body's declared readout skew. */
+  rollingShutterSkewSeconds?: number;
+}
+```
+
+## SimulateCaptureOptions
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SimulateCaptureOptions {
+  /** Generic tier preset id or a full preset record (for example a modified copy of a catalog entry). Default "professional". */
+  camera?: GenericEquipmentTier | GenericEquipmentTierPreset;
+  lens?: {
+    /** Must lie in the lens capability (the generic primes are 50 mm). Default: the lens's shortest focal length. */
+    focalLengthMm?: number;
+    /** Aperture for manual and aperture-priority modes. Default 8. */
+    fNumber?: number;
+    /** Focus distance in metres. Default: the subject distance. */
+    focusDistanceM?: number;
+    /** Opt-in ideal circular-pupil ray sampling (defocus/depth of field). Default off (central ray only). */
+    pupilSampling?: { radialSamples: number; angularSamples: number };
+    /** Ideal lens projection (`LENS_PROJECTION_MODELS`). Default "rectilinear". Not combinable with pupilSampling. */
+    projection?: LensProjectionModel;
+    /** Caller-declared radial or Brown–Conrady distortion profile. Default none. Not combinable with pupilSampling. */
+    distortion?: SimulateCaptureLensDistortion;
+    /** Caller-declared radial relative-illumination (vignetting) profile, applied as environment field throughput. */
+    vignetting?: IlluminationVignettingProfile;
+    /**
+     * Caller sampled lens PSF, passed unchanged to the environment contract. Its focal length, f-number and
+     * focus must equal the resolved capture settings exactly. Not combinable with pupilSampling.
+     */
+    psf?: Extract<CalculateEnvironmentSensorPhotoSignalInput["psf"], { kind: "sampled-local" }>;
+    /**
+     * Opt-in (2.1) diffraction blur of an ideal, aberration-free, in-focus lens with a circular pupil at the
+     * capture's resolved f-number: the engine builds the Airy kernels (`createDiffractionLimitedPsfProfile`)
+     * on the site pitch. `kernelRadiusSamples` (0–32) sets the kernel window; default: the third dark ring at
+     * the longest spectral node. Not combinable with `psf` or `pupilSampling`. Default off.
+     */
+    diffraction?: SimulateCaptureLensDiffraction;
+  };
+  exposure?: {
+    /** Default "manual". */
+    mode?: SimulateCaptureExposureMode;
+    /** Default 100. */
+    iso?: number;
+    /** Shutter for manual and shutter-priority modes. Default 1/125 s. */
+    shutterSeconds?: number;
+    /** Exposure compensation applied to the meter target, in stops. Default 0. */
+    compensationStops?: number;
+  };
+  /** Required: an engine chart (for example `{ preset: "uniform" }`, an 18 % grey card) or a caller reflectance/radiance function. */
+  scene: ChartScene | CallerReflectanceScene | CallerRadianceScene;
+  /** Distance from the camera to the scene plane in metres. Default 5. */
+  subjectDistanceM?: number;
+  /** Default: Planckian 6500 K (a blackbody stand-in for daylight; CIE D65 is not bundled). */
+  illuminant?: CaptureIlluminant;
+  /** Illuminance on the scene plane, lux. Default about 21 481 lux (see `SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX` and the assumptions). */
+  illuminanceLux?: number;
+  output?: {
+    /** Output pixels; the native sensor raster adds a one-site demosaic border on each side. Defaults 64 × 64. */
+    width?: number;
+    height?: number;
+    /** Default "srgb-8". */
+    format?: SimulateCaptureOutputFormat;
+    /** Default "identity". */
+    toneCurve?: SdrToneCurve;
+    /** Required by the luminance tone curves (see `SdrToneCurveParameters`). The facade does not make one up. */
+    toneCurveParameters?: SdrToneCurveParameters;
+    /** Default "clip". */
+    highlightMode?: RawHighlightMode;
+    /** Default "scene-illuminant". */
+    whiteBalance?: SimulateCaptureWhiteBalance;
+    /** JPEG constant quantization step 1-255 (not a manufacturer 'quality'). Default 2. */
+    jpegQuantizationStep?: number;
+    /** PNG only. Default "srgb". */
+    colorEncoding?: SimulateCaptureColorEncoding;
+    /** PNG only: 8 or 16 bits per sample. Default 8. */
+    bitDepth?: 8 | 16;
+    /**
+     * PNG SDR encodings only. Default "clip" (per-component clip to the target gamut). "perceptual" maps
+     * through `prepareRgbGamutMapping`: constant CIELAB L* and hue, chroma above 90 % of the boundary compressed.
+     */
+    gamutMapping?: "clip" | "perceptual";
+    /** Default: the 1.0 facade's bilinear RGGB kernels. */
+    demosaic?: SimulateCaptureDemosaic;
+    /** Default "margin". */
+    borderHandling?: SimulateCaptureBorderHandling;
+    /** DNG only: optional capture-event time (YYYY-MM-DDTHH:mm:ss.sssZ); without it no date tags are written. */
+    dng?: { capturedAtUtc?: string };
+  };
+  /** Camera motion and shutter type. Default: still camera, global electronic shutter. */
+  motion?: SimulateCaptureMotion;
+  sensor?: {
+    /** Pixel pitch in micrometres. Default 6. */
+    pixelPitchMicrometers?: number;
+    /** Maximum spectral quadrature subinterval in nm. Default 20. */
+    spectralStepNanometers?: number;
+    /** Temporal midpoint samples across the exposure. Default 1. */
+    temporalSampleCount?: number;
+    /** Noise seed (uint32). Default 1. */
+    noiseSeed?: number;
+    /**
+     * Opt-in (2.1) optical anti-aliasing filter (birefringent point splitting, `SimulateCaptureSensorAntiAliasing`).
+     * Multiplies the scene queries by the number of split points. Default off (the tiers declare no filter).
+     */
+    antiAliasing?: SimulateCaptureSensorAntiAliasing;
+  };
+  /** Aborting cancels the running task; the promise rejects with a domain error and returns no partial image. */
+  signal?: AbortSignal;
+  /** Called after each committed RAW, development or JPEG tile. Cannot change output. */
+  onProgress?: (progress: SimulateCaptureProgress) => void;
+}
+```
+
+## SimulateCaptureOutputFormat
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureOutputFormat = "srgb-8" | "srgb-16" | "jpeg" | "png" | "dng";
+```
+
+## SimulateCaptureProgress
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SimulateCaptureProgress {
+  stage: "raw" | "white-balance" | "development" | "jpeg";
+  completedTileCount: number;
+  totalTileCount: number;
+}
+```
+
+## SimulateCaptureResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SimulateCaptureResult {
+  facadeVersion: typeof SIMULATE_CAPTURE_FACADE_VERSION;
+  engineApiVersion: string;
+  image: {
+    width: number;
+    height: number;
+    format: SimulateCaptureOutputFormat;
+    /** Interleaved RGB, row by row from the top-left. sRGB-encoded (W3C CSS Color 4 sRGB; also IEC 61966-2-1) unless `colorEncoding` says otherwise. */
+    samples: Uint8Array | Uint16Array;
+    /** Baseline JPEG bytes when format is "jpeg". */
+    jpeg?: Uint8Array;
+    /** PNG file bytes when format is "png". */
+    png?: Uint8Array;
+    /** Encoding of `samples` and `png` when format is "png". */
+    colorEncoding?: SimulateCaptureColorEncoding;
+    /** Lossless uncompressed CFA DNG of the packed RAW when format is "dng" (`serializeNativeRawDng`); `samples` are then sRGB 8-bit. */
+    dng?: Uint8Array;
+  };
+  /** Packed native RAW (codes, black levels, saturation flags) as produced by the native environment RAW task. */
+  raw: NativeRawOutput;
+  plan: NativeRawPlan;
+  /** The complete underlying request. */
+  request: {
+    environmentRaw: NativeEnvironmentRawInput;
+    /** Rebuilds the exact physical site input the provider supplied for a native row-major index. */
+    siteInput(nativeIndex: number): SimulateEnvironmentSensorRawFrameInput["sites"][number];
+    development: Omit<NativeRawDevelopmentInput, "raw">;
+    whiteBalanceState: ResolvedWhiteBalanceState | null;
+    /**
+     * Present with lens.diffraction (2.1): the engine-built Airy profile, the equivalent environment sampled PSF
+     * selection, and how it was applied. With `object-space-convolution` the site inputs declare no PSF and the
+     * provider answers with the PSF-convolved radiance; putting `psf` into each site input and using the plain
+     * scene provider gives the same expected signal (to float rounding) through the per-tap environment quadrature.
+     */
+    diffraction?: { profile: DiffractionLimitedPsfProfile; psf: Extract<CalculateEnvironmentSensorPhotoSignalInput["psf"], { kind: "sampled-local" }>;
+      execution: "object-space-convolution" | "environment-psf-quadrature" };
+  };
+  exposure: {
+    mode: SimulateCaptureExposureMode;
+    settings: { fNumber: number; shutterSeconds: number; iso: number };
+    /** Exposure value at ISO 100 of the settings, log2(N²/t). */
+    ev100: number;
+    meteredSceneLuminanceCdPerSquareMeter: number;
+    /** Full output of the existing exposure-mode resolver. */
+    resolution: unknown;
+  };
+  scene: {
+    sceneId: string;
+    preset: string;
+    parameters: Readonly<Record<string, unknown>>;
+    illuminant: { id: string; description: string; illuminanceLux: number };
+    distanceM: number;
+    /** Physical size of the framed scene plane, metres. */
+    framedWidthM: number;
+    framedHeightM: number;
+    /**
+     * SHA-256 of the canonical scene description, recorded as the capture source digest. Caller spectra (a
+     * `spectrum` or `daylight` illuminant, chart reflectance spectra) are part of the description: tabulated
+     * data exactly, function spectra sampled at 1 nm over 380-780 nm, plus the daylight basis datasetId.
+     * The body of a caller scene's evaluate function is not hashed.
+     */
+    sourceSha256: string;
+  };
+  diagnostics: {
+    providerEvaluationCount: number;
+    highlight: RawHighlightDiagnostics;
+    rendering: SdrRenderingResult["diagnostics"];
+    /** Present with output.gamutMapping "perceptual": pixels whose chroma or lightness the mapping changed. */
+    gamutMapping?: { method: "cielab-hue-preserving-chroma-compression"; kneeFraction: number; adjustedPixelCount: number; lightnessClippedPixelCount: number };
+    /**
+     * Wall-clock milliseconds per stage. `raw`, `whiteBalance` (the second RAW pass of auto white balance), `development`
+     * (includes DNG writing), `jpeg` and `total` are whole milliseconds (`Date.now()`). Since 2.1, where a stage ran:
+     * `diffraction` (the object-space convolution of `lens.diffraction`; part of `raw` and `whiteBalance`), `demosaic`
+     * (the AHD demosaic; part of `development`) and `encode` (PNG, JPEG or DNG serialization), with sub-millisecond
+     * resolution where the host has `performance.now()`. Timings vary from run to run and never enter any digest or output byte.
+     */
+    timingsMs: { raw: number; whiteBalance: number; development: number; jpeg: number; total: number; diffraction?: number; demosaic?: number; encode?: number };
+    /**
+     * 2.1: the opt-in options that changed the work of this run, in a fixed order (see `SIMULATE_CAPTURE_COST_OPTIONS`).
+     * Empty for a capture with every default. With `timingsMs` it lets an application measure each option's cost on
+     * the user's device.
+     */
+    options: readonly SimulateCaptureCostOption[];
+  };
+  provenance: {
+    scientificStatus: "approximation";
+    cameraPresetId: string;
+    cameraPresetVersion: string;
+    evidence: readonly EvidenceProvenance[];
+    /** Existing engine contracts the facade composed, in execution order. */
+    composedContracts: readonly string[];
+    limitations: readonly string[];
+  };
+  assumptions: readonly SimulateCaptureAssumption[];
+}
+```
+
+## SimulateCaptureSensorAntiAliasing
+
+Optical anti-aliasing (low-pass) filter (2.1), modelled as birefringent point splitting: each image point is
+split into equally bright copies (the engine's `normalized-point-splitting-kernel` optical-stack response).
+- `four-spot`: two crossed birefringent plates; copies at (±d/2, ±d/2), weight 1/4 each, MTF |cos(π·f_x·d)·cos(π·f_y·d)|.
+- `two-spot`: one plate splitting along `axis`; copies at ±d/2, weight 1/2 each, MTF |cos(π·f·d)|.
+- `point-splitting`: the engine contract itself, offsets in micrometres (+x right, +y down) and positive weights
+  summing to 1 (at most 16 components, each within 4 sites).
+d = `separationSites` × pixel pitch, 0 < separationSites ≤ 4, default 1 (first MTF zero at the sensor's Nyquist
+frequency 1/(2·pitch)).
+
+```ts
+export type SimulateCaptureSensorAntiAliasing =
+  | { kind: "four-spot"; separationSites?: number }
+  | { kind: "two-spot"; axis: "horizontal" | "vertical"; separationSites?: number }
+  | { kind: "point-splitting"; components: readonly AntiAliasingPointSplitComponent[] };
+```
+
+## SimulateCaptureWhiteBalance
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureWhiteBalance =
+  | "scene-illuminant"
+  | "auto"
+  | "none"
+  | { kelvin: number; tint?: number }
+  | { channelGains: { red: number; green: number; blue: number } };
+```

package/docs/api/gpu-image-kernel-accelerator.md

@@ -0,0 +1,157 @@
+# gpu/image-kernel-accelerator.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.
+
+## AcceleratedNativeCaptureSdrOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AcceleratedNativeCaptureSdrOutput extends NativeCaptureSdrOutput { execution: ImageKernelExecution }
+```
+
+## AcceleratedNativeRawDevelopmentOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AcceleratedNativeRawDevelopmentOutput extends NativeRawDevelopmentOutput { execution: ImageKernelExecution }
+```
+
+## AcceleratedPackedSensorRawResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AcceleratedPackedSensorRawResult extends PackedSensorRawResult {
+  execution: ImageKernelExecution;
+  /**
+   * Region-relative indices of the flagged sites, ascending (empty for `cpu-reference`). Every other site
+   * equals the reference; recomputing these sites with the reference makes the whole region bit-identical.
+   */
+  flaggedSiteIndices: Uint32Array;
+}
+```
+
+## ChartRadianceResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ChartRadianceResult {
+  plan: ChartRadianceBatchPlan;
+  /** Row-major (query, column): float64 for `cpu-reference`, float32 for `webgpu-f32`. */
+  values: Float64Array | Float32Array;
+  columns: number;
+  execution: ImageKernelExecution;
+  /**
+   * Queries whose float32 classification fell inside its bound, recomputed on the host with the
+   * reference (then rounded to float32). Empty for `cpu-reference`.
+   */
+  hostRecomputedQueryIndices: Uint32Array;
+}
+```
+
+## createImageKernelAccelerator
+
+Requests a backend. Never swaps backends silently: a fallback must be set in the options and is shown in every result label.
+
+```ts
+export async function createImageKernelAccelerator(options: ImageKernelAcceleratorOptions): Promise<ImageKernelAccelerator>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
+## ImageKernelAccelerator
+
+Runs one operation at a time. dispose() releases the device and every buffer.
+
+```ts
+export interface ImageKernelAccelerator {
+  readonly backend: ImageKernelBackend;
+  readonly requestedBackend: ImageKernelBackend;
+  readonly fallbackReason: ImageKernelFallbackReason | null;
+  readonly state: ImageKernelAcceleratorState;
+  renderNativeCaptureSdr(input: NativeCaptureSdrInput, provider: NativeCaptureSdrProvider, options?: ImageKernelRunOptions): Promise<AcceleratedNativeCaptureSdrOutput>;
+  /** Takes ownership of `input.raw` exactly like `createNativeRawDevelopmentTask` (the caller's arrays are detached). */
+  developNativeRaw(input: NativeRawDevelopmentInput, provider: NativeRawDevelopmentProvider | ((signal: AbortSignal) => Promise<void>),
+    options?: ImageKernelRunOptions): Promise<AcceleratedNativeRawDevelopmentOutput>;
+  convolveIrradiance(input: IrradianceConvolutionInput, options?: ImageKernelRunOptions): Promise<IrradianceConvolutionResult>;
+  /** Sensor stage on typed arrays: seeded charge, read noise and ADC to RAW codes (see `simulatePackedSensorRaw`). */
+  simulateSensorRaw(input: PackedSensorRawInput, options?: ImageKernelRunOptions): Promise<AcceleratedPackedSensorRawResult>;
+  /** Exposure and motion as a weighted sum of shifted frames (see `calculateTemporalExposureSum`). */
+  sumTemporalExposure(input: TemporalExposureSumInput, options?: ImageKernelRunOptions): Promise<TemporalExposureSumResult>;
+  /** Chart scene radiance or its spectral integral at many frame points (see `calculateChartRadianceBatch`). */
+  evaluateChartRadiance(input: ChartRadianceBatchInput, options?: ImageKernelRunOptions): Promise<ChartRadianceResult>;
+  dispose(): void;
+}
+```
+
+## ImageKernelAcceleratorOptions
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ImageKernelAcceleratorOptions {
+  /** Requested backend. `cpu-reference` is the reference and never touches WebGPU. */
+  backend: ImageKernelBackend;
+  /** Required with `webgpu-f32`: use the CPU reference (labelled) or fail when WebGPU cannot be acquired. */
+  fallback?: "cpu-reference" | "fail";
+  /** WebGPU entry point; defaults to `navigator.gpu`. Supply a worker's `navigator.gpu` explicitly if needed. */
+  gpu?: unknown;
+  powerPreference?: "low-power" | "high-performance";
+  /** Largest single GPU band buffer in bytes (4 KiB up to the device limit); default min(64 MiB, device limit). Affects memory only, never results. */
+  maximumBandBytes?: number;
+  /** Aborts adapter/device acquisition. */
+  signal?: AbortSignal;
+}
+```
+
+## ImageKernelAcceleratorState
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ImageKernelAcceleratorState = "ready" | "lost" | "disposed";
+```
+
+## ImageKernelRunOptions
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ImageKernelRunOptions {
+  signal?: AbortSignal;
+  /** Yields to the host event loop between CPU reference chunks and GPU bands. Convolution, sensor and temporal stages; tasks keep their own yields. */
+  yieldControl?: (signal: AbortSignal) => Promise<void>;
+}
+```
+
+## IrradianceConvolutionResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IrradianceConvolutionResult {
+  plan: IrradianceConvolutionPlan;
+  /** Float64 for `cpu-reference`, float32 for `webgpu-f32`; row-major, same grid as the input. */
+  values: Float64Array | Float32Array;
+  /** Float64 sums of the input and output samples. Their difference is the amount lost across the grid edge. */
+  inputSum: number;
+  outputSum: number;
+  execution: ImageKernelExecution;
+}
+```
+
+## TemporalExposureSumResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface TemporalExposureSumResult {
+  plan: TemporalExposureSumPlan;
+  /** Float64 for `cpu-reference`, float32 for `webgpu-f32`; row-major, same grid as the input. */
+  values: Float64Array | Float32Array;
+  execution: ImageKernelExecution;
+}
+```