@photivra/engine 1.5.0 → 2.0.0

package/docs/api/optics-front-of-lens-filter.md

@@ -1,6 +1,6 @@
 # optics/front-of-lens-filter.ts public contracts
 
-Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## ComposedFrontOfLensFilterTransmission
 
@@ -9,7 +9,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface ComposedFrontOfLensFilterTransmission {
   schemaVersion:
-    typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION;
+    FrontOfLensFilterProfileSchemaVersion;
   wavelengthNanometers: number;
   wavelengthBasis:
     Exclude<
@@ -28,8 +28,11 @@ export interface ComposedFrontOfLensFilterTransmission {
     "not-propagated";
   uncertaintyLimitation: string;
   compositionModel:
-    "independent-multiplicative-unpolarized-transmission-no-inter-filter-reflections";
-  polarizationModeled: false;
+    | "independent-multiplicative-unpolarized-transmission-no-inter-filter-reflections"
+    | "ordered-linear-stokes-mueller-no-inter-filter-reflections";
+  polarizationModeled: boolean;
+  incidentPolarization: LinearPolarizationState;
+  transmittedPolarization: LinearPolarizationState;
   wavelengthChangingBehaviorModeled:
     false;
   lensTransmissionIncluded: false;
@@ -40,8 +43,9 @@ export interface ComposedFrontOfLensFilterTransmission {
 
 ## composeFrontOfLensFilterTransmission
 
-Composes multiple passive front-of-lens filters multiplicatively at one
-wavelength while preserving each component's identity.
+Combines several passive front-of-lens filters at one wavelength, in light-path order, and keeps
+each filter's identity. Without a polarizer the result is the product of the transmissions. With
+one, linear Stokes parameters pass through the Mueller matrices in order.
 
 ```ts
 export function composeFrontOfLensFilterTransmission(
@@ -58,6 +62,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 
 ```ts
 export interface ComposeFrontOfLensFilterTransmissionInput {
+  /** Filters in light-path order (scene side first). */
   filters:
     readonly FrontOfLensFilterProfile[];
   wavelengthNanometers: number;
@@ -66,6 +71,8 @@ export interface ComposeFrontOfLensFilterTransmissionInput {
       SpectralWavelengthBasis,
       "unspecified"
     >;
+  /** Incident scene polarization; omitted means unpolarized. */
+  incidentPolarization?: LinearPolarizationState;
 }
 ```
 
@@ -78,6 +85,15 @@ FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION =
   "0.1.0" as const
 ```
 
+## FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION
+
+Schema that also allows the `linear-polarizer` transmission kind.
+
+```ts
+FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION =
+  "0.2.0" as const
+```
+
 ## FrontOfLensFilterProfile
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -85,7 +101,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface FrontOfLensFilterProfile {
   schemaVersion:
-    typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION;
+    FrontOfLensFilterProfileSchemaVersion;
   filterId: string;
   profileVersion: string;
   identityScope:
@@ -106,7 +122,8 @@ export interface FrontOfLensFilterProfile {
     FrontOfLensFilterTransmissionModel;
   uncertainty:
     FrontOfLensFilterUncertainty;
-  polarizationModeled: false;
+  /** True exactly when the transmission kind is `linear-polarizer` (schema 0.2.0). */
+  polarizationModeled: boolean;
   wavelengthChangingBehaviorModeled:
     false;
   evidence: readonly EvidenceProvenance[];
@@ -114,6 +131,16 @@ export interface FrontOfLensFilterProfile {
 }
 ```
 
+## FrontOfLensFilterProfileSchemaVersion
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type FrontOfLensFilterProfileSchemaVersion =
+  | typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION
+  | typeof FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION;
+```
+
 ## FrontOfLensFilterScientificStatus
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -157,6 +184,18 @@ export type FrontOfLensFilterTransmissionModel =
         EvidenceBackedFact<
           readonly FrontOfLensFilterSpectralSample[]
         >;
+    }
+  | {
+      /** Schema 0.2.0 only. Neutral (wavelength-independent) within the declared range. */
+      kind: "linear-polarizer";
+      /** k1: intensity transmittance for light polarized along the transmission axis, (0, 1]. */
+      principalTransmittance:
+        EvidenceBackedFact<number>;
+      /** k1 / k2. Finite and >= 1. Use a large finite ratio for a near-ideal polarizer. */
+      extinctionRatio:
+        EvidenceBackedFact<number>;
+      /** Transmission-axis angle as mounted, degrees counter-clockwise from image +X. */
+      transmissionAxisDegrees: number;
     };
 ```
 
@@ -177,14 +216,27 @@ export type FrontOfLensFilterUncertainty =
     };
 ```
 
+## LinearPolarizationState
+
+Partially linearly polarized light: degree P in [0, 1] and polarization angle psi.
+
+```ts
+export interface LinearPolarizationState {
+  /** Degree of linear polarization P in [0, 1]; 0 is unpolarized. */
+  degreeOfLinearPolarization: number;
+  /** Electric-field polarization angle, degrees counter-clockwise from image +X. */
+  angleDegrees: number;
+}
+```
+
 ## parseFrontOfLensFilterProfile
 
 Parses one generic front-of-lens transmission filter.
 
 Schema 0.1.0 is explicitly unbranded and unpolarized. It models only
-passive transmission placed before the lens. Reflections between stacked
-filters, polarization, flare/ghosting and wavelength-changing behavior are
-outside this contract.
+passive transmission in front of the lens. It does not cover reflections
+between stacked filters, polarization, flare or ghosting, or filters that
+change wavelength.
 
 ```ts
 export function parseFrontOfLensFilterProfile(
@@ -201,7 +253,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface ResolvedFrontOfLensFilterTransmission {
   schemaVersion:
-    typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION;
+    FrontOfLensFilterProfileSchemaVersion;
   filterId: string;
   profileVersion: string;
   identityScope:
@@ -217,10 +269,13 @@ export interface ResolvedFrontOfLensFilterTransmission {
     >;
   transmissionKind:
     FrontOfLensFilterTransmissionModel["kind"];
+  /** Intensity transmittance for the declared incident polarization. */
   linearTransmissionFactor: number;
   attenuationStops: number;
   opticalDensityBase10: number;
-  polarizationModeled: false;
+  polarizationModeled: boolean;
+  incidentPolarization: LinearPolarizationState;
+  transmittedPolarization: LinearPolarizationState;
   wavelengthChangingBehaviorModeled:
     false;
   lensTransmissionIncluded: false;
@@ -235,7 +290,8 @@ export interface ResolvedFrontOfLensFilterTransmission {
 
 ## resolveFrontOfLensFilterTransmission
 
-Resolves one passive filter at one wavelength.
+Resolves one passive filter at one wavelength. Non-polarizing filters scale all Stokes
+components equally, so their transmission does not depend on the incident polarization.
 
 ```ts
 export function resolveFrontOfLensFilterTransmission(
@@ -259,5 +315,7 @@ export interface ResolveFrontOfLensFilterTransmissionInput {
       SpectralWavelengthBasis,
       "unspecified"
     >;
+  /** Incident polarization; omitted means unpolarized. */
+  incidentPolarization?: LinearPolarizationState;
 }
 ```

package/docs/api/optics-illumination-vignetting.md

@@ -1,15 +1,15 @@
 # optics/illumination-vignetting.ts public contracts
 
-Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateIlluminationVignetting
 
-Calculates generic field-dependent illumination falloff as a multiplicative
-linear-light throughput factor.
+Calculates generic illumination falloff across the image (vignetting) as a
+factor that multiplies linear light.
 
-The profile is accepted only when its relative throughput remains strictly
-positive and never exceeds the optical-axis normalization of 1 throughout
-the complete declared operating envelope.
+A profile is accepted only if its relative throughput stays strictly
+positive and never exceeds 1 (the value on the optical axis) anywhere in
+its declared range.
 
 ```ts
 export function calculateIlluminationVignetting(
@@ -28,8 +28,8 @@ export interface CalculateIlluminationVignettingInput {
   /**
    * Ideal image-plane field position relative to the optical axis, in mm.
    *
-   * This slice evaluates throughput from the declared ideal field coordinate;
-   * it does not apply or invert geometric distortion.
+   * Throughput is evaluated at this ideal field coordinate. Geometric
+   * distortion is neither applied nor inverted.
    */
   imagePointMm: LensFieldPointMm;
   profile: IlluminationVignettingProfile;
@@ -45,9 +45,9 @@ export interface IlluminationVignetting {
   imagePointMm: LensFieldPointMm;
   normalizedRadius: number;
   /**
-   * Multiplicative factor for scene-linear/channel-linear signal.
+   * Factor that multiplies scene-linear or channel-linear signal.
    *
-   * 1 means no attenuation; values are required to remain in (0, 1].
+   * 1 means no attenuation. Values must stay in (0, 1].
    */
   linearThroughputFactor: number;
   /** Positive exposure loss relative to the optical axis, in stops. */

package/docs/api/optics-irradiance-convolution.md

@@ -0,0 +1,95 @@
+# optics/irradiance-convolution.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculateIrradianceConvolution
+
+Synchronous float64 reference for bounded grids. Use the image-kernel accelerator for large grids.
+
+```ts
+export function calculateIrradianceConvolution(input: IrradianceConvolutionInput): { plan: IrradianceConvolutionPlan; values: Float64Array };
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateIrradianceConvolutionPlan
+
+Validates the request and returns its plan. Every sample and weight is checked once.
+
+```ts
+export function calculateIrradianceConvolutionPlan(input: IrradianceConvolutionInput): IrradianceConvolutionPlan;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## IRRADIANCE_CONVOLUTION_LIMITS
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+IRRADIANCE_CONVOLUTION_LIMITS = Object.freeze({
+  maximumPixels: 24_000_000,
+  maximumDimension: 16_384,
+  maximumKernelRadius: 32,
+  maximumPatchCount: 4_096,
+  maximumKernelWeights: 4_194_304,
+  /** A kernel may lose energy (vignetting, transmission) but may not create it, beyond rounding slack. */
+  maximumKernelSum: 1 + 2 ** -20,
+  /** Inputs larger than this are rejected so that float32 execution cannot overflow. */
+  maximumSampleMagnitude: 2 ** 100
+})
+```
+
+## IRRADIANCE_CONVOLUTION_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+IRRADIANCE_CONVOLUTION_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## IrradianceConvolutionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IrradianceConvolutionInput {
+  schemaVersion: typeof IRRADIANCE_CONVOLUTION_SCHEMA_VERSION;
+  width: number;
+  height: number;
+  /** Row-major samples. Finite, non-negative, linear and additive (for example irradiance, or expected photons per site). */
+  samples: Float32Array | Float64Array;
+  /** Kernel half-width in grid sites. Each kernel is (2r+1)×(2r+1). */
+  kernelRadius: number;
+  /** Patch size in grid sites. The last row and column of patches may be partial. */
+  patchWidth: number;
+  patchHeight: number;
+  /**
+   * Finite non-negative weights, `[patchRow][patchColumn][v + r][u + r]`, one kernel per patch in
+   * row-major patch order. Each kernel sums to at most 1 (+2^-20 rounding slack).
+   */
+  kernels: Float32Array | Float64Array;
+  boundary: "zero-outside-grid";
+}
+```
+
+## IrradianceConvolutionPlan
+
+Validated, immutable geometry of a convolution request. Sample arrays are borrowed, not copied.
+
+```ts
+export interface IrradianceConvolutionPlan {
+  width: number;
+  height: number;
+  kernelRadius: number;
+  kernelSize: number;
+  tapCount: number;
+  patchWidth: number;
+  patchHeight: number;
+  patchColumns: number;
+  patchRows: number;
+  /** Largest kernel sum and largest input magnitude. The float32 error bound uses them. */
+  maximumKernelSum: number;
+  maximumSampleMagnitude: number;
+}
+```

package/docs/api/optics-lateral-chromatic-aberration.md

@@ -1,14 +1,14 @@
 # optics/lateral-chromatic-aberration.ts public contracts
 
-Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateInverseLateralChromaticAberrationMapping
 
-Inverse-maps one distorted output destination independently for the
-representative red/green/blue channels.
+Inverse-maps one distorted output point separately for the representative
+red, green and blue channels.
 
-Renderers can use the returned per-channel ideal source coordinates for
-inverse sampling without inventing chromatic-aberration equations.
+Renderers can sample the returned per-channel ideal source points directly,
+without writing their own chromatic-aberration equations.
 
 ```ts
 export function calculateInverseLateralChromaticAberrationMapping(
@@ -25,8 +25,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface CalculateInverseLateralChromaticAberrationMappingInput {
   /**
-   * Distorted output image-plane destination. Each output channel is inverse-
-   * mapped independently to its ideal source coordinate.
+   * Distorted output image-plane point. Each channel is inverse-mapped on its
+   * own to its ideal source point.
    */
   distortedImagePointMm: LensFieldPointMm;
   profile: LateralChromaticAberrationProfile;
@@ -35,12 +35,12 @@ export interface CalculateInverseLateralChromaticAberrationMappingInput {
 
 ## calculateInverseLateralChromaticAberrationMappings
 
-Inverse-maps multiple distorted destinations while resolving the shared CA
-profile once and validating each combined channel profile once for the
-complete batch.
+Inverse-maps many distorted points at once. The shared CA profile is
+resolved once, and each combined channel profile is validated once, for
+the whole batch.
 
-Per-point values match calculateInverseLateralChromaticAberrationMapping();
-provenance is shared once at the batch boundary.
+Each point's values match calculateInverseLateralChromaticAberrationMapping().
+Provenance is reported once for the batch.
 
 ```ts
 export function calculateInverseLateralChromaticAberrationMappings(
@@ -57,9 +57,9 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface CalculateInverseLateralChromaticAberrationMappingsInput {
   /**
-   * Distorted output image-plane destinations. Each destination is inverse-
-   * mapped independently for red, green, and blue after one profile-resolution
-   * step for the batch.
+   * Distorted output image-plane points. The profile is resolved once for the
+   * batch. Then each point is inverse-mapped separately for red, green and
+   * blue.
    */
   distortedImagePointsMm: readonly LensFieldPointMm[];
   profile: LateralChromaticAberrationProfile;
@@ -68,11 +68,12 @@ export interface CalculateInverseLateralChromaticAberrationMappingsInput {
 
 ## calculateLateralChromaticAberrationMapping
 
-Calculates generic lateral chromatic-aberration field separation by mapping
-one ideal image-plane point through a shared green-reference base distortion
-and red/blue radial coefficient offsets.
+Calculates how far lateral chromatic aberration (CA) separates the colour
+channels at one ideal image-plane point. The point goes through a shared
+base distortion (green is the reference) plus extra radial coefficients for
+red and blue.
 
-This is channel-dependent field mapping, not a blur kernel.
+This moves each channel; it is not a blur kernel.
 
 ```ts
 export function calculateLateralChromaticAberrationMapping(
@@ -200,8 +201,8 @@ export interface LateralChromaticAberrationProfile {
   /**
    * Green-reference base geometric distortion.
    *
-   * This common mapping is included in every channel. Red/blue CA terms are
-   * added to this base, so callers should not apply a second distortion pass.
+   * Every channel includes this shared mapping. The red and blue CA terms are
+   * added on top of it, so do not apply a second distortion pass.
    */
   baseDistortionCoefficients: RadialDistortionCoefficients;
   /** Additional red-channel radial coefficients relative to green. */

package/docs/api/optics-lens-psf-kernels.md

@@ -0,0 +1,72 @@
+# optics/lens-psf-kernels.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS
+
+At most this many wavelengths per call.
+
+```ts
+LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS = 64
+```
+
+## LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## LensPsfConvolutionKernels
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensPsfConvolutionKernels {
+  schemaVersion: typeof LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION;
+  kernelRadius: number;
+  patchWidth: number;
+  patchHeight: number;
+  patchColumns: number;
+  patchRows: number;
+  /** `[patchRow][patchColumn][v + r][u + r]`, ready for `IrradianceConvolutionInput.kernels`. */
+  kernels: Float64Array;
+  /** True when every tap landed on one integer displacement (no bilinear splatting). */
+  exactSiteSampling: boolean;
+  maximumKernelSum: number;
+  /** Per patch, row-major: the field point used and the weight-averaged relative pupil throughput (not applied). */
+  patches: readonly { fieldPointMm: { x: number; y: number }; relativePupilThroughputFactor: number; interpolated: boolean }[];
+}
+```
+
+## LensPsfConvolutionKernelsInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensPsfConvolutionKernelsInput {
+  schemaVersion: typeof LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION;
+  /** The optical state, as for `resolveLensSampledPsf`, without the field point and wavelength. */
+  psf: Omit<ResolveLensSampledPsfInput, "fieldPointMm" | "wavelengthNm">;
+  /** One or more wavelengths with non-negative weights (at least one positive). */
+  spectralWeights: readonly { wavelengthNm: number; weight: number }[];
+  /** The convolution grid: sites, their pitch, and the optical axis in site units (site centres at i + 0.5). */
+  grid: { width: number; height: number; sitePitchMicrometers: { x: number; y: number }; opticalAxisSite: { x: number; y: number } };
+  /** Patch size in sites; the last row and column of patches may be partial. */
+  patchWidth: number;
+  patchHeight: number;
+  /** Kernel radius to use; omitted, the smallest radius that holds every tap. A radius too small to hold the PSF is rejected. */
+  kernelRadius?: number;
+}
+```
+
+## resolveLensPsfConvolutionKernels
+
+Builds the per-patch convolution kernels from a sampled lens PSF profile.
+
+```ts
+export function resolveLensPsfConvolutionKernels(input: LensPsfConvolutionKernelsInput): CalculationResult<LensPsfConvolutionKernels>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/optics-lens-psf-profile.md

@@ -1,16 +1,16 @@
 # optics/lens-psf-profile.ts public contracts
 
-Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## assessMtfOnlyPsfRenderability
 
-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.
+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.
 
 ```ts
 export function assessMtfOnlyPsfRenderability(
@@ -189,6 +189,28 @@ export interface LensSampledPsfGridNode {
 }
 ```
 
+## LensSampledPsfInterpolation
+
+Kernel interpolation between regular-grid nodes.
+- `bounded-regular-grid-multilinear`: the legacy weighted sum of kernel values. Blending kernels
+  whose peaks sit at different positions gives several peaks.
+- `bounded-regular-grid-centroid-aligned`: each node kernel is first shifted so its intensity
+  centroid sits at the weighted (interpolated) centroid. Then the same multilinear weights are
+  applied. Shifted or asymmetric PSFs therefore blend into one peak at the interpolated position.
+- `rotationally-symmetric-radial-field-centroid-aligned`: for a rotationally symmetric lens. Nodes
+  are declared only along the +X field axis (fieldYmm = [0], fieldXmm >= 0). A query at field
+  (x, y) is interpolated, with centroid alignment, at radius hypot(x, y). The kernel is then
+  rotated by atan2(y, x) about its centre. The sample pitch must be square.
+Shifts and rotations use bilinear resampling. This smooths the kernel slightly (by at most about
+one sample). Samples outside the kernel are zero, and the result is renormalised to unit energy.
+
+```ts
+export type LensSampledPsfInterpolation =
+  | "bounded-regular-grid-multilinear"
+  | "bounded-regular-grid-centroid-aligned"
+  | "rotationally-symmetric-radial-field-centroid-aligned";
+```
+
 ## LensSampledPsfProfile
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -210,7 +232,7 @@ export interface LensSampledPsfProfile {
   kernelEnergyNormalization:
     "unit-energy-shape";
   interpolation:
-    "bounded-regular-grid-multilinear";
+    LensSampledPsfInterpolation;
   throughputOwnership:
     "separate-relative-pupil-throughput-factor";
   responseIncludes: {
@@ -253,13 +275,13 @@ export interface MtfOnlyPsfRenderabilityAssessment {
 
 ## parseLensMtfDiagnosticProfile
 
-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.
+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.
 
 ```ts
 export function parseLensMtfDiagnosticProfile(
@@ -271,13 +293,13 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseLensSampledPsfProfile
 
-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.
+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.
 
 ```ts
 export function parseLensSampledPsfProfile(
@@ -341,13 +363,13 @@ export interface ResolvedLensSampledPsf {
 
 ## resolveLensSampledPsf
 
-Resolve the bounded sampled PSF for a declared optical state and support point without extrapolation
-or silently inventing missing dimensions.
+Resolves the sampled PSF for a declared optical state and query point. It never extrapolates and
+never invents 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.
+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.
 
 ```ts
 export function resolveLensSampledPsf(