@photivra/engine 1.4.0 → 2.0.0

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

@@ -0,0 +1,128 @@
+# optics/longitudinal-chromatic-aberration.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.
+
+## calculateCauchyRefractiveIndex
+
+Two-term Cauchy refractive index fitted to n_d and V_d. Valid as an approximation over
+360-830 nm only.
+
+```ts
+export function calculateCauchyRefractiveIndex(input: {
+  refractiveIndexD: number;
+  abbeNumberD: number;
+  wavelengthNm: number;
+}): CalculationResult<{ refractiveIndex: number }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateLongitudinalChromaticFocus
+
+Wavelength-dependent focus for one wavelength: focal length, image distance, signed defocus at
+a sensor focused at the reference wavelength, geometric blur and the defocus wavefront.
+
+```ts
+export function calculateLongitudinalChromaticFocus(
+  input: CalculateLongitudinalChromaticFocusInput
+): CalculationResult<LongitudinalChromaticFocus>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateLongitudinalChromaticFocusInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateLongitudinalChromaticFocusInput {
+  /** Focal length at the reference wavelength, in mm. */
+  focalLengthMm: number;
+  /** Wavelength at which the sensor is focused, in nm. */
+  referenceWavelengthNm: number;
+  /** Wavelength to evaluate, in nm (same wavelength basis as the dispersion data). */
+  wavelengthNm: number;
+  /** Nominal f-number at the reference wavelength (entrance-pupil diameter = f / N). */
+  apertureFNumber: number;
+  /** Focus (object) distance at the reference wavelength, metres from the principal plane. */
+  focusDistanceM: number;
+  /** Subject distance in metres; defaults to focusDistanceM. */
+  subjectDistanceM?: number;
+  dispersion: LongitudinalChromaticDispersion;
+}
+```
+
+## FRAUNHOFER_C_LINE_NM
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+FRAUNHOFER_C_LINE_NM = 656.2725
+```
+
+## FRAUNHOFER_D_LINE_NM
+
+Fraunhofer spectral-line wavelengths in nm (SCHOTT TIE-29 table; also ISO 7944 reference wavelengths).
+
+```ts
+FRAUNHOFER_D_LINE_NM = 587.5618
+```
+
+## FRAUNHOFER_F_LINE_NM
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+FRAUNHOFER_F_LINE_NM = 486.1327
+```
+
+## LongitudinalChromaticDispersion
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type LongitudinalChromaticDispersion =
+  | {
+      kind: "thin-singlet-abbe";
+      /** Refractive index at the d line. */
+      refractiveIndexD: number;
+      /** Abbe number V_d = (n_d - 1) / (n_F - n_C). */
+      abbeNumberD: number;
+    }
+  | {
+      kind: "declared-focal-shift";
+      /** Strictly increasing wavelengths; shift is f(lambda) - f_nominal in micrometres. */
+      samples: readonly {
+        wavelengthNm: number;
+        focalLengthShiftMicrometers: number;
+      }[];
+    };
+```
+
+## LongitudinalChromaticFocus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LongitudinalChromaticFocus {
+  wavelengthNm: number;
+  referenceWavelengthNm: number;
+  focalLengthAtWavelengthMm: number;
+  /** f(lambda) - f(reference), micrometres. */
+  focalShiftMicrometers: number;
+  /** Sensor plane distance (reference-wavelength image of the focus plane), mm. */
+  sensorImageDistanceMm: number;
+  /** Image distance of the subject at this wavelength, mm. */
+  imageDistanceAtWavelengthMm: number;
+  /** Sensor minus image distance, micrometres. */
+  signedDefocusImagePlaneMicrometers: number;
+  /** Geometric thin-lens blur-circle diameter at the sensor, mm. */
+  geometricBlurDiameterMm: number;
+  /** Image-side working f-number v(lambda) / D. */
+  workingFNumberAtWavelength: number;
+  /** Defocus wave aberration W020 for the complex-pupil PSF, micrometres. */
+  w020Micrometers: number;
+  /** Equivalent Noll Z4 coefficient, micrometres. */
+  zernikeZ4Micrometers: number;
+}
+```

package/docs/api/optics-polygon-diffraction.md

@@ -1,6 +1,6 @@
 # optics/polygon-diffraction.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## CalculateIdealPolygonDiffractionInput
 
@@ -10,9 +10,9 @@ On-axis, in-focus scalar diffraction of one ideal regular polygon pupil.
 export interface CalculateIdealPolygonDiffractionInput extends CalculateIdealApertureInput {
   /** Diameter of a circle with the SAME AREA as the physical polygon opening. */
   equivalentAreaPupilDiameterMm: number;
-  /** Paraxial pupil-to-image propagation scale; not silently inferred from focus. */
+  /** Paraxial propagation distance from pupil to image. Never inferred from focus. */
   pupilToImageDistanceMm: number;
-  /** Wavelength in the declared propagation medium; no air/vacuum conversion. */
+  /** Wavelength in the declared propagation medium. No air/vacuum conversion is applied. */
   wavelengthNm: number;
   wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
   /** Displacements from the on-axis PSF center, +X right / +Y up; at most 4096. */
@@ -22,15 +22,19 @@ export interface CalculateIdealPolygonDiffractionInput extends CalculateIdealApe
 
 ## calculateIdealPolygonDiffractionPsf
 
-Calculates continuous monochromatic Fraunhofer PSF density for a uniformly
-illuminated, zero-phase, on-axis ideal straight-edged regular polygon.
-Physical area is explicit; f/N may supply the equal-area diameter only under
-a declared nominal-area convention. No phase aberration, clipping, field
-dependence, curved blades, defocus or polychromatic behavior is inferred.
+Calculates the continuous, single-wavelength Fraunhofer (far-field) PSF
+density of an ideal regular polygon with straight edges. The pupil is
+uniformly lit, has zero phase and sits on the optical axis.
 
-Density = A |F/A|² / (lambda * propagationDistance)². Parseval normalization
-is over the infinite plane, NOT over the supplied point list. Downstream
-quadrature must preserve density × area and report truncation/convergence.
+The physical area is explicit. f/N may supply the equal-area diameter only
+when the caller declares the nominal-area convention. Nothing else is
+assumed: no phase aberration, clipping, field dependence, curved blades,
+defocus or multi-wavelength behaviour.
+
+Density = A |F/A|² / (lambda * propagationDistance)². It integrates to 1
+over the infinite plane (Parseval), NOT over the supplied points. Code that
+sums the samples must keep density × area and report truncation and
+convergence.
 
 ```ts
 export function calculateIdealPolygonDiffractionPsf(
@@ -40,9 +44,47 @@ export function calculateIdealPolygonDiffractionPsf(
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## calculatePolygonPupilFraunhoferPsf
+
+Continuous, single-wavelength Fraunhofer PSF density for any simple polygon pupil that is uniformly
+lit and has zero phase (for example a cat's-eye pupil from mechanical vignetting).
+
+It uses the same analytic edge integral as the regular-polygon model, so there is no aliasing from
+a pupil grid. Moving the pupil off the axis only adds a linear phase; the intensity does not
+change. Density = A |F/A|² / (lambda z)², and it integrates to 1 over the infinite plane.
+
+```ts
+export function calculatePolygonPupilFraunhoferPsf(
+  input: CalculatePolygonPupilFraunhoferPsfInput
+): CalculationResult<PolygonPupilFraunhoferPsf>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculatePolygonPupilFraunhoferPsfInput
+
+On-axis scalar Fraunhofer diffraction of one arbitrary simple polygon pupil.
+
+```ts
+export interface CalculatePolygonPupilFraunhoferPsfInput {
+  /**
+   * Simple (non-self-intersecting) pupil polygon in pupil-plane millimetres, +X right / +Y up,
+   * with 3 to 4096 vertices. For example, the cat's-eye pupil from calculateMechanicalVignetting().
+   */
+  pupilVerticesMm: readonly { x: number; y: number }[];
+  /** Paraxial propagation distance from pupil to image. Never inferred from focus. */
+  pupilToImageDistanceMm: number;
+  /** Wavelength in the declared propagation medium. No air/vacuum conversion is applied. */
+  wavelengthNm: number;
+  wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
+  /** Displacements from the PSF centre (the geometric image point), +X right / +Y up; at most 4096. */
+  imagePointsMicrometers: readonly { x: number; y: number }[];
+}
+```
+
 ## IdealPolygonDiffraction
 
-Continuous unit-energy PSF samples, not a normalized finite convolution kernel.
+Samples of a continuous unit-energy PSF. This is not a normalized finite convolution kernel.
 
 ```ts
 export interface IdealPolygonDiffraction {
@@ -59,7 +101,30 @@ export interface IdealPolygonDiffraction {
   throughputApplied: false;
   samples: readonly {
     imagePointMicrometers: { x: number; y: number };
-    /** |F/A|²; unity at the origin. Not an energy/probability weight. */
+    /** |F/A|². Equal to 1 at the origin. Not an energy or probability weight. */
+    peakNormalizedIntensity: number;
+    /** Density integrating to unity over the full image plane, in 1/µm². */
+    intensityDensityPerSquareMicrometer: number;
+  }[];
+}
+```
+
+## PolygonPupilFraunhoferPsf
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PolygonPupilFraunhoferPsf {
+  pupilAreaSquareMm: number;
+  pupilToImageDistanceMm: number;
+  wavelengthNm: number;
+  wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
+  fieldAxes: "+X right, +Y up";
+  energyNormalization: "unit-integral-over-infinite-image-plane";
+  throughputApplied: false;
+  samples: readonly {
+    imagePointMicrometers: { x: number; y: number };
+    /** |F/A|²; unity at the origin. */
     peakNormalizedIntensity: number;
     /** Density integrating to unity over the full image plane, in 1/µm². */
     intensityDensityPerSquareMicrometer: number;

package/docs/api/optics-profile-contract.md

@@ -1,10 +1,10 @@
 # optics/profile-contract.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## GenericOpticalEvidence
 
-Generic approximation evidence; never implies measured calibration.
+Evidence for a generic approximation. It never implies a measured calibration.
 
 ```ts
 export interface GenericOpticalEvidence {
@@ -17,7 +17,7 @@ export interface GenericOpticalEvidence {
 
 ## OpticalProfileState
 
-Exact, generic camera/lens and acquisition state; no implicit interpolation.
+Exact, generic camera, lens and acquisition state. Nothing is interpolated implicitly.
 
 ```ts
 export interface OpticalProfileState {
@@ -38,7 +38,7 @@ export interface OpticalProfileState {
 
 ## parseOpticalProfileState
 
-Parses a complete exact-state binding, including still/video/output settings.
+Parses a complete exact-state binding, including still, video and output settings.
 
 ```ts
 export function parseOpticalProfileState(value: unknown): OpticalProfileState;

package/docs/api/optics-psf-foundation.md

@@ -1,17 +1,16 @@
 # optics/psf-foundation.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## calculatePsfFoundationComponents
 
-Evaluates the currently implemented PSF-related diagnostics in one explicit
-field/depth/spectral/pupil context without combining them into a synthetic
-PSF or blur radius.
+Evaluates today's PSF-related diagnostics in one explicit context (field
+position, depth, wavelength and pupil). It does not combine them into a
+synthetic PSF or blur radius.
 
-Field position is recorded even though the current defocus-circle and
-circular-Airy diagnostics are not field dependent. Future field-dependent
-contributions can consume the same context without changing these existing
-primitives.
+The field position is recorded even though the current defocus-circle and
+circular-Airy diagnostics do not depend on it. Future field-dependent
+contributions can use the same context without changing these primitives.
 
 ```ts
 export function calculatePsfFoundationComponents(
@@ -37,8 +36,9 @@ export interface CalculatePsfFoundationComponentsInput {
    */
   fieldPointMm: LensFieldPointMm;
   /**
-   * Physical image-plane radius used only to normalize field position for
-   * cross-case diagnostics. It is not a lens calibration or validity bound.
+   * Physical image-plane radius. It is used only to normalize the field
+   * position so diagnostics can be compared across cases. It is not a lens
+   * calibration or a validity limit.
    */
   fieldNormalizationRadiusMm: number;
   spectralBasis: {
@@ -52,8 +52,8 @@ export interface CalculatePsfFoundationComponentsInput {
 
 Returns the public PSF/pupil foundation contract.
 
-The contract describes current diagnostics plus reserved future contribution
-ownership. It does not imply that reserved contributions are implemented.
+The contract lists today's diagnostics and reserves names for future
+contributions. A reserved contribution is not implemented.
 
 ```ts
 export function getPsfFoundationContract(): PsfFoundationContract;

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

@@ -0,0 +1,132 @@
+# optics/pupil-vignetting.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.
+
+## calculateMechanicalVignetting
+
+Mechanical vignetting at one field angle: the open (cat's-eye) pupil from intersecting the
+entrance pupil with displaced clipping apertures, its area ratio, and cos^4 x area ratio.
+
+```ts
+export function calculateMechanicalVignetting(
+  input: CalculateMechanicalVignettingInput
+): CalculationResult<MechanicalVignetting>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateMechanicalVignettingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateMechanicalVignettingInput {
+  /** Unclipped entrance-pupil diameter, mm. */
+  entrancePupilDiameterMm: number;
+  /** Object-space field angle from the optical axis, degrees, in [0, 90). */
+  fieldAngleDegrees: number;
+  /** Image-plane direction of the field point, degrees counter-clockwise from +X. */
+  fieldAzimuthDegrees: number;
+  /** One through eight clipping apertures. */
+  apertures: readonly MechanicalVignettingAperture[];
+  /** Boundary samples per circle for the polygon, from 16 to 4096 (default 256). */
+  boundarySamplesPerCircle?: number;
+}
+```
+
+## calculateNaturalVignetting
+
+Natural (cos^4 or finite Lambertian pupil) relative illumination at one image point.
+
+```ts
+export function calculateNaturalVignetting(
+  input: CalculateNaturalVignettingInput
+): CalculationResult<NaturalVignetting>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateNaturalVignettingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateNaturalVignettingInput {
+  model: NaturalVignettingModel;
+  /** Image-plane point relative to the optical axis, mm. */
+  imagePointMm: { x: number; y: number };
+  /** Axial distance from the exit pupil to the image plane, mm. */
+  exitPupilDistanceMm: number;
+  /** Exit-pupil diameter, mm; required for finite-lambertian-pupil. */
+  exitPupilDiameterMm?: number;
+}
+```
+
+## MechanicalVignetting
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface MechanicalVignetting {
+  fieldAngleDegrees: number;
+  fieldAzimuthDegrees: number;
+  entrancePupilAreaSquareMm: number;
+  /** Open area in mm^2. Exact for a single aperture; the polygon area otherwise. */
+  openAreaSquareMm: number;
+  areaMethod: "exact-circle-circle-intersection" | "boundary-polygon";
+  /** Open area / unclipped pupil area, in [0, 1]. */
+  openAreaRatio: number;
+  /** cos^4(field angle). */
+  cosineFourthFactor: number;
+  /** cos^4(theta) x openAreaRatio. */
+  combinedRelativeIllumination: number;
+  /** Counter-clockwise convex boundary of the open pupil (empty when fully vignetted), mm. */
+  openPupilPolygonMm: readonly { x: number; y: number }[];
+  /** Area centroid of the boundary polygon, mm (null when fully vignetted). */
+  openPupilCentroidMm: { x: number; y: number } | null;
+}
+```
+
+## MechanicalVignettingAperture
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface MechanicalVignettingAperture {
+  /** Aperture radius referred to the entrance-pupil plane, mm. */
+  radiusMm: number;
+  /**
+   * Signed shift of the aperture's projected centre per unit tan(field angle), in mm, along the
+   * field azimuth. Positive means toward the field point.
+   */
+  shiftPerTanFieldMm: number;
+}
+```
+
+## NaturalVignetting
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NaturalVignetting {
+  model: NaturalVignettingModel;
+  /** Image-space chief-ray angle, radians. */
+  chiefRayAngleRadians: number;
+  /** Relative illumination E / E(axis), in (0, 1]. */
+  relativeIllumination: number;
+  /** Positive exposure loss, stops. */
+  attenuationStops: number;
+  /** cos^4 of the chief-ray angle, reported for comparison. */
+  cosineFourthFactor: number;
+}
+```
+
+## NaturalVignettingModel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type NaturalVignettingModel =
+  | "cosine-fourth"
+  | "finite-lambertian-pupil";
+```

package/docs/api/optics-radial-distortion.md

@@ -1,11 +1,11 @@
 # optics/radial-distortion.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## calculateInverseRadialDistortionMapping
 
-Invert the declared monotonic radial field map within its supported envelope using the existing
-bounded root solve and preserve explicit optical coordinates.
+Inverts the declared monotonic radial field mapping inside its supported range, using the existing
+bounded root solver. Optical coordinates are kept explicit.
 
 ```ts
 export function calculateInverseRadialDistortionMapping(
@@ -29,11 +29,11 @@ export interface CalculateInverseRadialDistortionMappingInput {
 
 ## calculateInverseRadialDistortionMappings
 
-Inverse-maps multiple distorted image-plane destinations while validating
-and resolving the radial profile only once for the complete batch.
+Inverse-maps many distorted image-plane points at once. The radial profile
+is validated and resolved only once for the whole batch.
 
-The returned per-point mappings are numerically identical to the scalar API;
-provenance and profile validation are shared once at the batch boundary.
+Each returned mapping is numerically identical to the single-point API.
+Provenance and profile validation are reported once for the batch.
 
 ```ts
 export function calculateInverseRadialDistortionMappings(
@@ -66,9 +66,9 @@ The mapping is rotationally symmetric about the optical axis:
 
 where r is normalized by the caller-declared physical reference radius.
 
-The profile is accepted only when the radial mapping is strictly monotonic
-over its declared operating radius, which makes inverse destination-to-source
-sampling well-defined.
+A profile is accepted only if the radial mapping is strictly monotonic over
+its declared operating radius. That makes the inverse mapping
+(destination-to-source sampling) well defined.
 
 ```ts
 export function calculateRadialDistortionMapping(
@@ -185,8 +185,8 @@ export interface RadialDistortionProfile {
    */
   normalizationRadiusMm: number;
   /**
-   * Maximum undistorted normalized radius over which this profile is declared
-   * valid and must remain one-to-one/invertible.
+   * Largest undistorted normalized radius for which this profile is declared
+   * valid. Within it the mapping must stay one-to-one and invertible.
    */
   maximumNormalizedRadius: number;
   coefficients: RadialDistortionCoefficients;

package/docs/api/optics-scene-to-sensor-irradiance.md

@@ -1,16 +1,20 @@
 # optics/scene-to-sensor-irradiance.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## calculateSceneRadianceToSensorIrradiance
 
-Apply declared pupil acceptance and exactly one transmission/field-throughput path to spectral scene
-radiance, returning pre-stack irradiance with conservative evidence.
+Applies the declared pupil acceptance and exactly one transmission or field-throughput path to
+spectral scene radiance. Returns the irradiance before the sensor stack, with conservative
+evidence.
 
-The optical bridge maps outgoing W/m²/sr/nm radiance to pre-sensor-stack W/m²/nm irradiance.
-Circular paraxial acceptance is pi/(4*Nworking²); finite-focus unity-pupil geometry uses N*(1+m).
-Spectral transmission and effective working T-stop are alternative paths, and field throughput is
-applied exactly once. Sensor response and PSF redistribution are downstream.
+The optical bridge turns outgoing scene radiance (W/m²/sr/nm) into irradiance (W/m²/nm) arriving
+at the front of the sensor stack.
+- Circular paraxial acceptance is pi/(4*Nworking²). At finite focus with unit pupil magnification,
+  the working f-number is N*(1+m).
+- Spectral transmission and an effective working T-stop are alternative paths; use one.
+- Field throughput is applied exactly once.
+- Sensor response and PSF (point-spread function) blur happen later in the pipeline.
 
 ```ts
 export function calculateSceneRadianceToSensorIrradiance(
@@ -196,13 +200,16 @@ export type OpticalTransmissionModel =
 
 ## parseSceneToSensorIrradianceProfile
 
-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 scene-to-sensor profile and returns the normalized typed contract. Unknown
+enum values, missing required fields and incompatible scientific data are rejected here.
 
-The optical bridge maps outgoing W/m²/sr/nm radiance to pre-sensor-stack W/m²/nm irradiance.
-Circular paraxial acceptance is pi/(4*Nworking²); finite-focus unity-pupil geometry uses N*(1+m).
-Spectral transmission and effective working T-stop are alternative paths, and field throughput is
-applied exactly once. Sensor response and PSF redistribution are downstream.
+The optical bridge turns outgoing scene radiance (W/m²/sr/nm) into irradiance (W/m²/nm) arriving
+at the front of the sensor stack.
+- Circular paraxial acceptance is pi/(4*Nworking²). At finite focus with unit pupil magnification,
+  the working f-number is N*(1+m).
+- Spectral transmission and an effective working T-stop are alternative paths; use one.
+- Field throughput is applied exactly once.
+- Sensor response and PSF (point-spread function) blur happen later in the pipeline.
 
 ```ts
 export function parseSceneToSensorIrradianceProfile(
@@ -309,8 +316,12 @@ export interface SceneToSensorIrradianceResult {
     number;
   frontOfLensFilterTransmissionAppliedExactlyOnce:
     true;
+  /**
+   * True when a front-of-lens linear polarizer was applied. Scene radiance is unpolarized in this
+   * bridge, so a polarizer transmits (k1 + k2) / 2.
+   */
   frontOfLensFilterPolarizationModeled:
-    false;
+    boolean;
   fieldThroughputFactor: number;
   effectiveAcceptanceAfterTransmissionAndFieldSteradians:
     number;

package/docs/api/optics-scene-to-sensor-quadrature.md

@@ -1,13 +1,15 @@
 # optics/scene-to-sensor-quadrature.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## calculateSceneToSensorIrradianceQuadrature
 
-Calculate the existing paraxial optical bridge at every requested node.
-Exact identity/coverage and provider bindings are checked before returning
-physical W/m²/nm samples. Image coordinates belong to the spatial plan, so
-callers cannot attach a field-throughput result from a different point.
+Runs the existing paraxial optical bridge at every requested node.
+
+Before it returns physical W/m²/nm samples, it checks that node identities,
+grid coverage and provider bindings match exactly. Image coordinates come
+from the spatial plan, so a caller cannot attach a field-throughput result
+computed at a different point.
 
 ```ts
 export function calculateSceneToSensorIrradianceQuadrature(
@@ -19,27 +21,28 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## CalculateSceneToSensorIrradianceQuadratureInput
 
-Static point-sample bridge; PSF and temporal transport remain separate responsibilities.
+Static point-sample bridge. PSF blur and motion over time are handled elsewhere.
 
 ```ts
 export interface CalculateSceneToSensorIrradianceQuadratureInput {
   spatialQuadrature: ReduceSensorSpatioSpectralIrradianceInput["spatialQuadrature"];
   spectralQuadrature: ReduceSensorSpatioSpectralIrradianceInput["spectralQuadrature"];
-  /** Evidence-backed provider/illumination/material identities, parsed before use. */
+  /** Provider, illumination and material identities with their evidence. Parsed before use. */
   sceneBindings: Omit<ValidateSceneRadianceEvaluationBindingsInput, "request" | "result">;
   /** One declared lens/focus/filter state shared by every node. */
   optics: Omit<CalculateSceneRadianceToSensorIrradianceInput,
     "sceneRadianceRequest" | "sceneRadianceResult" | "imagePointMm" | "fieldThroughput">;
-  /** Explicit nonnegative instant shared by all queries; not an exposure integration. */
+  /** One non-negative instant shared by all queries. This is not an integral over the exposure. */
   timeSecondsFromExposureStart: number;
-  /** Complete Cartesian coverage with a unique scene sampleId per node. */
+  /** Every combination of the grid axes, with a unique scene sampleId per node. */
   samples: readonly SceneSensorQuadratureSample[];
 }
 ```
 
 ## SceneSensorQuadratureSample
 
-One declared scene query/result for an exact pre-AA spatial/wavelength node.
+One declared scene query and its result, for one exact spatial and wavelength node before the
+anti-aliasing (AA) filter.
 
 ```ts
 export interface SceneSensorQuadratureSample {
@@ -66,9 +69,9 @@ export interface SceneToSensorIrradianceQuadrature {
   reduction: ReturnType<typeof reduceSensorSpatioSpectralIrradiance>;
   samples: readonly {
     node: SensorSpatioSpectralNodeIdentity;
-    /** Physical source coordinate before AA redistribution, in mm. */
+    /** Physical source coordinate, in mm, before the anti-aliasing filter spreads it. */
     preAntiAliasingSourcePointMm: { x: number; y: number };
-    /** Owned provider target/time declaration; not a verified ray intersection. */
+    /** The provider's declared target and time. This is not a verified ray intersection. */
     request: SceneSensorQuadratureSample["sceneRadianceRequest"];
     result: SceneSensorQuadratureSample["sceneRadianceResult"];
     bindings: ReturnType<typeof validateSceneRadianceEvaluationBindings>;