@photivra/engine 1.5.0 → 2.0.0

package/dist/sensor/fixed-pattern-noise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixed-pattern-noise.js","sourceRoot":"","sources":["../../src/sensor/fixed-pattern-noise.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Fixed-pattern noise (FPN): the part of sensor noise that stays the same from shot to shot for one\n * physical sensor. It covers photo-response non-uniformity (PRNU), dark-signal non-uniformity (DSNU),\n * hot pixels and row and column readout offsets, as defined in EMVA Standard 1288 Release 4.0 (spatial\n * non-uniformity of the photo response and of the dark signal).\n *\n * The pattern is deterministic. It is seeded from an explicit sensor-instance seed and absolute\n * colour-sampling site coordinates, never from the per-capture noise seed, so the same sensor shows\n * the same pattern in every capture.\n *\n * Application points in the readout chain (see raw-readout.ts):\n * - PRNU multiplies the expected photo charge before photo shot-noise sampling;\n * - DSNU and hot pixels multiply the population-mean dark-current expectation before dark shot-noise\n *   sampling, so their excess charge scales with exposure duration and with the declared\n *   temperature model of the dark-current profile;\n * - row and column offsets are input-referred electron offsets added with read noise, before the\n *   pre-ADC threshold.\n *\n * The dark-current model itself stays a population mean; this module is a separate spatial model that\n * must be attached explicitly. Values are declared by the caller (or are synthetic preset values).\n * Nothing here is a measured calibration.\n * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support\n * limits.\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { parseEvidenceList, type EvidenceBackedFact, type EvidenceProvenance } from \"../core/evidence-provenance.js\";\nimport { requireAllowlistedRecord, requirePublicOpaqueId, requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport {\n  createDeterministicUniformStream,\n  deriveSensorFixedPatternSeedUint32,\n  sampleDeterministicStandardNormal,\n  SENSOR_FIXED_PATTERN_COLUMN_STREAM_ID,\n  SENSOR_FIXED_PATTERN_DSNU_STREAM_ID,\n  SENSOR_FIXED_PATTERN_HOT_PIXEL_STREAM_ID,\n  SENSOR_FIXED_PATTERN_PRNU_STREAM_ID,\n  SENSOR_FIXED_PATTERN_ROW_STREAM_ID\n} from \"./stochastic-seed.js\";\n\nexport const SENSOR_FIXED_PATTERN_NOISE_PROFILE_SCHEMA_VERSION = \"0.1.0\" as const;\n/** Versioned identity of the pattern-generation equations and seed schedule. */\nexport const SENSOR_FIXED_PATTERN_NOISE_MODEL = Object.freeze({ id: \"photivra-sensor-fixed-pattern\", version: \"1.0.0\" } as const);\n\n/**\n * Explicit fixed-pattern parameters for one sensor instance. Every component is required; a zero\n * standard deviation, fraction or RMS disables that component.\n */\nexport interface SensorFixedPatternNoiseProfile {\n  schemaVersion: typeof SENSOR_FIXED_PATTERN_NOISE_PROFILE_SCHEMA_VERSION;\n  profileId: string;\n  /** The colour-sampling grid whose absolute site coordinates index the pattern. */\n  colorSamplingProfileId: string;\n  scientificStatus: \"approximation\";\n  /** Identifies the physical sensor. Independent of every per-capture noise seed. */\n  sensorInstanceSeedUint32: number;\n  /** EMVA 1288 PRNU: spatial standard deviation of the photo response divided by its mean. */\n  photoResponseNonUniformity: { relativeStandardDeviation: EvidenceBackedFact<number> };\n  /** Spatial standard deviation of the dark-current rate divided by the population-mean rate. */\n  darkSignalNonUniformity: { relativeStandardDeviation: EvidenceBackedFact<number> };\n  /** Fraction of sites whose dark-current rate is the population mean times the multiplier. */\n  hotPixels: { siteFraction: EvidenceBackedFact<number>; darkCurrentMultiplier: EvidenceBackedFact<number> };\n  /** Fixed readout offset per row, in input-referred electrons, normally distributed with zero mean. */\n  rowOffset: { rmsElectrons: EvidenceBackedFact<number> };\n  /** Fixed readout offset per column, in input-referred electrons, normally distributed with zero mean. */\n  columnOffset: { rmsElectrons: EvidenceBackedFact<number> };\n  patternDistribution: \"normal-factors-truncated-at-zero\";\n  evidence: readonly EvidenceProvenance[];\n  limitations: readonly string[];\n}\n\n/** The deterministic pattern values of one colour-sampling site. */\nexport interface SensorFixedPatternSiteValues {\n  profileId: string;\n  modelId: typeof SENSOR_FIXED_PATTERN_NOISE_MODEL.id;\n  modelVersion: typeof SENSOR_FIXED_PATTERN_NOISE_MODEL.version;\n  site: { x: number; y: number };\n  /** Multiplies the expected photo charge (1 = no PRNU); never negative. */\n  photoResponseGainFactor: number;\n  /** Multiplies the population-mean dark expectation (1 = no DSNU); never negative. */\n  darkCurrentFactor: number;\n  hotPixel: boolean;\n  rowOffsetElectrons: number;\n  columnOffsetElectrons: number;\n  /** rowOffsetElectrons + columnOffsetElectrons, added at readout. */\n  readoutOffsetElectrons: number;\n}\n\nconst FACT_KEYS = [\"value\", \"evidence\"];\n\nfunction fact(value: unknown, path: string, maximum: number, minimum = 0): EvidenceBackedFact<number> {\n  const record = requireAllowlistedRecord(value, FACT_KEYS, path + \" must be an evidence-backed fact.\");\n  const v = record.value;\n  if (typeof v !== \"number\" || !Number.isFinite(v) || v < minimum || v > maximum) {\n    throw new InvalidConfigurationError(path + \".value must be finite from \" + minimum + \" through \" + maximum + \".\");\n  }\n  return { value: v, evidence: parseEvidenceList(record.evidence, path + \".evidence\") };\n}\n\nfunction limitations(value: unknown): readonly string[] {\n  if (!Array.isArray(value) || value.some((entry) => typeof entry !== \"string\" || entry.trim().length === 0)) {\n    throw new InvalidConfigurationError(\"sensorFixedPatternNoise.limitations must be an array of non-empty strings.\");\n  }\n  if (new Set(value).size !== value.length) {\n    throw new InvalidConfigurationError(\"sensorFixedPatternNoise.limitations must not contain duplicates.\");\n  }\n  return value.map((entry: string) => entry.trim());\n}\n\n/**\n * Validates an untrusted fixed-pattern noise profile. Unknown keys, out-of-range parameters and\n * missing evidence are rejected. The PRNU and DSNU relative standard deviations are limited to 0.5\n * and 5, and the hot-pixel multiplier to 1–1e6.\n * @param value - Untrusted data. TypeScript types alone are not validation.\n * @returns The validated profile.\n * @see docs/MOTION_AND_SIGNAL.md for the model and its sources.\n */\nexport function parseSensorFixedPatternNoiseProfile(value: unknown): SensorFixedPatternNoiseProfile {\n  const r = requireAllowlistedRecord(value, [\"schemaVersion\", \"profileId\", \"colorSamplingProfileId\", \"scientificStatus\",\n    \"sensorInstanceSeedUint32\", \"photoResponseNonUniformity\", \"darkSignalNonUniformity\", \"hotPixels\", \"rowOffset\", \"columnOffset\",\n    \"patternDistribution\", \"evidence\", \"limitations\"], \"Invalid sensor fixed-pattern noise profile fields.\");\n  if (r.schemaVersion !== SENSOR_FIXED_PATTERN_NOISE_PROFILE_SCHEMA_VERSION) {\n    throw new InvalidConfigurationError('sensorFixedPatternNoise.schemaVersion must be \"' + SENSOR_FIXED_PATTERN_NOISE_PROFILE_SCHEMA_VERSION + '\".');\n  }\n  if (r.scientificStatus !== \"approximation\") {\n    throw new InvalidConfigurationError('sensorFixedPatternNoise.scientificStatus must be \"approximation\".');\n  }\n  if (r.patternDistribution !== \"normal-factors-truncated-at-zero\") {\n    throw new InvalidConfigurationError('sensorFixedPatternNoise.patternDistribution must be \"normal-factors-truncated-at-zero\".');\n  }\n  const seed = r.sensorInstanceSeedUint32;\n  if (typeof seed !== \"number\" || !Number.isSafeInteger(seed) || seed < 0 || seed > 0xffff_ffff) {\n    throw new InvalidConfigurationError(\"sensorFixedPatternNoise.sensorInstanceSeedUint32 must be an unsigned 32-bit integer.\");\n  }\n  const prnu = requireAllowlistedRecord(r.photoResponseNonUniformity, [\"relativeStandardDeviation\"], \"Invalid PRNU fields.\");\n  const dsnu = requireAllowlistedRecord(r.darkSignalNonUniformity, [\"relativeStandardDeviation\"], \"Invalid DSNU fields.\");\n  const hot = requireAllowlistedRecord(r.hotPixels, [\"siteFraction\", \"darkCurrentMultiplier\"], \"Invalid hot-pixel fields.\");\n  const row = requireAllowlistedRecord(r.rowOffset, [\"rmsElectrons\"], \"Invalid row-offset fields.\");\n  const column = requireAllowlistedRecord(r.columnOffset, [\"rmsElectrons\"], \"Invalid column-offset fields.\");\n  return {\n    schemaVersion: SENSOR_FIXED_PATTERN_NOISE_PROFILE_SCHEMA_VERSION,\n    profileId: requirePublicOpaqueId(r.profileId, \"sensorFixedPatternNoise.profileId must be a public opaque identifier.\"),\n    colorSamplingProfileId: requirePublicOpaqueId(r.colorSamplingProfileId, \"sensorFixedPatternNoise.colorSamplingProfileId must be a public opaque identifier.\"),\n    scientificStatus: \"approximation\",\n    sensorInstanceSeedUint32: seed,\n    photoResponseNonUniformity: { relativeStandardDeviation: fact(prnu.relativeStandardDeviation, \"photoResponseNonUniformity.relativeStandardDeviation\", 0.5) },\n    darkSignalNonUniformity: { relativeStandardDeviation: fact(dsnu.relativeStandardDeviation, \"darkSignalNonUniformity.relativeStandardDeviation\", 5) },\n    hotPixels: { siteFraction: fact(hot.siteFraction, \"hotPixels.siteFraction\", 1),\n      darkCurrentMultiplier: fact(hot.darkCurrentMultiplier, \"hotPixels.darkCurrentMultiplier\", 1e6, 1) },\n    rowOffset: { rmsElectrons: fact(row.rmsElectrons, \"rowOffset.rmsElectrons\", 1e6) },\n    columnOffset: { rmsElectrons: fact(column.rmsElectrons, \"columnOffset.rmsElectrons\", 1e6) },\n    patternDistribution: \"normal-factors-truncated-at-zero\",\n    evidence: parseEvidenceList(r.evidence, \"sensorFixedPatternNoise.evidence\"),\n    limitations: limitations(r.limitations)\n  };\n}\n\nfunction normal(seed: number, x: number, y: number, stream: number): number {\n  return sampleDeterministicStandardNormal(createDeterministicUniformStream(deriveSensorFixedPatternSeedUint32(seed, x, y, stream)));\n}\n\n/**\n * Computes the fixed-pattern values of one absolute colour-sampling site.\n *\n * - PRNU gain g = max(0, 1 + σ_PRNU·z₁);\n * - hot pixel when u < f_hot, then dark factor d = m_hot; otherwise d = max(0, 1 + σ_DSNU·z₂);\n * - row offset σ_row·z(row y), column offset σ_col·z(column x), in input-referred electrons.\n *\n * Each z is a standard normal value and u a uniform value, each from its own stream hashed with\n * MurmurHash3 from (sensorInstanceSeed, x, y, stream). Row values use x = 0 and column values y = 0,\n * so a whole row or column shares one value. Cutting negative factors off at zero shifts the mean\n * factor by less than 1e-6 for σ ≤ 0.2.\n * @param input - A parsed or untrusted profile plus a nonnegative integer site.\n * @returns The site's fixed-pattern values.\n */\nexport function calculateSensorFixedPatternSite(input: {\n  profile: SensorFixedPatternNoiseProfile; site: { x: number; y: number };\n}): SensorFixedPatternSiteValues {\n  requireInputKeys(input, \"calculateSensorFixedPatternSite\", [\"profile\", \"site\"]);\n  const profile = parseSensorFixedPatternNoiseProfile(input.profile);\n  return evaluateParsedFixedPatternSite(profile, input.site);\n}\n\n/** Internal: the PRNU gain, dark-current factor and hot-pixel state of one site (no readout offsets). */\nexport function evaluateFixedPatternSiteFactors(profile: SensorFixedPatternNoiseProfile, x: number, y: number):\n  { photoResponseGainFactor: number; darkCurrentFactor: number; hotPixel: boolean } {\n  const seed = profile.sensorInstanceSeedUint32;\n  const prnuSd = profile.photoResponseNonUniformity.relativeStandardDeviation.value;\n  const dsnuSd = profile.darkSignalNonUniformity.relativeStandardDeviation.value;\n  const hotFraction = profile.hotPixels.siteFraction.value;\n  const photoResponseGainFactor = prnuSd === 0 ? 1 : Math.max(0, 1 + prnuSd * normal(seed, x, y, SENSOR_FIXED_PATTERN_PRNU_STREAM_ID));\n  const hotPixel = hotFraction > 0 &&\n    createDeterministicUniformStream(deriveSensorFixedPatternSeedUint32(seed, x, y, SENSOR_FIXED_PATTERN_HOT_PIXEL_STREAM_ID)).next() < hotFraction;\n  const darkCurrentFactor = hotPixel ? profile.hotPixels.darkCurrentMultiplier.value :\n    dsnuSd === 0 ? 1 : Math.max(0, 1 + dsnuSd * normal(seed, x, y, SENSOR_FIXED_PATTERN_DSNU_STREAM_ID));\n  return { photoResponseGainFactor, darkCurrentFactor, hotPixel };\n}\n\n/** Internal: the fixed readout offset of row `y`, in input-referred electrons. */\nexport function evaluateFixedPatternRowOffset(profile: SensorFixedPatternNoiseProfile, y: number): number {\n  const rms = profile.rowOffset.rmsElectrons.value;\n  return rms === 0 ? 0 : rms * normal(profile.sensorInstanceSeedUint32, 0, y, SENSOR_FIXED_PATTERN_ROW_STREAM_ID);\n}\n\n/** Internal: the fixed readout offset of column `x`, in input-referred electrons. */\nexport function evaluateFixedPatternColumnOffset(profile: SensorFixedPatternNoiseProfile, x: number): number {\n  const rms = profile.columnOffset.rmsElectrons.value;\n  return rms === 0 ? 0 : rms * normal(profile.sensorInstanceSeedUint32, x, 0, SENSOR_FIXED_PATTERN_COLUMN_STREAM_ID);\n}\n\n/** Internal: the same calculation for an already parsed profile. */\nexport function evaluateParsedFixedPatternSite(profile: SensorFixedPatternNoiseProfile,\n  site: { x: number; y: number }): SensorFixedPatternSiteValues {\n  const { x, y } = site ?? {};\n  if (!Number.isSafeInteger(x) || !Number.isSafeInteger(y) || x < 0 || y < 0 || x > 0xffff_ffff || y > 0xffff_ffff) {\n    throw new InvalidScientificInputError(\"Fixed-pattern site coordinates must be nonnegative uint32 integers.\");\n  }\n  const { photoResponseGainFactor, darkCurrentFactor, hotPixel } = evaluateFixedPatternSiteFactors(profile, x, y);\n  const rowOffsetElectrons = evaluateFixedPatternRowOffset(profile, y);\n  const columnOffsetElectrons = evaluateFixedPatternColumnOffset(profile, x);\n  return {\n    profileId: profile.profileId,\n    modelId: SENSOR_FIXED_PATTERN_NOISE_MODEL.id,\n    modelVersion: SENSOR_FIXED_PATTERN_NOISE_MODEL.version,\n    site: { x, y },\n    photoResponseGainFactor,\n    darkCurrentFactor,\n    hotPixel,\n    rowOffsetElectrons,\n    columnOffsetElectrons,\n    readoutOffsetElectrons: rowOffsetElectrons + columnOffsetElectrons\n  };\n}\n"]}

