@photivra/engine 1.4.0 → 2.0.0

package/docs/api/sensor-color-sampling.md

@@ -1,6 +1,6 @@
 # sensor/color-sampling.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## LayeredColorSamplingLayout
 
@@ -10,13 +10,13 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface LayeredColorSamplingLayout {
   kind: "layered";
   /**
-   * Semantic layer/channel identifiers only. They do not define spectral
-   * response, depth ordering, spatial sampling density, or registration.
+   * Names for the layers or channels only. They do not define spectral
+   * response, depth order, sampling density or alignment between layers.
    */
   layerChannelIds: readonly string[];
   /**
-   * The first layered representation is deliberately structural only because
-   * real layered sensors may use unequal per-layer spatial sampling.
+   * Layered layouts are described structurally only for now, because real
+   * layered sensors may sample each layer differently.
    */
   spatialSamplingRelationship: "not-resolved";
 }
@@ -30,8 +30,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface MonochromeColorSamplingLayout {
   kind: "monochrome";
   /**
-   * Semantic measurement-channel identifier only. It is not a spectral
-   * response curve, wavelength, colorimetric primary, or calibration.
+   * A name for the measured channel only. It is not a spectral response
+   * curve, wavelength, colour primary or calibration.
    */
   channelId: string;
 }
@@ -55,8 +55,8 @@ export interface NativeColorSamplingSiteIndex {
   /**
    * Zero-based integer site index from the native sensor's left edge.
    *
-   * This is an abstract color-sampling-site lattice index. It is not a
-   * NativeImageRaster coordinate and does not assert one site = one physical
+   * It indexes the abstract grid of colour-sampling sites. It is not a
+   * NativeImageRaster coordinate and does not claim one site is one physical
    * photodiode.
    */
   x: number;
@@ -71,19 +71,17 @@ export interface NativeColorSamplingSiteIndex {
 
 ## parseSensorColorSamplingProfile
 
-Parses an exact color-sampling topology declaration without binding it to
-NativeImageRaster, physical photodiodes, spectral response, or a
-manufacturer-specific family enum.
+Parses an exact colour-sampling layout. It is not tied to NativeImageRaster,
+physical photodiodes, spectral response or a manufacturer's layout name.
 
-Periodic mosaics use an abstract native sensor color-sampling-site lattice
-with zero-based integer indices, top-left origin, +X right and +Y down.
-The repeat phase is anchored to the sensor lattice, so later active crops or
-orientation transforms must preserve the original native site indices.
+Repeating mosaics use an abstract grid of native sensor sites with zero-based
+integer indices, origin at the top left, +X right and +Y down. The repeat
+pattern is fixed to this grid, so later crops or orientation changes must keep
+the original native site indices.
 
-Layered layouts are structural-only in this first contract because real
-layered sensors may use unequal spatial sampling density/registration across
-layers. No per-site layered resolver is exposed until that relationship is
-modeled explicitly.
+Layered layouts are described structurally only, because real layered sensors
+may sample each layer at different densities or offsets. There is no per-site
+lookup for layered layouts until that is modelled explicitly.
 
 ```ts
 export function parseSensorColorSamplingProfile(
@@ -109,15 +107,15 @@ export interface PeriodicMosaicColorSamplingLayout {
    */
   repeatHeightSites: number;
   /**
-   * Row-major semantic channel IDs for one repeating tile.
+   * Channel IDs for one repeating tile, in row-major order.
    *
    * Length must equal repeatWidthSites × repeatHeightSites.
    */
   siteChannelIds: readonly string[];
   /**
-   * The repeat tile is anchored at native sensor sampling-site index (0, 0).
+   * The repeat tile starts at native sensor site (0, 0).
    *
-   * Active crops and physical orientation must not silently reset this phase.
+   * Active-area crops and camera orientation must not silently reset this phase.
    */
   anchor: "native-sensor-top-left-site";
 }
@@ -125,15 +123,15 @@ export interface PeriodicMosaicColorSamplingLayout {
 
 ## resolveColorSamplingSite
 
-Resolves the semantic measurement-channel assignment at one abstract native
-sensor color-sampling-site index for monochrome or periodic-mosaic layouts.
+Returns which channel one native site measures, for monochrome or repeating
+mosaic layouts.
 
-This API intentionally has no NativeImageRaster input. A later explicit
-binding must establish how a selected capture mode's effective raster maps
-to this color-sampling-site lattice before RAW/CFA sampling can be simulated.
+It deliberately takes no NativeImageRaster. A separate binding
+(capture-color-sampling-binding) must say how a capture mode's sample grid
+maps onto this site grid before RAW or CFA sampling can be simulated.
 
-Layered layouts fail closed because their per-layer spatial relationship is
-not resolved by the first structural contract.
+Layered layouts are rejected, because how their layers line up spatially is
+not defined yet.
 
 ```ts
 export function resolveColorSamplingSite(
@@ -179,7 +177,7 @@ export interface ResolvedColorSamplingSite {
         repeatHeightSites: number;
       };
   /**
-   * Explicit scientific boundaries for downstream consumers.
+   * States what this profile does not establish, for downstream code.
    */
   spectralResponseEstablished: false;
   nativeImageRasterBindingEstablished: false;
@@ -207,9 +205,9 @@ export interface SensorColorSamplingProfile {
   schemaVersion: "0.1.0";
   profileId: string;
   /**
-   * Evidence supporting this exact topology declaration.
+   * Evidence for this exact layout.
    *
-   * Descriptive architecture-family metadata remains a separate contract.
+   * Descriptive sensor-architecture metadata is a separate type.
    */
   evidence: readonly EvidenceProvenance[];
   coordinateSystem: SensorColorSamplingProfileCoordinateSystem;

package/docs/api/sensor-constant-rate-temporal-integration.md

@@ -1,6 +1,6 @@
 # sensor/constant-rate-temporal-integration.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## IntegrateStationarySensorRateInput
 
@@ -19,11 +19,12 @@ export interface IntegrateStationarySensorRateInput {
 
 ## integrateStationarySensorRateOverLocalExposure
 
-Integrates one explicitly stationary response-rate result over its exact
-bound local exposure window.
+Integrates one response rate, declared constant, over its exact local
+exposure window.
 
-This function is intentionally limited to the constant-rate approximation.
-It does not sample or integrate a time-varying signal.
+This is the constant-rate approximation only. It does not sample or
+integrate a time-varying signal. EQE rates give expected photons and
+electrons; A/W rates give coulombs. Counts stay fractional.
 
 ```ts
 export function integrateStationarySensorRateOverLocalExposure(
@@ -36,13 +37,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSensorRateTemporalStationarityProfile
 
-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 untrusted input and returns it as a normalized, typed value. Unknown enum values,
+missing required fields and inconsistent scientific data are rejected.
 
-Rate times duration is allowed only by explicit stationarity bound to the exact site and local
-shutter interval. EQE integrates to expected photons/electrons; A/W integrates current magnitude to
-coulombs without an implicit carrier mapping. Counts remain fractional expectations before
-stochastic sampling.
+The profile declares that a rate is constant (stationary) for an exact site and local shutter
+interval, which is what allows rate × duration.
 
 ```ts
 export function parseSensorRateTemporalStationarityProfile(

package/docs/api/sensor-dark-current.md

@@ -1,16 +1,14 @@
 # sensor/dark-current.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## calculateSensorDarkCurrentCharge
 
-Evaluate the declared temperature-dependent dark electron rate and integrate over the exact
-photo-signal local exposure event.
+Evaluates the declared dark-current rate at the sensor temperature and integrates it over the exact
+local exposure of the photo signal.
 
-Dark current is an independently declared pre-compensation thermal electron rate. Exact-temperature
-or sampled linear interpolation is supported only within declared applicability; no universal
-doubling-temperature law is inferred. Population means remain approximations and do not model
-hot-pixel/DCNU structure.
+The rate is a population mean, an approximation. Hot pixels and DCNU (dark-current non-uniformity)
+are not modelled. No universal doubling-temperature law is assumed.
 
 ```ts
 export function calculateSensorDarkCurrentCharge(
@@ -55,13 +53,12 @@ export interface CalculateSensorDarkCurrentChargeInput<Exposure extends SensorEq
 
 ## parseSensorDarkCurrentProfile
 
-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 untrusted input and returns it as a normalized, typed value. Unknown enum values,
+missing required fields and inconsistent scientific data are rejected.
 
-Dark current is an independently declared pre-compensation thermal electron rate. Exact-temperature
-or sampled linear interpolation is supported only within declared applicability; no universal
-doubling-temperature law is inferred. Population means remain approximations and do not model
-hot-pixel/DCNU structure.
+The profile declares the dark-current rate (before compensation) against temperature, at an exact
+temperature or as samples. Interpolation (log-linear, or the legacy linear rule) is allowed only
+within the declared range. No universal doubling-temperature law is assumed.
 
 ```ts
 export function parseSensorDarkCurrentProfile(
@@ -193,6 +190,7 @@ export type SensorDarkCurrentTemperatureModel =
         number;
     }
   | {
+      /** Legacy interpolation, linear in rate. Between samples of an exponential curve it gives values that are too high. */
       kind:
         "piecewise-linear-temperature-table";
       interpolation: "piecewise-linear";
@@ -203,6 +201,24 @@ export type SensorDarkCurrentTemperatureModel =
         darkCurrentElectronsPerSecond:
           number;
       }[];
+    }
+  | {
+      /**
+       * Linear interpolation of ln(rate) between neighbouring samples. That makes the rate exponential
+       * in temperature within each interval, matching the roughly exponential (Arrhenius, or
+       * "doubling temperature") behaviour of thermally generated dark current. Rates must be strictly
+       * positive. No single doubling temperature is imposed; each interval follows its own two samples.
+       */
+      kind:
+        "log-linear-temperature-table";
+      interpolation: "log-linear";
+      outsideRangeBehavior:
+        "fail-closed";
+      samples: readonly {
+        temperatureC: number;
+        darkCurrentElectronsPerSecond:
+          number;
+      }[];
     };
 ```
 
@@ -216,7 +232,7 @@ export type SensorPhotoDarkCurrentCharge = SensorDarkCurrentCharge | SensorTempo
 
 ## SensorTemporalDarkCurrentCharge
 
-Dark charge shares the exact temporal photo event, without a stationarity ID.
+Dark charge for the exact same time-resolved photo event. It has no stationarity ID.
 
 ```ts
 export type SensorTemporalDarkCurrentCharge = Omit<SensorDarkCurrentCharge, "stationarityProfileId" | "temporalIntegrationId" | "componentEvidence"> & {

package/docs/api/sensor-environment-photo-signal.md

@@ -1,10 +1,10 @@
 # sensor/environment-photo-signal.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## calculateEnvironmentSensorPhotoSignal
 
-Generate, evaluate and integrate one site's actual local midpoint environment support.
+Plans, queries the provider and integrates the photo signal for one site, at the site's own midpoint sample positions.
 
 ```ts
 export function calculateEnvironmentSensorPhotoSignal(input: CalculateEnvironmentSensorPhotoSignalInput): CalculationResult<EnvironmentSensorPhotoSignal>;
@@ -26,9 +26,16 @@ export interface CalculateEnvironmentSensorPhotoSignalInput {
   motion: Pick<CalculateSensorEnvironmentRadianceQueryInput,
     "angularVelocityRadPerSec" | "timeReference" | "environmentDirectionConvention">;
   temporalSampleCount: number;
-  /** Optional ideal geometric DOF/visibility support; cannot combine with a sampled PSF. */
+  /** Optional ideal circular pupil, for geometric depth of field (DOF) and visibility. Cannot be combined with a sampled PSF. */
   pupil?: IdealCircularPupil;
-  /** Explicit source-field attenuation, applied once before PSF redistribution. */
+  /**
+   * Optional lens field mapping (added in 2.0): a projection model and radial or Brown-Conrady
+   * distortion for the scene-ray query. Its distortion area factor is applied to irradiance exactly
+   * once. If omitted, the ideal rectilinear, distortion-free path is unchanged. Cannot be combined
+   * with `pupil`.
+   */
+  lensFieldMapping?: EnvironmentLensFieldMapping;
+  /** Explicit attenuation across the field (such as vignetting), applied once before the PSF spreads the light. */
   fieldThroughput: { kind: "unity"; evidence: readonly EvidenceProvenance[]; limitation: string } | {
     kind: "radial-illumination-vignetting"; profile: IlluminationVignettingProfile;
     evidence: readonly EvidenceProvenance[]; limitation: string;
@@ -38,7 +45,7 @@ export interface CalculateEnvironmentSensorPhotoSignalInput {
     configuration: Pick<CalculateSensorPsfIrradianceQuadratureInput, "psf" | "psfWavelengthBasis" | "spatialModel">;
   };
   evaluateRadiance: EnvironmentRadianceEvaluator;
-  /** Required with pupil; origin-aware scene intersections cannot use direction-only code. */
+  /** Required with `pupil`: rays start at different points on the aperture, so a direction-only function cannot be used. */
   evaluateApertureRadiance?: EnvironmentApertureRadianceEvaluator;
 }
 ```
@@ -53,7 +60,7 @@ export type EnvironmentApertureRadianceEvaluator = (request: Readonly<SceneRadia
 
 ## EnvironmentRadianceEvaluator
 
-Supplied synchronous code executes locally. Invocation does not prove physical transport.
+Caller-supplied synchronous radiance function, run locally. Calling it does not prove its light transport is physical.
 
 ```ts
 export type EnvironmentRadianceEvaluator = (request: Readonly<SceneRadianceEvaluationRequest>) => SceneRadianceEvaluationResult;

package/docs/api/sensor-eqe-electron-rate.md

@@ -1,17 +1,18 @@
 # sensor/eqe-electron-rate.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## calculateSensorEqeElectronRate
 
-Converts pre-response geometric-aperture spectral radiant power into
-incident-photon rate and expected generated-electron rate.
+Converts the spectral radiant power collected by the site's geometric aperture
+(before the sensor response) into an incident photon rate and an expected
+generated electron rate.
 
-This function applies response per wavelength node. It never applies one
-broadband-average QE to total radiant power.
+The response is applied at each wavelength node. One broadband-average QE is
+never applied to the total power.
 
-Temporal exposure integration remains downstream, so all outputs are rates
-(per second), not photon/electron counts.
+Integration over exposure time happens later, so all outputs are rates per
+second, not photon or electron counts.
 
 ```ts
 export function calculateSensorEqeElectronRate(
@@ -80,7 +81,7 @@ export interface SensorEqeElectronRate {
   responseProfileId: string;
   responseApplicationProfileId: string;
   operatingRangeProfileId: string;
-  /** Engine-produced results populate the exact source color site. */
+  /** The exact source colour site. Results produced by the engine fill this in. */
   site?: {
     x: number;
     y: number;

package/docs/api/sensor-eqe-local-exposure.md

@@ -1,13 +1,14 @@
 # sensor/eqe-local-exposure.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## calculateSensorEqeLocalExposure
 
-Compose validated irradiance reduction, response applicability/range, EQE
-conversion and stationary local integration. The exposure value is suitable
-for accumulated-charge photoSignal; dark/completeness/capacity/readout remain
-explicit downstream inputs. Invalid or unsupported evidence fails closed.
+Runs irradiance reduction, the response applicability and range checks, EQE
+conversion and constant-rate integration over the local exposure. The result
+can be the photoSignal for accumulated charge. Dark current, completeness,
+capacity and readout are separate later inputs. Invalid or unsupported
+evidence is rejected.
 
 ```ts
 export function calculateSensorEqeLocalExposure(
@@ -19,38 +20,38 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## CalculateSensorEqeLocalExposureInput
 
-Explicit post-optics irradiance samples and evidence; no renderer or RGB conversion.
+Input: explicit irradiance samples after the optics, with evidence. No renderer or RGB conversion is involved.
 
 ```ts
 export interface CalculateSensorEqeLocalExposureInput {
-  /** Physical area, registered aperture/lattice, AA support and destination site. */
+  /** Physical area, the site's aperture on its grid, anti-aliasing (AA) support and the destination site. */
   spatialSampling: Omit<CalculateSensorSpatialSamplingQuadratureInput,
     "colorSamplingProfile" | "colorSamplingBindingProfile" | "nativeRaster">;
-  /** Explicit wavelength basis/range, channel and midpoint subdivision budget. */
+  /** Wavelength basis and range, channel, and the budget for midpoint subdivisions. */
   spectralSampling: Omit<CalculateSensorSpectralQuadratureInput,
     "colorSamplingProfile" | "spectralResponseProfile">;
-  /** One W/m²/nm value per identified pre-AA spatial/spectral node. */
+  /** One value in W/m²/nm for each identified spatial and spectral node, before anti-aliasing. */
   irradianceSamples: ReduceSensorSpatioSpectralIrradianceInput["sampleValues"];
-  /** Source-plane, collection-area and reference-condition evidence. */
+  /** Evidence about the source plane, collection area and reference conditions of the response data. */
   responseApplication: Omit<AssessSensorResponseApplicationCompatibilityInput, "reduction">;
-  /** Evidence-backed linear response domain; no extrapolation is authorized. */
+  /** Evidence-backed range in which the response is linear. No extrapolation beyond it is allowed. */
   operatingRangeProfile: AssessSensorResponseOperatingRangeInput["operatingRangeProfile"];
-  /** Destination CFA/channel identity shared by every composed step. */
+  /** The destination CFA site and channel, shared by every step. */
   colorSamplingProfile: CalculateSensorEqeElectronRateInput["colorSamplingProfile"];
-  /** Direct or separable EQE response; A/W responsivity is unsupported here. */
+  /** EQE response, given directly or as separable factors. A/W responsivity is not supported here. */
   spectralResponseProfile: CalculateSensorEqeElectronRateInput["spectralResponseProfile"];
-  /** Required explicit photon-energy conversion context for air wavelengths. */
+  /** Required for air wavelengths: the explicit context for converting to photon energy. */
   airPhotonEnergyContext?: CalculateSensorEqeElectronRateInput["airPhotonEnergyContext"];
-  /** Native one-to-one site binding and one opening/closing shutter event. */
+  /** One-to-one native site binding and one shutter opening and closing. */
   localExposure: Omit<BindSensorRateToLocalExposureInput, "rate" | "colorSamplingProfile">;
-  /** Separate declaration authorizing a constant rate across this exact window. */
+  /** A separate declaration that the rate is constant over this exact window. */
   stationarityProfile: SensorRateTemporalStationarityProfile;
 }
 ```
 
 ## SensorEqeLocalExposure
 
-Child envelopes retain separate provenance, validity and unpropagated uncertainty.
+Result. Each step's result keeps its own provenance, validity and uncertainty; uncertainties are not combined.
 
 ```ts
 export interface SensorEqeLocalExposure {

package/docs/api/sensor-eqe-temporal-exposure.md

@@ -1,13 +1,14 @@
 # sensor/eqe-temporal-exposure.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## calculateSensorEqeTemporalExposure
 
-Evaluate response validity and EQE independently at each declared shutter
-midpoint, then sum rates times seconds. This is quadrature, not a stationarity
-claim or convergence proof. Shared profile/geometry state prevents combining
-rates from different sites or shutter events. No renderer executes here.
+Runs the response checks and EQE conversion separately at each declared
+midpoint time, then sums rate × time step. This is numerical quadrature. It does
+not claim the light is constant or prove convergence. Shared profile and
+geometry stop rates from different sites or shutter events being mixed. No
+renderer runs here.
 
 ```ts
 export function calculateSensorEqeTemporalExposure(
@@ -19,17 +20,17 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## CalculateSensorEqeTemporalExposureInput
 
-Shared response/site/shutter state, with separately evaluated physical light at each time.
+Input: shared response, site and shutter settings, plus the light evaluated separately at each time.
 
 ```ts
 export interface CalculateSensorEqeTemporalExposureInput
   extends Omit<CalculateSensorEqeLocalExposureInput, "irradianceSamples" | "stationarityProfile"> {
-  /** Complete uniform-midpoint coverage; array order is not temporal identity. */
+  /** One sample for every uniform midpoint time. Array order does not define which time a sample is. */
   samples: readonly {
     temporalSampleIndex: number;
-    /** Seconds on the shutter's first-opening-boundary-phase reference. */
+    /** Seconds from the shutter's reference time (the first opening boundary). */
     timeSecondsFromOpeningReference: number;
-    /** Complete W/m²/nm Cartesian irradiance coverage for this instant. */
+    /** Irradiance in W/m²/nm at every spatial × spectral node, for this instant. */
     irradianceSamples: CalculateSensorEqeLocalExposureInput["irradianceSamples"];
   }[];
 }
@@ -37,7 +38,7 @@ export interface CalculateSensorEqeTemporalExposureInput
 
 ## SensorEqeTemporalExposure
 
-Nonstationary photo expectation, deliberately distinct from stationary RAW producer inputs.
+Expected photo signal with light that varies over time. Kept separate from the constant-rate inputs of the RAW producer.
 
 ```ts
 export interface SensorEqeTemporalExposure {
@@ -61,7 +62,7 @@ export interface SensorEqeTemporalExposure {
   physicalFullWellAssessmentAuthorized: false;
   shotNoiseApplied: false;
   rawCodeValueProduced: false;
-  /** Canonical order, seconds-valued integration measures and independent child evidence. */
+  /** Samples in canonical order, each with its time step in seconds and its own evidence. */
   samples: readonly {
     temporalSampleIndex: number;
     timeSecondsFromOpeningReference: number;

package/docs/api/sensor-exposure-window.md

@@ -1,25 +1,25 @@
 # sensor/exposure-window.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## calculateCaptureExposureWindows
 
-Resolves local capture exposure windows from independent opening and closing
-boundary schedules.
+Works out each point's local exposure window from separate opening and
+closing boundary schedules.
 
-The returned time basis is seconds from the first opening-boundary phase.
-This is intentionally not the existing camera-rotation API's global
-"exposure start" semantic; a later integration layer must bind those time
-bases explicitly.
+Times are seconds from the first opening boundary. This is deliberately not
+the camera-rotation API's global "exposure start"; a later layer must link the
+two explicitly.
 
-The mechanism identifies whether each boundary is mechanical or electronic,
-but does not supply any traversal duration or direction. Every non-simultaneous
-timing value and direction is caller-declared with evidence.
+The mechanism records whether each boundary is mechanical or electronic, but
+supplies no sweep duration or direction. Every timing value and direction for
+a non-simultaneous boundary is declared by the caller, with evidence.
 
-The first model supports simultaneous boundaries and uniform-linear
-single-axis native-sensor scans only. It does not model curtain acceleration,
-segmented/nonlinear electronic schedules, flash/flicker, rolling-shutter
-image distortion, shutter shock, or EFCS-specific pupil/bokeh behavior.
+Only simultaneous boundaries and a uniform linear sweep along one native
+sensor axis are supported. Not modelled: curtain acceleration, segmented or
+non-linear electronic schedules, flash or flicker, rolling-shutter image
+distortion, shutter shock, and EFCS (electronic first-curtain shutter)
+effects on the pupil or bokeh.
 
 ```ts
 export function calculateCaptureExposureWindows(
@@ -37,25 +37,25 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface CalculateCaptureExposureWindowsInput {
   nativeRaster: NativeImageRaster;
   /**
-   * Active capture rectangle in invariant native-raster coordinates.
+   * Active capture rectangle, in fixed native pixel coordinates.
    *
-   * Defaults to the complete native raster. Boundary traversal timing is never
-   * inferred by scaling a full-frame timing value to this rectangle.
+   * Defaults to the whole native image. Sweep timing is never worked out by
+   * scaling a full-frame timing value to this rectangle.
    */
   activeCaptureRect?: RasterRect;
   shutterMechanism: CaptureShutterMechanism;
   /**
-   * Nominal interval between the zero-phase opening and closing references.
+   * Nominal time between the opening and closing reference points (phase zero).
    *
-   * Local exposure duration may differ from this value when opening and closing
-   * boundary schedules have different spatial phase behavior.
+   * A point's local exposure can differ from this when the opening and closing
+   * boundaries sweep differently across the sensor.
    */
   nominalExposureDurationSeconds: SourcedCaptureTimingSeconds;
   opening: ExposureBoundarySchedule;
   closing: ExposureBoundarySchedule;
   /**
-   * Optional continuous native raster edge-coordinate points for diagnostics.
-   * Pixel centers may be represented with +0.5 offsets.
+   * Optional points, in continuous native pixel coordinates measured from pixel
+   * edges, to report windows for. A pixel centre is at +0.5.
    */
   samplePointsNative?: readonly RasterPoint[];
 }
@@ -100,11 +100,11 @@ export interface CaptureExposureWindowSample {
   openingNormalizedScanPosition: number | null;
   closingNormalizedScanPosition: number | null;
   /**
-   * Seconds from the first opening-boundary phase.
+   * Seconds from the first opening boundary.
    */
   startOffsetSecondsFromOpeningReference: number;
   /**
-   * Seconds from the first opening-boundary phase.
+   * Seconds from the first opening boundary.
    */
   endOffsetSecondsFromOpeningReference: number;
   localExposureDurationSeconds: number;