@photivra/engine 0.6.0 → 1.0.1

package/dist/sensor/dark-current.js

@@ -0,0 +1,427 @@
+// 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. Dark current is an
+ * independently declared pre-compensation thermal electron rate. Exact-temperature or sampled linear
+ * interpolation is supported only within declared applicability; no universal doubling-temperature law
+ * is inferred. Population means remain approximations and do not model hot-pixel/DCNU structure.
+ * Evaluate the declared temperature-dependent dark electron rate and integrate over the exact
+ * photo-signal local exposure event. Dark current is an independently declared pre-compensation
+ * thermal electron rate. Exact-temperature or sampled linear interpolation is supported only within
+ * declared applicability; no universal doubling-temperature law is inferred. Population means remain
+ * approximations and do not model hot-pixel/DCNU structure.
+ * @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 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");
+        if (typeof record.basis !== "string" ||
+            record.basis.trim().length === 0) {
+            throw new InvalidConfigurationError(path +
+                ".basis must be a non-empty string.");
+        }
+        return {
+            kind: "relative",
+            fraction,
+            basis: record.basis
+        };
+    }
+    if (record.kind === "not-quantified") {
+        return {
+            kind: "not-quantified",
+            limitation: requireNonEmptyString(record.limitation, path + ".limitation")
+        };
+    }
+    throw new InvalidConfigurationError(path + ".kind is invalid.");
+}
+function parseSiteApplicability(value) {
+    const record = requireRecord(value, "sensorDarkCurrent.siteApplicability");
+    if (record.kind === "exact-site") {
+        const site = requireRecord(record.site, "sensorDarkCurrent.siteApplicability.site");
+        return {
+            kind: "exact-site",
+            site: {
+                x: requireSiteIndex(site.x, "sensorDarkCurrent.siteApplicability.site.x"),
+                y: requireSiteIndex(site.y, "sensorDarkCurrent.siteApplicability.site.y")
+            }
+        };
+    }
+    if (record.kind ===
+        "uniform-site-mean-approximation") {
+        return {
+            kind: "uniform-site-mean-approximation",
+            limitation: requireNonEmptyString(record.limitation, "sensorDarkCurrent.siteApplicability.limitation"),
+            evidence: parseEvidenceList(record.evidence, "sensorDarkCurrent.siteApplicability.evidence")
+        };
+    }
+    throw new InvalidConfigurationError("sensorDarkCurrent.siteApplicability.kind is invalid.");
+}
+function parseTemperatureModel(value) {
+    const record = requireRecord(value, "sensorDarkCurrent.temperatureModel");
+    if (record.kind ===
+        "fixed-reference-temperature") {
+        return {
+            kind: "fixed-reference-temperature",
+            referenceTemperatureC: requireFinite(record.referenceTemperatureC, "sensorDarkCurrent.temperatureModel.referenceTemperatureC"),
+            darkCurrentElectronsPerSecond: requireNonNegativeFinite(record.darkCurrentElectronsPerSecond, "sensorDarkCurrent.temperatureModel.darkCurrentElectronsPerSecond")
+        };
+    }
+    if (record.kind !==
+        "piecewise-linear-temperature-table") {
+        throw new InvalidConfigurationError("sensorDarkCurrent.temperatureModel.kind is invalid.");
+    }
+    if (record.interpolation !==
+        "piecewise-linear") {
+        throw new InvalidConfigurationError('sensorDarkCurrent.temperatureModel.interpolation must be "piecewise-linear".');
+    }
+    if (record.outsideRangeBehavior !==
+        "fail-closed") {
+        throw new InvalidConfigurationError('sensorDarkCurrent.temperatureModel.outsideRangeBehavior must be "fail-closed".');
+    }
+    if (!Array.isArray(record.samples) ||
+        record.samples.length < 2) {
+        throw new InvalidConfigurationError("sensorDarkCurrent.temperatureModel.samples must contain at least two samples.");
+    }
+    let previousTemperature = Number.NEGATIVE_INFINITY;
+    const samples = record.samples.map((sample, index) => {
+        const parsed = requireRecord(sample, "sensorDarkCurrent.temperatureModel.samples[" +
+            index +
+            "]");
+        const temperatureC = requireFinite(parsed.temperatureC, "sensorDarkCurrent.temperatureModel.samples[" +
+            index +
+            "].temperatureC");
+        if (temperatureC <=
+            previousTemperature) {
+            throw new InvalidConfigurationError("sensorDarkCurrent.temperatureModel.samples must be strictly increasing in temperature.");
+        }
+        previousTemperature =
+            temperatureC;
+        return {
+            temperatureC,
+            darkCurrentElectronsPerSecond: requireNonNegativeFinite(parsed.darkCurrentElectronsPerSecond, "sensorDarkCurrent.temperatureModel.samples[" +
+                index +
+                "].darkCurrentElectronsPerSecond")
+        };
+    });
+    return {
+        kind: "piecewise-linear-temperature-table",
+        interpolation: "piecewise-linear",
+        outsideRangeBehavior: "fail-closed",
+        samples
+    };
+}
+/**
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary.
+ *
+ * Dark current is an independently declared pre-compensation thermal electron rate. Exact-temperature
+ * or sampled linear interpolation is supported only within declared applicability; no universal
+ * doubling-temperature law is inferred. Population means remain approximations and do not model
+ * hot-pixel/DCNU structure.
+ * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
+ * @returns SensorDarkCurrentProfile. 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 parseSensorDarkCurrentProfile(value) {
+    const record = requireRecord(value, "sensorDarkCurrent");
+    if (record.schemaVersion !== "0.1.0") {
+        throw new InvalidConfigurationError('sensorDarkCurrent.schemaVersion must be "0.1.0".');
+    }
+    if (record.chargeMeaning !==
+        "pre-compensation-thermally-generated-electrons") {
+        throw new InvalidConfigurationError("sensorDarkCurrent.chargeMeaning is invalid.");
+    }
+    if (record.scientificStatus !==
+        "calibrated" &&
+        record.scientificStatus !==
+            "approximation") {
+        throw new InvalidConfigurationError("sensorDarkCurrent.scientificStatus is invalid.");
+    }
+    if (record.darkCurrentCompensationIncluded !==
+        false) {
+        throw new InvalidConfigurationError("sensorDarkCurrent.darkCurrentCompensationIncluded must be false.");
+    }
+    if (typeof record
+        .spatialDarkCurrentNonuniformityModeled !==
+        "boolean") {
+        throw new InvalidConfigurationError("sensorDarkCurrent.spatialDarkCurrentNonuniformityModeled must be boolean.");
+    }
+    const uncertainty = parseUncertainty(record.uncertainty, "sensorDarkCurrent.uncertainty");
+    if (record.scientificStatus ===
+        "calibrated" &&
+        uncertainty.kind ===
+            "not-quantified") {
+        throw new InvalidConfigurationError("A calibrated dark-current profile must declare quantified relative uncertainty.");
+    }
+    const siteApplicability = parseSiteApplicability(record.siteApplicability);
+    if (siteApplicability.kind ===
+        "uniform-site-mean-approximation" &&
+        record.scientificStatus !==
+            "approximation") {
+        throw new InvalidConfigurationError("Uniform site-mean dark current must remain an approximation.");
+    }
+    if (siteApplicability.kind ===
+        "uniform-site-mean-approximation" &&
+        record
+            .spatialDarkCurrentNonuniformityModeled !==
+            false) {
+        throw new InvalidConfigurationError("Uniform site-mean dark current cannot claim spatial dark-current nonuniformity is modeled.");
+    }
+    return {
+        schemaVersion: "0.1.0",
+        profileId: requireNonEmptyString(record.profileId, "sensorDarkCurrent.profileId"),
+        colorSamplingProfileId: requireNonEmptyString(record.colorSamplingProfileId, "sensorDarkCurrent.colorSamplingProfileId"),
+        channelId: requireNonEmptyString(record.channelId, "sensorDarkCurrent.channelId"),
+        scientificStatus: record.scientificStatus,
+        uncertainty,
+        evidence: parseEvidenceList(record.evidence, "sensorDarkCurrent.evidence"),
+        chargeMeaning: "pre-compensation-thermally-generated-electrons",
+        siteApplicability,
+        temperatureModel: parseTemperatureModel(record.temperatureModel),
+        darkCurrentCompensationIncluded: false,
+        spatialDarkCurrentNonuniformityModeled: record
+            .spatialDarkCurrentNonuniformityModeled
+    };
+}
+function sameSite(a, b) {
+    return a.x === b.x && a.y === b.y;
+}
+function resolveDarkCurrentRate(model, operatingTemperatureC) {
+    if (!Number.isFinite(operatingTemperatureC)) {
+        throw new InvalidScientificInputError("operatingTemperatureC must be finite.");
+    }
+    if (model.kind ===
+        "fixed-reference-temperature") {
+        if (operatingTemperatureC !==
+            model.referenceTemperatureC) {
+            throw new InvalidScientificInputError("Fixed-reference dark current may only be used at its exact reference temperature.");
+        }
+        return {
+            rate: model
+                .darkCurrentElectronsPerSecond,
+            interpolationUsed: false
+        };
+    }
+    const first = model.samples[0];
+    const last = model.samples[model.samples.length - 1];
+    if (operatingTemperatureC <
+        first.temperatureC ||
+        operatingTemperatureC >
+            last.temperatureC) {
+        throw new InvalidScientificInputError("operatingTemperatureC is outside the measured dark-current temperature range; extrapolation is not permitted.");
+    }
+    const exact = model.samples.find((sample) => sample.temperatureC ===
+        operatingTemperatureC);
+    if (exact !== undefined) {
+        return {
+            rate: exact
+                .darkCurrentElectronsPerSecond,
+            interpolationUsed: false
+        };
+    }
+    const upperIndex = model.samples.findIndex((sample) => sample.temperatureC >
+        operatingTemperatureC);
+    const upper = model.samples[upperIndex];
+    const lower = model.samples[upperIndex - 1];
+    const alpha = (operatingTemperatureC -
+        lower.temperatureC) /
+        (upper.temperatureC -
+            lower.temperatureC);
+    const rate = lower
+        .darkCurrentElectronsPerSecond +
+        alpha *
+            (upper
+                .darkCurrentElectronsPerSecond -
+                lower
+                    .darkCurrentElectronsPerSecond);
+    return {
+        rate,
+        interpolationUsed: true
+    };
+}
+function validateExposure(exposure) {
+    if (exposure.kind === "eqe-temporal-photo-signal")
+        parseSensorEqeTemporalPhotoSignal(exposure);
+    if ((exposure.kind !== "eqe-expected-counts" && exposure.kind !== "eqe-temporal-photo-signal") ||
+        exposure.temporalIntegrationApplied !==
+            true ||
+        exposure.exposureDurationApplied !==
+            true ||
+        exposure.accumulatedSignalCompleteness !==
+            "photo-signal-only" ||
+        exposure.darkChargeIncluded !== false ||
+        exposure.otherChargeIncluded !== false ||
+        exposure
+            .physicalFullWellAssessmentAuthorized !==
+            false) {
+        throw new InvalidScientificInputError("Dark-current composition requires an unmodified photo-signal-only EQE exposure integration.");
+    }
+    if (typeof exposure
+        .localExposureDurationSeconds !==
+        "number" ||
+        !Number.isFinite(exposure
+            .localExposureDurationSeconds) ||
+        exposure
+            .localExposureDurationSeconds <=
+            0) {
+        throw new InvalidScientificInputError("EQE exposure local duration must be finite and positive.");
+    }
+}
+/**
+ * Evaluate the declared temperature-dependent dark electron rate and integrate over the exact
+ * photo-signal local exposure event.
+ *
+ * Dark current is an independently declared pre-compensation thermal electron rate. Exact-temperature
+ * or sampled linear interpolation is supported only within declared applicability; no universal
+ * doubling-temperature law is inferred. Population means remain approximations and do not model
+ * hot-pixel/DCNU structure.
+ * @param input - CalculateSensorDarkCurrentChargeInput<SensorEqePhotoExposure>. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns CalculationResult<SensorPhotoDarkCurrentCharge>. 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 calculateSensorDarkCurrentCharge(input) {
+    validateExposure(input.exposure);
+    const profile = parseSensorDarkCurrentProfile(input.darkCurrentProfile);
+    if (profile.colorSamplingProfileId !==
+        input.exposure
+            .colorSamplingProfileId ||
+        profile.channelId !==
+            input.exposure.channelId) {
+        throw new InvalidScientificInputError("Dark-current profile color/channel identity must match the EQE exposure.");
+    }
+    const site = input.exposure.site;
+    if (profile.siteApplicability.kind ===
+        "exact-site" &&
+        !sameSite(profile.siteApplicability.site, site)) {
+        throw new InvalidScientificInputError("Exact-site dark-current profile does not apply to the exposure site.");
+    }
+    const resolved = resolveDarkCurrentRate(profile.temperatureModel, input.operatingTemperatureC);
+    const expectedDarkElectronCount = resolved.rate *
+        input.exposure
+            .localExposureDurationSeconds;
+    if (!Number.isFinite(expectedDarkElectronCount) ||
+        expectedDarkElectronCount < 0) {
+        throw new InvalidScientificInputError("Expected dark-electron count must remain finite and nonnegative.");
+    }
+    const result = {
+        darkCurrentProfileId: profile.profileId,
+        colorSamplingProfileId: input.exposure
+            .colorSamplingProfileId,
+        channelId: input.exposure.channelId,
+        site: {
+            ...site
+        },
+        bindingId: input.exposure.bindingId,
+        ...(input.exposure.kind === "eqe-temporal-photo-signal"
+            ? { temporalIntegrationId: input.exposure.temporalIntegrationId }
+            : { stationarityProfileId: input.exposure.stationarityProfileId }),
+        timeReference: input.exposure.timeReference,
+        startOffsetSecondsFromOpeningReference: input.exposure
+            .startOffsetSecondsFromOpeningReference,
+        endOffsetSecondsFromOpeningReference: input.exposure
+            .endOffsetSecondsFromOpeningReference,
+        operatingTemperatureC: input.operatingTemperatureC,
+        temperatureModel: profile.temperatureModel.kind,
+        temperatureInterpolationUsed: resolved.interpolationUsed,
+        darkCurrentElectronsPerSecond: resolved.rate,
+        localExposureDurationSeconds: input.exposure
+            .localExposureDurationSeconds,
+        expectedDarkElectronCount,
+        countMeaning: "expected-thermally-generated-electrons",
+        expectationValueOnly: true,
+        integerDarkElectronCountSampled: false,
+        darkShotNoiseApplied: false,
+        darkCurrentCompensationApplied: false,
+        spatialDarkCurrentNonuniformityModeled: profile
+            .spatialDarkCurrentNonuniformityModeled,
+        photoSignalIncluded: false,
+        otherChargeIncluded: false,
+        physicalFullWellAssessmentAuthorized: false,
+        saturationAssessed: false,
+        componentEvidence: {
+            darkCurrent: profile.evidence,
+            siteApproximation: profile.siteApplicability.kind ===
+                "uniform-site-mean-approximation"
+                ? profile
+                    .siteApplicability
+                    .evidence
+                : [],
+            exposure: input.exposure
+                .componentEvidence
+        }
+    };
+    const assumptions = [
+        "Dark current is modeled as pre-compensation thermally generated electron rate in electrons per second.",
+        "Release 4.0 style temperature handling is data-driven: no universal exponential or doubling-temperature law is inferred.",
+        "Piecewise-linear interpolation is allowed only inside an explicitly sampled temperature table; extrapolation fails closed.",
+        "Dark-current compensation, dark offset, hot-pixel/defect excess, leakage and charge injection remain separate from this thermal dark-current expectation.",
+        "Expected dark-electron count is rate × the exact local exposure duration; no integer sampling or dark-current shot-noise realization is performed.",
+        "This result is dark charge only. Photo-signal and other accumulated charge are not included, so physical full-well assessment remains unauthorized.",
+        "A/W current-domain exposure results cannot enter this electron-storage path without a separate carrier/storage mapping."
+    ];
+    return profile.scientificStatus ===
+        "calibrated"
+        ? calculatedResult(result, "sensor-dark-current-charge", input.exposure.kind === "eqe-temporal-photo-signal" ? "1.1.0" : "1.0.0", assumptions)
+        : approximationResult(result, "sensor-dark-current-charge", input.exposure.kind === "eqe-temporal-photo-signal" ? "1.1.0" : "1.0.0", [
+            ...assumptions,
+            ...(profile
+                .siteApplicability.kind ===
+                "uniform-site-mean-approximation"
+                ? [
+                    profile
+                        .siteApplicability
+                        .limitation
+                ]
+                : [])
+        ]);
+}
+//# sourceMappingURL=dark-current.js.map

package/dist/sensor/dark-current.js.map

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

package/dist/sensor/environment-photo-signal.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Module boundary and integration notes.
+ * Preflight all optical, spatial, spectral and temporal support into an internal owned execution plan
+ * without invoking provider code. Planning checks complete spatial/spectral/temporal support before
+ * invoking supplied synchronous radiance code. Queries use explicit environment directions, vacuum/air
+ * wavelength and opening-reference seconds. Optical throughput, optional local PSF and typed EQE
+ * produce photo expectations; callback invocation does not verify transport, visibility or
+ * calibration.
+ * Internal executor consumes a completed bounded geometric plan; returns no partial success on
+ * failure.
+ * @see docs/ENVIRONMENT_RAW_CAPTURE.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 { validateSceneRadianceEvaluationBindings, type SceneRadianceEvaluationRequest, type SceneRadianceEvaluationResult } from "../schema/scene-radiance.js";
+import { calculateSensorEnvironmentRadianceQuery, type CalculateSensorEnvironmentRadianceQueryInput } from "../optics/sensor-environment-query.js";
+import { calculateSceneRadianceToSensorIrradiance, type CalculateSceneRadianceToSensorIrradianceInput } from "../optics/scene-to-sensor-irradiance.js";
+import { calculateSensorPsfIrradianceQuadrature, type CalculateSensorPsfIrradianceQuadratureInput } from "../optics/sensor-psf-quadrature.js";
+import { calculateSensorSpatialSamplingQuadrature } from "./spatial-sampling-quadrature.js";
+import { calculateSensorSpectralQuadrature } from "./spectral-quadrature.js";
+import { createSensorEqeTemporalPhotoSignal } from "./temporal-photo-signal.js";
+import type { CalculateSensorEqeTemporalExposureInput } from "./eqe-temporal-exposure.js";
+import type { CalculateSceneToSensorIrradianceQuadratureInput } from "../optics/scene-to-sensor-quadrature.js";
+/** Supplied synchronous code executes locally. Invocation does not prove physical transport. */
+export type EnvironmentRadianceEvaluator = (request: Readonly<SceneRadianceEvaluationRequest>) => SceneRadianceEvaluationResult;
+export interface CalculateEnvironmentSensorPhotoSignalInput {
+    temporalIntegrationId: string;
+    sensor: Omit<CalculateSensorEqeTemporalExposureInput, "samples">;
+    sceneBindings: CalculateSceneToSensorIrradianceQuadratureInput["sceneBindings"];
+    optics: Omit<CalculateSceneRadianceToSensorIrradianceInput, "sceneRadianceRequest" | "sceneRadianceResult" | "imagePointMm" | "fieldThroughput">;
+    motion: Pick<CalculateSensorEnvironmentRadianceQueryInput, "angularVelocityRadPerSec" | "timeReference" | "environmentDirectionConvention">;
+    temporalSampleCount: number;
+    /** Explicit unity field throughput; spatial vignetting is not inferred or applied. */
+    fieldThroughput: {
+        kind: "unity";
+        evidence: readonly EvidenceProvenance[];
+        limitation: string;
+    };
+    psf: {
+        kind: "not-applied";
+        evidence: readonly EvidenceProvenance[];
+        limitation: string;
+    } | {
+        kind: "sampled-local";
+        configuration: Pick<CalculateSensorPsfIrradianceQuadratureInput, "psf" | "psfWavelengthBasis" | "spatialModel">;
+    };
+    evaluateRadiance: EnvironmentRadianceEvaluator;
+}
+export interface EnvironmentSensorPhotoSignal {
+    sourceTargetProjectionCalculated: true;
+    providerCallbackExecuted: true;
+    providerTransportVerified: false;
+    sceneVisibilityCalculated: false;
+    productionPlanActivated: false;
+    providerEvaluationCount: number;
+    sourcePlane: "sensor-package-incident";
+    fieldThroughputEvidence: readonly EvidenceProvenance[];
+    fieldThroughputLimitation: string;
+    psfOmission: {
+        evidence: readonly EvidenceProvenance[];
+        limitation: string;
+    } | null;
+    psfRedistributionApplied: boolean;
+    photo: ReturnType<typeof createSensorEqeTemporalPhotoSignal>;
+    instants: readonly {
+        temporalSampleIndex: number;
+        timeSecondsFromOpeningReference: number;
+        psf: ReturnType<typeof calculateSensorPsfIrradianceQuadrature> | null;
+        evaluations: readonly {
+            query: ReturnType<typeof calculateSensorEnvironmentRadianceQuery>;
+            result: SceneRadianceEvaluationResult;
+            bindings: ReturnType<typeof validateSceneRadianceEvaluationBindings>;
+            optics: ReturnType<typeof calculateSceneRadianceToSensorIrradiance>;
+        }[];
+    }[];
+}
+/** Internal preflight is shared with the full-frame composer to bound all work before callbacks. */
+interface EnvironmentPhotoPlan {
+    owned: Omit<CalculateEnvironmentSensorPhotoSignalInput, "evaluateRadiance">;
+    sceneBindings: CalculateSceneToSensorIrradianceQuadratureInput["sceneBindings"];
+    fieldThroughputEvidence: readonly EvidenceProvenance[];
+    spatialQuadrature: ReturnType<typeof calculateSensorSpatialSamplingQuadrature>["value"];
+    spectralQuadrature: ReturnType<typeof calculateSensorSpectralQuadrature>["value"];
+    count: number;
+    focus: CalculateSensorEnvironmentRadianceQueryInput["focus"];
+    instants: {
+        temporalSampleIndex: number;
+        time: number;
+        groups: {
+            node: CalculateSensorPsfIrradianceQuadratureInput["samples"][number]["node"];
+            taps: {
+                kernelSampleX: number;
+                kernelSampleY: number;
+                point: {
+                    x: number;
+                    y: number;
+                };
+                query: ReturnType<typeof calculateSensorEnvironmentRadianceQuery>;
+            }[];
+        }[];
+    }[];
+}
+/**
+ * Preflight all optical, spatial, spectral and temporal support into an internal owned execution plan
+ * without invoking provider code.
+ *
+ * Planning checks complete spatial/spectral/temporal support before invoking supplied synchronous
+ * radiance code. Queries use explicit environment directions, vacuum/air wavelength and
+ * opening-reference seconds. Optical throughput, optional local PSF and typed EQE produce photo
+ * expectations; callback invocation does not verify transport, visibility or calibration.
+ * @param input - Omit<CalculateEnvironmentSensorPhotoSignalInput, "evaluateRadiance">. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns EnvironmentPhotoPlan. 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 planEnvironmentSensorPhotoSignal(input: Omit<CalculateEnvironmentSensorPhotoSignalInput, "evaluateRadiance">): EnvironmentPhotoPlan;
+/** Internal executor consumes a completed bounded geometric plan; returns no partial success on failure. */
+export declare function executeEnvironmentSensorPhotoSignal(plan: ReturnType<typeof planEnvironmentSensorPhotoSignal>, evaluate: EnvironmentRadianceEvaluator): CalculationResult<EnvironmentSensorPhotoSignal>;
+/** Generate, evaluate and integrate one site's actual local midpoint environment support. */
+export declare function calculateEnvironmentSensorPhotoSignal(input: CalculateEnvironmentSensorPhotoSignalInput): CalculationResult<EnvironmentSensorPhotoSignal>;
+export {};
+//# sourceMappingURL=environment-photo-signal.d.ts.map

package/dist/sensor/environment-photo-signal.d.ts.map

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