package/dist/sensor/iso-gain.d.ts

@@ -0,0 +1,44 @@
+import { type EvidenceBackedFact, type EvidenceProvenance } from "../core/evidence-provenance.js";
+import { type SensorReadoutConversionRegime, type SensorReadoutExposureIndexGain } from "./raw-readout.js";
+import type { GenericIsoStandardRegimeBand } from "./iso-signal-chain.js";
+import type { SensorSpectralResponseScientificStatus } from "./spectral-response.js";
+/** One conversion-gain mode, active from its minimum exposure index up to the next mode's. */
+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>;
+}
+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[];
+}
+export interface IsoGainReadoutRegimes {
+    regimes: readonly SensorReadoutConversionRegime[];
+    /** One single-value band per setting, ready for a GenericIsoSignalChainProfile. */
+    standardRegimeBands: readonly GenericIsoStandardRegimeBand[];
+}
+/**
+ * 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.
+ * @param input - The sensor parameters and ISO settings; untrusted values are validated.
+ * @returns The readout regimes and bands.
+ */
+export declare function createIsoGainReadoutRegimes(input: CreateIsoGainReadoutRegimesInput): IsoGainReadoutRegimes;

package/dist/sensor/iso-gain.js

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * ISO gain: builds one explicit readout regime for each ISO (exposure index) setting from declared
+ * sensor parameters, so that raising ISO brightens the RAW the way a camera's programmable gain does.
+ *
+ * Model (exposure index S = 10 / H of CIPA DC-004-2020, free at https://www.cipa.jp/e/std/std-sec.html,
+ * also specified in ISO 12232:2019; EMVA Standard 1288 Release 4.0 linear camera model,
+ * where the system gain K in DN/e- multiplies the electron signal):
+ *   R = S / S0                      exposure-index ratio to the base exposure index S0
+ *   a = min(R, A_max)               analog (pre-ADC) gain relative to the base regime
+ *   d = R / a                       post-ADC digital gain beyond the analog range
+ *   g(S) = Q0 / (span * a)          electrons per code (1/K), span = digitalSaturation - black
+ *   Q_preADC(S) = Q0 / a            electrons that drive the ADC to digital saturation
+ * So the electrons needed to reach digital saturation are Q0 * S0 / S.
+ *
+ * The exposure indices of CIPA DC-004 put the reference exposure H_ref in proportion to 1/S: standard
+ * output sensitivity (SOS) and REI (recommended exposure index) both use S = 10 / H (§3.2, §3.3). So a
+ * correct exposure for S gives the same black-subtracted fraction of digital saturation at every S.
+ *
+ * Read noise in electrons is declared per conversion-gain mode, never derived from S. (With dual
+ * conversion gain, the high-conversion-gain mode used at high S has lower input-referred read noise.)
+ *
+ * Inputs are explicit declarations; Photivra presets use synthetic teaching values. No camera
+ * calibration is implied.
+ * @see docs/MOTION_AND_SIGNAL.md for equations, sources and limits.
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { parseEvidenceList } from "../core/evidence-provenance.js";
+import { requireAllowlistedRecord, requirePublicOpaqueId } from "../core/record-validation.js";
+import { parseSensorReadoutConversionProfile } from "./raw-readout.js";
+function positive(value, path) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new InvalidConfigurationError(path + " must be finite and greater than zero.");
+    }
+    return value;
+}
+function positiveFact(value, path) {
+    const r = requireAllowlistedRecord(value, ["value", "evidence"], path + " must be an evidence-backed fact.");
+    return { value: positive(r.value, path + ".value"), evidence: parseEvidenceList(r.evidence, path + ".evidence") };
+}
+/**
+ * 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.
+ * @param input - The sensor parameters and ISO settings; untrusted values are validated.
+ * @returns The readout regimes and bands.
+ */
+export function createIsoGainReadoutRegimes(input) {
+    const r = requireAllowlistedRecord(input, ["regimeIdPrefix", "scientificStatus", "baseExposureIndex", "exposureIndices",
+        "baseSaturationElectronEquivalent", "maximumAnalogGain", "adc", "conversionGainModes", "evidence", "limitations"], "Invalid ISO gain readout fields.");
+    const prefix = r.regimeIdPrefix === "" ? "" : requirePublicOpaqueId(r.regimeIdPrefix, "regimeIdPrefix must be empty or a public opaque identifier.");
+    const base = positive(r.baseExposureIndex, "baseExposureIndex");
+    const q0 = positiveFact(r.baseSaturationElectronEquivalent, "baseSaturationElectronEquivalent");
+    const aMax = positiveFact(r.maximumAnalogGain, "maximumAnalogGain");
+    if (aMax.value < 1)
+        throw new InvalidConfigurationError("maximumAnalogGain must be at least 1.");
+    const evidence = parseEvidenceList(r.evidence, "evidence");
+    const adc = requireAllowlistedRecord(r.adc, ["bitDepth", "blackLevelCode", "digitalSaturationCode"], "Invalid ISO gain ADC fields.");
+    if (!Array.isArray(r.exposureIndices) || r.exposureIndices.length === 0 || r.exposureIndices.length > 256) {
+        throw new InvalidConfigurationError("exposureIndices must contain 1 through 256 settings.");
+    }
+    const indices = r.exposureIndices.map((value, i) => positive(value, "exposureIndices[" + i + "]"));
+    if (indices[0] < base || indices.some((value, i) => i > 0 && value <= indices[i - 1])) {
+        throw new InvalidConfigurationError("exposureIndices must strictly increase from at least the base exposure index.");
+    }
+    if (!Array.isArray(r.conversionGainModes) || r.conversionGainModes.length === 0 || r.conversionGainModes.length > 8) {
+        throw new InvalidConfigurationError("conversionGainModes must contain 1 through 8 modes.");
+    }
+    const modes = r.conversionGainModes.map((value, i) => {
+        const m = requireAllowlistedRecord(value, ["mode", "minimumExposureIndex", "readNoiseRmsElectrons", "maximumChargeElectrons"], "Invalid conversion-gain mode fields.");
+        if (m.mode !== "single-conversion-gain" && m.mode !== "low-conversion-gain" && m.mode !== "high-conversion-gain") {
+            throw new InvalidConfigurationError("conversionGainModes[" + i + "].mode is invalid.");
+        }
+        const noise = requireAllowlistedRecord(m.readNoiseRmsElectrons, ["value", "evidence"], "Invalid read-noise fact.");
+        if (typeof noise.value !== "number" || !Number.isFinite(noise.value) || noise.value < 0) {
+            throw new InvalidConfigurationError("conversionGainModes[" + i + "].readNoiseRmsElectrons.value must be finite and nonnegative.");
+        }
+        return { mode: m.mode,
+            minimumExposureIndex: positive(m.minimumExposureIndex, "conversionGainModes[" + i + "].minimumExposureIndex"),
+            readNoiseRmsElectrons: { value: noise.value, evidence: parseEvidenceList(noise.evidence, "readNoiseRmsElectrons.evidence") },
+            ...(m.maximumChargeElectrons === undefined ? {} :
+                { maximumChargeElectrons: positiveFact(m.maximumChargeElectrons, "conversionGainModes[" + i + "].maximumChargeElectrons") }) };
+    });
+    if (modes[0].minimumExposureIndex !== base || modes.some((m, i) => i > 0 && m.minimumExposureIndex <= modes[i - 1].minimumExposureIndex)) {
+        throw new InvalidConfigurationError("conversionGainModes must start at the base exposure index and strictly increase.");
+    }
+    const gainEvidence = [...q0.evidence, ...aMax.evidence].filter((entry, i, all) => all.findIndex((other) => JSON.stringify(other) === JSON.stringify(entry)) === i);
+    const black = adc.blackLevelCode, saturation = adc.digitalSaturationCode;
+    const span = saturation - black;
+    const regimes = indices.map((exposureIndex) => {
+        const ratio = exposureIndex / base;
+        const analogGain = Math.min(ratio, aMax.value);
+        const digitalGain = ratio / analogGain;
+        const mode = modes.filter((m) => m.minimumExposureIndex <= exposureIndex).pop();
+        const preAdc = q0.value / analogGain;
+        if (mode.maximumChargeElectrons !== undefined && preAdc > mode.maximumChargeElectrons.value) {
+            throw new InvalidConfigurationError("A " + mode.mode + " regime would need more charge than its declared storage limit.");
+        }
+        const regimeEvidence = [...evidence];
+        return {
+            regimeId: prefix + "iso-" + exposureIndex,
+            scientificStatus: r.scientificStatus,
+            systemConversionGainElectronsPerCode: { value: preAdc / span, evidence: gainEvidence },
+            preAdcSaturationElectronEquivalent: { value: preAdc, evidence: gainEvidence },
+            readNoiseComponents: [{ componentId: "electronic", rmsElectrons: mode.readNoiseRmsElectrons, evidence: mode.readNoiseRmsElectrons.evidence }],
+            adc: { bitDepth: adc.bitDepth, blackLevelCode: black, digitalSaturationCode: saturation, transfer: "uniform-round-half-up",
+                ...(digitalGain === 1 ? {} : { digitalGain }) },
+            exposureIndexGain: { exposureIndex, baseExposureIndex: base, analogGain, digitalGain, conversionGainMode: mode.mode, evidence: regimeEvidence },
+            evidence: regimeEvidence,
+            limitations: r.limitations
+        };
+    });
+    // Reuse the regime parser to check the ADC, limitations and consistency.
+    const parsed = parseSensorReadoutConversionProfile({ schemaVersion: "0.1.0", profileId: prefix + "validation", colorSamplingProfileId: "validation",
+        channelId: "validation", regimeSelectionOwnedBy: "explicit-upstream-camera-state-not-inferred-from-iso", regimes, evidence }).regimes;
+    return { regimes: parsed, standardRegimeBands: indices.map((exposureIndex, i) => ({ minimumExposureIndex: exposureIndex,
+            maximumExposureIndex: exposureIndex, readoutRegimeId: parsed[i].regimeId })) };
+}
+//# sourceMappingURL=iso-gain.js.map

