@photivra/engine 1.5.0 → 2.1.0

package/docs/api/sensor-optical-stack.md

@@ -1,6 +1,6 @@
 # sensor/optical-stack.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.
 
 ## AntiAliasingPointSplitComponent
 
@@ -9,16 +9,16 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface AntiAliasingPointSplitComponent {
   /**
-   * Native sensor physical offset from the nominal landing point.
-   * +X right, +Y down. Units: micrometres.
+   * Physical offset on the native sensor from where the light would otherwise
+   * land. +X right, +Y down. Units: micrometres.
    */
   offsetMicrometers: {
     x: number;
     y: number;
   };
   /**
-   * Dimensionless normalized spatial weight. Point-splitting kernels describe
-   * spatial redistribution only; total stack throughput is outside this field.
+   * Normalized weight (dimensionless). A point-splitting kernel only describes
+   * where the light goes; the stack's total throughput is not part of it.
    */
   normalizedWeight: number;
 }
@@ -26,18 +26,17 @@ export interface AntiAliasingPointSplitComponent {
 
 ## parseSensorOpticalStackProfile
 
-Parses descriptive sensor optical-stack metadata plus an optional explicitly
-declared effective anti-aliasing spatial response.
+Parses descriptive sensor optical-stack metadata, plus an optional explicitly
+declared anti-aliasing (AA) spatial response.
 
-Unknown facts are omitted instead of inferred. Physical component presence
-is intentionally separate from effective anti-aliasing response so the
-schema can represent cancellation/neutralization designs without claiming
-the physical assembly is absent.
+Leave out unknown facts rather than guessing them. Physical presence of a
+component is separate from the net AA response, so the schema can describe
+designs that cancel the AA effect without claiming the hardware is missing.
 
-Cover/filter-stack and microlens presence do not create optical effects in
-schema 0.1.0. Thickness, refractive index, spectral transmission, angular
-acceptance, focus shift and microlens collection behavior require later
-explicit models/calibration.
+In schema 0.1.0, cover glass, filters and microlenses create no optical
+effect. Thickness, refractive index, spectral transmission, angle of
+acceptance, focus shift and microlens collection need later explicit models
+or calibration.
 
 ```ts
 export function parseSensorOpticalStackProfile(
@@ -49,15 +48,15 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## resolveAntiAliasingSpatialKernel
 
-Resolves only the effective anti-aliasing spatial kernel.
+Resolves only the anti-aliasing (AA) spatial kernel.
 
-This is not a whole optical-stack PSF. Cover/filter transmission, refraction,
-microlens behavior, field/wavelength/polarization dependence, and total
-throughput remain excluded.
+This is not the PSF (point-spread function) of the whole optical stack. Cover
+glass and filter transmission, refraction, microlens behaviour, dependence on
+field position, wavelength or polarization, and total throughput are excluded.
 
-A documented absent effective anti-aliasing response resolves to an identity
-component at zero offset. An unknown response (field omitted) or a
-present-but-unresolved response fails closed.
+A documented absent AA response gives a single component with weight 1 at zero
+offset (no blur). An unknown response (field omitted) or one that is present
+but unspecified is rejected.
 
 ```ts
 export function resolveAntiAliasingSpatialKernel(
@@ -103,25 +102,24 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export type SensorEffectiveAntiAliasingSpatialResponse =
   | {
       /**
-       * Documented absence/cancellation of intentional anti-aliasing spatial
-       * splitting. This does not mean the whole sensor stack is optically
-       * identity.
+       * Documented absence (or cancellation) of deliberate AA splitting. It does
+       * not mean the rest of the sensor stack has no optical effect.
        */
       kind: "absent";
       evidence: readonly EvidenceProvenance[];
     }
   | {
       /**
-       * An effective anti-aliasing response is known to exist, but its spatial
-       * response is not defensibly specified.
+       * An AA effect is known to exist, but its spatial response is not
+       * specified well enough to use.
        */
       kind: "present-unresolved";
       evidence: readonly EvidenceProvenance[];
     }
   | {
       /**
-       * Generic normalized point-splitting approximation in native sensor
-       * physical coordinates.
+       * Generic approximation: each point is split into weighted copies at
+       * offsets in native sensor physical coordinates.
        */
       kind: "normalized-point-splitting-kernel";
       evidence: readonly EvidenceProvenance[];
@@ -141,8 +139,8 @@ export interface SensorMicrolensDeclaration {
   presence: "present" | "absent";
   evidence: readonly EvidenceProvenance[];
   /**
-   * Presence alone does not establish an angular, spectral, fill-factor, or
-   * collection-efficiency model.
+   * Being present does not establish any model of angle, spectrum, fill factor
+   * or collection efficiency.
    */
   opticalEffectModel: "unresolved";
 }
@@ -156,8 +154,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface SensorOpticalStackComponent {
   componentId: string;
   /**
-   * Roles may be combined because one physical element can provide multiple
-   * optical/filter functions.
+   * A component can have several roles, because one physical element can do
+   * more than one optical or filtering job.
    */
   roles: readonly SensorOpticalStackComponentRole[];
   evidence: readonly EvidenceProvenance[];
@@ -189,22 +187,21 @@ export interface SensorOpticalStackProfile {
   profileId: string;
   evidence: readonly EvidenceProvenance[];
   /**
-   * Ordered from incident-light side toward the sensor.
+   * In order from the side light enters towards the sensor.
    *
    * These components are descriptive metadata only. Their presence does not
-   * create transmission, focus-shift, aberration, or spectral effects.
+   * create transmission, focus-shift, aberration or spectral effects.
    */
   orderedComponents?: readonly SensorOpticalStackComponent[];
   /**
-   * Omitted means unknown/unasserted.
+   * Omitted means "unknown, not stated".
    *
-   * This is intentionally separate from physical component presence so a
-   * stack can contain low-pass-related hardware while its net effective
-   * anti-aliasing response is absent/cancelled.
+   * This is separate from which components are present, so a stack can
+   * contain low-pass hardware while its net AA effect is absent or cancelled.
    */
   effectiveAntiAliasingSpatialResponse?: SensorEffectiveAntiAliasingSpatialResponse;
   /**
-   * Omitted means unknown/unasserted.
+   * Omitted means "unknown, not stated".
    */
   microlens?: SensorMicrolensDeclaration;
 }

package/docs/api/sensor-photon-energy.md

@@ -1,6 +1,6 @@
 # sensor/photon-energy.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.
 
 ## AirRefractiveIndexConditionPolicy
 
@@ -33,12 +33,12 @@ export interface AirRefractiveIndexReferenceConditions {
 
 ## calculatePhotonEnergyFromWavelength
 
-Convert a valid vacuum wavelength, or explicitly atmosphere-bound air wavelength, into optical
-frequency and photon energy using exact SI constants.
+Converts a vacuum wavelength, or an air wavelength with its stated atmosphere, into optical
+frequency and photon energy using the exact SI constants h and c.
 
-Photon energy uses exact SI h and c with vacuum wavelength. Air wavelength requires an
-exact-wavelength sourced phase index and atmosphere compatibility; lambdaVacuum = n*lambdaAir.
-Retained refractive-index uncertainty is not an automatically propagated photon-energy uncertainty.
+An air wavelength needs a sourced phase refractive index for that exact wavelength and matching
+atmosphere; λ_vacuum = n·λ_air. The index's uncertainty is kept but not automatically carried
+through to the photon energy.
 
 ```ts
 export function calculatePhotonEnergyFromWavelength(
@@ -69,12 +69,11 @@ export interface CalculatePhotonEnergyFromWavelengthInput {
 
 ## parseSourcedAirPhaseRefractiveIndex
 
-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.
 
-Photon energy uses exact SI h and c with vacuum wavelength. Air wavelength requires an
-exact-wavelength sourced phase index and atmosphere compatibility; lambdaVacuum = n*lambdaAir.
-Retained refractive-index uncertainty is not an automatically propagated photon-energy uncertainty.
+The index is the phase refractive index n of air at one exact wavelength, from a cited source, for
+stated atmospheric conditions. It converts air to vacuum wavelength: λ_vacuum = n·λ_air.
 
 ```ts
 export function parseSourcedAirPhaseRefractiveIndex(

package/docs/api/sensor-physical-charge-capacity.md

@@ -1,16 +1,13 @@
 # sensor/physical-charge-capacity.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.
 
 ## assessSensorPhysicalChargeCapacity
 
-Compare complete expected stored electrons to the explicitly applicable physical capacity and report
-expectation-domain headroom without nonlinear storage simulation.
+Compares the complete expected stored electrons with the physical capacity that applies, and
+reports the remaining headroom in expected electrons. Non-linear storage is not simulated.
 
-Physical storage capacity is a source-specific total stored-electron limit tied to site, operating
-state and temperature. The assessment compares complete expected charge; it does not clamp
-realizations or infer overflow/blooming. Camera saturation and ADC/readout thresholds remain
-distinct.
+It does not clip random realizations and does not model overflow or blooming.
 
 ```ts
 export function assessSensorPhysicalChargeCapacity(
@@ -38,13 +35,11 @@ export interface AssessSensorPhysicalChargeCapacityInput {
 
 ## parseSensorPhysicalChargeCapacityProfile
 
-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.
 
-Physical storage capacity is a source-specific total stored-electron limit tied to site, operating
-state and temperature. The assessment compares complete expected charge; it does not clamp
-realizations or infer overflow/blooming. Camera saturation and ADC/readout thresholds remain
-distinct.
+The capacity is a total stored-electron limit from a specific source, tied to a site, operating
+state and temperature. Camera saturation capacity and ADC or readout thresholds are separate.
 
 ```ts
 export function parseSensorPhysicalChargeCapacityProfile(

package/docs/api/sensor-pixel-pitch.md

@@ -1,6 +1,6 @@
 # sensor/pixel-pitch.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.
 
 ## calculatePixelPitch
 

package/docs/api/sensor-radiometry-readiness.md

@@ -1,13 +1,13 @@
 # sensor/radiometry-readiness.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.
 
 ## assessRadiometryReadiness
 
-Assesses whether the declared prerequisites are sufficient for a nominal
-photon estimate and, separately, for a calibrated photon claim.
+Checks whether the declared prerequisites are enough for a nominal photon
+estimate and, separately, for a calibrated photon claim.
 
-This assessment does not enable composed photon/noise output.
+It does not switch on composed photon or noise output.
 
 ```ts
 export function assessRadiometryReadiness(
@@ -65,10 +65,10 @@ export type OpticalTransmissionRequirement =
 
 ## parseRadiometryReadinessProfile
 
-Parses untrusted radiometry-prerequisite metadata.
+Parses untrusted metadata about radiometry prerequisites.
 
-This validates structure and provenance; it cannot prove that a cited
-calibration/evidence claim is scientifically true.
+It checks structure and provenance. It cannot prove that a cited calibration
+or evidence claim is scientifically true.
 
 ```ts
 export function parseRadiometryReadinessProfile(
@@ -127,8 +127,8 @@ export interface RadiometryReadinessAssessment {
   approximateRequirements: readonly RadiometryRequirementId[];
   unquantifiedUncertaintyRequirements: readonly RadiometryRequirementId[];
   /**
-   * This assessment never enables composed photon/noise output by itself.
-   * Integration remains an explicit later product/engine decision.
+   * Always false: this assessment never switches on composed photon or noise
+   * output by itself. Doing so is a separate, explicit later decision.
    */
   composedPhotonOutputEnabled: false;
 }

package/docs/api/sensor-raw-readout.md

@@ -1,17 +1,11 @@
 # sensor/raw-readout.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.
 
 ## calculateExpectedSensorReadout
 
-Map expected charge through declared gain/offset/readout limits without stochastic sampling and
-retain separate clipping domains.
-
-Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
-noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
-limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
-pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
-regime.
+Maps the expected charge through the declared gain, offset and readout limits, with no random
+sampling. Each kind of clipping (physical storage, pre-ADC, digital) is reported separately.
 
 ```ts
 export function calculateExpectedSensorReadout(
@@ -40,14 +34,10 @@ export interface CalculateExpectedSensorReadoutInput {
 
 ## parseSensorChargeSamplingProfile
 
-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.
 
-Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
-noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
-limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
-pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
-regime.
+The profile sets how expected charge is sampled into random photo and dark counts.
 
 ```ts
 export function parseSensorChargeSamplingProfile(
@@ -59,14 +49,10 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSensorReadoutConversionProfile
 
-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.
 
-Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
-noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
-limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
-pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
-regime.
+The profile lists the declared conversion regimes. ISO never invents a regime.
 
 ```ts
 export function parseSensorReadoutConversionProfile(
@@ -97,14 +83,8 @@ export interface ResolvedSensorReadoutRegime {
 
 ## resolveSensorReadoutRegime
 
-Select and validate a declared readout regime against exact channel/profile identity rather than
-inferring it from ISO.
-
-Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
-noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
-limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
-pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
-regime.
+Selects a declared readout regime and checks it against the exact channel and profile identity.
+The regime is never inferred from ISO.
 
 ```ts
 export function resolveSensorReadoutRegime(
@@ -145,6 +125,20 @@ SENSOR_READOUT_CONVERSION_PROFILE_SCHEMA_VERSION =
   "0.1.0" as const
 ```
 
+## SensorAdcIntegralNonLinearity
+
+Optional ADC integral non-linearity (INL): an offset in code units (LSB, least significant bit),
+piecewise linear in the ideal continuous ADC input code, added before quantization. The points must
+start at code 0 and end at the ADC maximum code. If omitted, the ADC is ideal and uniform.
+
+```ts
+export interface SensorAdcIntegralNonLinearity {
+  kind: "piecewise-linear-code-offset";
+  knots: readonly { code: number; offsetCodes: number }[];
+  evidence: readonly EvidenceProvenance[];
+}
+```
+
 ## SensorAdditionalChargeSamplingModel
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -187,6 +181,17 @@ export interface SensorChargeRealization {
   photoRealizedElectronCount: number;
   darkExpectedElectronCount: number;
   darkRealizedElectronCount: number;
+  /** Fixed-pattern profile applied to this realization, or null for the uniform population model. */
+  fixedPatternNoiseProfileId:
+    string | null;
+  /** PRNU gain applied to the photo expectation (exactly 1 without a fixed pattern). */
+  photoResponseGainFactor: number;
+  /** DSNU/hot-pixel factor applied to the dark expectation (exactly 1 without a fixed pattern). */
+  darkCurrentFactor: number;
+  hotPixel: boolean;
+  /** Poisson means actually sampled: expectation × the site's fixed-pattern factor. */
+  photoSampledMeanElectronCount: number;
+  darkSampledMeanElectronCount: number;
   additionalComponents:
     readonly {
       componentId: string;
@@ -280,8 +285,15 @@ export interface SensorExpectedReadoutSignal {
   expectedCodeBeforeBlackOffset:
     number;
   blackLevelCode: number;
+  /** Continuous ADC input code including any declared INL offset. */
   expectedCodeBeforeQuantization:
     number;
+  adcIntegralNonLinearityOffsetCodes:
+    number;
+  digitalGain: number;
+  /** Continuous code after post-ADC digital gain about black (equals the ADC input without one). */
+  expectedCodeAfterDigitalGain:
+    number;
   adcBitDepth: number;
   adcMaximumCode: number;
   digitalSaturationCode: number;
@@ -337,11 +349,17 @@ export interface SensorRawCodeSample {
     }[];
   totalElectronicReadNoiseElectrons:
     number;
+  /** Fixed-pattern profile applied at readout, or null. */
+  fixedPatternNoiseProfileId:
+    string | null;
+  /** Static fixed-pattern row + column offset in input-referred electrons (0 without a pattern). */
+  fixedPatternReadoutOffsetElectrons:
+    number;
   electronEquivalentAfterReadNoise:
     number;
   preAdcSaturationElectronEquivalent:
     number;
-  /** Signed electronic signal after upper saturation, before conversion/pedestal. */
+  /** Signed electronic signal after the upper (pre-ADC) clip, before conversion and the black pedestal. */
   electronEquivalentAfterPreAdcSaturation:
     number;
   preAdcSaturationApplied:
@@ -349,8 +367,17 @@ export interface SensorRawCodeSample {
   systemConversionGainElectronsPerCode:
     number;
   blackLevelCode: number;
+  /** Continuous ADC input code including any declared integral non-linearity offset. */
   codeBeforeQuantization:
     number;
+  /** INL offset added before quantization (0 for an ideal ADC). */
+  adcIntegralNonLinearityOffsetCodes:
+    number;
+  /** ADC output after quantization and the ADC code-range limit, before digital gain. */
+  adcCodeBeforeDigitalGain:
+    number;
+  /** Post-ADC digital gain (1 when the regime declares none). */
+  digitalGain: number;
   quantizedCodeBeforeDigitalClamp:
     number;
   adcBitDepth: number;
@@ -397,11 +424,12 @@ export interface SensorReadoutConversionProfile {
 
 ## SensorReadoutConversionRegime
 
-One explicitly selected electronic conversion regime, with sourced electrons
-per code, upper pre-ADC electron-equivalent threshold, independent RMS-electron
-read-noise components and unsigned ADC coding policy. Black pedestal and digital
-saturation are code-domain quantities. The regime does not infer its hardware
-mechanism or selection from ISO and does not replace physical storage capacity.
+One explicitly selected electronic conversion regime. It has a sourced number of
+electrons per code, an upper pre-ADC threshold in electron equivalents, separate
+read-noise components (RMS electrons) and an unsigned ADC coding policy. The black
+pedestal and digital saturation are in code units. The regime does not guess its
+hardware mechanism, is not chosen from ISO automatically, and does not replace
+physical storage capacity.
 
 ```ts
 export interface SensorReadoutConversionRegime {
@@ -420,23 +448,52 @@ export interface SensorReadoutConversionRegime {
     digitalSaturationCode: number;
     transfer:
       "uniform-round-half-up";
+    /**
+     * Optional post-ADC digital gain (>= 1) applied about the black level:
+     * code = roundHalfUp((adcCode - black) * digitalGain + black). Omission means 1.
+     */
+    digitalGain?: number;
+    integralNonLinearity?:
+      SensorAdcIntegralNonLinearity;
   };
+  exposureIndexGain?:
+    SensorReadoutExposureIndexGain;
   evidence:
     readonly EvidenceProvenance[];
   limitations: readonly string[];
 }
 ```
 
+## SensorReadoutExposureIndexGain
+
+Optional record of how one regime's ISO gain was derived (the exposure index of CIPA DC-004,
+relative to the base exposure index). The readout equations still use
+systemConversionGainElectronsPerCode (analog, before the ADC) and adc.digitalGain (after the ADC).
+This record must agree with them and never replaces them.
+
+```ts
+export interface SensorReadoutExposureIndexGain {
+  exposureIndex: number;
+  baseExposureIndex: number;
+  /** Analog (pre-ADC) gain relative to the base-exposure-index regime. */
+  analogGain: number;
+  /** Post-ADC digital gain; equals adc.digitalGain (1 when omitted). */
+  digitalGain: number;
+  conversionGainMode:
+    | "single-conversion-gain"
+    | "low-conversion-gain"
+    | "high-conversion-gain";
+  evidence: readonly EvidenceProvenance[];
+}
+```
+
 ## simulateSensorChargeRealization
 
-Draw deterministic independently seeded photo/dark Poisson counts and explicit additional-component
-policies from expected accumulated charge.
+Draws deterministic, separately seeded Poisson counts for photo and dark charge, and applies the
+declared policies for additional components, starting from the expected accumulated charge.
 
-Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
-noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
-limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
-pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
-regime.
+This is steps 1–2 of the readout order (see the module notes). Physical storage saturation is
+reported separately from later clipping.
 
 ```ts
 export function simulateSensorChargeRealization(
@@ -458,19 +515,22 @@ export interface SimulateSensorChargeRealizationInput {
   samplingProfile:
     SensorChargeSamplingProfile;
   seedUint32: number;
+  /**
+   * Optional fixed-pattern noise for this sensor. PRNU (photo-response non-uniformity) scales the
+   * photo Poisson mean; DSNU (dark-signal non-uniformity) and hot pixels scale the dark Poisson mean.
+   * If omitted, the result is exactly the uniform population model.
+   */
+  fixedPatternNoise?:
+    SensorFixedPatternNoiseProfile;
 }
 ```
 
 ## simulateSensorRawCode
 
-Use the declared seed/regime to preserve signed electronic noise through pedestal and quantization,
-then return the bounded native ADC code and stage diagnostics.
-
-Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
-noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
-limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
-pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
-regime.
+Simulates one RAW code from a charge realization with the declared seed and regime: steps 3–7 of
+the readout order (see the module notes). Signed read noise is kept through the black pedestal and
+quantization, and only the final code is clamped. Returns the bounded native ADC code and per-step
+diagnostics.
 
 ```ts
 export function simulateSensorRawCode(
@@ -495,5 +555,11 @@ export interface SimulateSensorRawCodeInput {
     SensorReadoutConversionProfile;
   regimeId: string;
   readNoiseSeedUint32: number;
+  /**
+   * Optional fixed pattern; must be the same profile used for the charge realization. Its static
+   * row/column offsets are added with read noise before the pre-ADC threshold.
+   */
+  fixedPatternNoise?:
+    SensorFixedPatternNoiseProfile;
 }
 ```