@photivra/engine 1.5.0 → 2.0.0

package/dist/optics/lens-psf-profile.js

@@ -1,25 +1,34 @@
 // 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. Sampled lens PSF
- * shapes bind exact generic optical state, field, wavelength and signed defocus support. Interpolation
- * stays within declared applicability and preserves normalized shape separately from throughput.
- * MTF-only data lacks phase/spatial information and does not authorize rendering a unique PSF.
- * Resolve the bounded sampled PSF for a declared optical state and support point without extrapolation
- * or silently inventing missing dimensions. Sampled lens PSF shapes bind exact generic optical state,
- * field, wavelength and signed defocus support. Interpolation stays within declared applicability and
- * preserves normalized shape separately from throughput. MTF-only data lacks phase/spatial information
- * and does not authorize rendering a unique PSF.
- * @see docs/PSF_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support limits.
+ * Sampled lens PSF (point-spread function) profiles, and MTF-only diagnostic profiles.
+ *
+ * The parsers validate untrusted input and return the normalized typed contract. Unknown enum
+ * values, missing required fields and incompatible scientific data are rejected.
+ *
+ * The resolver finds the sampled PSF for a declared optical state and query point. It never
+ * extrapolates and never invents missing dimensions.
+ *
+ * A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+ * position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+ * the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+ * has no phase or spatial information, so it cannot justify rendering one unique PSF.
+ * @see docs/PSF_FOUNDATION.md for the equations, units, coordinate conventions, known blockers and
+ * support limits.
  */
 import { approximationResult } from "../core/calculation-result.js";
 import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { freezeOwnedData } from "../core/owned-data.js";
 import { parseEvidenceList } from "../core/evidence-provenance.js";
 import { InvalidScientificInputError } from "../core/validation.js";
 import { parseFocusPlane } from "./focus-state.js";
+import { requireInputKeys, rejectUnknownFields, rejectUnknownVariantFields, UNCERTAINTY_VARIANT_FIELDS } from "../core/record-validation.js";
 export const LENS_SAMPLED_PSF_PROFILE_SCHEMA_VERSION = "0.1.0";
 export const LENS_MTF_DIAGNOSTIC_PROFILE_SCHEMA_VERSION = "0.1.0";