package/dist/sensor/iso-gain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iso-gain.js","sourceRoot":"","sources":["../../src/sensor/iso-gain.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * ISO gain: builds one explicit readout regime for each ISO (exposure index) setting from declared\n * sensor parameters, so that raising ISO brightens the RAW the way a camera's programmable gain does.\n *\n * Model (exposure index S = 10 / H of CIPA DC-004-2020, free at https://www.cipa.jp/e/std/std-sec.html,\n * also specified in ISO 12232:2019; EMVA Standard 1288 Release 4.0 linear camera model,\n * where the system gain K in DN/e- multiplies the electron signal):\n *   R = S / S0                      exposure-index ratio to the base exposure index S0\n *   a = min(R, A_max)               analog (pre-ADC) gain relative to the base regime\n *   d = R / a                       post-ADC digital gain beyond the analog range\n *   g(S) = Q0 / (span * a)          electrons per code (1/K), span = digitalSaturation - black\n *   Q_preADC(S) = Q0 / a            electrons that drive the ADC to digital saturation\n * So the electrons needed to reach digital saturation are Q0 * S0 / S.\n *\n * The exposure indices of CIPA DC-004 put the reference exposure H_ref in proportion to 1/S: standard\n * output sensitivity (SOS) and REI (recommended exposure index) both use S = 10 / H (§3.2, §3.3). So a\n * correct exposure for S gives the same black-subtracted fraction of digital saturation at every S.\n *\n * Read noise in electrons is declared per conversion-gain mode, never derived from S. (With dual\n * conversion gain, the high-conversion-gain mode used at high S has lower input-referred read noise.)\n *\n * Inputs are explicit declarations; Photivra presets use synthetic teaching values. No camera\n * calibration is implied.\n * @see docs/MOTION_AND_SIGNAL.md for equations, sources and limits.\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { parseEvidenceList, type EvidenceBackedFact, type EvidenceProvenance } from \"../core/evidence-provenance.js\";\nimport { requireAllowlistedRecord, requirePublicOpaqueId } from \"../core/record-validation.js\";\nimport { parseSensorReadoutConversionProfile, type SensorReadoutConversionRegime,\n  type SensorReadoutExposureIndexGain } from \"./raw-readout.js\";\nimport type { GenericIsoStandardRegimeBand } from \"./iso-signal-chain.js\";\nimport type { SensorSpectralResponseScientificStatus } from \"./spectral-response.js\";\n\n/** One conversion-gain mode, active from its minimum exposure index up to the next mode's. */\nexport interface IsoGainConversionGainMode {\n  mode: SensorReadoutExposureIndexGain[\"conversionGainMode\"];\n  minimumExposureIndex: number;\n  readNoiseRmsElectrons: EvidenceBackedFact<number>;\n  /** Optional charge storage limit of this mode. Every regime's pre-ADC threshold must be at or below it. */\n  maximumChargeElectrons?: EvidenceBackedFact<number>;\n}\n\nexport interface CreateIsoGainReadoutRegimesInput {\n  regimeIdPrefix: string;\n  scientificStatus: SensorSpectralResponseScientificStatus;\n  baseExposureIndex: number;\n  /** Strictly increasing settings, each at least the base exposure index. */\n  exposureIndices: readonly number[];\n  /** Q0: electron-equivalent signal that reaches digital saturation at the base exposure index. */\n  baseSaturationElectronEquivalent: EvidenceBackedFact<number>;\n  /** A_max: largest analog gain relative to the base regime (>= 1). */\n  maximumAnalogGain: EvidenceBackedFact<number>;\n  adc: { bitDepth: number; blackLevelCode: number; digitalSaturationCode: number };\n  conversionGainModes: readonly IsoGainConversionGainMode[];\n  evidence: readonly EvidenceProvenance[];\n  limitations: readonly string[];\n}\n\nexport interface IsoGainReadoutRegimes {\n  regimes: readonly SensorReadoutConversionRegime[];\n  /** One single-value band per setting, ready for a GenericIsoSignalChainProfile. */\n  standardRegimeBands: readonly GenericIsoStandardRegimeBand[];\n}\n\nfunction positive(value: unknown, path: string): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value <= 0) {\n    throw new InvalidConfigurationError(path + \" must be finite and greater than zero.\");\n  }\n  return value;\n}\n\nfunction positiveFact(value: unknown, path: string): EvidenceBackedFact<number> {\n  const r = requireAllowlistedRecord(value, [\"value\", \"evidence\"], path + \" must be an evidence-backed fact.\");\n  return { value: positive(r.value, path + \".value\"), evidence: parseEvidenceList(r.evidence, path + \".evidence\") };\n}\n\n/**\n * Builds a readout regime and signal-chain band for each exposure index (see the module comment\n * for the equations). The result is checked with the same rules as parseSensorReadoutConversionProfile.\n * Each regime carries an `exposureIndexGain` record of how it was derived.\n * @param input - The sensor parameters and ISO settings; untrusted values are validated.\n * @returns The readout regimes and bands.\n */\nexport function createIsoGainReadoutRegimes(input: CreateIsoGainReadoutRegimesInput): IsoGainReadoutRegimes {\n  const r = requireAllowlistedRecord(input, [\"regimeIdPrefix\", \"scientificStatus\", \"baseExposureIndex\", \"exposureIndices\",\n    \"baseSaturationElectronEquivalent\", \"maximumAnalogGain\", \"adc\", \"conversionGainModes\", \"evidence\", \"limitations\"],\n  \"Invalid ISO gain readout fields.\");\n  const prefix = r.regimeIdPrefix === \"\" ? \"\" : requirePublicOpaqueId(r.regimeIdPrefix, \"regimeIdPrefix must be empty or a public opaque identifier.\");\n  const base = positive(r.baseExposureIndex, \"baseExposureIndex\");\n  const q0 = positiveFact(r.baseSaturationElectronEquivalent, \"baseSaturationElectronEquivalent\");\n  const aMax = positiveFact(r.maximumAnalogGain, \"maximumAnalogGain\");\n  if (aMax.value < 1) throw new InvalidConfigurationError(\"maximumAnalogGain must be at least 1.\");\n  const evidence = parseEvidenceList(r.evidence, \"evidence\");\n  const adc = requireAllowlistedRecord(r.adc, [\"bitDepth\", \"blackLevelCode\", \"digitalSaturationCode\"], \"Invalid ISO gain ADC fields.\");\n  if (!Array.isArray(r.exposureIndices) || r.exposureIndices.length === 0 || r.exposureIndices.length > 256) {\n    throw new InvalidConfigurationError(\"exposureIndices must contain 1 through 256 settings.\");\n  }\n  const indices = r.exposureIndices.map((value: unknown, i: number) => positive(value, \"exposureIndices[\" + i + \"]\"));\n  if (indices[0]! < base || indices.some((value, i) => i > 0 && value <= indices[i - 1]!)) {\n    throw new InvalidConfigurationError(\"exposureIndices must strictly increase from at least the base exposure index.\");\n  }\n  if (!Array.isArray(r.conversionGainModes) || r.conversionGainModes.length === 0 || r.conversionGainModes.length > 8) {\n    throw new InvalidConfigurationError(\"conversionGainModes must contain 1 through 8 modes.\");\n  }\n  const modes = r.conversionGainModes.map((value: unknown, i: number) => {\n    const m = requireAllowlistedRecord(value, [\"mode\", \"minimumExposureIndex\", \"readNoiseRmsElectrons\", \"maximumChargeElectrons\"],\n      \"Invalid conversion-gain mode fields.\");\n    if (m.mode !== \"single-conversion-gain\" && m.mode !== \"low-conversion-gain\" && m.mode !== \"high-conversion-gain\") {\n      throw new InvalidConfigurationError(\"conversionGainModes[\" + i + \"].mode is invalid.\");\n    }\n    const noise = requireAllowlistedRecord(m.readNoiseRmsElectrons, [\"value\", \"evidence\"], \"Invalid read-noise fact.\");\n    if (typeof noise.value !== \"number\" || !Number.isFinite(noise.value) || noise.value < 0) {\n      throw new InvalidConfigurationError(\"conversionGainModes[\" + i + \"].readNoiseRmsElectrons.value must be finite and nonnegative.\");\n    }\n    return { mode: m.mode as IsoGainConversionGainMode[\"mode\"],\n      minimumExposureIndex: positive(m.minimumExposureIndex, \"conversionGainModes[\" + i + \"].minimumExposureIndex\"),\n      readNoiseRmsElectrons: { value: noise.value, evidence: parseEvidenceList(noise.evidence, \"readNoiseRmsElectrons.evidence\") },\n      ...(m.maximumChargeElectrons === undefined ? {} :\n        { maximumChargeElectrons: positiveFact(m.maximumChargeElectrons, \"conversionGainModes[\" + i + \"].maximumChargeElectrons\") }) };\n  });\n  if (modes[0]!.minimumExposureIndex !== base || modes.some((m, i) => i > 0 && m.minimumExposureIndex <= modes[i - 1]!.minimumExposureIndex)) {\n    throw new InvalidConfigurationError(\"conversionGainModes must start at the base exposure index and strictly increase.\");\n  }\n  const gainEvidence = [...q0.evidence, ...aMax.evidence].filter((entry, i, all) =>\n    all.findIndex((other) => JSON.stringify(other) === JSON.stringify(entry)) === i);\n  const black = adc.blackLevelCode as number, saturation = adc.digitalSaturationCode as number;\n  const span = saturation - black;\n  const regimes = indices.map((exposureIndex) => {\n    const ratio = exposureIndex / base;\n    const analogGain = Math.min(ratio, aMax.value);\n    const digitalGain = ratio / analogGain;\n    const mode = modes.filter((m) => m.minimumExposureIndex <= exposureIndex).pop()!;\n    const preAdc = q0.value / analogGain;\n    if (mode.maximumChargeElectrons !== undefined && preAdc > mode.maximumChargeElectrons.value) {\n      throw new InvalidConfigurationError(\"A \" + mode.mode + \" regime would need more charge than its declared storage limit.\");\n    }\n    const regimeEvidence = [...evidence];\n    return {\n      regimeId: prefix + \"iso-\" + exposureIndex,\n      scientificStatus: r.scientificStatus as SensorSpectralResponseScientificStatus,\n      systemConversionGainElectronsPerCode: { value: preAdc / span, evidence: gainEvidence },\n      preAdcSaturationElectronEquivalent: { value: preAdc, evidence: gainEvidence },\n      readNoiseComponents: [{ componentId: \"electronic\", rmsElectrons: mode.readNoiseRmsElectrons, evidence: mode.readNoiseRmsElectrons.evidence }],\n      adc: { bitDepth: adc.bitDepth as number, blackLevelCode: black, digitalSaturationCode: saturation, transfer: \"uniform-round-half-up\" as const,\n        ...(digitalGain === 1 ? {} : { digitalGain }) },\n      exposureIndexGain: { exposureIndex, baseExposureIndex: base, analogGain, digitalGain, conversionGainMode: mode.mode, evidence: regimeEvidence },\n      evidence: regimeEvidence,\n      limitations: r.limitations as readonly string[]\n    };\n  });\n  // Reuse the regime parser to check the ADC, limitations and consistency.\n  const parsed = parseSensorReadoutConversionProfile({ schemaVersion: \"0.1.0\", profileId: prefix + \"validation\", colorSamplingProfileId: \"validation\",\n    channelId: \"validation\", regimeSelectionOwnedBy: \"explicit-upstream-camera-state-not-inferred-from-iso\", regimes, evidence }).regimes;\n  return { regimes: parsed, standardRegimeBands: indices.map((exposureIndex, i) => ({ minimumExposureIndex: exposureIndex,\n    maximumExposureIndex: exposureIndex, readoutRegimeId: parsed[i]!.regimeId })) };\n}\n"]}

