@photivra/engine 0.6.0 → 1.0.0

package/dist/sensor/accumulated-charge.d.ts

@@ -0,0 +1,199 @@
+/**
+ * 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. Photo, dark and
+ * explicitly incremental stored-electron components must share the exact site/channel/local shutter
+ * event. Completeness is an evidence-backed declaration, not the consequence of an empty component
+ * array. Expected stored charge remains distinct from a stochastic realization or nonlinear full-well
+ * clamp.
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary. Photo, dark and
+ * explicitly incremental stored-electron components must share the exact site/channel/local shutter
+ * event. Completeness is an evidence-backed declaration, not the consequence of an empty component
+ * array. Expected stored charge remains distinct from a stochastic realization or nonlinear full-well
+ * clamp.
+ * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
+ * limits.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type EvidenceProvenance } from "../core/evidence-provenance.js";
+import type { SensorEqeExposureIntegration } from "./constant-rate-temporal-integration.js";
+import type { SensorEqePhotoExposure, SensorEqeTemporalPhotoSignal } from "./temporal-photo-signal.js";
+import type { SensorPhotoDarkCurrentCharge, SensorDarkCurrentCharge, SensorTemporalDarkCurrentCharge } from "./dark-current.js";
+import type { SensorSpectralResponseScientificStatus, SensorSpectralResponseUncertainty } from "./spectral-response.js";
+export type SensorAdditionalStoredChargeKind = "hot-pixel-defect-excess" | "leakage" | "charge-injection" | "clock-induced-charge" | "other";
+export interface SensorAdditionalStoredChargeComponent {
+    componentId: string;
+    kind: SensorAdditionalStoredChargeKind;
+    colorSamplingProfileId: string;
+    channelId: string;
+    site: {
+        x: number;
+        y: number;
+    };
+    bindingId: string;
+    timeReference: "first-opening-boundary-phase";
+    startOffsetSecondsFromOpeningReference: number;
+    endOffsetSecondsFromOpeningReference: number;
+    accountingMeaning: "incremental-stored-electrons-beyond-photo-and-modeled-dark-current";
+    expectedElectronCount: number;
+    scientificStatus: SensorSpectralResponseScientificStatus;
+    uncertainty: SensorSpectralResponseUncertainty;
+    evidence: readonly EvidenceProvenance[];
+}
+export interface SensorAccumulatedChargeCompletenessProfile {
+    schemaVersion: "0.1.0";
+    profileId: string;
+    colorSamplingProfileId: string;
+    channelId: string;
+    site: {
+        x: number;
+        y: number;
+    };
+    bindingId: string;
+    timeReference: "first-opening-boundary-phase";
+    startOffsetSecondsFromOpeningReference: number;
+    endOffsetSecondsFromOpeningReference: number;
+    darkCurrentProfileId: string;
+    includedAdditionalComponentIds: readonly string[];
+    coverageMeaning: "all-material-stored-electron-contributors-accounted-for";
+    scientificStatus: SensorSpectralResponseScientificStatus;
+    evidence: readonly EvidenceProvenance[];
+    limitation?: string;
+}
+export interface ComposeSensorAccumulatedChargeInput<Photo extends SensorEqePhotoExposure = SensorEqeExposureIntegration, Dark extends SensorPhotoDarkCurrentCharge = SensorDarkCurrentCharge> {
+    photoSignal: Photo;
+    darkCharge: Dark;
+    additionalChargeComponents?: readonly SensorAdditionalStoredChargeComponent[];
+    completenessProfile: SensorAccumulatedChargeCompletenessProfile;
+}
+export type ComposeSensorPhotoAccumulatedChargeInput = ComposeSensorAccumulatedChargeInput<SensorEqePhotoExposure, SensorPhotoDarkCurrentCharge>;
+export interface SensorAccumulatedChargeComposition<Photo extends SensorEqePhotoExposure = SensorEqeExposureIntegration, Dark extends SensorPhotoDarkCurrentCharge = SensorDarkCurrentCharge> {
+    completenessProfileId: string;
+    colorSamplingProfileId: string;
+    channelId: string;
+    site: {
+        x: number;
+        y: number;
+    };
+    bindingId: string;
+    timeReference: "first-opening-boundary-phase";
+    startOffsetSecondsFromOpeningReference: number;
+    endOffsetSecondsFromOpeningReference: number;
+    localExposureDurationSeconds: number;
+    photoExpectedElectronCount: number;
+    darkExpectedElectronCount: number;
+    additionalExpectedElectronCount: number;
+    totalExpectedStoredElectronCount: number;
+    additionalComponents: readonly {
+        componentId: string;
+        kind: SensorAdditionalStoredChargeKind;
+        expectedElectronCount: number;
+        scientificStatus: SensorSpectralResponseScientificStatus;
+        uncertainty: SensorSpectralResponseUncertainty;
+        evidence: readonly EvidenceProvenance[];
+    }[];
+    accumulatedChargeCompleteness: "complete-for-physical-storage-capacity-assessment";
+    completenessScientificStatus: SensorSpectralResponseScientificStatus;
+    allCountsAreExpectationValues: true;
+    integerChargeSampled: false;
+    photoSignalIncluded: true;
+    darkChargeIncluded: true;
+    otherChargeIncluded: boolean;
+    darkShotNoiseApplied: false;
+    photoShotNoiseApplied: false;
+    readNoiseApplied: false;
+    physicalFullWellAssessmentAuthorized: true;
+    cameraSaturationAssessmentAuthorized: false;
+    saturationAssessed: false;
+    bloomingModeled: false;
+    adcQuantizationApplied: false;
+    rawCodeValueProduced: false;
+    componentEvidence: {
+        completeness: readonly EvidenceProvenance[];
+        photoSignal: Photo["componentEvidence"];
+        darkCurrent: Dark["componentEvidence"];
+    };
+}
+export type SensorPhotoAccumulatedChargeComposition = SensorAccumulatedChargeComposition<SensorEqePhotoExposure, SensorPhotoDarkCurrentCharge>;
+/**
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary.
+ *
+ * Photo, dark and explicitly incremental stored-electron components must share the exact
+ * site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
+ * consequence of an empty component array. Expected stored charge remains distinct from a stochastic
+ * realization or nonlinear full-well clamp.
+ * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
+ * @returns SensorAdditionalStoredChargeComponent. 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.
+ */
+export declare function parseSensorAdditionalStoredChargeComponent(value: unknown): SensorAdditionalStoredChargeComponent;
+/**
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary.
+ *
+ * Photo, dark and explicitly incremental stored-electron components must share the exact
+ * site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
+ * consequence of an empty component array. Expected stored charge remains distinct from a stochastic
+ * realization or nonlinear full-well clamp.
+ * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
+ * @returns SensorAccumulatedChargeCompletenessProfile. 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.
+ */
+export declare function parseSensorAccumulatedChargeCompletenessProfile(value: unknown): SensorAccumulatedChargeCompletenessProfile;
+/**
+ * Compose photo, independently evaluated dark and explicitly incremental charge by exact local
+ * exposure identity, retaining completeness assessment before capacity/noise.
+ *
+ * Photo, dark and explicitly incremental stored-electron components must share the exact
+ * site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
+ * consequence of an empty component array. Expected stored charge remains distinct from a stochastic
+ * realization or nonlinear full-well clamp.
+ * @param input - Omit<ComposeSensorAccumulatedChargeInput, "photoSignal" | "darkCharge"> & {
+    photoSignal: SensorEqeExposureIntegration; darkCharge: SensorDarkCurrentCharge;
+  }. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns CalculationResult<SensorAccumulatedChargeComposition>. 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.
+ */
+export declare function composeSensorAccumulatedCharge(input: Omit<ComposeSensorAccumulatedChargeInput, "photoSignal" | "darkCharge"> & {
+    photoSignal: SensorEqeExposureIntegration;
+    darkCharge: SensorDarkCurrentCharge;
+}): CalculationResult<SensorAccumulatedChargeComposition>;
+/**
+ * Compose photo, independently evaluated dark and explicitly incremental charge by exact local
+ * exposure identity, retaining completeness assessment before capacity/noise.
+ *
+ * Photo, dark and explicitly incremental stored-electron components must share the exact
+ * site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
+ * consequence of an empty component array. Expected stored charge remains distinct from a stochastic
+ * realization or nonlinear full-well clamp.
+ * @param input - Omit<ComposeSensorAccumulatedChargeInput, "photoSignal" | "darkCharge"> & {
+    photoSignal: SensorEqeTemporalPhotoSignal; darkCharge: SensorTemporalDarkCurrentCharge;
+  }. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns CalculationResult<SensorAccumulatedChargeComposition<SensorEqeTemporalPhotoSignal, SensorTemporalDarkCurrentCharge>>. 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.
+ */
+export declare function composeSensorAccumulatedCharge(input: Omit<ComposeSensorAccumulatedChargeInput, "photoSignal" | "darkCharge"> & {
+    photoSignal: SensorEqeTemporalPhotoSignal;
+    darkCharge: SensorTemporalDarkCurrentCharge;
+}): CalculationResult<SensorAccumulatedChargeComposition<SensorEqeTemporalPhotoSignal, SensorTemporalDarkCurrentCharge>>;
+/**
+ * Compose photo, independently evaluated dark and explicitly incremental charge by exact local
+ * exposure identity, retaining completeness assessment before capacity/noise.
+ *
+ * Photo, dark and explicitly incremental stored-electron components must share the exact
+ * site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
+ * consequence of an empty component array. Expected stored charge remains distinct from a stochastic
+ * realization or nonlinear full-well clamp.
+ * @param input - ComposeSensorPhotoAccumulatedChargeInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns CalculationResult<SensorPhotoAccumulatedChargeComposition>. 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.
+ */
+export declare function composeSensorAccumulatedCharge(input: ComposeSensorPhotoAccumulatedChargeInput): CalculationResult<SensorPhotoAccumulatedChargeComposition>;
+//# sourceMappingURL=accumulated-charge.d.ts.map

package/dist/sensor/accumulated-charge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accumulated-charge.d.ts","sourceRoot":"","sources":["../../src/sensor/accumulated-charge.ts"],"names":[],"mappings":"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"}

package/dist/sensor/accumulated-charge.js

@@ -0,0 +1,450 @@
+// 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. Photo, dark and
+ * explicitly incremental stored-electron components must share the exact site/channel/local shutter
+ * event. Completeness is an evidence-backed declaration, not the consequence of an empty component
+ * array. Expected stored charge remains distinct from a stochastic realization or nonlinear full-well
+ * clamp.
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary. Photo, dark and
+ * explicitly incremental stored-electron components must share the exact site/channel/local shutter
+ * event. Completeness is an evidence-backed declaration, not the consequence of an empty component
+ * array. Expected stored charge remains distinct from a stochastic realization or nonlinear full-well
+ * clamp.
+ * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
+ * limits.
+ */
+import { approximationResult, calculatedResult } from "../core/calculation-result.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { parseEvidenceList } from "../core/evidence-provenance.js";
+import { parseSensorEqeTemporalPhotoSignal } from "./temporal-photo-signal.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+function addCompensated(state, value) {
+    const adjusted = value - state.correction;
+    const next = state.sum + adjusted;
+    state.correction =
+        (next - state.sum) - adjusted;
+    state.sum = next;
+}
+function requireRecord(value, path) {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value)) {
+        throw new InvalidConfigurationError(path + " must be an object.");
+    }
+    return value;
+}
+function requireNonEmptyString(value, path) {
+    if (typeof value !== "string" ||
+        value.trim().length === 0) {
+        throw new InvalidConfigurationError(path + " must be a non-empty string.");
+    }
+    return value;
+}
+function requireFinite(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value)) {
+        throw new InvalidConfigurationError(path + " must be finite.");
+    }
+    return value;
+}
+function requireNonNegativeFinite(value, path) {
+    const parsed = requireFinite(value, path);
+    if (parsed < 0) {
+        throw new InvalidConfigurationError(path +
+            " must be greater than or equal to zero.");
+    }
+    return parsed;
+}
+function requireSiteIndex(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value < 0) {
+        throw new InvalidConfigurationError(path +
+            " must be a non-negative safe integer.");
+    }
+    return value;
+}
+function parseUncertainty(value, path) {
+    const record = requireRecord(value, path);
+    if (record.kind === "relative") {
+        const fraction = requireNonNegativeFinite(record.fraction, path + ".fraction");
+        return {
+            kind: "relative",
+            fraction,
+            basis: requireNonEmptyString(record.basis, path + ".basis")
+        };
+    }
+    if (record.kind === "not-quantified") {
+        return {
+            kind: "not-quantified",
+            limitation: requireNonEmptyString(record.limitation, path + ".limitation")
+        };
+    }
+    throw new InvalidConfigurationError(path + ".kind is invalid.");
+}
+function parseStatus(value, path) {
+    if (value !== "calibrated" &&
+        value !== "approximation") {
+        throw new InvalidConfigurationError(path + " is invalid.");
+    }
+    return value;
+}
+function parseWindowIdentity(record, path) {
+    if (record.timeReference !==
+        "first-opening-boundary-phase") {
+        throw new InvalidConfigurationError(path +
+            '.timeReference must be "first-opening-boundary-phase".');
+    }
+    const start = requireFinite(record.startOffsetSecondsFromOpeningReference, path +
+        ".startOffsetSecondsFromOpeningReference");
+    const end = requireFinite(record.endOffsetSecondsFromOpeningReference, path +
+        ".endOffsetSecondsFromOpeningReference");
+    if (!(end > start)) {
+        throw new InvalidConfigurationError(path +
+            " exposure window end must be greater than start.");
+    }
+    return {
+        bindingId: requireNonEmptyString(record.bindingId, path + ".bindingId"),
+        timeReference: "first-opening-boundary-phase",
+        start,
+        end
+    };
+}
+/**
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary.
+ *
+ * Photo, dark and explicitly incremental stored-electron components must share the exact
+ * site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
+ * consequence of an empty component array. Expected stored charge remains distinct from a stochastic
+ * realization or nonlinear full-well clamp.
+ * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
+ * @returns SensorAdditionalStoredChargeComponent. 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.
+ */
+export function parseSensorAdditionalStoredChargeComponent(value) {
+    const record = requireRecord(value, "sensorAdditionalStoredCharge");
+    const kinds = new Set([
+        "hot-pixel-defect-excess",
+        "leakage",
+        "charge-injection",
+        "clock-induced-charge",
+        "other"
+    ]);
+    if (typeof record.kind !== "string" ||
+        !kinds.has(record.kind)) {
+        throw new InvalidConfigurationError("sensorAdditionalStoredCharge.kind is invalid.");
+    }
+    if (record.accountingMeaning !==
+        "incremental-stored-electrons-beyond-photo-and-modeled-dark-current") {
+        throw new InvalidConfigurationError("sensorAdditionalStoredCharge.accountingMeaning is invalid.");
+    }
+    const site = requireRecord(record.site, "sensorAdditionalStoredCharge.site");
+    const window = parseWindowIdentity(record, "sensorAdditionalStoredCharge");
+    const scientificStatus = parseStatus(record.scientificStatus, "sensorAdditionalStoredCharge.scientificStatus");
+    const uncertainty = parseUncertainty(record.uncertainty, "sensorAdditionalStoredCharge.uncertainty");
+    if (scientificStatus === "calibrated" &&
+        uncertainty.kind ===
+            "not-quantified") {
+        throw new InvalidConfigurationError("A calibrated additional stored-charge component must declare quantified relative uncertainty.");
+    }
+    return {
+        componentId: requireNonEmptyString(record.componentId, "sensorAdditionalStoredCharge.componentId"),
+        kind: record.kind,
+        colorSamplingProfileId: requireNonEmptyString(record.colorSamplingProfileId, "sensorAdditionalStoredCharge.colorSamplingProfileId"),
+        channelId: requireNonEmptyString(record.channelId, "sensorAdditionalStoredCharge.channelId"),
+        site: {
+            x: requireSiteIndex(site.x, "sensorAdditionalStoredCharge.site.x"),
+            y: requireSiteIndex(site.y, "sensorAdditionalStoredCharge.site.y")
+        },
+        bindingId: window.bindingId,
+        timeReference: window.timeReference,
+        startOffsetSecondsFromOpeningReference: window.start,
+        endOffsetSecondsFromOpeningReference: window.end,
+        accountingMeaning: "incremental-stored-electrons-beyond-photo-and-modeled-dark-current",
+        expectedElectronCount: requireNonNegativeFinite(record.expectedElectronCount, "sensorAdditionalStoredCharge.expectedElectronCount"),
+        scientificStatus,
+        uncertainty,
+        evidence: parseEvidenceList(record.evidence, "sensorAdditionalStoredCharge.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.
+ *
+ * Photo, dark and explicitly incremental stored-electron components must share the exact
+ * site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
+ * consequence of an empty component array. Expected stored charge remains distinct from a stochastic
+ * realization or nonlinear full-well clamp.
+ * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
+ * @returns SensorAccumulatedChargeCompletenessProfile. 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.
+ */
+export function parseSensorAccumulatedChargeCompletenessProfile(value) {
+    const record = requireRecord(value, "sensorAccumulatedChargeCompleteness");
+    if (record.schemaVersion !== "0.1.0") {
+        throw new InvalidConfigurationError('sensorAccumulatedChargeCompleteness.schemaVersion must be "0.1.0".');
+    }
+    if (record.coverageMeaning !==
+        "all-material-stored-electron-contributors-accounted-for") {
+        throw new InvalidConfigurationError("sensorAccumulatedChargeCompleteness.coverageMeaning is invalid.");
+    }
+    const site = requireRecord(record.site, "sensorAccumulatedChargeCompleteness.site");
+    const window = parseWindowIdentity(record, "sensorAccumulatedChargeCompleteness");
+    const scientificStatus = parseStatus(record.scientificStatus, "sensorAccumulatedChargeCompleteness.scientificStatus");
+    const limitation = record.limitation === undefined
+        ? undefined
+        : requireNonEmptyString(record.limitation, "sensorAccumulatedChargeCompleteness.limitation");
+    if (scientificStatus === "approximation" &&
+        limitation === undefined) {
+        throw new InvalidConfigurationError("sensorAccumulatedChargeCompleteness.limitation is required for an approximation.");
+    }
+    if (!Array.isArray(record.includedAdditionalComponentIds)) {
+        throw new InvalidConfigurationError("sensorAccumulatedChargeCompleteness.includedAdditionalComponentIds must be an array.");
+    }
+    const ids = record.includedAdditionalComponentIds.map((entry, index) => requireNonEmptyString(entry, "sensorAccumulatedChargeCompleteness.includedAdditionalComponentIds[" +
+        index +
+        "]"));
+    if (new Set(ids).size !== ids.length) {
+        throw new InvalidConfigurationError("sensorAccumulatedChargeCompleteness.includedAdditionalComponentIds must not contain duplicates.");
+    }
+    return {
+        schemaVersion: "0.1.0",
+        profileId: requireNonEmptyString(record.profileId, "sensorAccumulatedChargeCompleteness.profileId"),
+        colorSamplingProfileId: requireNonEmptyString(record.colorSamplingProfileId, "sensorAccumulatedChargeCompleteness.colorSamplingProfileId"),
+        channelId: requireNonEmptyString(record.channelId, "sensorAccumulatedChargeCompleteness.channelId"),
+        site: {
+            x: requireSiteIndex(site.x, "sensorAccumulatedChargeCompleteness.site.x"),
+            y: requireSiteIndex(site.y, "sensorAccumulatedChargeCompleteness.site.y")
+        },
+        bindingId: window.bindingId,
+        timeReference: window.timeReference,
+        startOffsetSecondsFromOpeningReference: window.start,
+        endOffsetSecondsFromOpeningReference: window.end,
+        darkCurrentProfileId: requireNonEmptyString(record.darkCurrentProfileId, "sensorAccumulatedChargeCompleteness.darkCurrentProfileId"),
+        includedAdditionalComponentIds: [...ids].sort(),
+        coverageMeaning: "all-material-stored-electron-contributors-accounted-for",
+        scientificStatus,
+        evidence: parseEvidenceList(record.evidence, "sensorAccumulatedChargeCompleteness.evidence"),
+        ...(limitation === undefined
+            ? {}
+            : { limitation })
+    };
+}
+function sameSite(a, b) {
+    return a.x === b.x && a.y === b.y;
+}
+function sameWindow(startA, endA, startB, endB) {
+    return (startA === startB &&
+        endA === endB);
+}
+function validatePhoto(photo) {
+    if (photo.kind === "eqe-temporal-photo-signal")
+        parseSensorEqeTemporalPhotoSignal(photo);
+    if ((photo.kind !== "eqe-expected-counts" && photo.kind !== "eqe-temporal-photo-signal") ||
+        photo.temporalIntegrationApplied !==
+            true ||
+        photo.accumulatedSignalCompleteness !==
+            "photo-signal-only" ||
+        photo.darkChargeIncluded !== false ||
+        photo.otherChargeIncluded !== false ||
+        photo
+            .physicalFullWellAssessmentAuthorized !==
+            false) {
+        throw new InvalidScientificInputError("Charge composition requires an unmodified photo-signal-only EQE exposure result.");
+    }
+    if (!Number.isFinite(photo
+        .expectedGeneratedElectronCount) ||
+        photo
+            .expectedGeneratedElectronCount < 0) {
+        throw new InvalidScientificInputError("Photo expected electron count must be finite and nonnegative.");
+    }
+}
+function validateDarkBinding(photo, dark) {
+    if (dark.colorSamplingProfileId !==
+        photo.colorSamplingProfileId ||
+        dark.channelId !==
+            photo.channelId ||
+        !sameSite(dark.site, photo.site) ||
+        dark.bindingId !==
+            photo.bindingId ||
+        (photo.kind === "eqe-temporal-photo-signal"
+            ? dark.stationarityProfileId !== undefined || dark.temporalIntegrationId !== photo.temporalIntegrationId
+            : dark.temporalIntegrationId !== undefined || dark.stationarityProfileId !== photo.stationarityProfileId) ||
+        dark.timeReference !==
+            photo.timeReference ||
+        !sameWindow(dark.startOffsetSecondsFromOpeningReference, dark.endOffsetSecondsFromOpeningReference, photo.startOffsetSecondsFromOpeningReference, photo.endOffsetSecondsFromOpeningReference) ||
+        dark.localExposureDurationSeconds !==
+            photo.localExposureDurationSeconds ||
+        dark.photoSignalIncluded !== false ||
+        dark.otherChargeIncluded !== false ||
+        dark
+            .physicalFullWellAssessmentAuthorized !==
+            false) {
+        throw new InvalidScientificInputError("Dark charge must bind to the exact same uncombined EQE local exposure event.");
+    }
+    if (!Number.isFinite(dark.expectedDarkElectronCount) ||
+        dark.expectedDarkElectronCount < 0) {
+        throw new InvalidScientificInputError("Dark expected electron count must be finite and nonnegative.");
+    }
+}
+function validateComponentBinding(component, photo) {
+    if (component.colorSamplingProfileId !==
+        photo.colorSamplingProfileId ||
+        component.channelId !==
+            photo.channelId ||
+        !sameSite(component.site, photo.site) ||
+        component.bindingId !==
+            photo.bindingId ||
+        component.timeReference !==
+            photo.timeReference ||
+        !sameWindow(component.startOffsetSecondsFromOpeningReference, component.endOffsetSecondsFromOpeningReference, photo.startOffsetSecondsFromOpeningReference, photo.endOffsetSecondsFromOpeningReference)) {
+        throw new InvalidScientificInputError("Additional stored-charge component must bind to the exact same local exposure event.");
+    }
+}
+/**
+ * Compose photo, independently evaluated dark and explicitly incremental charge by exact local
+ * exposure identity, retaining completeness assessment before capacity/noise.
+ *
+ * Photo, dark and explicitly incremental stored-electron components must share the exact
+ * site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
+ * consequence of an empty component array. Expected stored charge remains distinct from a stochastic
+ * realization or nonlinear full-well clamp.
+ * @param input - ComposeSensorPhotoAccumulatedChargeInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns CalculationResult<SensorPhotoAccumulatedChargeComposition>. 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.
+ */
+export function composeSensorAccumulatedCharge(input) {
+    validatePhoto(input.photoSignal);
+    validateDarkBinding(input.photoSignal, input.darkCharge);
+    const profile = parseSensorAccumulatedChargeCompletenessProfile(input.completenessProfile);
+    const components = (input.additionalChargeComponents ??
+        []).map(parseSensorAdditionalStoredChargeComponent);
+    if (profile.colorSamplingProfileId !==
+        input.photoSignal
+            .colorSamplingProfileId ||
+        profile.channelId !==
+            input.photoSignal.channelId ||
+        !sameSite(profile.site, input.photoSignal.site) ||
+        profile.bindingId !==
+            input.photoSignal.bindingId ||
+        profile.timeReference !==
+            input.photoSignal.timeReference ||
+        !sameWindow(profile.startOffsetSecondsFromOpeningReference, profile.endOffsetSecondsFromOpeningReference, input.photoSignal.startOffsetSecondsFromOpeningReference, input.photoSignal.endOffsetSecondsFromOpeningReference) ||
+        profile.darkCurrentProfileId !==
+            input.darkCharge
+                .darkCurrentProfileId) {
+        throw new InvalidScientificInputError("Charge-completeness profile must bind to the exact photo/dark exposure pipeline.");
+    }
+    const seen = new Set();
+    for (const component of components) {
+        validateComponentBinding(component, input.photoSignal);
+        if (seen.has(component.componentId)) {
+            throw new InvalidScientificInputError("Additional stored-charge component IDs must be unique.");
+        }
+        seen.add(component.componentId);
+    }
+    const actualIds = [...seen].sort();
+    if (JSON.stringify(actualIds) !==
+        JSON.stringify(profile
+            .includedAdditionalComponentIds)) {
+        throw new InvalidScientificInputError("Charge-completeness profile additional component IDs must exactly match the supplied components.");
+    }
+    const sum = {
+        sum: 0,
+        correction: 0
+    };
+    addCompensated(sum, input.photoSignal
+        .expectedGeneratedElectronCount);
+    addCompensated(sum, input.darkCharge
+        .expectedDarkElectronCount);
+    let additionalTotal = 0;
+    for (const component of components) {
+        additionalTotal +=
+            component.expectedElectronCount;
+        addCompensated(sum, component.expectedElectronCount);
+    }
+    if (!Number.isFinite(additionalTotal) ||
+        !Number.isFinite(sum.sum) ||
+        sum.sum < 0) {
+        throw new InvalidScientificInputError("Accumulated stored-electron totals must remain finite and nonnegative.");
+    }
+    const result = {
+        completenessProfileId: profile.profileId,
+        colorSamplingProfileId: input.photoSignal
+            .colorSamplingProfileId,
+        channelId: input.photoSignal.channelId,
+        site: {
+            ...input.photoSignal.site
+        },
+        bindingId: input.photoSignal.bindingId,
+        timeReference: input.photoSignal.timeReference,
+        startOffsetSecondsFromOpeningReference: input.photoSignal
+            .startOffsetSecondsFromOpeningReference,
+        endOffsetSecondsFromOpeningReference: input.photoSignal
+            .endOffsetSecondsFromOpeningReference,
+        localExposureDurationSeconds: input.photoSignal
+            .localExposureDurationSeconds,
+        photoExpectedElectronCount: input.photoSignal
+            .expectedGeneratedElectronCount,
+        darkExpectedElectronCount: input.darkCharge
+            .expectedDarkElectronCount,
+        additionalExpectedElectronCount: additionalTotal,
+        totalExpectedStoredElectronCount: sum.sum,
+        additionalComponents: components.map((component) => ({
+            componentId: component.componentId,
+            kind: component.kind,
+            expectedElectronCount: component.expectedElectronCount,
+            scientificStatus: component.scientificStatus,
+            uncertainty: component.uncertainty,
+            evidence: component.evidence
+        })),
+        accumulatedChargeCompleteness: "complete-for-physical-storage-capacity-assessment",
+        completenessScientificStatus: profile.scientificStatus,
+        allCountsAreExpectationValues: true,
+        integerChargeSampled: false,
+        photoSignalIncluded: true,
+        darkChargeIncluded: true,
+        otherChargeIncluded: components.length > 0,
+        darkShotNoiseApplied: false,
+        photoShotNoiseApplied: false,
+        readNoiseApplied: false,
+        physicalFullWellAssessmentAuthorized: true,
+        cameraSaturationAssessmentAuthorized: false,
+        saturationAssessed: false,
+        bloomingModeled: false,
+        adcQuantizationApplied: false,
+        rawCodeValueProduced: false,
+        componentEvidence: {
+            completeness: profile.evidence,
+            photoSignal: input.photoSignal
+                .componentEvidence,
+            darkCurrent: input.darkCharge
+                .componentEvidence
+        }
+    };
+    const assumptions = [
+        "Stored-electron accounting is bound to one exact EQE local exposure event; equal duration alone is insufficient.",
+        "Photo-signal expected electrons and thermally generated dark electrons are separate terms.",
+        "Every additional component must declare itself incremental beyond both modeled photo signal and modeled dark current to avoid silent double counting.",
+        "The completeness profile is an evidence-backed scientific assertion that all material stored-electron contributors for physical charge-capacity assessment are accounted for; it is not inferred from an empty additional-component list.",
+        "All values remain expectation counts. Photo/dark shot noise, read noise and stochastic integer sampling are not applied.",
+        "Physical full-well assessment becomes structurally authorized, but no saturation or blooming behavior is calculated by this composition.",
+        "Camera/digital saturation remains a separate response-chain property and is not authorized by physical charge completeness.",
+        "A/W current/charge results remain outside this stored-electron composition until a separate carrier/storage mapping exists."
+    ];
+    return profile.scientificStatus ===
+        "calibrated"
+        ? calculatedResult(result, "sensor-accumulated-charge-composition", input.photoSignal.kind === "eqe-temporal-photo-signal" ? "1.1.0" : "1.0.0", assumptions)
+        : approximationResult(result, "sensor-accumulated-charge-composition", input.photoSignal.kind === "eqe-temporal-photo-signal" ? "1.1.0" : "1.0.0", [
+            ...assumptions,
+            profile.limitation
+        ]);
+}
+//# sourceMappingURL=accumulated-charge.js.map