@photivra/engine 1.5.0 → 2.1.0

package/docs/api/motion-temporal-exposure-sum.md

@@ -0,0 +1,98 @@
+# motion/temporal-exposure-sum.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.
+
+## calculateTemporalExposureSum
+
+Synchronous float64 reference for bounded grids. Use the image-kernel accelerator for large grids.
+
+```ts
+export function calculateTemporalExposureSum(input: TemporalExposureSumInput): { plan: TemporalExposureSumPlan; values: Float64Array };
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateTemporalExposureSumPlan
+
+Validates the request (every value once) and returns its plan.
+
+```ts
+export function calculateTemporalExposureSumPlan(input: TemporalExposureSumInput): TemporalExposureSumPlan;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## TEMPORAL_EXPOSURE_SUM_LIMITS
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+TEMPORAL_EXPOSURE_SUM_LIMITS = Object.freeze({
+  maximumPixels: 24_000_000,
+  maximumDimension: 16_384,
+  maximumTemporalSamples: 256,
+  maximumDisplacementSites: 4_096,
+  maximumRowWeights: 4_194_304,
+  /** Keeps every float32 partial sum finite: 256 · 2^16 · 2^100 < 2^128. */
+  maximumSampleMagnitude: 2 ** 100,
+  maximumWeight: 2 ** 16
+})
+```
+
+## TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## TemporalExposureSumInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface TemporalExposureSumInput {
+  schemaVersion: typeof TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION;
+  width: number;
+  height: number;
+  /** Row-major rate samples E₀ at site centres. Finite, non-negative, linear and additive (irradiance, photon or electron rate). */
+  samples: Float32Array | Float64Array;
+  /** Image displacement at each temporal node in grid sites, interleaved (dx₀, dy₀, dx₁, dy₁, …); +x right, +y down. */
+  displacements: Float64Array;
+  /** Quadrature weights `[k][row]` (nodes × height), finite and non-negative, for example seconds of each row's window near t_k. */
+  rowWeights: Float32Array | Float64Array;
+  boundary: "zero-outside-grid";
+}
+```
+
+## TemporalExposureSumNode
+
+One temporal node: integer source offset of the top-left tap and the four bilinear weights (float64).
+
+```ts
+export interface TemporalExposureSumNode {
+  offsetX: number;
+  offsetY: number;
+  weights: readonly [number, number, number, number];
+}
+```
+
+## TemporalExposureSumPlan
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface TemporalExposureSumPlan {
+  width: number;
+  height: number;
+  nodeCount: number;
+  nodes: readonly TemporalExposureSumNode[];
+  maximumSampleMagnitude: number;
+  /** Largest Σ_k w_k(y) over rows; the operator's weight sum for error composition. */
+  maximumRowWeightSum: number;
+  maximumWeight: number;
+  /** True when every displacement is a whole number of sites (no interpolation). */
+  integerDisplacements: boolean;
+}
+```

package/docs/api/motion-video-sequence.md

@@ -0,0 +1,159 @@
+# motion/video-sequence.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.
+
+## assessShutterAngleRule
+
+Compares a shutter angle with the 180° cinematographic convention (exposure = half the frame
+period). Within a relative 1e-9 the angle "matches". Otherwise the signed deviation is reported.
+
+```ts
+export function assessShutterAngleRule(frameRateHz: number, shutterAngleDegrees: number): ShutterAngleRuleAssessment;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateShutterAngleExposureSeconds
+
+Exposure time for a shutter angle (as on a rotary film-camera shutter): t = (angle / 360) / frameRateHz.
+A 180° angle exposes for half of each frame period.
+
+```ts
+export function calculateShutterAngleExposureSeconds(frameRateHz: number, shutterAngleDegrees: number): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateShutterAngleFromExposureSeconds
+
+Inverse of {@link calculateShutterAngleExposureSeconds}: angle = 360 · frameRateHz · t.
+
+```ts
+export function calculateShutterAngleFromExposureSeconds(frameRateHz: number, exposureSeconds: number): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## resolveVideoFrameSequence
+
+Resolves `frameCount` consecutive video frames starting at `firstFrameIndex`.
+
+Frame k (absolute index) opens k / frameRateHz seconds after the sequence starts, and exposes for
+(angle / 360) / frameRateHz. Its random seed is a MurmurHash3 of (sequence seed, k, stream id).
+
+Every value depends only on the inputs and k. So resolving frames 0–99 at once, or as 0–49 then
+50–99, gives identical frames.
+
+With a rolling shutter, the line at normalized scan position s in frame k integrates over
+[k/f + s·τ, k/f + s·τ + T]. τ must not exceed the frame period, so each line is read once per
+frame.
+
+```ts
+export function resolveVideoFrameSequence(input: ResolveVideoFrameSequenceInput): VideoFrameSequence;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveVideoFrameSequenceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveVideoFrameSequenceInput {
+  sequenceId: string;
+  /** Exact optical capture state. captureMode must be "video", with a positive frameRateHz. */
+  opticalState: OpticalProfileState;
+  /** Shutter angle in (0, 360]; exposure = angle / 360 / frameRateHz. */
+  shutterAngleDegrees: number;
+  /** Absolute index of the first frame to resolve (default 0). */
+  firstFrameIndex?: number;
+  frameCount: number;
+  sequenceSeedUint32: number;
+  iso: number;
+  /** Defaults to the optical state's finite focus distance. */
+  focus?: FocusPlane;
+  automation: { ae: ReleaseAutomationState; af: ReleaseAutomationState; awb: ReleaseAutomationState };
+  whiteBalanceStateId?: string;
+  /** Evidence for the commanded frame rate and shutter-angle timing. Used for the exposure fact. */
+  timingEvidence: readonly EvidenceProvenance[];
+  /** Optional electronic rolling shutter applied identically to every frame. */
+  rollingShutter?: {
+    readout: RollingSensorReadoutTimingDeclaration;
+    linkageEvidence: readonly EvidenceProvenance[];
+  };
+}
+```
+
+## ShutterAngleRuleAssessment
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ShutterAngleRuleAssessment {
+  frameRateHz: number;
+  shutterAngleDegrees: number;
+  exposureSeconds: number;
+  /** 1 / (2 · frameRateHz): the 180° convention. */
+  conventionExposureSeconds: number;
+  /** log2(exposure / convention): negative is shorter (crisper, more staccato) motion. */
+  deviationStops: number;
+  classification: "matches-180-degree-convention" | "shorter-than-convention" | "longer-than-convention";
+  /** The 180° rule is a cinematographic convention for motion-blur appearance, not a physical law. */
+  conventionNotPhysics: true;
+}
+```
+
+## VIDEO_FRAME_SEED_STREAM_ID
+
+Stream identifier ("VIDF"). Keeps per-frame video seeds separate from per-site noise streams.
+
+```ts
+VIDEO_FRAME_SEED_STREAM_ID = 0x56494446 as const
+```
+
+## VIDEO_FRAME_SEQUENCE_MAXIMUM_FRAMES
+
+Maximum frames per call. Resolve longer clips in chunks using firstFrameIndex.
+
+```ts
+VIDEO_FRAME_SEQUENCE_MAXIMUM_FRAMES = 100_000 as const
+```
+
+## VIDEO_FRAME_SEQUENCE_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+VIDEO_FRAME_SEQUENCE_VERSION = "1.0.0" as const
+```
+
+## VideoFrameSequence
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface VideoFrameSequence {
+  version: typeof VIDEO_FRAME_SEQUENCE_VERSION;
+  sequenceId: string;
+  frameRateHz: number;
+  framePeriodSeconds: number;
+  shutterAngleDegrees: number;
+  exposureSeconds: number;
+  shutterAngleRule: ShutterAngleRuleAssessment;
+  firstFrameIndex: number;
+  frameCount: number;
+  sequenceSeedUint32: number;
+  seedDerivation: "murmur3-x86-32(sequenceSeed, absoluteFrameIndex, VIDEO_FRAME_SEED_STREAM_ID)";
+  frameTimeDerivation: "absoluteFrameIndex / frameRateHz";
+  /**
+   * Exposure schedule for each frame. It is the same for every frame; times are relative to each
+   * frame's own first-opening phase. Null when no rolling shutter is declared; the caller then
+   * supplies the global schedule of its capture mode.
+   */
+  exposureSchedule: ReturnType<typeof createRollingShutterCaptureExposureSchedule> | null;
+  rollingShutter: Pick<ElectronicRollingShutterExposureSchedule, "modelId" | "modelVersion" | "lineScanSkewSeconds" | "linkage"> | null;
+  /** Ordinary release frames: pass each to createProductionCaptureSnapshotFromReleaseFrame. */
+  frames: readonly ResolvedReleaseFrame[];
+  limitations: readonly string[];
+}
+```

package/docs/api/optics-aperture.md

@@ -1,6 +1,6 @@
 # optics/aperture.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.
 
 ## ApertureVertex
 
@@ -15,12 +15,12 @@ export interface ApertureVertex {
 
 ## calculateIdealApertureGeometry
 
-Calculates ideal regular-polygon aperture geometry and the corresponding
-straight-edge diffraction-ray directions.
+Calculates ideal regular-polygon aperture geometry and the directions of
+the diffraction rays from its straight edges.
 
-This models only geometry/symmetry. It does not calculate diffraction
+This models only geometry and symmetry. It does not calculate diffraction
 intensity, wavelength-dependent star length, blade curvature, lens
-aberrations, coatings, or sensor blooming.
+aberrations, coatings or sensor blooming.
 
 ```ts
 export function calculateIdealApertureGeometry(
@@ -58,9 +58,9 @@ export interface IdealApertureGeometry {
   /**
    * Diffraction-ray directions in degrees, normalized to [0, 360).
    *
-   * Each ray is perpendicular to a blade edge. Parallel opposite edges overlap
-   * for even blade counts; odd blade counts therefore produce twice as many
-   * visible ray directions.
+   * Each ray is perpendicular to a blade edge. With an even blade count,
+   * opposite edges are parallel and their rays overlap. An odd blade count
+   * therefore gives twice as many visible ray directions.
    */
   sunstarRayAnglesDegrees: readonly number[];
   /** Unit-circumradius regular-polygon vertices. */

package/docs/api/optics-atmospheric-haze.md

@@ -0,0 +1,104 @@
+# optics/atmospheric-haze.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.
+
+## AtmosphericExtinctionModel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AtmosphericExtinctionModel {
+  /** Wavelength at which the reference coefficients apply, nm. */
+  referenceWavelengthNm: number;
+  /** Molecular (Rayleigh) extinction coefficient at the reference wavelength, 1/m (>= 0). */
+  rayleighExtinctionPerMeter: number;
+  /** Aerosol extinction coefficient at the reference wavelength, 1/m (>= 0). */
+  aerosolExtinctionPerMeter: number;
+  /** Angstrom exponent alpha for the aerosol term (finite, typically 0-2.5). */
+  angstromExponent: number;
+  /** Rayleigh wavelength exponent; defaults to 4. */
+  rayleighExponent?: number;
+}
+```
+
+## AtmosphericHaze
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AtmosphericHaze {
+  wavelengthNm: number;
+  pathLengthM: number;
+  rayleighExtinctionPerMeter: number;
+  aerosolExtinctionPerMeter: number;
+  extinctionPerMeter: number;
+  opticalDepth: number;
+  /** Direct transmittance t = exp(-beta d). */
+  transmittance: number;
+  /** L0 t. */
+  attenuatedSceneRadiance: number;
+  /** L_air (1 - t). */
+  airlightContribution: number;
+  /** L0 t + L_air (1 - t), in the input radiance unit. */
+  hazedRadiance: number;
+  /** Apparent contrast against the horizon divided by the intrinsic contrast: (L - L_air)/(L0 - L_air) = t. */
+  contrastTransmittance: number;
+}
+```
+
+## calculateAtmosphericHaze
+
+Koschmieder haze at one wavelength: attenuated scene radiance plus airlight, with Rayleigh and
+Angstrom-law aerosol extinction.
+
+```ts
+export function calculateAtmosphericHaze(
+  input: CalculateAtmosphericHazeInput
+): CalculationResult<AtmosphericHaze>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateAtmosphericHazeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateAtmosphericHazeInput {
+  /** Line-of-sight distance through the homogeneous haze, metres (>= 0). */
+  pathLengthM: number;
+  /** Wavelength, nm (same basis as the extinction data). */
+  wavelengthNm: number;
+  /** Scene (object) radiance at zero distance, any linear radiance unit (>= 0). */
+  sceneRadiance: number;
+  /** Horizon/airlight radiance in the same unit (>= 0). */
+  airlightRadiance: number;
+  extinction: AtmosphericExtinctionModel;
+}
+```
+
+## calculateExtinctionFromVisibility
+
+Extinction coefficient from meteorological visibility with Koschmieder's relation
+beta = -ln(epsilon) / V.
+
+```ts
+export function calculateExtinctionFromVisibility(
+  input: CalculateExtinctionFromVisibilityInput
+): CalculationResult<{ extinctionPerMeter: number; contrastThreshold: number }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateExtinctionFromVisibilityInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateExtinctionFromVisibilityInput {
+  /** Meteorological visibility, metres. */
+  visibilityM: number;
+  /** Contrast threshold epsilon in (0, 1); Koschmieder 0.02 by default, WMO MOR uses 0.05. */
+  contrastThreshold?: number;
+}
+```

package/docs/api/optics-brown-conrady-distortion.md

@@ -0,0 +1,123 @@
+# optics/brown-conrady-distortion.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.
+
+## BrownConradyDistortionCoefficients
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BrownConradyDistortionCoefficients {
+  /** Radial r^2 coefficient. */
+  k1: number;
+  /** Radial r^4 coefficient. */
+  k2: number;
+  /** Radial r^6 coefficient. */
+  k3: number;
+  /** Tangential (decentering) coefficient p1 (couples to y; see module equation). */
+  p1: number;
+  /** Tangential (decentering) coefficient p2 (couples to x; see module equation). */
+  p2: number;
+}
+```
+
+## BrownConradyDistortionMapping
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BrownConradyDistortionMapping {
+  direction: "undistorted-to-distorted";
+  sourceImagePointMm: LensFieldPointMm;
+  mappedImagePointMm: LensFieldPointMm;
+  sourceNormalizedRadius: number;
+  /** Determinant of d(mapped)/d(source) at the source point (dimensionless area scale). */
+  jacobianDeterminant: number;
+  deltaMm: { x: number; y: number; distance: number };
+  profileMinimumJacobianDeterminant: number;
+}
+```
+
+## BrownConradyDistortionProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BrownConradyDistortionProfile {
+  /** Physical image-plane radius used to normalize field position, in mm. */
+  normalizationRadiusMm: number;
+  /** Maximum undistorted normalized radius of the operating envelope. */
+  maximumNormalizedRadius: number;
+  coefficients: BrownConradyDistortionCoefficients;
+}
+```
+
+## calculateBrownConradyDistortionMapping
+
+Applies the Brown-Conrady forward mapping to one ideal image-plane point.
+
+```ts
+export function calculateBrownConradyDistortionMapping(
+  input: CalculateBrownConradyDistortionMappingInput
+): CalculationResult<BrownConradyDistortionMapping>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateBrownConradyDistortionMappingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateBrownConradyDistortionMappingInput {
+  /** Ideal/undistorted image-plane point, in mm. */
+  imagePointMm: LensFieldPointMm;
+  profile: BrownConradyDistortionProfile;
+}
+```
+
+## calculateInverseBrownConradyDistortionMapping
+
+Inverse-maps one distorted image-plane point to its ideal source point, for destination-to-source
+resampling. Damped Newton iteration starts from the radial-only inverse. The solution must lie
+inside the declared envelope and must reproduce the distorted point within a relative tolerance of
+1e-12.
+
+```ts
+export function calculateInverseBrownConradyDistortionMapping(
+  input: CalculateInverseBrownConradyDistortionMappingInput
+): CalculationResult<InverseBrownConradyDistortionMapping>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateInverseBrownConradyDistortionMappingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateInverseBrownConradyDistortionMappingInput {
+  /** Distorted image-plane point to map back to ideal coordinates, in mm. */
+  distortedImagePointMm: LensFieldPointMm;
+  profile: BrownConradyDistortionProfile;
+}
+```
+
+## InverseBrownConradyDistortionMapping
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface InverseBrownConradyDistortionMapping {
+  direction: "distorted-to-undistorted";
+  distortedImagePointMm: LensFieldPointMm;
+  sourceImagePointMm: LensFieldPointMm;
+  sourceNormalizedRadius: number;
+  jacobianDeterminantAtSource: number;
+  newtonIterations: number;
+  /** Forward-mapping residual of the solved source point, in mm. */
+  residualMm: number;
+  deltaMm: { x: number; y: number; distance: number };
+  profileMinimumJacobianDeterminant: number;
+}
+```

package/docs/api/optics-circle-of-confusion.md

@@ -1,6 +1,6 @@
 # optics/circle-of-confusion.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.
 
 ## EquivalentViewingCircleOfConfusion
 
@@ -17,11 +17,12 @@ export interface EquivalentViewingCircleOfConfusion {
 
 ## estimateEquivalentViewingCircleOfConfusion
 
-Estimates a circle-of-confusion criterion for equivalent final viewing by
-scaling a caller-supplied reference criterion in proportion to sensor
+Estimates a circle-of-confusion criterion for equivalent final viewing. It
+scales a caller-supplied reference criterion in proportion to the sensor
 diagonal.
 
-This is a viewing/acceptability convention, not a physical blur threshold.
+This is a viewing (acceptable-sharpness) convention, not a physical blur
+threshold.
 
 ```ts
 export function estimateEquivalentViewingCircleOfConfusion(

package/docs/api/optics-complex-pupil-psf.md

@@ -1,16 +1,16 @@
 # optics/complex-pupil-psf.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.
 
 ## calculateLensComplexPupilPsf
 
-Evaluate a declared complex pupil with explicit amplitude/phase and sampling support; normalize PSF
-shape and retain pupil throughput as a separate quantity.
+Evaluates a declared complex pupil with explicit amplitude, phase and sampling support. Returns the
+normalized PSF shape, and the 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.
+The complex pupil is evaluated by summing the declared amplitude and phase over a bounded, regular
+pupil grid. The PSF shape is normalized separately from the pupil throughput. A single blur radius
+cannot stand in for coherent phase, pupil energy, or the wavelength and field range where the
+profile applies. Numeric profiles need provenance showing the data is owned or reusable.
 
 ```ts
 export function calculateLensComplexPupilPsf(
@@ -29,9 +29,9 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface CalculateLensComplexPupilPsfInput {
   profile:
     LensComplexPupilProfile;
-  /** Physical pupil-to-image propagation scale in mm. Omission preserves the
-   * nominal focal-plane reference. Finite-focus callers must explicitly resolve
-   * the supported principal-plane geometry; profile metadata does not do so. */
+  /** Physical propagation distance from pupil to image, in mm. If omitted, the
+   * nominal focal-plane reference is used. At finite focus the caller must
+   * resolve the supported principal-plane geometry; profile metadata does not. */
   propagationDistanceMm?: number;
 }
 ```
@@ -146,6 +146,8 @@ export interface LensComplexPupilPsf {
   context:
     LensComplexPupilProfile["context"];
   kernel: LensPsfKernel;
+  /** Nyquist sampling diagnostics and the applied zero padding. */
+  sampling: LensComplexPupilPsfSampling;
   relativePupilThroughputFactor:
     number;
   throughputOwnership:
@@ -180,15 +182,54 @@ export interface LensComplexPupilPsf {
 }
 ```
 
+## LensComplexPupilPsfSampling
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensComplexPupilPsfSampling {
+  criterion: "discrete-intensity-alias-free-goodman-q-above-2";
+  /** Number of pupil samples spanned by non-zero amplitude, per axis. */
+  pupilSupportSamplesX: number;
+  pupilSupportSamplesY: number;
+  /**
+   * Sampled pupil diameter D = (support samples - 1) x pupil pitch: the
+   * centre-to-centre span of the outermost non-zero samples, in millimetres.
+   */
+  pupilSupportDiameterMmX: number;
+  pupilSupportDiameterMmY: number;
+  /**
+   * Widest support allowed by the declared f-number at the resolved propagation distance:
+   * propagationDistanceMm / apertureFNumber, in millimetres. For the nominal focal-plane reference
+   * this is focalLengthMm / apertureFNumber.
+   */
+  declaredPupilDiameterMm: number;
+  /** Declared pupil grid size before zero padding. */
+  pupilGridWidthSamples: number;
+  pupilGridHeightSamples: number;
+  /** DFT size after zero padding; equals the output kernel size. */
+  transformWidthSamples: number;
+  transformHeightSamples: number;
+  zeroPaddingApplied: boolean;
+  /**
+   * Achieved Goodman sampling factor Q = lambda*(z/D)/imagePitch =
+   * transform samples / (support samples - 1). Always greater than 2. Null
+   * when the support is a single sample on that axis (no finite diameter).
+   */
+  samplingFactorQX: number | null;
+  samplingFactorQY: number | null;
+}
+```
+
 ## parseLensComplexPupilProfile
 
-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.
 
-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.
+The complex pupil is evaluated by summing the declared amplitude and phase over a bounded, regular
+pupil grid. The PSF shape is normalized separately from the pupil throughput. A single blur radius
+cannot stand in for coherent phase, pupil energy, or the wavelength and field range where the
+profile applies. Numeric profiles need provenance showing the data is owned or reusable.
 
 ```ts
 export function parseLensComplexPupilProfile(