package/dist/sensor/iso-signal-chain.d.ts

@@ -72,69 +72,47 @@ export interface GenericIsoSignalChainPresetCatalog {
     realCameraRankingClaimed: false;
 }
 /**
- * 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.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns GenericIsoSignalChainProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The profile binds each ISO and capture-mode state to an explicit readout regime, whose gain,
+ * read noise and clipping are declared separately.
+ * @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 declare function parseGenericIsoSignalChainProfile(value: unknown): GenericIsoSignalChainProfile;
 /**
- * Select the explicit readout regime bound to the resolved ISO and capture-mode state; do not derive
- * gain/noise from an ISO number.
+ * Picks the explicit readout regime bound to the resolved ISO and capture-mode state. Gain and noise
+ * are never derived from the ISO number.
+ * @param input - The input; see `ResolveGenericIsoSignalChainInput` for its fields, units and coordinates.
+ * @returns The result. Success does not imply 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.
- * @param input - ResolveGenericIsoSignalChainInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ResolvedGenericIsoSignalChain. 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 declare function resolveGenericIsoSignalChain(input: ResolveGenericIsoSignalChainInput): ResolvedGenericIsoSignalChain;
 /**
- * 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.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns GenericIsoSignalChainPresetCatalog. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Generic tier labels in the catalogue do not calibrate or rank real cameras.
+ * @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 declare function parseGenericIsoSignalChainPresetCatalog(value: unknown): GenericIsoSignalChainPresetCatalog;
 /**
- * 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.
- * @param input - {
-    catalog:
-      GenericIsoSignalChainPresetCatalog;
-    preset:
-      GenericIsoSignalChainPreset;
-  }. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns {
-  preset:
-    GenericIsoSignalChainPreset;
-  signalChainProfileId:
-    string;
-  performanceOrderingClaimed:
-    false;
-  realCameraRankingClaimed:
-    false;
-}. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Generic tier labels do not calibrate or rank real cameras.
+ * @param input - The preset catalogue and the chosen preset.
+ * @returns The preset and its signal-chain profile ID. `performanceOrderingClaimed` and
+ *   `realCameraRankingClaimed` are always false. 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 declare function resolveGenericIsoSignalChainPreset(input: {
     catalog: GenericIsoSignalChainPresetCatalog;
@@ -145,4 +123,3 @@ export declare function resolveGenericIsoSignalChainPreset(input: {
     performanceOrderingClaimed: false;
     realCameraRankingClaimed: false;
 };
-//# sourceMappingURL=iso-signal-chain.d.ts.map

package/dist/sensor/iso-signal-chain.js

@@ -1,15 +1,11 @@
 // 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. 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.
- * 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.
+ * ISO signal chain: picks the explicit readout regime (gain, read noise, clipping) that belongs to the
+ * selected ISO and capture mode.
+ *
+ * Gain and noise are never derived from the ISO number itself; each regime is declared. Photons and
+ * photo or dark shot noise are computed earlier in the chain. Generic tier labels do not calibrate or
+ * rank real cameras.
  * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
  * limits.
  */
@@ -18,14 +14,17 @@ import { parseEvidenceList } from "../core/evidence-provenance.js";
 import { InvalidScientificInputError } from "../core/validation.js";
 import { parseIsoCapabilityProfile, resolveIsoCapability } from "../equipment/iso-capabilities.js";
 import { parseSensorReadoutConversionProfile, resolveSensorReadoutRegime } from "./raw-readout.js";
+import { requireInputKeys, rejectUnknownFields } from "../core/record-validation.js";
 export const GENERIC_ISO_SIGNAL_CHAIN_PROFILE_SCHEMA_VERSION = "0.1.0";
 export const GENERIC_ISO_SIGNAL_CHAIN_PRESET_CATALOG_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) {
@@ -61,7 +60,7 @@ function parseLimitations(value, path) {
     return parsed;
 }
 function parseStandardBand(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, ["minimumExposureIndex", "maximumExposureIndex", "readoutRegimeId"]);
     const minimumExposureIndex = requirePositiveFinite(record.minimumExposureIndex, path +
         ".minimumExposureIndex");
     const maximumExposureIndex = requirePositiveFinite(record.maximumExposureIndex, path +
@@ -79,7 +78,7 @@ function parseStandardBand(value, path) {
     };
 }
 function parseCaptureModeBinding(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, ["standardRegimeBands", "expandedRegimeBindings", "captureModeId", "evidence"]);
     if (!Array.isArray(record.standardRegimeBands) ||
         record.standardRegimeBands
             .length === 0) {
@@ -109,7 +108,7 @@ function parseCaptureModeBinding(value, path) {
             ".expandedRegimeBindings[" +
             index +
             "]";
-        const binding = requireRecord(entry, entryPath);
+        const binding = requireRecord(entry, entryPath, ["expandedSettingId", "readoutRegimeId"]);
         return {
             expandedSettingId: requireNonEmptyString(binding.expandedSettingId, entryPath +
                 ".expandedSettingId"),
@@ -131,19 +130,18 @@ function parseCaptureModeBinding(value, path) {
     };
 }
 /**
- * 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.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns GenericIsoSignalChainProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The profile binds each ISO and capture-mode state to an explicit readout regime, whose gain,
+ * read noise and clipping are declared separately.
+ * @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 parseGenericIsoSignalChainProfile(value) {
-    const record = requireRecord(value, "genericIsoSignalChainProfile");
+    const record = requireRecord(value, "genericIsoSignalChainProfile", ["schemaVersion", "scientificStatus", "behaviorMeaning", "photonShotNoiseOwnedUpstream", "processedImageBehaviorIncluded", "fixedPatternNoiseModeled", "lowSignalColorDegradationModeled", "captureModeBindings", "profileId", "profileVersion", "isoCapabilityProfileId", "readoutProfileId", "evidence", "limitations"]);
     if (record.schemaVersion !==
         GENERIC_ISO_SIGNAL_CHAIN_PROFILE_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('genericIsoSignalChainProfile.schemaVersion must be "' +
@@ -236,18 +234,15 @@ function regimeIdForIso(binding, iso) {
     };
 }
 /**
- * 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.
- * @param input - ResolveGenericIsoSignalChainInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ResolvedGenericIsoSignalChain. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Picks the explicit readout regime bound to the resolved ISO and capture-mode state. Gain and noise
+ * are never derived from the ISO number.
+ * @param input - The input; see `ResolveGenericIsoSignalChainInput` 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 resolveGenericIsoSignalChain(input) {
+    requireInputKeys(input, "resolveGenericIsoSignalChain", ["profile", "isoCapability", "requestedIsoSetting", "captureModeId", "readoutProfile"]);
     const profile = parseGenericIsoSignalChainProfile(input.profile);
     const isoCapability = parseIsoCapabilityProfile(input.isoCapability);
     const readoutProfile = parseSensorReadoutConversionProfile(input.readoutProfile);
@@ -263,7 +258,7 @@ export function resolveGenericIsoSignalChain(input) {
         "string" ||
         input.captureModeId.trim()
             .length === 0) {
-        throw new InvalidScientificInputError("captureModeId must be a non-empty string.");
+        throw new InvalidConfigurationError("captureModeId must be a non-empty string.");
     }
     const binding = profile.captureModeBindings.find((entry) => entry.captureModeId ===
         input.captureModeId);
@@ -281,6 +276,13 @@ export function resolveGenericIsoSignalChain(input) {
         profile: readoutProfile,
         regimeId: regime.regimeId
     });
+    const gain = readout.regime
+        .exposureIndexGain;
+    if (gain !== undefined &&
+        gain.exposureIndex !==
+            iso.reportedExposureIndex) {
+        throw new InvalidScientificInputError("The bound readout regime declares an ISO-gain derivation for a different exposure index.");
+    }
     return {
         profileId: profile.profileId,
         profileVersion: profile.profileVersion,
@@ -305,19 +307,17 @@ const PRESETS = new Set([
     "best"
 ]);
 /**
- * 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.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns GenericIsoSignalChainPresetCatalog. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Generic tier labels in the catalogue do not calibrate or rank real cameras.
+ * @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 parseGenericIsoSignalChainPresetCatalog(value) {
-    const record = requireRecord(value, "genericIsoSignalChainPresetCatalog");
+    const record = requireRecord(value, "genericIsoSignalChainPresetCatalog", ["schemaVersion", "performanceOrderingClaimed", "realCameraRankingClaimed", "entries", "catalogId", "catalogVersion"]);
     if (record.schemaVersion !==
         GENERIC_ISO_SIGNAL_CHAIN_PRESET_CATALOG_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('genericIsoSignalChainPresetCatalog.schemaVersion must be "' +
@@ -338,7 +338,7 @@ export function parseGenericIsoSignalChainPresetCatalog(value) {
         const path = "genericIsoSignalChainPresetCatalog.entries[" +
             index +
             "]";
-        const parsed = requireRecord(entry, path);
+        const parsed = requireRecord(entry, path, ["preset", "signalChainProfileId", "evidence"]);
         if (typeof parsed.preset !==
             "string" ||
             !PRESETS.has(parsed.preset)) {
@@ -368,35 +368,21 @@ export function parseGenericIsoSignalChainPresetCatalog(value) {
     };
 }
 /**
- * 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.
- * @param input - {
-    catalog:
-      GenericIsoSignalChainPresetCatalog;
-    preset:
-      GenericIsoSignalChainPreset;
-  }. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns {
-  preset:
-    GenericIsoSignalChainPreset;
-  signalChainProfileId:
-    string;
-  performanceOrderingClaimed:
-    false;
-  realCameraRankingClaimed:
-    false;
-}. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Generic tier labels do not calibrate or rank real cameras.
+ * @param input - The preset catalogue and the chosen preset.
+ * @returns The preset and its signal-chain profile ID. `performanceOrderingClaimed` and
+ *   `realCameraRankingClaimed` are always false. 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 resolveGenericIsoSignalChainPreset(input) {
+    requireInputKeys(input, "resolveGenericIsoSignalChainPreset", ["catalog", "preset"]);
     const catalog = parseGenericIsoSignalChainPresetCatalog(input.catalog);
     if (!PRESETS.has(input.preset)) {
-        throw new InvalidScientificInputError("preset must be good, better, or best.");
+        throw new InvalidConfigurationError("preset must be good, better, or best.");
     }
     const entry = catalog.entries.find((candidate) => candidate.preset ===
         input.preset);