@photivra/engine 1.5.0 → 2.0.0

package/dist/sensor/raw-readout.js

@@ -1,18 +1,20 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary. 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.
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary. 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.
+ * RAW readout: turns the expected charge in a sensor site into a RAW code, with shot noise, read
+ * noise and the ADC (analogue-to-digital converter).
+ *
+ * The steps, in order:
+ * 1. expected charge;
+ * 2. separately seeded random photo and dark draws (Poisson shot noise);
+ * 3. signed electronic read noise;
+ * 4. the upper pre-ADC clipping threshold;
+ * 5. the black pedestal (offset);
+ * 6. ADC quantization, rounding to nearest with ties up;
+ * 7. limits on the unsigned code.
+ *
+ * Values below black stay signed until the final code clamp. Physical storage saturation, pre-ADC
+ * clipping and digital clipping are reported separately. The ISO setting never invents a conversion
+ * regime; regimes are declared.
  * @see docs/SENSOR_RAW_PRODUCER.md for equations, coordinate/unit conventions, blockers and support
  * limits.
  */
@@ -20,14 +22,19 @@ import { approximationResult } from "../core/calculation-result.js";
 import { InvalidConfigurationError } from "../core/configuration-error.js";
 import { parseEvidenceList } from "../core/evidence-provenance.js";
 import { InvalidScientificInputError } from "../core/validation.js";
+import { createDeterministicUniformStream, sampleDeterministicStandardNormal } from "./stochastic-seed.js";
+import { requireInputKeys, rejectUnknownFields } from "../core/record-validation.js";
+import { evaluateParsedFixedPatternSite, parseSensorFixedPatternNoiseProfile } from "./fixed-pattern-noise.js";
 export const SENSOR_CHARGE_SAMPLING_PROFILE_SCHEMA_VERSION = "0.1.0";
 export const SENSOR_READOUT_CONVERSION_PROFILE_SCHEMA_VERSION = "0.1.0";
-function requireRecord(value, path) {
+function requireRecord(value, path, allowedKeys) {
     if (typeof value !== "object" ||
         value === null ||
         Array.isArray(value)) {
         throw new InvalidConfigurationError(path + " must be an object.");
     }
+    if (allowedKeys !== null)
+        rejectUnknownFields(value, allowedKeys, path);
     return value;
 }
 function requireNonEmptyString(value, path) {
@@ -93,35 +100,31 @@ function parseLimitations(value, path) {
     return parsed;
 }
 function parsePositiveFact(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, ["value", "evidence"]);
     return {
         value: requirePositiveFinite(record.value, path + ".value"),
         evidence: parseEvidenceList(record.evidence, path + ".evidence")
     };
 }
 function parseNonNegativeFact(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, ["value", "evidence"]);
     return {
         value: requireNonNegativeFinite(record.value, path + ".value"),
         evidence: parseEvidenceList(record.evidence, path + ".evidence")
     };
 }
 /**
- * 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.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns SensorChargeSamplingProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The profile sets how expected charge is sampled into random photo and dark counts.
+ * @param value - Untrusted data. TypeScript types alone are not validation.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export function parseSensorChargeSamplingProfile(value) {
-    const record = requireRecord(value, "sensorChargeSamplingProfile");
+    const record = requireRecord(value, "sensorChargeSamplingProfile", ["schemaVersion", "scientificStatus", "photoShotNoiseModel", "darkShotNoiseModel", "additionalComponentPolicies", "profileId", "completenessProfileId", "evidence", "limitations"]);
     if (record.schemaVersion !==
         SENSOR_CHARGE_SAMPLING_PROFILE_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('sensorChargeSamplingProfile.schemaVersion must be "' +
@@ -145,7 +148,7 @@ export function parseSensorChargeSamplingProfile(value) {
         const path = "sensorChargeSamplingProfile.additionalComponentPolicies[" +
             index +
             "]";
-        const policy = requireRecord(entry, path);
+        const policy = requireRecord(entry, path, ["model", "componentId"]);
         if (policy.model !==
             "poisson" &&
             policy.model !==
@@ -184,16 +187,85 @@ function parseStatus(value, path) {
     return value;
 }
 function parseReadNoiseComponent(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, ["componentId", "rmsElectrons", "evidence"]);
     return {
         componentId: requireNonEmptyString(record.componentId, path + ".componentId"),
         rmsElectrons: parseNonNegativeFact(record.rmsElectrons, path + ".rmsElectrons"),
         evidence: parseEvidenceList(record.evidence, path + ".evidence")
     };
 }
+function parseIntegralNonLinearity(value, path, adcMaximumCode) {
+    const record = requireRecord(value, path, ["kind", "knots", "evidence"]);
+    if (record.kind !==
+        "piecewise-linear-code-offset") {
+        throw new InvalidConfigurationError(path +
+            '.kind must be "piecewise-linear-code-offset".');
+    }
+    if (!Array.isArray(record.knots) ||
+        record.knots.length < 2 ||
+        record.knots.length > 4096) {
+        throw new InvalidConfigurationError(path +
+            ".knots must contain 2 through 4096 knots.");
+    }
+    const knots = record.knots.map((entry, index) => {
+        const knot = requireRecord(entry, path + ".knots[" + index + "]", ["code", "offsetCodes"]);
+        return {
+            code: requireFinite(knot.code, path + ".knots[" + index + "].code"),
+            offsetCodes: requireFinite(knot.offsetCodes, path + ".knots[" + index + "].offsetCodes")
+        };
+    });
+    if (knots[0].code !== 0 ||
+        knots[knots.length - 1].code !==
+            adcMaximumCode ||
+        knots.some((knot, index) => index > 0 &&
+            knot.code <=
+                knots[index - 1].code) ||
+        knots.some((knot) => Math.abs(knot.offsetCodes) >
+            adcMaximumCode)) {
+        throw new InvalidConfigurationError(path +
+            ".knots must strictly increase from code 0 to the ADC maximum code with bounded offsets.");
+    }
+    return {
+        kind: "piecewise-linear-code-offset",
+        knots,
+        evidence: parseEvidenceList(record.evidence, path + ".evidence")
+    };
+}
+function parseExposureIndexGain(value, path, adcDigitalGain) {
+    const record = requireRecord(value, path, ["exposureIndex", "baseExposureIndex", "analogGain", "digitalGain", "conversionGainMode", "evidence"]);
+    const exposureIndex = requirePositiveFinite(record.exposureIndex, path + ".exposureIndex");
+    const baseExposureIndex = requirePositiveFinite(record.baseExposureIndex, path + ".baseExposureIndex");
+    const analogGain = requirePositiveFinite(record.analogGain, path + ".analogGain");
+    const digitalGain = requirePositiveFinite(record.digitalGain, path + ".digitalGain");
+    const mode = record.conversionGainMode;
+    if (mode !== "single-conversion-gain" &&
+        mode !== "low-conversion-gain" &&
+        mode !== "high-conversion-gain") {
+        throw new InvalidConfigurationError(path +
+            ".conversionGainMode is invalid.");
+    }
+    const ratio = exposureIndex /
+        baseExposureIndex;
+    if (digitalGain !==
+        adcDigitalGain ||
+        Math.abs(analogGain * digitalGain -
+            ratio) >
+            1e-12 * ratio) {
+        throw new InvalidConfigurationError(path +
+            " must satisfy analogGain x digitalGain = exposureIndex / baseExposureIndex and digitalGain = adc.digitalGain.");
+    }
+    return {
+        exposureIndex,
+        baseExposureIndex,
+        analogGain,
+        digitalGain,
+        conversionGainMode: mode,
+        evidence: parseEvidenceList(record.evidence, path + ".evidence")
+    };
+}
 function parseRegime(value, path) {
-    const record = requireRecord(value, path);
-    const adc = requireRecord(record.adc, path + ".adc");
+    const record = requireRecord(value, path, ["adc", "readNoiseComponents", "systemConversionGainElectronsPerCode", "exposureIndexGain", "regimeId", "scientificStatus", "preAdcSaturationElectronEquivalent", "evidence", "limitations"]);
+    const adc = requireRecord(record.adc, path + ".adc", ["bitDepth", "blackLevelCode", "digitalSaturationCode", "transfer", "digitalGain", "integralNonLinearity"]);
     const bitDepth = requireSafeInteger(adc.bitDepth, path + ".adc.bitDepth");
     if (bitDepth < 1 ||
         bitDepth > 30) {
@@ -236,13 +308,29 @@ function parseRegime(value, path) {
         throw new InvalidConfigurationError(path +
             ".readNoiseComponents must not contain duplicate componentId values.");
     }
+    const digitalGain = adc.digitalGain === undefined
+        ? undefined
+        : requireFinite(adc.digitalGain, path + ".adc.digitalGain");
+    if (digitalGain !== undefined &&
+        (digitalGain < 1 ||
+            digitalGain > 65536)) {
+        throw new InvalidConfigurationError(path +
+            ".adc.digitalGain must be from 1 through 65536.");
+    }
+    const integralNonLinearity = adc.integralNonLinearity === undefined
+        ? undefined
+        : parseIntegralNonLinearity(adc.integralNonLinearity, path + ".adc.integralNonLinearity", adcMaximumCode);
+    const systemConversionGainElectronsPerCode = parsePositiveFact(record
+        .systemConversionGainElectronsPerCode, path +
+        ".systemConversionGainElectronsPerCode");
+    const exposureIndexGain = record.exposureIndexGain === undefined
+        ? undefined
+        : parseExposureIndexGain(record.exposureIndexGain, path + ".exposureIndexGain", digitalGain ?? 1);
     return {
         regimeId: requireNonEmptyString(record.regimeId, path + ".regimeId"),
         scientificStatus: parseStatus(record.scientificStatus, path +
             ".scientificStatus"),
-        systemConversionGainElectronsPerCode: parsePositiveFact(record
-            .systemConversionGainElectronsPerCode, path +
-            ".systemConversionGainElectronsPerCode"),
+        systemConversionGainElectronsPerCode,
         preAdcSaturationElectronEquivalent: parsePositiveFact(record
             .preAdcSaturationElectronEquivalent, path +
             ".preAdcSaturationElectronEquivalent"),
@@ -251,28 +339,33 @@ function parseRegime(value, path) {
             bitDepth,
             blackLevelCode,
             digitalSaturationCode,
-            transfer: "uniform-round-half-up"
+            transfer: "uniform-round-half-up",
+            ...(digitalGain === undefined
+                ? {}
+                : { digitalGain }),
+            ...(integralNonLinearity === undefined
+                ? {}
+                : { integralNonLinearity })
         },
+        ...(exposureIndexGain === undefined
+            ? {}
+            : { exposureIndexGain }),
         evidence: parseEvidenceList(record.evidence, path + ".evidence"),
         limitations: parseLimitations(record.limitations, path + ".limitations")
     };
 }
 /**
- * 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.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns SensorReadoutConversionProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The profile lists the declared conversion regimes. ISO never invents a regime.
+ * @param value - Untrusted data. TypeScript types alone are not validation.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export function parseSensorReadoutConversionProfile(value) {
-    const record = requireRecord(value, "sensorReadoutConversionProfile");
+    const record = requireRecord(value, "sensorReadoutConversionProfile", ["schemaVersion", "regimeSelectionOwnedBy", "regimes", "profileId", "colorSamplingProfileId", "channelId", "evidence"]);
     if (record.schemaVersion !==
         SENSOR_READOUT_CONVERSION_PROFILE_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('sensorReadoutConversionProfile.schemaVersion must be "' +
@@ -306,26 +399,21 @@ export function parseSensorReadoutConversionProfile(value) {
     };
 }
 /**
- * Select and validate a declared readout regime against exact channel/profile identity rather than
- * inferring it from ISO.
+ * Selects a declared readout regime and checks it against the exact channel and profile identity.
+ * The regime is never inferred from ISO.
+ * @param input - The input; see `ResolveSensorReadoutRegimeInput` for its fields, units and coordinates.
+ * @returns The result. Success does not imply calibration.
  *
- * 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.
- * @param input - ResolveSensorReadoutRegimeInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ResolvedSensorReadoutRegime. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
- *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export function resolveSensorReadoutRegime(input) {
+    requireInputKeys(input, "resolveSensorReadoutRegime", ["profile", "regimeId"]);
     const profile = parseSensorReadoutConversionProfile(input.profile);
     if (typeof input.regimeId !==
         "string" ||
         input.regimeId.trim().length ===
             0) {
-        throw new InvalidScientificInputError("regimeId must be a non-empty string.");
+        throw new InvalidConfigurationError("regimeId must be a non-empty string.");
     }
     const regimeId = input.regimeId.trim();
     const regime = profile.regimes.find((entry) => entry.regimeId === regimeId);
@@ -367,6 +455,14 @@ function validateChargeIdentity(charge, capacity, readout) {
             capacity.bindingId) {
         throw new InvalidScientificInputError("Physical capacity assessment identity must match the accumulated charge.");
     }
+    // The assessment copies the complete expected stored-electron total exactly from the charge it
+    // assessed. So the match must be exact: an assessment made for any other charge is out of date.
+    if (charge
+        .totalExpectedStoredElectronCount !==
+        capacity
+            .totalExpectedStoredElectronCount) {
+        throw new InvalidScientificInputError("Physical capacity assessment must be computed for the supplied accumulated charge; its total expected stored electrons differ.");
+    }
     if (readout
         .colorSamplingProfileId !==
         charge.colorSamplingProfileId ||
@@ -374,9 +470,14 @@ function validateChargeIdentity(charge, capacity, readout) {
             charge.channelId) {
         throw new InvalidScientificInputError("Sensor readout profile color/channel identity must match the accumulated charge.");
     }
+    const belowOrAtCapacity = capacity
+        .totalExpectedStoredElectronCount <=
+        capacity
+            .physicalChargeCapacityElectrons;
     if (capacity
         .expectedChargeCapacityStatus ===
-        "above-capacity") {
+        "above-capacity" ||
+        !belowOrAtCapacity) {
         throw new InvalidScientificInputError("Expected stored charge above physical capacity cannot enter linear expected readout; the actual post-saturation stored charge is not defined by the upstream assessment.");
     }
     if (charge.saturationAssessed !==
@@ -387,6 +488,7 @@ function validateChargeIdentity(charge, capacity, readout) {
             false) {
         throw new InvalidScientificInputError("Sensor readout requires the unmodified accumulated-charge result.");
     }
+    return belowOrAtCapacity;
 }
 function additionalPolicyMap(profile, charge) {
     if (profile.completenessProfileId !==
@@ -408,37 +510,14 @@ function additionalPolicyMap(profile, charge) {
         policy
     ]));
 }
-/**
- * Create the deterministic non-cryptographic xorshift32 stream for one charge or
- * read-noise identity. The XOR mix and nonzero fallback avoid the absorbing zero
- * state. Adding 0.5 before division produces values strictly inside (0,1), so
- * logarithmic Poisson/normal transforms never receive a zero or one endpoint.
- * Changing these mechanics changes realized RAW and requires model/replay review.
- */
 function createRandom(seedUint32) {
-    let state = (seedUint32 ^
-        0x9e3779b9) >>>
-        0;
-    if (state === 0) {
-        state =
-            0x6d2b79f5;
-    }
-    return {
-        next() {
-            state ^= state << 13;
-            state ^= state >>> 17;
-            state ^= state << 5;
-            state >>>= 0;
-            return ((state + 0.5) /
-                0x1_0000_0000);
-        }
-    };
+    return createDeterministicUniformStream(seedUint32);
 }
 /**
- * Compute log(n!) without materializing an overflowing factorial. Small integer
- * counts sum logarithms directly; larger counts use the stated Stirling correction
- * terms 1/(12n) - 1/(360n³). This is internal to the Poisson rejection calculation,
- * not an independent physical accuracy or uncertainty claim.
+ * Computes log(n!) without forming the factorial, which would overflow. Small counts
+ * sum the logarithms directly. Larger counts use Stirling's formula with the
+ * correction terms 1/(12n) - 1/(360n³). This is internal to the Poisson rejection
+ * sampler; it is not a claim about physical accuracy or uncertainty.
  */
 function logFactorial(n) {
     if (n < 2) {
@@ -460,14 +539,23 @@ function logFactorial(n) {
         inverse / 12 -
         inverseCubed / 360);
 }
+/** Means at or above this use the continuity-corrected normal approximation. */
+const POISSON_NORMAL_APPROXIMATION_MINIMUM_MEAN = 1e9;
 /**
- * Sample a nonnegative integer from the declared Poisson expectation. Zero mean
- * returns exactly zero. Below mean 30, multiply uniforms until the exponential
- * threshold is crossed; larger means use transformed rejection and compare log
- * probabilities to avoid overflow. The same mean and stream reproduce a draw;
- * changing means does not guarantee monotonic individual samples.
+ * Draws a nonnegative integer from a Poisson distribution with the given mean.
+ *
+ * - Mean 0 returns exactly 0.
+ * - Mean below 30: multiply uniform random numbers until the product drops below e^(−mean).
+ * - Mean from 30 to below 1e9: Hörmann's (1993) PTRS transformed rejection, comparing log
+ *   probabilities to avoid overflow.
+ * - Mean of 1e9 and above: a continuity-corrected normal approximation, because the log terms lose
+ *   precision there.
+ *
+ * The same mean and random stream reproduce the same draw. Increasing the mean does not guarantee
+ * that each individual draw increases. Exported internally for the lean native executor, which must
+ * draw exactly as simulateSensorChargeRealization does; not exported from the package.
  */
-function samplePoisson(mean, random) {
+export function samplePoisson(mean, random) {
     if (!Number.isFinite(mean) ||
         mean < 0) {
         throw new InvalidScientificInputError("Poisson mean must be finite and nonnegative.");
@@ -475,6 +563,19 @@ function samplePoisson(mean, random) {
     if (mean === 0) {
         return 0;
     }
+    if (mean >=
+        POISSON_NORMAL_APPROXIMATION_MINIMUM_MEAN) {
+        // Above 1e9 the log-probability terms of the rejection test reach about 1e10 and cancel badly
+        // (variance/mean is 1.012 at 1e14). Here the continuity-corrected normal approximation has a
+        // relative skewness error of 1/sqrt(mean) <= 3.2e-5 (Poisson skewness 1/sqrt(mean): NIST/SEMATECH
+        // e-Handbook of Statistical Methods, sec. 1.3.6.6.19, free; normal approximation with continuity
+        // correction: SOCR, University of Michigan, free. Also see: Johnson, Kemp & Kotz, Univariate
+        // Discrete Distributions, 3rd ed., section 4.4).
+        return Math.max(0, Math.floor(mean +
+            Math.sqrt(mean) *
+                sampleStandardNormal(random) +
+            0.5));
+    }
     if (mean < 30) {
         const threshold = Math.exp(-mean);
         let product = 1;
@@ -532,31 +633,37 @@ function samplePoisson(mean, random) {
     }
 }
 /**
- * Box–Muller transform of two open-interval uniforms. Each call consumes two
- * values and returns one signed unit-normal sample; no cached partner changes the
- * seed schedule. Electronic noise is allowed to be negative before pedestal/ADC.
+ * Internal (not exported from the package): draws `count` Poisson samples of one mean from one seeded
+ * stream, exactly as the charge realization does. Used by the sampler's distribution tests.
+ */
+export function samplePoissonStreamForValidation(mean, seedUint32, count) {
+    const random = createRandom(seedUint32);
+    return Array.from({ length: count }, () => samplePoisson(mean, random));
+}
+/**
+ * Internal (not exported from the package): draws `count` standard normal values from one seeded
+ * stream, exactly as the read-noise path does. Used by the sampler's distribution tests.
  */
+export function sampleStandardNormalStreamForValidation(seedUint32, count) {
+    const random = createRandom(seedUint32);
+    return Array.from({ length: count }, () => sampleStandardNormal(random));
+}
 function sampleStandardNormal(random) {
-    const u1 = random.next();
-    const u2 = random.next();
-    return (Math.sqrt(-2 * Math.log(u1)) *
-        Math.cos(2 * Math.PI * u2));
+    return sampleDeterministicStandardNormal(random);
 }
 /**
- * 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.
- * @param input - SimulateSensorChargeRealizationInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns CalculationResult<SensorChargeRealization>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * This is steps 1–2 of the readout order (see the module notes). Physical storage saturation is
+ * reported separately from later clipping.
+ * @param input - The input; see `SimulateSensorChargeRealizationInput` for its fields, units and coordinates.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export function simulateSensorChargeRealization(input) {
+    requireInputKeys(input, "simulateSensorChargeRealization", ["accumulatedCharge", "samplingProfile", "seedUint32", "fixedPatternNoise"]);
     const profile = parseSensorChargeSamplingProfile(input.samplingProfile);
     const seed = requireUint32(input.seedUint32, "seedUint32");
     const charge = input.accumulatedCharge;
@@ -571,11 +678,32 @@ export function simulateSensorChargeRealization(input) {
         throw new InvalidScientificInputError("Charge realization requires a complete unsaturated pre-readout accumulated-charge result.");
     }
     const policies = additionalPolicyMap(profile, charge);
+    const pattern = input.fixedPatternNoise === undefined
+        ? null
+        : fixedPatternAtSite(parseSensorFixedPatternNoiseProfile(input.fixedPatternNoise), charge
+            .colorSamplingProfileId, charge.site);
+    const photoGain = pattern === null
+        ? 1
+        : pattern
+            .photoResponseGainFactor;
+    const darkFactor = pattern === null
+        ? 1
+        : pattern.darkCurrentFactor;
+    const photoMean = pattern === null
+        ? charge
+            .photoExpectedElectronCount
+        : charge
+            .photoExpectedElectronCount *
+            photoGain;
+    const darkMean = pattern === null
+        ? charge
+            .darkExpectedElectronCount
+        : charge
+            .darkExpectedElectronCount *
+            darkFactor;
     const random = createRandom(seed);
-    const photoRealized = samplePoisson(charge
-        .photoExpectedElectronCount, random);
-    const darkRealized = samplePoisson(charge
-        .darkExpectedElectronCount, random);
+    const photoRealized = samplePoisson(photoMean, random);
+    const darkRealized = samplePoisson(darkMean, random);
     const additionalComponents = charge.additionalComponents.map((component) => {
         const policy = policies.get(component.componentId);
         const realized = policy.model ===
@@ -620,6 +748,14 @@ export function simulateSensorChargeRealization(input) {
         darkExpectedElectronCount: charge
             .darkExpectedElectronCount,
         darkRealizedElectronCount: darkRealized,
+        fixedPatternNoiseProfileId: pattern === null
+            ? null
+            : pattern.profileId,
+        photoResponseGainFactor: photoGain,
+        darkCurrentFactor: darkFactor,
+        hotPixel: pattern?.hotPixel ?? false,
+        photoSampledMeanElectronCount: photoMean,
+        darkSampledMeanElectronCount: darkMean,
         additionalComponents,
         totalExpectedStoredElectronCount: charge
             .totalExpectedStoredElectronCount,
@@ -634,13 +770,39 @@ export function simulateSensorChargeRealization(input) {
         rawCodeValueProduced: false,
         stochasticModel: "independent-poisson-photo-dark-explicit-additional-policy",
         deterministicSeededRealization: true
-    }, "sensor-charge-stochastic-realization", "1.0.0", [
+    }, "sensor-charge-stochastic-realization", "3.0.0", [
+        "An optional explicit fixed-pattern profile multiplies the photo Poisson mean by the site's PRNU gain and the dark Poisson mean by its DSNU/hot-pixel factor; without one the uniform population expectation is sampled. Fixed-pattern values are deterministic per sensor instance and colour-sampling site.",
+        "Poisson means of 1e9 electrons and above use a continuity-corrected normal approximation.",
         "Photo-generated and dark-generated electron counts are sampled independently from Poisson distributions using an explicit deterministic seed.",
         "Each additional stored-charge component uses its explicitly declared Poisson or deterministic electron-equivalent policy; Photivra does not infer defect/leakage statistics from the component name.",
         "This is a pre-saturation, pre-electronic-read-noise charge realization and remains separate from expectation-value calculations.",
-        "The seeded PRNG is a deterministic simulation mechanism and is not cryptographically secure."
+        "The seeded PRNG is a deterministic simulation mechanism and is not cryptographically secure; its seed is scrambled by the MurmurHash3 fmix32 finalizer so nearby seeds give unrelated streams."
     ]);
 }
+function fixedPatternAtSite(profile, colorSamplingProfileId, site) {
+    if (profile.colorSamplingProfileId !==
+        colorSamplingProfileId) {
+        throw new InvalidScientificInputError("Fixed-pattern noise profile colour-sampling identity must match the charge.");
+    }
+    return evaluateParsedFixedPatternSite(profile, site);
+}
+function fixedPatternForRealization(value, charge) {
+    if (value === undefined) {
+        if (charge.fixedPatternNoiseProfileId !==
+            null &&
+            charge.fixedPatternNoiseProfileId !==
+                undefined) {
+            throw new InvalidScientificInputError("A charge realization with a fixed pattern requires the same fixed-pattern profile at readout.");
+        }
+        return null;
+    }
+    const profile = parseSensorFixedPatternNoiseProfile(value);
+    if (charge.fixedPatternNoiseProfileId !==
+        profile.profileId) {
+        throw new InvalidScientificInputError("Readout fixed-pattern profile must be the profile used for the charge realization.");
+    }
+    return fixedPatternAtSite(profile, charge.colorSamplingProfileId, charge.site);
+}
 function validateCapacityAgainstRealization(charge, capacity, readout) {
     if (charge.completenessProfileId !==
         capacity
@@ -658,6 +820,12 @@ function validateCapacityAgainstRealization(charge, capacity, readout) {
             capacity.bindingId) {
         throw new InvalidScientificInputError("Physical capacity assessment identity must match the charge realization.");
     }
+    if (charge
+        .totalExpectedStoredElectronCount !==
+        capacity
+            .totalExpectedStoredElectronCount) {
+        throw new InvalidScientificInputError("Physical capacity assessment must be computed for the charge behind the realization; its total expected stored electrons differ.");
+    }
     if (readout
         .colorSamplingProfileId !==
         charge.colorSamplingProfileId ||
@@ -667,25 +835,20 @@ function validateCapacityAgainstRealization(charge, capacity, readout) {
     }
 }
 /**
- * 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.
- * @param input - CalculateExpectedSensorReadoutInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns CalculationResult<SensorExpectedReadoutSignal>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * 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.
+ * @param input - The input; see `CalculateExpectedSensorReadoutInput` for its fields, units and coordinates.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export function calculateExpectedSensorReadout(input) {
+    requireInputKeys(input, "calculateExpectedSensorReadout", ["accumulatedCharge", "physicalCapacityAssessment", "readoutProfile", "regimeId"]);
     const readout = resolveSensorReadoutRegime({
         profile: input.readoutProfile,
         regimeId: input.regimeId
     });
-    validateChargeIdentity(input.accumulatedCharge, input
+    const expectedStoredChargeBelowOrAtPhysicalCapacity = validateChargeIdentity(input.accumulatedCharge, input
         .physicalCapacityAssessment, readout);
     const expected = input.accumulatedCharge
         .totalExpectedStoredElectronCount;
@@ -697,9 +860,25 @@ export function calculateExpectedSensorReadout(input) {
         readout.regime
             .systemConversionGainElectronsPerCode
             .value;
+    const inlOffset = integralNonLinearityOffset(readout.regime.adc
+        .integralNonLinearity, codeSignal +
+        readout.regime
+            .adc.blackLevelCode);
     const codeBeforeQuantization = codeSignal +
         readout.regime
-            .adc.blackLevelCode;
+            .adc.blackLevelCode +
+        inlOffset;
+    const digitalGain = readout.regime.adc
+        .digitalGain ?? 1;
+    const codeAfterDigitalGain = readout.regime.adc
+        .digitalGain === undefined
+        ? codeBeforeQuantization
+        : (Math.min(codeBeforeQuantization, readout.adcMaximumCode) -
+            readout.regime.adc
+                .blackLevelCode) *
+            digitalGain +
+            readout.regime.adc
+                .blackLevelCode;
     return approximationResult({
         readoutProfileId: readout.profileId,
         regimeId: readout.regime
@@ -721,7 +900,7 @@ export function calculateExpectedSensorReadout(input) {
         bindingId: input.accumulatedCharge
             .bindingId,
         expectedStoredElectronCount: expected,
-        expectedStoredChargeBelowOrAtPhysicalCapacity: true,
+        expectedStoredChargeBelowOrAtPhysicalCapacity,
         expectedElectronEquivalentAfterPreAdcSaturation: afterPreAdc,
         preAdcSaturationAppliedToExpectation: afterPreAdc < expected,
         systemConversionGainElectronsPerCode: readout.regime
@@ -731,13 +910,16 @@ export function calculateExpectedSensorReadout(input) {
         blackLevelCode: readout.regime
             .adc.blackLevelCode,
         expectedCodeBeforeQuantization: codeBeforeQuantization,
+        adcIntegralNonLinearityOffsetCodes: inlOffset,
+        digitalGain,
+        expectedCodeAfterDigitalGain: codeAfterDigitalGain,
         adcBitDepth: readout.regime
             .adc.bitDepth,
         adcMaximumCode: readout.adcMaximumCode,
         digitalSaturationCode: readout.regime
             .adc
             .digitalSaturationCode,
-        expectedDigitalSaturation: codeBeforeQuantization >=
+        expectedDigitalSaturation: codeAfterDigitalGain >=
             readout.regime
                 .adc
                 .digitalSaturationCode,
@@ -748,32 +930,106 @@ export function calculateExpectedSensorReadout(input) {
         adcQuantizationApplied: false,
         rawCodeValueProduced: false,
         isoUsedToInferRegime: false
-    }, "sensor-expected-electronic-readout", "1.0.0", [
+    }, "sensor-expected-electronic-readout", "2.0.0", [
         "Expected readout uses complete expected stored charge only after the upstream physical-capacity assessment confirms the expectation is not above physical capacity.",
         "Electronic read-noise mean is zero and is not sampled in this expectation result.",
-        "The explicitly selected conversion regime is not inferred from ISO, sensor technology family or marketing mode names.",
+        "The explicitly selected conversion regime is not inferred from ISO, sensor technology family or marketing mode names; an ISO signal chain may bind an exposure index to a declared regime.",
+        "Declared ADC integral non-linearity and post-ADC digital gain are applied to the continuous expectation without quantization.",
         "Pre-ADC electron-equivalent saturation, black offset and ADC/digital saturation remain separate domains.",
         "ADC quantization is not applied to the expectation value."
     ]);
 }
+/**
+ * Nearest integer, with ties going towards +infinity. Math.round is exact for every double. (In
+ * contrast, floor(x + 0.5) returns 1 for 0.49999999999999994, because the addition rounds up.)
+ * Adding 0 turns -0 into +0.
+ */
 function roundHalfUp(value) {
-    return Math.floor(value + 0.5);
+    return Math.round(value) + 0;
+}
+function integralNonLinearityOffset(inl, code) {
+    if (inl === undefined) {
+        return 0;
+    }
+    const knots = inl.knots;
+    const first = knots[0];
+    const last = knots[knots.length - 1];
+    if (code <= first.code) {
+        return first.offsetCodes;
+    }
+    if (code >= last.code) {
+        return last.offsetCodes;
+    }
+    let low = 0;
+    let high = knots.length - 1;
+    while (high - low > 1) {
+        const middle = (low + high) >> 1;
+        if (knots[middle].code <= code) {
+            low = middle;
+        }
+        else {
+            high = middle;
+        }
+    }
+    const a = knots[low];
+    const b = knots[high];
+    return (a.offsetCodes +
+        ((code - a.code) /
+            (b.code - a.code)) *
+            (b.offsetCodes - a.offsetCodes));
 }
 /**
- * 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.
- * @param input - SimulateSensorRawCodeInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns CalculationResult<SensorRawCodeSample>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Shared ADC transfer function: continuous input code (signal/gain + black + INL), rounded half up
+ * and limited to the ADC code range, then optional post-ADC digital gain about black, rounded again.
+ * The caller applies the final clamp to [0, digitalSaturationCode]. Exported internally for the lean
+ * native executor; not exported from the package.
+ */
+export function adcTransfer(regime, adcMaximumCode, electronEquivalent) {
+    const ideal = electronEquivalent /
+        regime
+            .systemConversionGainElectronsPerCode
+            .value +
+        regime.adc.blackLevelCode;
+    const inlOffset = integralNonLinearityOffset(regime.adc.integralNonLinearity, ideal);
+    const codeBeforeQuantization = ideal + inlOffset;
+    const quantizedAdc = roundHalfUp(codeBeforeQuantization);
+    const digitalGain = regime.adc.digitalGain ?? 1;
+    if (regime.adc.digitalGain ===
+        undefined) {
+        return {
+            codeBeforeQuantization,
+            inlOffset,
+            adcCode: quantizedAdc,
+            digitalGain,
+            quantized: quantizedAdc
+        };
+    }
+    const adcCode = Math.max(0, Math.min(quantizedAdc, adcMaximumCode));
+    return {
+        codeBeforeQuantization,
+        inlOffset,
+        adcCode,
+        digitalGain,
+        quantized: roundHalfUp((adcCode -
+            regime.adc
+                .blackLevelCode) *
+            digitalGain +
+            regime.adc
+                .blackLevelCode)
+    };
+}
+/**
+ * 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.
+ * @param input - The input; see `SimulateSensorRawCodeInput` for its fields, units and coordinates.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export function simulateSensorRawCode(input) {
+    requireInputKeys(input, "simulateSensorRawCode", ["chargeRealization", "physicalCapacityAssessment", "readoutProfile", "regimeId", "readNoiseSeedUint32", "fixedPatternNoise"]);
     const readout = resolveSensorReadoutRegime({
         profile: input.readoutProfile,
         regimeId: input.regimeId
@@ -816,23 +1072,25 @@ export function simulateSensorRawCode(input) {
     const totalReadNoise = readNoiseComponents.reduce((sum, component) => sum +
         component
             .sampledElectrons, 0);
+    const pattern = fixedPatternForRealization(input.fixedPatternNoise, input.chargeRealization);
+    const fixedPatternOffset = pattern === null
+        ? 0
+        : pattern
+            .readoutOffsetElectrons;
     const afterReadNoise = afterPhysical +
-        totalReadNoise;
+        totalReadNoise +
+        fixedPatternOffset;
     const preAdcThreshold = readout.regime
         .preAdcSaturationElectronEquivalent
         .value;
-    // Stored charge is nonnegative; the downstream electronic signal is signed.
-    // Preserve negative read noise until the black pedestal and unsigned ADC boundary.
+    // Stored charge is nonnegative, but the electronic signal after it is signed.
+    // Keep negative read noise until the black pedestal and the unsigned ADC limit.
     const afterPreAdc = Math.min(afterReadNoise, preAdcThreshold);
     const preAdcSaturation = afterReadNoise >
         preAdcThreshold;
-    const codeBeforeQuantization = afterPreAdc /
-        readout.regime
-            .systemConversionGainElectronsPerCode
-            .value +
-        readout.regime
-            .adc.blackLevelCode;
-    const quantized = roundHalfUp(codeBeforeQuantization);
+    const transfer = adcTransfer(readout.regime, readout.adcMaximumCode, afterPreAdc);
+    const codeBeforeQuantization = transfer.codeBeforeQuantization;
+    const quantized = transfer.quantized;
     const rawCode = Math.max(0, Math.min(quantized, readout.regime
         .adc
         .digitalSaturationCode));
@@ -868,6 +1126,10 @@ export function simulateSensorRawCode(input) {
         bloomingModeled: false,
         electronicReadNoiseComponents: readNoiseComponents,
         totalElectronicReadNoiseElectrons: totalReadNoise,
+        fixedPatternNoiseProfileId: pattern === null
+            ? null
+            : pattern.profileId,
+        fixedPatternReadoutOffsetElectrons: fixedPatternOffset,
         electronEquivalentAfterReadNoise: afterReadNoise,
         preAdcSaturationElectronEquivalent: preAdcThreshold,
         electronEquivalentAfterPreAdcSaturation: afterPreAdc,
@@ -878,6 +1140,9 @@ export function simulateSensorRawCode(input) {
         blackLevelCode: readout.regime
             .adc.blackLevelCode,
         codeBeforeQuantization,
+        adcIntegralNonLinearityOffsetCodes: transfer.inlOffset,
+        adcCodeBeforeDigitalGain: transfer.adcCode,
+        digitalGain: transfer.digitalGain,
         quantizedCodeBeforeDigitalClamp: quantized,
         adcBitDepth: readout.regime
             .adc.bitDepth,
@@ -886,7 +1151,7 @@ export function simulateSensorRawCode(input) {
             .adc
             .digitalSaturationCode,
         rawCode,
-        digitalSaturationApplied: quantized >
+        digitalSaturationApplied: quantized >=
             readout.regime
                 .adc
                 .digitalSaturationCode,
@@ -902,11 +1167,11 @@ export function simulateSensorRawCode(input) {
         rawCodeValueProduced: true,
         isoUsedToInferRegime: false,
         deterministicSeededRealization: true
-    }, "sensor-raw-code-stochastic-readout", "2.0.0", [
+    }, "sensor-raw-code-stochastic-readout", "4.0.0", [
         "A stochastic stored-charge realization is scalar-clamped at the explicit physical storage capacity; this is a bounded saturation approximation and does not model blooming, neighbor transport or anti-blooming behavior.",
-        "Independent input-referred Gaussian electronic read-noise components are sampled after physical charge saturation and before the explicit pre-ADC electron-equivalent saturation threshold.",
-        "System conversion gain is expressed in electrons per digital-number code unit for the explicitly selected regime and is not inferred from ISO.",
-        "Signed electronic read noise survives the upper-only pre-ADC saturation threshold. Black level is added before uniform round-half-up quantization and clamping to zero/digital saturation; valid below-black codes are retained.",
+        "Independent input-referred Gaussian electronic read-noise components, plus any declared static fixed-pattern row/column offsets, are added after physical charge saturation and before the explicit pre-ADC electron-equivalent saturation threshold.",
+        "System conversion gain is expressed in electrons per digital-number code unit for the explicitly selected regime; an ISO-dependent gain exists only where an explicit ISO signal chain binds the setting to a declared regime.",
+        "Signed electronic read noise survives the upper-only pre-ADC saturation threshold. Black level and any declared ADC integral non-linearity are added before uniform round-half-up quantization (exact ties toward +infinity); an optional post-ADC digital gain about black is re-quantized; codes are then clamped to zero/digital saturation and valid below-black codes are retained.",
         "Physical storage capacity, pre-ADC saturation and digital/ADC saturation remain separate thresholds.",
         "The charge seed and read-noise seed are separate deterministic simulation identities; neither is cryptographically secure."
     ]);