+const LENS_SAMPLED_PSF_INTERPOLATIONS = [
+    "bounded-regular-grid-multilinear",
+    "bounded-regular-grid-centroid-aligned",
+    "rotationally-symmetric-radial-field-centroid-aligned"
+];
 const AXIS_KEYS = [
     "focalLengthMm",
     "focusDiopters",
@@ -29,12 +38,14 @@ const AXIS_KEYS = [
     "wavelengthNm",
     "signedDefocusImagePlaneMicrometers"
 ];
-function requireRecord(value, path) {
+function requireRecord(value, path, allowedKeys) {
     if (typeof value !== "object" ||
         value === null ||
         Array.isArray(value)) {
         throw new InvalidConfigurationError(path + " must be an object.");
     }
+    if (allowedKeys !== null)
+        rejectUnknownFields(value, allowedKeys, path);
     return value;
 }
 function requireNonEmptyString(value, path) {
@@ -103,7 +114,8 @@ function parseStatus(value, path) {
     return value;
 }
 function parseUncertainty(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, null);
+    rejectUnknownVariantFields(record, "kind", UNCERTAINTY_VARIANT_FIELDS, path);
     if (record.kind === "relative") {
         return {
             kind: "relative",
@@ -165,7 +177,7 @@ function parseAxis(value, path, options = {}) {
     return parsed;
 }
 function parseKernel(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, ["widthSamples", "heightSamples", "centerSampleX", "centerSampleY", "normalizedIntensity", "samplePitchMicrometersX", "samplePitchMicrometersY"]);
     const widthSamples = requirePositiveSafeInteger(record.widthSamples, path + ".widthSamples");
     const heightSamples = requirePositiveSafeInteger(record.heightSamples, path + ".heightSamples");
     const total = widthSamples *
@@ -218,7 +230,7 @@ function parseKernel(value, path) {
     };
 }
 function parseAxes(value) {
-    const record = requireRecord(value, "lensPsfProfile.axes");
+    const record = requireRecord(value, "lensPsfProfile.axes", ["focalLengthMm", "focusDiopters", "apertureFNumber", "fieldXmm", "fieldYmm", "wavelengthNm", "signedDefocusImagePlaneMicrometers"]);
     return {
         focalLengthMm: parseAxis(record.focalLengthMm, "lensPsfProfile.axes.focalLengthMm", {
             positive: true
@@ -239,7 +251,7 @@ function parseAxes(value) {
     };
 }
 function parseCoordinate(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, ["focalLengthMm", "focusDiopters", "apertureFNumber", "fieldXmm", "fieldYmm", "wavelengthNm", "signedDefocusImagePlaneMicrometers"]);
     return {
         focalLengthMm: requirePositiveFinite(record.focalLengthMm, path + ".focalLengthMm"),
         focusDiopters: requireNonNegativeFinite(record.focusDiopters, path + ".focusDiopters"),
@@ -274,7 +286,7 @@ function parseNode(value, index, axes, status) {
     const path = "lensPsfProfile.nodes[" +
         index +
         "]";
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, ["coordinate", "uncertainty", "nodeId", "kernel", "bestFocusImagePlaneOffsetMicrometers", "relativePupilThroughputFactor", "evidence"]);
     const coordinate = parseCoordinate(record.coordinate, path + ".coordinate");
     validateNodeCoordinate(axes, coordinate, path + ".coordinate");
     const uncertainty = parseUncertainty(record.uncertainty, path + ".uncertainty");
@@ -327,21 +339,61 @@ function sameKernelGeometry(first, second) {
         first.centerSampleY ===
             second.centerSampleY);
 }
+/** Private profile declarations owned by the engine, registered by markEngineOwnedLensSampledPsfProfile. */
+const ENGINE_OWNED_PROFILES = new WeakSet();
+/** Deep-frozen parse of a deep-frozen engine-owned declaration. */
+const PARSED_OWNED_PROFILES = new WeakMap();
+/** Grid node index of a cached, deep-frozen parse. */
+const TRUSTED_NODE_INDEX = new WeakMap();
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Internal: registers a private profile declaration owned by the engine, so that repeated
+ * resolveLensSampledPsf calls reuse one parse. The declaration is a structured clone that caller code
+ * never sees.
  *
- * Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
- * support. Interpolation stays within declared applicability and preserves normalized shape separately
- * from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
- * unique PSF.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns LensSampledPsfProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The first resolve parses it exactly like untrusted input. It then deep-freezes the declaration and
+ * caches the frozen parse with its node index. A frozen declaration cannot change, so the cached
+ * parse stays exact. Caller objects that were never registered are always parsed again.
+ */
+export function markEngineOwnedLensSampledPsfProfile(value) {
+    if (typeof value === "object" && value !== null)
+        ENGINE_OWNED_PROFILES.add(value);
+}
+function parseOwnedOrUntrustedProfile(value) {
+    if (typeof value !== "object" || value === null || !ENGINE_OWNED_PROFILES.has(value)) {
+        return parseLensSampledPsfProfile(value);
+    }
+    const cached = PARSED_OWNED_PROFILES.get(value);
+    if (cached !== undefined)
+        return cached;
+    const parsed = parseLensSampledPsfProfile(value);
+    try {
+        freezeOwnedData(value);
+    }
+    catch {
+        // Not plain data that freezeOwnedData accepts (for example typed-array storage), so do not cache.
+        ENGINE_OWNED_PROFILES.delete(value);
+        return parsed;
+    }
+    freezeOwnedData(parsed);
+    TRUSTED_NODE_INDEX.set(parsed, buildGridNodeIndex(parsed));
+    PARSED_OWNED_PROFILES.set(value, parsed);
+    return parsed;
+}
+/**
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
+ *
+ * A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+ * position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+ * the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+ * has no phase or spatial information, so it cannot justify rendering one unique PSF.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns LensSampledPsfProfile. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function parseLensSampledPsfProfile(value) {
-    const record = requireRecord(value, "lensPsfProfile");
+    const record = requireRecord(value, "lensPsfProfile", ["schemaVersion", "opticalDomain", "coordinateSystem", "fieldAxes", "kernelEnergyNormalization", "interpolation", "throughputOwnership", "sensorOpticalStackIncluded", "sensorSamplingIncluded", "reconstructionIncluded", "strayLightIncluded", "scientificStatus", "responseIncludes", "axes", "nodes", "profileId", "profileVersion", "evidence", "limitations"]);
     if (record.schemaVersion !==
         LENS_SAMPLED_PSF_PROFILE_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('lensPsfProfile.schemaVersion must be "' +
@@ -360,8 +412,7 @@ export function parseLensSampledPsfProfile(value) {
     }
     if (record.kernelEnergyNormalization !==
         "unit-energy-shape" ||
-        record.interpolation !==
-            "bounded-regular-grid-multilinear" ||
+        !LENS_SAMPLED_PSF_INTERPOLATIONS.includes(record.interpolation) ||
         record.throughputOwnership !==
             "separate-relative-pupil-throughput-factor") {
         throw new InvalidConfigurationError("lensPsfProfile normalization/interpolation/throughput ownership is invalid.");
@@ -377,7 +428,7 @@ export function parseLensSampledPsfProfile(value) {
         throw new InvalidConfigurationError("V1 lens PSF profiles must remain lens-primary-optical-path-only and exclude sensor/reconstruction/stray-light effects.");
     }
     const status = parseStatus(record.scientificStatus, "lensPsfProfile.scientificStatus");
-    const response = requireRecord(record.responseIncludes, "lensPsfProfile.responseIncludes");
+    const response = requireRecord(record.responseIncludes, "lensPsfProfile.responseIncludes", ["diffraction", "aberration", "defocus", "pupilClippingShape"]);
     for (const key of [
         "diffraction",
         "aberration",
@@ -419,6 +470,18 @@ export function parseLensSampledPsfProfile(value) {
             throw new InvalidConfigurationError("Every lensPsfProfile node must use identical PSF kernel grid geometry for multilinear interpolation.");
         }
     }
+    if (record.interpolation ===
+        "rotationally-symmetric-radial-field-centroid-aligned") {
+        if (axes.fieldYmm.length !== 1 ||
+            axes.fieldYmm[0] !== 0 ||
+            axes.fieldXmm.some((value) => value < 0)) {
+            throw new InvalidConfigurationError("Rotationally symmetric PSF profiles must declare fieldYmm = [0] and non-negative fieldXmm radii.");
+        }
+        if (firstKernel.samplePitchMicrometersX !==
+            firstKernel.samplePitchMicrometersY) {
+            throw new InvalidConfigurationError("Rotationally symmetric PSF profiles require square kernel sample pitch for rotation.");
+        }
+    }
     return {
         schemaVersion: LENS_SAMPLED_PSF_PROFILE_SCHEMA_VERSION,
         profileId: requireNonEmptyString(record.profileId, "lensPsfProfile.profileId"),
@@ -428,7 +491,7 @@ export function parseLensSampledPsfProfile(value) {
         coordinateSystem: "image-plane-metric",
         fieldAxes: "+X right, +Y up",
         kernelEnergyNormalization: "unit-energy-shape",
-        interpolation: "bounded-regular-grid-multilinear",
+        interpolation: record.interpolation,
         throughputOwnership: "separate-relative-pupil-throughput-factor",
         responseIncludes: {
             diffraction: response.diffraction,
@@ -484,11 +547,14 @@ function bracketAxis(values, target, path) {
         throw new InvalidScientificInputError(path +
             " lies outside the declared PSF profile grid; extrapolation is not permitted.");
     }
-    for (const value of values) {
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
         if (Math.abs(target - value) <= tolerance) {
             return {
                 lower: value,
                 upper: value,
+                lowerIndex: index,
+                upperIndex: index,
                 fraction: 0,
                 exact: true
             };
@@ -503,6 +569,8 @@ function bracketAxis(values, target, path) {
             return {
                 lower,
                 upper,
+                lowerIndex: index,
+                upperIndex: index + 1,
                 fraction: (target - lower) /
                     (upper - lower),
                 exact: false
@@ -541,66 +609,68 @@ function bracketCoordinate(axes, coordinate) {
             .signedDefocusImagePlaneMicrometers, "signedDefocusImagePlaneMicrometers")
     };
 }
-function cornerCoordinates(brackets) {
-    let corners = [{
-            partial: {},
-            weight: 1
-        }];
-    for (const key of AXIS_KEYS) {
-        const bracket = brackets[key];
-        const values = bracket.exact
-            ? [{
-                    value: bracket.lower,
-                    weight: 1
-                }]
-            : [
-                {
-                    value: bracket.lower,
-                    weight: 1 -
-                        bracket.fraction
-                },
-                {
-                    value: bracket.upper,
-                    weight: bracket.fraction
-                }
-            ];
-        const next = [];
-        for (const corner of corners) {
-            for (const option of values) {
-                if (option.weight === 0) {
-                    continue;
-                }
-                next.push({
-                    partial: {
-                        ...corner.partial,
-                        [key]: option.value
-                    },
-                    weight: corner.weight *
-                        option.weight
-                });
-            }
+/** Flat-index strides of the regular grid over AXIS_KEYS (the last axis varies fastest). */
+function gridStrides(axes) {
+    const strides = new Array(AXIS_KEYS.length);
+    let stride = 1;
+    for (let a = AXIS_KEYS.length - 1; a >= 0; a -= 1) {
+        strides[a] = stride;
+        stride *= axes[AXIS_KEYS[a]].length;
+    }
+    return strides;
+}
+/**
+ * Nodes indexed by grid position. Node coordinates match declared axis values exactly (checked by the
+ * parser, with `===`, so −0 and 0 are one position) and are unique, so each position holds at most one node.
+ */
+function buildGridNodeIndex(profile) {
+    const strides = gridStrides(profile.axes);
+    const nodes = new Array(AXIS_KEYS.reduce((n, key) => n * profile.axes[key].length, 1));
+    for (const node of profile.nodes) {
+        let flat = 0;
+        for (let a = 0; a < AXIS_KEYS.length; a += 1) {
+            const key = AXIS_KEYS[a];
+            flat += profile.axes[key].indexOf(node.coordinate[key]) * strides[a];
         }
-        corners = next;
+        nodes[flat] = node;
     }
-    return corners.map((corner) => ({
-        coordinate: corner.partial,
-        weight: corner.weight
-    }));
+    return { strides, nodes };
 }
+/**
+ * The multilinear corners of a bracketed query and their weights, in a fixed order: axes in AXIS_KEYS order,
+ * lower before upper, zero-weight options skipped. Each weight is the product of its per-axis weights in that order.
+ */
 function resolveWeightedNodes(profile, brackets) {
-    const byKey = new Map(profile.nodes.map((node) => [
-        coordinateKey(node.coordinate),
-        node
-    ]));
-    return cornerCoordinates(brackets).map((corner) => {
-        const node = byKey.get(coordinateKey(corner.coordinate));
+    const index = TRUSTED_NODE_INDEX.get(profile) ?? buildGridNodeIndex(profile);
+    let flats = [0], weights = [1];
+    for (let a = 0; a < AXIS_KEYS.length; a += 1) {
+        const bracket = brackets[AXIS_KEYS[a]], stride = index.strides[a];
+        const nextFlats = [], nextWeights = [];
+        for (let c = 0; c < flats.length; c += 1) {
+            if (bracket.exact) {
+                nextFlats.push(flats[c] + bracket.lowerIndex * stride);
+                nextWeights.push(weights[c] * 1);
+                continue;
+            }
+            const lowerWeight = 1 - bracket.fraction, upperWeight = bracket.fraction;
+            if (lowerWeight !== 0) {
+                nextFlats.push(flats[c] + bracket.lowerIndex * stride);
+                nextWeights.push(weights[c] * lowerWeight);
+            }
+            if (upperWeight !== 0) {
+                nextFlats.push(flats[c] + bracket.upperIndex * stride);
+                nextWeights.push(weights[c] * upperWeight);
+            }
+        }
+        flats = nextFlats;
+        weights = nextWeights;
+    }
+    return flats.map((flat, c) => {
+        const node = index.nodes[flat];
         if (node === undefined) {
             throw new InvalidScientificInputError("PSF profile grid is missing a required interpolation corner.");
         }
-        return {
-            node,
-            weight: corner.weight
-        };
+        return { node, weight: weights[c] };
     });
 }
 function interpolateKernel(weighted) {
@@ -637,41 +707,170 @@ function interpolateKernel(weighted) {
         normalizedIntensity: normalized
     };
 }
+function kernelCentroid(kernel) {
+    let sum = 0;
+    let x = 0;
+    let y = 0;
+    for (let row = 0; row < kernel.heightSamples; row += 1) {
+        for (let column = 0; column < kernel.widthSamples; column += 1) {
+            const value = kernel.normalizedIntensity[row * kernel.widthSamples + column];
+            sum += value;
+            x += value * (column - kernel.centerSampleX);
+            y += value * (row - kernel.centerSampleY);
+        }
+    }
+    return { x: x / sum, y: y / sum };
+}
+/** Bilinear sample at fractional array coordinates; zero outside the kernel. */
+function bilinearSample(kernel, column, row) {
+    const x0 = Math.floor(column);
+    const y0 = Math.floor(row);
+    const fx = column - x0;
+    const fy = row - y0;
+    const at = (x, y) => x < 0 || y < 0 || x >= kernel.widthSamples || y >= kernel.heightSamples
+        ? 0
+        : kernel.normalizedIntensity[y * kernel.widthSamples + x];
+    const top = fx === 0 ? at(x0, y0) : (1 - fx) * at(x0, y0) + fx * at(x0 + 1, y0);
+    if (fy === 0) {
+        return top;
+    }
+    const bottom = fx === 0 ? at(x0, y0 + 1) : (1 - fx) * at(x0, y0 + 1) + fx * at(x0 + 1, y0 + 1);
+    return (1 - fy) * top + fy * bottom;
+}
+function normalizedKernel(template, values) {
+    const sum = values.reduce((acc, value) => acc + value, 0);
+    if (!Number.isFinite(sum) || sum <= 0) {
+        throw new InvalidScientificInputError("Interpolated PSF energy must remain finite and positive.");
+    }
+    return {
+        widthSamples: template.widthSamples,
+        heightSamples: template.heightSamples,
+        samplePitchMicrometersX: template.samplePitchMicrometersX,
+        samplePitchMicrometersY: template.samplePitchMicrometersY,
+        centerSampleX: template.centerSampleX,
+        centerSampleY: template.centerSampleY,
+        normalizedIntensity: values.map((value) => value / sum)
+    };
+}
+/**
+ * Centroid-aligned interpolation. Each node kernel is shifted so its intensity centroid lands on the
+ * weighted centroid. Then the multilinear weights are applied. A single exact node is returned
+ * unchanged.
+ */
+function interpolateKernelCentroidAligned(weighted) {
+    const first = weighted[0]?.node.kernel;
+    if (first === undefined) {
+        throw new InvalidScientificInputError("PSF interpolation requires at least one source node.");
+    }
+    if (weighted.length === 1) {
+        // An exact grid node is already a validated unit-energy kernel; return it bit-for-bit.
+        return { ...first, normalizedIntensity: [...first.normalizedIntensity] };
+    }
+    const centroids = weighted.map((entry) => kernelCentroid(entry.node.kernel));
+    const target = centroids.reduce((acc, centroid, index) => ({
+        x: acc.x + weighted[index].weight * centroid.x,
+        y: acc.y + weighted[index].weight * centroid.y
+    }), { x: 0, y: 0 });
+    const values = new Array(first.normalizedIntensity.length).fill(0);
+    weighted.forEach((entry, index) => {
+        const dx = centroids[index].x - target.x;
+        const dy = centroids[index].y - target.y;
+        for (let row = 0; row < first.heightSamples; row += 1) {
+            for (let column = 0; column < first.widthSamples; column += 1) {
+                values[row * first.widthSamples + column] +=
+                    entry.weight * bilinearSample(entry.node.kernel, column + dx, row + dy);
+            }
+        }
+    });
+    return normalizedKernel(first, values);
+}
+/** Rotates a kernel by angleRadians (counter-clockwise, +Y up) about its centre sample. */
+function rotateKernel(kernel, angleRadians) {
+    const cos = Math.cos(angleRadians);
+    const sin = Math.sin(angleRadians);
+    const values = [];
+    for (let row = 0; row < kernel.heightSamples; row += 1) {
+        // Array rows increase downward; image +Y is up.
+        const y = kernel.centerSampleY - row;
+        for (let column = 0; column < kernel.widthSamples; column += 1) {
+            const x = column - kernel.centerSampleX;
+            // Inverse rotation: destination (x, y) samples source R(-angle) (x, y).
+            const sourceX = cos * x + sin * y;
+            const sourceY = -sin * x + cos * y;
+            values.push(bilinearSample(kernel, kernel.centerSampleX + sourceX, kernel.centerSampleY - sourceY));
+        }
+    }
+    return normalizedKernel(kernel, values);
+}
 function weightedScalar(weighted, select) {
     return weighted.reduce((sum, entry) => sum +
         entry.weight *
             select(entry.node), 0);
 }
-/**
- * Resolve the bounded sampled PSF for a declared optical state and support point without extrapolation
- * or silently inventing missing dimensions.
- *
- * Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
- * support. Interpolation stays within declared applicability and preserves normalized shape separately
- * from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
- * unique PSF.
- * @param input - ResolveLensSampledPsfInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns CalculationResult<ResolvedLensSampledPsf>. 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 resolveLensSampledPsf(input) {
-    const profile = parseLensSampledPsfProfile(input.profile);
+function resolveLensSampledPsfCore(input) {
+    requireInputKeys(input, "resolveLensSampledPsf", ["profile", "focalLengthMm", "focus", "apertureFNumber", "fieldPointMm", "wavelengthNm", "signedDefocusImagePlaneMicrometers"]);
+    const profile = parseOwnedOrUntrustedProfile(input.profile);
     const query = queryCoordinate(input);
-    const brackets = bracketCoordinate(profile.axes, query.coordinate);
+    const rotational = profile.interpolation ===
+        "rotationally-symmetric-radial-field-centroid-aligned";
+    const fieldRadiusMm = Math.hypot(query.coordinate.fieldXmm, query.coordinate.fieldYmm);
+    const fieldAngleRadians = rotational
+        ? Math.atan2(query.coordinate.fieldYmm, query.coordinate.fieldXmm)
+        : 0;
+    const brackets = bracketCoordinate(profile.axes, rotational
+        ? { ...query.coordinate, fieldXmm: fieldRadiusMm, fieldYmm: 0 }
+        : query.coordinate);
     const weighted = resolveWeightedNodes(profile, brackets);
-    const exact = AXIS_KEYS.every((key) => brackets[key].exact);
-    const kernel = interpolateKernel(weighted);
+    const exact = AXIS_KEYS.every((key) => brackets[key].exact) && fieldAngleRadians === 0;
+    const kernel = profile.interpolation === "bounded-regular-grid-multilinear"
+        ? interpolateKernel(weighted)
+        : fieldAngleRadians === 0
+            ? interpolateKernelCentroidAligned(weighted)
+            : rotateKernel(interpolateKernelCentroidAligned(weighted), fieldAngleRadians);
     const bestFocus = weightedScalar(weighted, (node) => node
         .bestFocusImagePlaneOffsetMicrometers);
-    const throughput = weightedScalar(weighted, (node) => node
+    // A multilinear blend is a convex combination, so it cannot exceed its largest node value. But its
+    // floating-point weights can sum to a few ulps above 1. A result above 1 that lies within
+    // 8·ε·(node count)·max of the largest node is that rounding error. It is clamped to the largest node
+    // value (≤ 1, so the result is again a declared value). Results already within [0, 1] are unchanged.
+    const blended = weightedScalar(weighted, (node) => node
         .relativePupilThroughputFactor);
+    const largestThroughput = Math.max(...weighted.map((entry) => entry.node.relativePupilThroughputFactor));
+    const throughput = blended > 1 && largestThroughput <= 1 &&
+        blended - largestThroughput <= 8 * Number.EPSILON * weighted.length * Math.max(1, largestThroughput)
+        ? largestThroughput
+        : blended;
     if (!Number.isFinite(bestFocus) ||
         !Number.isFinite(throughput) ||
         throughput < 0 ||
         throughput > 1) {
         throw new InvalidScientificInputError("Interpolated PSF metadata must remain finite and physically bounded.");
     }
+    return { profile, query, rotational, exact, weighted, kernel, bestFocus, throughput };
+}
+/**
+ * Internal (2.0 performance): the kernel resolveLensSampledPsf returns for the same input, computed by
+ * the same code without building the result envelope. Throws whenever resolveLensSampledPsf would throw
+ * before its envelope. Not exported from the package.
+ */
+export function resolveLensSampledPsfKernel(input) {
+    return resolveLensSampledPsfCore(input).kernel;
+}
+/**
+ * Resolves the sampled PSF for a declared optical state and query point. It never extrapolates and
+ * never invents missing dimensions.
+ *
+ * A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+ * position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+ * the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+ * has no phase or spatial information, so it cannot justify rendering one unique PSF.
+ * @param input - ResolveLensSampledPsfInput. See that type for coordinates, units and profile binding.
+ * @returns CalculationResult<ResolvedLensSampledPsf>. The result states its shape and scientific status; a successful call does not imply calibration.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export function resolveLensSampledPsf(input) {
+    const { profile, query, rotational, exact, weighted, kernel, bestFocus, throughput } = resolveLensSampledPsfCore(input);
     return approximationResult({
         profileId: profile.profileId,
         profileVersion: profile.profileVersion,
@@ -705,7 +904,19 @@ export function resolveLensSampledPsf(input) {
         reconstructionIncluded: false,
         strayLightIncluded: false,
         scalarSharpnessScoreProduced: false
-    }, "lens-sampled-psf-bounded-interpolation", "1.0.0", [
+    }, profile.interpolation === "bounded-regular-grid-multilinear"
+        ? "lens-sampled-psf-bounded-interpolation"
+        : rotational
+            ? "lens-sampled-psf-rotational-centroid-aligned-interpolation"
+            : "lens-sampled-psf-centroid-aligned-interpolation", "1.0.0", [
+        ...(profile.interpolation === "bounded-regular-grid-multilinear"
+            ? []
+            : [
+                "Node kernels are translated to the weighted intensity centroid before blending (bilinear resampling, outside samples zero, renormalised), so shifted PSFs blend into one peak.",
+                ...(rotational
+                    ? ["Rotationally symmetric lens: nodes along +X are interpolated at the field radius and the kernel is rotated by the field azimuth."]
+                    : [])
+            ]),
         "PSF intensity is a unit-energy shape; relative pupil throughput remains a separate factor for the optical-throughput path.",
         "Regular-grid interpolation is bounded and never extrapolates beyond declared focal-length, focus, aperture, field, wavelength or signed-defocus axes.",
         "Full 2D image-plane kernel orientation is preserved in +X right, +Y up coordinates; no radial or sagittal/tangential averaging is forced.",
@@ -715,20 +926,20 @@ export function resolveLensSampledPsf(input) {
     ]);
 }
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
  *
- * Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
- * support. Interpolation stays within declared applicability and preserves normalized shape separately
- * from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
- * unique PSF.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns LensMtfDiagnosticProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+ * position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+ * the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+ * has no phase or spatial information, so it cannot justify rendering one unique PSF.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns LensMtfDiagnosticProfile. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function parseLensMtfDiagnosticProfile(value) {
-    const record = requireRecord(value, "lensMtfProfile");
+    const record = requireRecord(value, "lensMtfProfile", ["schemaVersion", "opticalDomain", "phaseInformationAvailable", "magnitudeMeaning", "samples", "fieldPointMm", "wavelengthNm", "profileId", "profileVersion", "focalLengthMm", "focus", "apertureFNumber", "evidence", "limitations"]);
     if (record.schemaVersion !==
         LENS_MTF_DIAGNOSTIC_PROFILE_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('lensMtfProfile.schemaVersion must be "' +
@@ -753,7 +964,7 @@ export function parseLensMtfDiagnosticProfile(value) {
         const path = "lensMtfProfile.samples[" +
             index +
             "]";
-        const sample = requireRecord(entry, path);
+        const sample = requireRecord(entry, path, ["spatialFrequencyCyclesPerMm", "sagittalMagnitude", "tangentialMagnitude"]);
         const frequency = requireNonNegativeFinite(sample
             .spatialFrequencyCyclesPerMm, path +
             ".spatialFrequencyCyclesPerMm");
@@ -773,7 +984,7 @@ export function parseLensMtfDiagnosticProfile(value) {
                 ".tangentialMagnitude")
         };
     });
-    const field = requireRecord(record.fieldPointMm, "lensMtfProfile.fieldPointMm");
+    const field = requireRecord(record.fieldPointMm, "lensMtfProfile.fieldPointMm", ["x", "y"]);
     const wavelength = record.wavelengthNm ===
         null
         ? null
@@ -799,15 +1010,15 @@ export function parseLensMtfDiagnosticProfile(value) {
     };
 }
 /**
- * Explain why MTF-only evidence cannot determine a unique renderable PSF; return blockers instead of
- * fabricating phase information.
+ * Explains why MTF-only evidence cannot determine one unique renderable PSF. Returns blockers instead
+ * of making up phase information.
  *
- * Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
- * support. Interpolation stays within declared applicability and preserves normalized shape separately
- * from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
- * unique PSF.
- * @param profile - LensMtfDiagnosticProfile. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns MtfOnlyPsfRenderabilityAssessment. Read structured blockers before consuming an authorization.
+ * A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+ * position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+ * the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+ * has no phase or spatial information, so it cannot justify rendering one unique PSF.
+ * @param profile - LensMtfDiagnosticProfile. See that type for coordinates, units and profile binding.
+ * @returns MtfOnlyPsfRenderabilityAssessment. Read the structured blockers before relying on any authorization.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */