@photivra/engine 0.5.1 → 1.0.0

package/dist/optics/complex-pupil-psf.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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. Complex pupil
+ * evaluation sums declared amplitude and phase on a bounded regular pupil grid. PSF shape is
+ * normalized separately from pupil throughput; coherent phase, pupil energy and spectral/field
+ * applicability cannot be replaced by a scalar blur radius. Numeric profiles require owned or
+ * reusable-data provenance.
+ * Evaluate a declared complex pupil with explicit amplitude/phase and sampling support; normalize PSF
+ * shape and retain pupil throughput as a separate quantity. Complex pupil evaluation sums declared
+ * amplitude and phase on a bounded regular pupil grid. PSF shape is normalized separately from pupil
+ * throughput; coherent phase, pupil energy and spectral/field applicability cannot be replaced by a
+ * scalar blur radius. Numeric profiles require owned or reusable-data provenance.
+ * @see docs/PSF_FOUNDATION.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 FocusPlane } from "./focus-state.js";
+import type { LensPsfKernel, LensPsfScientificStatus, LensPsfUncertainty } from "./lens-psf-profile.js";
+export declare const LENS_COMPLEX_PUPIL_PROFILE_SCHEMA_VERSION: "0.1.0";
+export interface LensComplexPupilGrid {
+    widthSamples: number;
+    heightSamples: number;
+    pupilSamplePitchMmX: number;
+    pupilSamplePitchMmY: number;
+    centerSampleX: number;
+    centerSampleY: number;
+    relativeAmplitude: readonly number[];
+    opticalPathDifferenceMicrometers: readonly number[];
+}
+export interface LensComplexPupilProfile {
+    schemaVersion: typeof LENS_COMPLEX_PUPIL_PROFILE_SCHEMA_VERSION;
+    profileId: string;
+    profileVersion: string;
+    scientificStatus: LensPsfScientificStatus;
+    opticalDomain: "lens-primary-optical-path-only";
+    representation: "complex-pupil-amplitude-plus-opd";
+    pupilCoordinateSystem: "pupil-plane-metric-aligned-to-image-plane";
+    imageFieldAxes: "+X right, +Y up";
+    amplitudeMeaning: "relative-complex-pupil-amplitude-shape";
+    wavefrontMeaning: "optical-path-difference-micrometers";
+    throughputOwnership: "separate-relative-pupil-throughput-factor";
+    kernelEnergyNormalization: "unit-energy-shape";
+    propagationModel: "scalar-fraunhofer-discrete-reference";
+    context: {
+        focalLengthMm: number;
+        focus: FocusPlane;
+        apertureFNumber: number;
+        fieldPointMm: {
+            x: number;
+            y: number;
+        };
+        wavelengthNm: number;
+        signedDefocusImagePlaneMicrometers: number;
+    };
+    responseIncludes: {
+        diffraction: true;
+        aberration: boolean;
+        defocus: boolean;
+        pupilClippingShape: boolean;
+    };
+    relativePupilThroughputFactor: number;
+    grid: LensComplexPupilGrid;
+    sensorOpticalStackIncluded: false;
+    sensorSamplingIncluded: false;
+    reconstructionIncluded: false;
+    strayLightIncluded: false;
+    evidence: readonly EvidenceProvenance[];
+    uncertainty: LensPsfUncertainty;
+    limitations: readonly string[];
+}
+export interface CalculateLensComplexPupilPsfInput {
+    profile: LensComplexPupilProfile;
+}
+export interface LensComplexPupilPsf {
+    profileId: string;
+    profileVersion: string;
+    scientificStatus: LensPsfScientificStatus;
+    context: LensComplexPupilProfile["context"];
+    kernel: LensPsfKernel;
+    relativePupilThroughputFactor: number;
+    throughputOwnership: "separate-relative-pupil-throughput-factor";
+    diffractionAndAberrationJointlyEvaluated: true;
+    pupilClippingShapeIncluded: boolean;
+    pupilClippingThroughputAppliedToKernel: false;
+    scalarFraunhoferReference: true;
+    full2dOrientationPreserved: true;
+    geometricDistortionModified: false;
+    lateralChromaticPositionShiftApplied: false;
+    sensorOpticalStackIncluded: false;
+    sensorSamplingIncluded: false;
+    reconstructionIncluded: false;
+    strayLightIncluded: false;
+    scalarSharpnessScoreProduced: false;
+    componentEvidence: {
+        pupilProfile: readonly EvidenceProvenance[];
+    };
+    uncertainty: LensPsfUncertainty;
+}
+/**
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary.
+ *
+ * Complex pupil evaluation sums declared amplitude and phase on a bounded regular pupil grid. PSF
+ * shape is normalized separately from pupil throughput; coherent phase, pupil energy and
+ * spectral/field applicability cannot be replaced by a scalar blur radius. Numeric profiles require
+ * owned or reusable-data provenance.
+ * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
+ * @returns LensComplexPupilProfile. 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 parseLensComplexPupilProfile(value: unknown): LensComplexPupilProfile;
+/**
+ * Evaluate a declared complex pupil with explicit amplitude/phase and sampling support; normalize PSF
+ * shape and retain pupil throughput as a separate quantity.
+ *
+ * Complex pupil evaluation sums declared amplitude and phase on a bounded regular pupil grid. PSF
+ * shape is normalized separately from pupil throughput; coherent phase, pupil energy and
+ * spectral/field applicability cannot be replaced by a scalar blur radius. Numeric profiles require
+ * owned or reusable-data provenance.
+ * @param input - CalculateLensComplexPupilPsfInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns CalculationResult<LensComplexPupilPsf>. 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 calculateLensComplexPupilPsf(input: CalculateLensComplexPupilPsfInput): CalculationResult<LensComplexPupilPsf>;
+//# sourceMappingURL=complex-pupil-psf.d.ts.map

package/dist/optics/complex-pupil-psf.d.ts.map

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

package/dist/optics/complex-pupil-psf.js

@@ -0,0 +1,462 @@
+// 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. Complex pupil
+ * evaluation sums declared amplitude and phase on a bounded regular pupil grid. PSF shape is
+ * normalized separately from pupil throughput; coherent phase, pupil energy and spectral/field
+ * applicability cannot be replaced by a scalar blur radius. Numeric profiles require owned or
+ * reusable-data provenance.
+ * Evaluate a declared complex pupil with explicit amplitude/phase and sampling support; normalize PSF
+ * shape and retain pupil throughput as a separate quantity. Complex pupil evaluation sums declared
+ * amplitude and phase on a bounded regular pupil grid. PSF shape is normalized separately from pupil
+ * throughput; coherent phase, pupil energy and spectral/field applicability cannot be replaced by a
+ * scalar blur radius. Numeric profiles require owned or reusable-data provenance.
+ * @see docs/PSF_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support limits.
+ */
+import { approximationResult } from "../core/calculation-result.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { parseEvidenceList } from "../core/evidence-provenance.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { parseFocusPlane } from "./focus-state.js";
+export const LENS_COMPLEX_PUPIL_PROFILE_SCHEMA_VERSION = "0.1.0";
+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.trim();
+}
+function requireFinite(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value)) {
+        throw new InvalidConfigurationError(path + " must be finite.");
+    }
+    return value;
+}
+function requirePositiveFinite(value, path) {
+    const parsed = requireFinite(value, path);
+    if (parsed <= 0) {
+        throw new InvalidConfigurationError(path +
+            " must be greater than zero.");
+    }
+    return parsed;
+}
+function requireUnitInterval(value, path) {
+    const parsed = requireFinite(value, path);
+    if (parsed < 0 ||
+        parsed > 1) {
+        throw new InvalidConfigurationError(path +
+            " must lie from zero through one.");
+    }
+    return parsed;
+}
+function requirePositiveSafeInteger(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value <= 0) {
+        throw new InvalidConfigurationError(path +
+            " must be a positive safe integer.");
+    }
+    return value;
+}
+function requireNonNegativeSafeInteger(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 parseStatus(value, path) {
+    if (value !== "calibrated" &&
+        value !== "approximation") {
+        throw new InvalidConfigurationError(path + " is invalid.");
+    }
+    return value;
+}
+function parseUncertainty(value, path) {
+    const record = requireRecord(value, path);
+    if (record.kind === "relative") {
+        const fraction = requireFinite(record.fraction, path + ".fraction");
+        if (fraction < 0) {
+            throw new InvalidConfigurationError(path +
+                ".fraction must be nonnegative.");
+        }
+        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 parseLimitations(value, path) {
+    if (!Array.isArray(value)) {
+        throw new InvalidConfigurationError(path + " must be an array.");
+    }
+    const parsed = value.map((entry, index) => requireNonEmptyString(entry, path +
+        "[" +
+        index +
+        "]"));
+    if (new Set(parsed).size !==
+        parsed.length) {
+        throw new InvalidConfigurationError(path +
+            " must not contain duplicates.");
+    }
+    return parsed;
+}
+function parseGrid(value) {
+    const record = requireRecord(value, "lensComplexPupil.grid");
+    const widthSamples = requirePositiveSafeInteger(record.widthSamples, "lensComplexPupil.grid.widthSamples");
+    const heightSamples = requirePositiveSafeInteger(record.heightSamples, "lensComplexPupil.grid.heightSamples");
+    const total = widthSamples *
+        heightSamples;
+    if (!Number.isSafeInteger(total) ||
+        total > 4096) {
+        throw new InvalidConfigurationError("lensComplexPupil grid must contain at most 4096 samples.");
+    }
+    const centerSampleX = requireNonNegativeSafeInteger(record.centerSampleX, "lensComplexPupil.grid.centerSampleX");
+    const centerSampleY = requireNonNegativeSafeInteger(record.centerSampleY, "lensComplexPupil.grid.centerSampleY");
+    if (centerSampleX >=
+        widthSamples ||
+        centerSampleY >=
+            heightSamples) {
+        throw new InvalidConfigurationError("lensComplexPupil grid center must lie within the pupil array.");
+    }
+    if (!Array.isArray(record.relativeAmplitude) ||
+        record.relativeAmplitude
+            .length !== total) {
+        throw new InvalidConfigurationError("lensComplexPupil.grid.relativeAmplitude length must equal widthSamples × heightSamples.");
+    }
+    if (!Array.isArray(record
+        .opticalPathDifferenceMicrometers) ||
+        record
+            .opticalPathDifferenceMicrometers
+            .length !== total) {
+        throw new InvalidConfigurationError("lensComplexPupil.grid.opticalPathDifferenceMicrometers length must equal widthSamples × heightSamples.");
+    }
+    const relativeAmplitude = record.relativeAmplitude.map((entry, index) => requireUnitInterval(entry, "lensComplexPupil.grid.relativeAmplitude[" +
+        index +
+        "]"));
+    if (!relativeAmplitude.some((value) => value > 0)) {
+        throw new InvalidConfigurationError("lensComplexPupil must contain at least one non-zero pupil-amplitude sample.");
+    }
+    const opd = record
+        .opticalPathDifferenceMicrometers
+        .map((entry, index) => requireFinite(entry, "lensComplexPupil.grid.opticalPathDifferenceMicrometers[" +
+        index +
+        "]"));
+    return {
+        widthSamples,
+        heightSamples,
+        pupilSamplePitchMmX: requirePositiveFinite(record
+            .pupilSamplePitchMmX, "lensComplexPupil.grid.pupilSamplePitchMmX"),
+        pupilSamplePitchMmY: requirePositiveFinite(record
+            .pupilSamplePitchMmY, "lensComplexPupil.grid.pupilSamplePitchMmY"),
+        centerSampleX,
+        centerSampleY,
+        relativeAmplitude,
+        opticalPathDifferenceMicrometers: opd
+    };
+}
+/**
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary.
+ *
+ * Complex pupil evaluation sums declared amplitude and phase on a bounded regular pupil grid. PSF
+ * shape is normalized separately from pupil throughput; coherent phase, pupil energy and
+ * spectral/field applicability cannot be replaced by a scalar blur radius. Numeric profiles require
+ * owned or reusable-data provenance.
+ * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
+ * @returns LensComplexPupilProfile. 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 parseLensComplexPupilProfile(value) {
+    const record = requireRecord(value, "lensComplexPupil");
+    if (record.schemaVersion !==
+        LENS_COMPLEX_PUPIL_PROFILE_SCHEMA_VERSION) {
+        throw new InvalidConfigurationError('lensComplexPupil.schemaVersion must be "' +
+            LENS_COMPLEX_PUPIL_PROFILE_SCHEMA_VERSION +
+            '".');
+    }
+    if (record.opticalDomain !==
+        "lens-primary-optical-path-only" ||
+        record.representation !==
+            "complex-pupil-amplitude-plus-opd" ||
+        record.pupilCoordinateSystem !==
+            "pupil-plane-metric-aligned-to-image-plane" ||
+        record.imageFieldAxes !==
+            "+X right, +Y up" ||
+        record.amplitudeMeaning !==
+            "relative-complex-pupil-amplitude-shape" ||
+        record.wavefrontMeaning !==
+            "optical-path-difference-micrometers" ||
+        record.throughputOwnership !==
+            "separate-relative-pupil-throughput-factor" ||
+        record.kernelEnergyNormalization !==
+            "unit-energy-shape" ||
+        record.propagationModel !==
+            "scalar-fraunhofer-discrete-reference") {
+        throw new InvalidConfigurationError("lensComplexPupil representation/coordinate/energy semantics are invalid.");
+    }
+    if (record.sensorOpticalStackIncluded !==
+        false ||
+        record.sensorSamplingIncluded !==
+            false ||
+        record.reconstructionIncluded !==
+            false ||
+        record.strayLightIncluded !==
+            false) {
+        throw new InvalidConfigurationError("V1 complex pupil profiles must exclude sensor/reconstruction/stray-light effects.");
+    }
+    const status = parseStatus(record.scientificStatus, "lensComplexPupil.scientificStatus");
+    const uncertainty = parseUncertainty(record.uncertainty, "lensComplexPupil.uncertainty");
+    if (status === "calibrated" &&
+        uncertainty.kind ===
+            "not-quantified") {
+        throw new InvalidConfigurationError("Calibrated complex-pupil profiles must declare quantified relative uncertainty.");
+    }
+    const context = requireRecord(record.context, "lensComplexPupil.context");
+    const field = requireRecord(context.fieldPointMm, "lensComplexPupil.context.fieldPointMm");
+    const response = requireRecord(record.responseIncludes, "lensComplexPupil.responseIncludes");
+    if (response.diffraction !==
+        true ||
+        typeof response.aberration !==
+            "boolean" ||
+        typeof response.defocus !==
+            "boolean" ||
+        typeof response.pupilClippingShape !==
+            "boolean") {
+        throw new InvalidConfigurationError("lensComplexPupil.responseIncludes is invalid; diffraction must be included in this pupil propagation path.");
+    }
+    return {
+        schemaVersion: LENS_COMPLEX_PUPIL_PROFILE_SCHEMA_VERSION,
+        profileId: requireNonEmptyString(record.profileId, "lensComplexPupil.profileId"),
+        profileVersion: requireNonEmptyString(record.profileVersion, "lensComplexPupil.profileVersion"),
+        scientificStatus: status,
+        opticalDomain: "lens-primary-optical-path-only",
+        representation: "complex-pupil-amplitude-plus-opd",
+        pupilCoordinateSystem: "pupil-plane-metric-aligned-to-image-plane",
+        imageFieldAxes: "+X right, +Y up",
+        amplitudeMeaning: "relative-complex-pupil-amplitude-shape",
+        wavefrontMeaning: "optical-path-difference-micrometers",
+        throughputOwnership: "separate-relative-pupil-throughput-factor",
+        kernelEnergyNormalization: "unit-energy-shape",
+        propagationModel: "scalar-fraunhofer-discrete-reference",
+        context: {
+            focalLengthMm: requirePositiveFinite(context.focalLengthMm, "lensComplexPupil.context.focalLengthMm"),
+            focus: parseFocusPlane(context.focus),
+            apertureFNumber: requirePositiveFinite(context.apertureFNumber, "lensComplexPupil.context.apertureFNumber"),
+            fieldPointMm: {
+                x: requireFinite(field.x, "lensComplexPupil.context.fieldPointMm.x"),
+                y: requireFinite(field.y, "lensComplexPupil.context.fieldPointMm.y")
+            },
+            wavelengthNm: requirePositiveFinite(context.wavelengthNm, "lensComplexPupil.context.wavelengthNm"),
+            signedDefocusImagePlaneMicrometers: requireFinite(context
+                .signedDefocusImagePlaneMicrometers, "lensComplexPupil.context.signedDefocusImagePlaneMicrometers")
+        },
+        responseIncludes: {
+            diffraction: true,
+            aberration: response.aberration,
+            defocus: response.defocus,
+            pupilClippingShape: response
+                .pupilClippingShape
+        },
+        relativePupilThroughputFactor: requireUnitInterval(record
+            .relativePupilThroughputFactor, "lensComplexPupil.relativePupilThroughputFactor"),
+        grid: parseGrid(record.grid),
+        sensorOpticalStackIncluded: false,
+        sensorSamplingIncluded: false,
+        reconstructionIncluded: false,
+        strayLightIncluded: false,
+        evidence: parseEvidenceList(record.evidence, "lensComplexPupil.evidence"),
+        uncertainty,
+        limitations: parseLimitations(record.limitations, "lensComplexPupil.limitations")
+    };
+}
+function pupilComplexValue(amplitude, opdMicrometers, wavelengthMicrometers) {
+    const phase = 2 *
+        Math.PI *
+        opdMicrometers /
+        wavelengthMicrometers;
+    return {
+        re: amplitude *
+            Math.cos(phase),
+        im: amplitude *
+            Math.sin(phase)
+    };
+}
+function calculateDiscreteFraunhoferKernel(profile) {
+    const grid = profile.grid;
+    const width = grid.widthSamples;
+    const height = grid.heightSamples;
+    const wavelengthMicrometers = profile.context
+        .wavelengthNm /
+        1000;
+    const wavelengthMm = profile.context
+        .wavelengthNm /
+        1_000_000;
+    const pupil = grid.relativeAmplitude.map((amplitude, index) => pupilComplexValue(amplitude, grid
+        .opticalPathDifferenceMicrometers[index], wavelengthMicrometers));
+    const intensity = new Array(width * height).fill(0);
+    for (let outY = 0; outY < height; outY += 1) {
+        const ky = outY -
+            grid.centerSampleY;
+        for (let outX = 0; outX < width; outX += 1) {
+            const kx = outX -
+                grid.centerSampleX;
+            let re = 0;
+            let im = 0;
+            for (let y = 0; y < height; y += 1) {
+                const py = y -
+                    grid.centerSampleY;
+                for (let x = 0; x < width; x += 1) {
+                    const px = x -
+                        grid.centerSampleX;
+                    const source = pupil[y * width +
+                        x];
+                    const angle = -2 *
+                        Math.PI *
+                        (kx * px /
+                            width +
+                            ky * py /
+                                height);
+                    const cos = Math.cos(angle);
+                    const sin = Math.sin(angle);
+                    re +=
+                        source.re *
+                            cos -
+                            source.im *
+                                sin;
+                    im +=
+                        source.re *
+                            sin +
+                            source.im *
+                                cos;
+                }
+            }
+            intensity[outY * width +
+                outX] =
+                re * re +
+                    im * im;
+        }
+    }
+    const sum = intensity.reduce((acc, value) => acc + value, 0);
+    if (!Number.isFinite(sum) ||
+        sum <= 0) {
+        throw new InvalidScientificInputError("Complex-pupil propagation must produce finite positive PSF energy.");
+    }
+    const normalized = intensity.map((value) => value / sum);
+    const samplePitchMmX = wavelengthMm *
+        profile.context
+            .focalLengthMm /
+        (width *
+            grid
+                .pupilSamplePitchMmX);
+    const samplePitchMmY = wavelengthMm *
+        profile.context
+            .focalLengthMm /
+        (height *
+            grid
+                .pupilSamplePitchMmY);
+    if (!Number.isFinite(samplePitchMmX) ||
+        !Number.isFinite(samplePitchMmY) ||
+        samplePitchMmX <= 0 ||
+        samplePitchMmY <= 0) {
+        throw new InvalidScientificInputError("Complex-pupil PSF sample pitch must remain finite and positive.");
+    }
+    return {
+        widthSamples: width,
+        heightSamples: height,
+        samplePitchMicrometersX: samplePitchMmX *
+            1000,
+        samplePitchMicrometersY: samplePitchMmY *
+            1000,
+        centerSampleX: grid.centerSampleX,
+        centerSampleY: grid.centerSampleY,
+        normalizedIntensity: normalized
+    };
+}
+/**
+ * Evaluate a declared complex pupil with explicit amplitude/phase and sampling support; normalize PSF
+ * shape and retain pupil throughput as a separate quantity.
+ *
+ * Complex pupil evaluation sums declared amplitude and phase on a bounded regular pupil grid. PSF
+ * shape is normalized separately from pupil throughput; coherent phase, pupil energy and
+ * spectral/field applicability cannot be replaced by a scalar blur radius. Numeric profiles require
+ * owned or reusable-data provenance.
+ * @param input - CalculateLensComplexPupilPsfInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns CalculationResult<LensComplexPupilPsf>. 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 calculateLensComplexPupilPsf(input) {
+    const profile = parseLensComplexPupilProfile(input.profile);
+    const kernel = calculateDiscreteFraunhoferKernel(profile);
+    return approximationResult({
+        profileId: profile.profileId,
+        profileVersion: profile.profileVersion,
+        scientificStatus: profile.scientificStatus,
+        context: {
+            ...profile.context,
+            focus: {
+                ...profile.context.focus
+            },
+            fieldPointMm: {
+                ...profile.context
+                    .fieldPointMm
+            }
+        },
+        kernel,
+        relativePupilThroughputFactor: profile
+            .relativePupilThroughputFactor,
+        throughputOwnership: "separate-relative-pupil-throughput-factor",
+        diffractionAndAberrationJointlyEvaluated: true,
+        pupilClippingShapeIncluded: profile
+            .responseIncludes
+            .pupilClippingShape,
+        pupilClippingThroughputAppliedToKernel: false,
+        scalarFraunhoferReference: true,
+        full2dOrientationPreserved: true,
+        geometricDistortionModified: false,
+        lateralChromaticPositionShiftApplied: false,
+        sensorOpticalStackIncluded: false,
+        sensorSamplingIncluded: false,
+        reconstructionIncluded: false,
+        strayLightIncluded: false,
+        scalarSharpnessScoreProduced: false,
+        componentEvidence: {
+            pupilProfile: profile.evidence
+        },
+        uncertainty: profile.uncertainty
+    }, "lens-complex-pupil-fraunhofer-psf", "1.0.0", [
+        "The reference evaluator performs deterministic scalar Fraunhofer propagation of one explicit complex pupil amplitude plus optical-path-difference grid.",
+        "Diffraction and aberration phase are evaluated together in the same pupil propagation; callers must not stack an independent diffraction blur over this result.",
+        "The output PSF is unit-energy normalized. The explicit relativePupilThroughputFactor is not multiplied into the kernel and remains owned by the separate optical-throughput path.",
+        "Pupil amplitude shape can represent mechanical clipping/cat-eye geometry without silently encoding unknown transmission loss.",
+        "The pupil and image-plane axes preserve full 2D orientation; no radial or sagittal/tangential averaging is imposed.",
+        "This scalar Fraunhofer grid is a bounded reference approximation, not a full vector electromagnetic, polarization, stray-light or sensor-system model.",
+        "Sensor OLPF, microlens, CFA, sampling and reconstruction are downstream and excluded."
+    ]);
+}
+//# sourceMappingURL=complex-pupil-psf.js.map

package/dist/optics/complex-pupil-psf.js.map

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

package/dist/optics/depth-of-field.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Module boundary and integration notes.
+ * Calculates thin-lens depth-of-field limits using the conventional hyperfocal-distance formulation.
+ * The model is geometric and does not include diffraction, aberrations, focus breathing, pupil
+ * magnification, or macro/high-magnification effects.
+ * Calculates the geometric defocus-circle diameter at the sensor plane for a subject plane away from
+ * the selected focus plane.
+ * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
+ * limits.
+ */
 import { type CalculationResult } from "../core/calculation-result.js";
 export interface CalculateDepthOfFieldInput {
     /** Lens focal length in millimetres. */
@@ -50,4 +60,12 @@ export interface DefocusCircle {
  * @returns Geometric blur-circle diameter.
  */
 export declare function calculateDefocusCircle(input: CalculateDefocusCircleInput): CalculationResult<DefocusCircle>;
+/** @internal Immutable request-local identity; never a root public cache/API. */
+export interface ResolvedDefocusFocusProjection {
+    readonly focalLengthMm: number;
+    readonly focusDistanceM: number;
+    readonly imageDistanceMm: number;
+}
+/** @internal Reuses a projection already calculated for this exact POC request. */
+export declare function calculateDefocusCircleUsingFocusProjection(input: CalculateDefocusCircleInput, projection?: ResolvedDefocusFocusProjection): CalculationResult<DefocusCircle>;
 //# sourceMappingURL=depth-of-field.d.ts.map

package/dist/optics/depth-of-field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"depth-of-field.d.ts","sourceRoot":"","sources":["../../src/optics/depth-of-field.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAOvC,MAAM,WAAW,0BAA0B;IACzC,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,qDAAqD;IACrD,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,0BAA0B,GAChC,iBAAiB,CAAC,YAAY,CAAC,CA6CjC;AAED,MAAM,WAAW,2BAA2B;IAC1C,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,2BAA2B,GACjC,iBAAiB,CAAC,aAAa,CAAC,CAsClC"}
+{"version":3,"file":"depth-of-field.d.ts","sourceRoot":"","sources":["../../src/optics/depth-of-field.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAOvC,MAAM,WAAW,0BAA0B;IACzC,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,qDAAqD;IACrD,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,0BAA0B,GAChC,iBAAiB,CAAC,YAAY,CAAC,CA6CjC;AAED,MAAM,WAAW,2BAA2B;IAC1C,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,2BAA2B,GACjC,iBAAiB,CAAC,aAAa,CAAC,CAElC;AAED,iFAAiF;AACjF,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,mFAAmF;AACnF,wBAAgB,0CAA0C,CACxD,KAAK,EAAE,2BAA2B,EAClC,UAAU,CAAC,EAAE,8BAA8B,GAC1C,iBAAiB,CAAC,aAAa,CAAC,CAgDlC"}