@photivra/engine 1.5.0 → 2.1.0

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

@@ -1,10 +1,10 @@
 # sensor/environment-photo-signal.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.
 
 ## 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.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.
 
 ## 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.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.
 
 ## 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.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.
 
 ## 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.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.
 
 ## 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;

package/docs/api/sensor-fixed-pattern-noise.md

@@ -0,0 +1,104 @@
+# sensor/fixed-pattern-noise.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.
+
+## calculateSensorFixedPatternSite
+
+Computes the fixed-pattern values of one absolute colour-sampling site.
+
+- PRNU gain g = max(0, 1 + σ_PRNU·z₁);
+- hot pixel when u < f_hot, then dark factor d = m_hot; otherwise d = max(0, 1 + σ_DSNU·z₂);
+- row offset σ_row·z(row y), column offset σ_col·z(column x), in input-referred electrons.
+
+Each z is a standard normal value and u a uniform value, each from its own stream hashed with
+MurmurHash3 from (sensorInstanceSeed, x, y, stream). Row values use x = 0 and column values y = 0,
+so a whole row or column shares one value. Cutting negative factors off at zero shifts the mean
+factor by less than 1e-6 for σ ≤ 0.2.
+
+```ts
+export function calculateSensorFixedPatternSite(input: {
+  profile: SensorFixedPatternNoiseProfile; site: { x: number; y: number };
+}): SensorFixedPatternSiteValues;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSensorFixedPatternNoiseProfile
+
+Validates an untrusted fixed-pattern noise profile. Unknown keys, out-of-range parameters and
+missing evidence are rejected. The PRNU and DSNU relative standard deviations are limited to 0.5
+and 5, and the hot-pixel multiplier to 1–1e6.
+
+```ts
+export function parseSensorFixedPatternNoiseProfile(value: unknown): SensorFixedPatternNoiseProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SENSOR_FIXED_PATTERN_NOISE_MODEL
+
+Versioned identity of the pattern-generation equations and seed schedule.
+
+```ts
+SENSOR_FIXED_PATTERN_NOISE_MODEL = Object.freeze({ id: "photivra-sensor-fixed-pattern", version: "1.0.0" } as const)
+```
+
+## SENSOR_FIXED_PATTERN_NOISE_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SENSOR_FIXED_PATTERN_NOISE_PROFILE_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## SensorFixedPatternNoiseProfile
+
+Explicit fixed-pattern parameters for one sensor instance. Every component is required; a zero
+standard deviation, fraction or RMS disables that component.
+
+```ts
+export interface SensorFixedPatternNoiseProfile {
+  schemaVersion: typeof SENSOR_FIXED_PATTERN_NOISE_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  /** The colour-sampling grid whose absolute site coordinates index the pattern. */
+  colorSamplingProfileId: string;
+  scientificStatus: "approximation";
+  /** Identifies the physical sensor. Independent of every per-capture noise seed. */
+  sensorInstanceSeedUint32: number;
+  /** EMVA 1288 PRNU: spatial standard deviation of the photo response divided by its mean. */
+  photoResponseNonUniformity: { relativeStandardDeviation: EvidenceBackedFact<number> };
+  /** Spatial standard deviation of the dark-current rate divided by the population-mean rate. */
+  darkSignalNonUniformity: { relativeStandardDeviation: EvidenceBackedFact<number> };
+  /** Fraction of sites whose dark-current rate is the population mean times the multiplier. */
+  hotPixels: { siteFraction: EvidenceBackedFact<number>; darkCurrentMultiplier: EvidenceBackedFact<number> };
+  /** Fixed readout offset per row, in input-referred electrons, normally distributed with zero mean. */
+  rowOffset: { rmsElectrons: EvidenceBackedFact<number> };
+  /** Fixed readout offset per column, in input-referred electrons, normally distributed with zero mean. */
+  columnOffset: { rmsElectrons: EvidenceBackedFact<number> };
+  patternDistribution: "normal-factors-truncated-at-zero";
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## SensorFixedPatternSiteValues
+
+The deterministic pattern values of one colour-sampling site.
+
+```ts
+export interface SensorFixedPatternSiteValues {
+  profileId: string;
+  modelId: typeof SENSOR_FIXED_PATTERN_NOISE_MODEL.id;
+  modelVersion: typeof SENSOR_FIXED_PATTERN_NOISE_MODEL.version;
+  site: { x: number; y: number };
+  /** Multiplies the expected photo charge (1 = no PRNU); never negative. */
+  photoResponseGainFactor: number;
+  /** Multiplies the population-mean dark expectation (1 = no DSNU); never negative. */
+  darkCurrentFactor: number;
+  hotPixel: boolean;
+  rowOffsetElectrons: number;
+  columnOffsetElectrons: number;
+  /** rowOffsetElectrons + columnOffsetElectrons, added at readout. */
+  readoutOffsetElectrons: number;
+}
+```

package/docs/api/sensor-iso-gain.md

@@ -0,0 +1,63 @@
+# sensor/iso-gain.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.
+
+## createIsoGainReadoutRegimes
+
+Builds a readout regime and signal-chain band for each exposure index (see the module comment
+for the equations). The result is checked with the same rules as parseSensorReadoutConversionProfile.
+Each regime carries an `exposureIndexGain` record of how it was derived.
+
+```ts
+export function createIsoGainReadoutRegimes(input: CreateIsoGainReadoutRegimesInput): IsoGainReadoutRegimes;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateIsoGainReadoutRegimesInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateIsoGainReadoutRegimesInput {
+  regimeIdPrefix: string;
+  scientificStatus: SensorSpectralResponseScientificStatus;
+  baseExposureIndex: number;
+  /** Strictly increasing settings, each at least the base exposure index. */
+  exposureIndices: readonly number[];
+  /** Q0: electron-equivalent signal that reaches digital saturation at the base exposure index. */
+  baseSaturationElectronEquivalent: EvidenceBackedFact<number>;
+  /** A_max: largest analog gain relative to the base regime (>= 1). */
+  maximumAnalogGain: EvidenceBackedFact<number>;
+  adc: { bitDepth: number; blackLevelCode: number; digitalSaturationCode: number };
+  conversionGainModes: readonly IsoGainConversionGainMode[];
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## IsoGainConversionGainMode
+
+One conversion-gain mode, active from its minimum exposure index up to the next mode's.
+
+```ts
+export interface IsoGainConversionGainMode {
+  mode: SensorReadoutExposureIndexGain["conversionGainMode"];
+  minimumExposureIndex: number;
+  readNoiseRmsElectrons: EvidenceBackedFact<number>;
+  /** Optional charge storage limit of this mode. Every regime's pre-ADC threshold must be at or below it. */
+  maximumChargeElectrons?: EvidenceBackedFact<number>;
+}
+```
+
+## IsoGainReadoutRegimes
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IsoGainReadoutRegimes {
+  regimes: readonly SensorReadoutConversionRegime[];
+  /** One single-value band per setting, ready for a GenericIsoSignalChainProfile. */
+  standardRegimeBands: readonly GenericIsoStandardRegimeBand[];
+}
+```

package/docs/api/sensor-iso-signal-chain.md

@@ -1,6 +1,6 @@
 # sensor/iso-signal-chain.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.
 
 ## GENERIC_ISO_SIGNAL_CHAIN_PRESET_CATALOG_SCHEMA_VERSION
 
@@ -128,12 +128,10 @@ export interface GenericIsoStandardRegimeBand {
 
 ## parseGenericIsoSignalChainPresetCatalog
 
-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.
 
-The selected ISO/capture-mode state binds an explicit generic readout regime. Photons and photo/dark
-shot-noise expectations remain upstream; regime gain, read noise and clipping are separately
-declared. Generic tier labels do not calibrate or rank commercial equipment.
+Generic tier labels in the catalogue do not calibrate or rank real cameras.
 
 ```ts
 export function parseGenericIsoSignalChainPresetCatalog(
@@ -145,12 +143,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseGenericIsoSignalChainProfile
 
-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.
 
-The selected ISO/capture-mode state binds an explicit generic readout regime. Photons and photo/dark
-shot-noise expectations remain upstream; regime gain, read noise and clipping are separately
-declared. Generic tier labels do not calibrate or rank commercial equipment.
+The profile binds each ISO and capture-mode state to an explicit readout regime, whose gain,
+read noise and clipping are declared separately.
 
 ```ts
 export function parseGenericIsoSignalChainProfile(
@@ -198,12 +195,8 @@ export interface ResolvedGenericIsoSignalChain {
 
 ## resolveGenericIsoSignalChain
 
-Select the explicit readout regime bound to the resolved ISO and capture-mode state; do not derive
-gain/noise from an ISO number.
-
-The selected ISO/capture-mode state binds an explicit generic readout regime. Photons and photo/dark
-shot-noise expectations remain upstream; regime gain, read noise and clipping are separately
-declared. Generic tier labels do not calibrate or rank commercial equipment.
+Picks the explicit readout regime bound to the resolved ISO and capture-mode state. Gain and noise
+are never derived from the ISO number.
 
 ```ts
 export function resolveGenericIsoSignalChain(
@@ -234,12 +227,10 @@ export interface ResolveGenericIsoSignalChainInput {
 
 ## resolveGenericIsoSignalChainPreset
 
-Select a generic catalog preset and return its explicit profile binding without claiming
-manufacturer calibration.
+Picks a generic preset from the catalogue and returns the signal-chain profile it uses. It makes
+no claim of manufacturer calibration.
 
-The selected ISO/capture-mode state binds an explicit generic readout regime. Photons and photo/dark
-shot-noise expectations remain upstream; regime gain, read noise and clipping are separately
-declared. Generic tier labels do not calibrate or rank commercial equipment.
+Generic tier labels do not calibrate or rank real cameras.
 
 ```ts
 export function resolveGenericIsoSignalChainPreset(

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

@@ -1,21 +1,20 @@
 # sensor/local-exposure-binding.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.
 
 ## bindSensorRateToLocalExposure
 
-Binds one engine-produced sensor response-rate result to the local exposure
-window at the same color-sampling site.
+Links one engine-made sensor response-rate result to the local exposure
+window of the same colour-sampling site.
 
-This first temporal binding supports only the explicit one-to-one
-native-effective-sample ↔ color-site relationship. A multi-site block
-binding proves contributor membership but does not prove each color site's
-sub-sample timing coordinate, so spatially varying shutter timing fails
-closed rather than inventing fractional positions.
+Only a one-to-one link between native image samples and colour sites is
+supported. A block binding shows which sites contribute, but not each site's
+timing position within the sample. So shutter timing that varies across the
+sensor is rejected rather than guessing fractional positions.
 
-The result establishes timing only. It deliberately does not establish that
-the optical/electrical rate is stationary through the local exposure window,
-so rate×duration integration remains unauthorized.
+The result fixes timing only. It does not establish that the optical or
+electrical rate is constant through the window, so it does not by itself
+allow rate × duration integration.
 
 ```ts
 export function bindSensorRateToLocalExposure(
@@ -39,8 +38,8 @@ export interface BindSensorRateToLocalExposureInput {
   bindingProfile:
     NativeEffectiveRasterColorSamplingBindingProfile;
   /**
-   * One capture/exposure event. samplePointsNative is owned by this binding
-   * function and therefore intentionally excluded.
+   * One capture (exposure) event. samplePointsNative is left out on purpose,
+   * because this function sets it.
    */
   exposureWindowInput:
     Omit<