@photivra/engine 0.6.0 → 1.0.1

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

@@ -0,0 +1,371 @@
+# optics/scene-to-sensor-irradiance.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## calculateSceneRadianceToSensorIrradiance
+
+Apply declared pupil acceptance and exactly one transmission/field-throughput path to spectral scene
+radiance, returning pre-stack irradiance 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.
+
+```ts
+export function calculateSceneRadianceToSensorIrradiance(
+  input:
+    CalculateSceneRadianceToSensorIrradianceInput
+): CalculationResult<
+  SceneToSensorIrradianceResult
+>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSceneRadianceToSensorIrradianceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSceneRadianceToSensorIrradianceInput {
+  sceneRadianceRequest:
+    SceneRadianceEvaluationRequest;
+  sceneRadianceResult:
+    SceneRadianceEvaluationResult;
+  profile:
+    SceneToSensorIrradianceProfile;
+  focalLengthMm: number;
+  nominalFNumber: number;
+  focus:
+    OpticalBridgeFocusContext;
+  imagePointMm: {
+    x: number;
+    y: number;
+  };
+  fieldThroughput:
+    OpticalBridgeFieldThroughput;
+  frontOfLensFilters?:
+    readonly FrontOfLensFilterProfile[];
+}
+```
+
+## NumericRange
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NumericRange {
+  minimum: number;
+  maximum: number;
+}
+```
+
+## OpticalBridgeFieldThroughput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type OpticalBridgeFieldThroughput =
+  | {
+      kind: "unity";
+    }
+  | {
+      kind:
+        "illumination-vignetting-result";
+      result:
+        IlluminationVignetting;
+    };
+```
+
+## OpticalBridgeFocusApplicability
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type OpticalBridgeFocusApplicability =
+  | {
+      kind: "any";
+    }
+  | {
+      kind: "finite-distance-range";
+      objectDistanceM: NumericRange;
+    };
+```
+
+## OpticalBridgeFocusContext
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type OpticalBridgeFocusContext =
+  | {
+      kind: "infinity-focus";
+    }
+  | {
+      kind:
+        "ideal-symmetric-thin-lens";
+      objectDistanceM: number;
+      pupilMagnificationAssumption:
+        "unity";
+    }
+  | {
+      kind:
+        "supplied-working-f-number";
+      focus:
+        | {
+            kind: "infinity";
+          }
+        | {
+            kind: "finite";
+            objectDistanceM: number;
+          };
+      workingFNumber:
+        EvidenceBackedFact<number>;
+      basis: string;
+    };
+```
+
+## OpticalBridgeScientificStatus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type OpticalBridgeScientificStatus =
+  | "calibrated"
+  | "approximation";
+```
+
+## OpticalBridgeUncertainty
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type OpticalBridgeUncertainty =
+  | {
+      kind: "relative";
+      fraction: number;
+      basis: string;
+    }
+  | {
+      kind: "not-quantified";
+      limitation: string;
+    };
+```
+
+## OpticalTransmissionModel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type OpticalTransmissionModel =
+  | {
+      kind: "spectral-transmission";
+      scientificStatus:
+        OpticalBridgeScientificStatus;
+      wavelengthBasis:
+        Exclude<
+          SpectralWavelengthBasis,
+          "unspecified"
+        >;
+      samples:
+        EvidenceBackedFact<
+          readonly SpectralTransmissionSample[]
+        >;
+      uncertainty:
+        OpticalBridgeUncertainty;
+    }
+  | {
+      kind:
+        "effective-working-t-stop-approximation";
+      scientificStatus: "approximation";
+      workingTStop:
+        EvidenceBackedFact<number>;
+      wavelengthBasis:
+        Exclude<
+          SpectralWavelengthBasis,
+          "unspecified"
+        >;
+      wavelengthRangeNanometers:
+        NumericRange;
+      uncertainty:
+        OpticalBridgeUncertainty;
+      limitation: string;
+    };
+```
+
+## 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.
+
+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.
+
+```ts
+export function parseSceneToSensorIrradianceProfile(
+  value: unknown
+): SceneToSensorIrradianceProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SCENE_TO_SENSOR_IRRADIANCE_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SCENE_TO_SENSOR_IRRADIANCE_PROFILE_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## SceneToSensorIrradianceProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneToSensorIrradianceProfile {
+  schemaVersion:
+    typeof SCENE_TO_SENSOR_IRRADIANCE_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  lensProfileId: string;
+  scientificStatus:
+    OpticalBridgeScientificStatus;
+  applicability: {
+    focalLengthMm: NumericRange;
+    nominalFNumber: NumericRange;
+    focus:
+      OpticalBridgeFocusApplicability;
+  };
+  transmission:
+    OpticalTransmissionModel;
+  distortionAreaMappingOwnership:
+    "not-applied-by-bridge";
+  psfRedistributionOwnership:
+    "downstream-normalized-energy-redistribution";
+  sensorOpticalStackIncluded: false;
+  strayLightIncluded: false;
+  polarizationModeled: false;
+  wavelengthChangingBehaviorModeled: false;
+  volumetricScatteringModeled: false;
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## SceneToSensorIrradianceResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneToSensorIrradianceResult {
+  schemaVersion:
+    typeof SCENE_TO_SENSOR_IRRADIANCE_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  lensProfileId: string;
+  sampleId: string;
+  providerProfileId: string;
+  sceneId: string;
+  timeSecondsFromExposureStart: number;
+  wavelengthNanometers: number;
+  wavelengthBasis:
+    Exclude<
+      SpectralWavelengthBasis,
+      "unspecified"
+    >;
+  inputQuantity:
+    "outgoing-spectral-radiance";
+  inputUnit:
+    "W/m^2/sr/nm";
+  outputQuantity:
+    "sensor-plane-spectral-irradiance";
+  outputUnit:
+    "W/m^2/nm";
+  sceneSpectralRadianceWattsPerSquareMeterSteradianNanometer:
+    number;
+  focalLengthMm: number;
+  nominalFNumber: number;
+  workingFNumber: number;
+  focusModel:
+    OpticalBridgeFocusContext["kind"];
+  paraxialGeometricAcceptanceSolidAngleSteradians:
+    number;
+  transmissionPath:
+    OpticalTransmissionModel["kind"];
+  spectralTransmissionFactor:
+    number | null;
+  effectiveWorkingTStop:
+    number | null;
+  tStopEquivalentTransmissionFactor:
+    number | null;
+  frontOfLensFilterCount: number;
+  frontOfLensFilterTransmissionFactor:
+    number;
+  frontOfLensFilterAttenuationStops:
+    number;
+  frontOfLensFilterTransmissionAppliedExactlyOnce:
+    true;
+  frontOfLensFilterPolarizationModeled:
+    false;
+  fieldThroughputFactor: number;
+  effectiveAcceptanceAfterTransmissionAndFieldSteradians:
+    number;
+  sensorPlaneSpectralIrradianceWattsPerSquareMeterNanometer:
+    number;
+  scientificStatus: "approximation";
+  sceneRadianceScientificStatus:
+    SceneRadianceEvaluationResult["scientificStatus"];
+  opticalProfileScientificStatus:
+    OpticalBridgeScientificStatus;
+  sceneRadianceUncertainty:
+    SceneRadianceEvaluationResult["uncertainty"];
+  opticalUncertainty:
+    OpticalBridgeUncertainty;
+  radianceAmplificationApplied: false;
+  fieldThroughputAppliedExactlyOnce:
+    true;
+  universalCos4FalloffApplied: false;
+  distortionAreaCorrectionApplied: false;
+  psfRedistributionApplied: false;
+  sensorOpticalStackApplied: false;
+  cfaApplied: false;
+  quantumEfficiencyApplied: false;
+  spectralResponsivityApplied: false;
+  strayLightApplied: false;
+  polarizationModeled: false;
+  wavelengthChangingBehaviorModeled:
+    false;
+  volumetricScatteringModeled: false;
+  calibratedSensorPlaneIrradianceClaimAuthorized:
+    false;
+  componentEvidence: {
+    sceneRadiance:
+      readonly EvidenceProvenance[];
+    opticalProfile:
+      readonly EvidenceProvenance[];
+    transmission:
+      readonly EvidenceProvenance[];
+    workingFNumber:
+      readonly EvidenceProvenance[];
+    frontOfLensFilters:
+      readonly EvidenceProvenance[];
+  };
+  limitations:
+    readonly string[];
+}
+```
+
+## SpectralTransmissionSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SpectralTransmissionSample {
+  wavelengthNanometers: number;
+  linearTransmissionFactor: number;
+}
+```

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

@@ -0,0 +1,78 @@
+# optics/scene-to-sensor-quadrature.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## 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.
+
+```ts
+export function calculateSceneToSensorIrradianceQuadrature(
+  input: CalculateSceneToSensorIrradianceQuadratureInput
+): CalculationResult<SceneToSensorIrradianceQuadrature>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSceneToSensorIrradianceQuadratureInput
+
+Static point-sample bridge; PSF and temporal transport remain separate responsibilities.
+
+```ts
+export interface CalculateSceneToSensorIrradianceQuadratureInput {
+  spatialQuadrature: ReduceSensorSpatioSpectralIrradianceInput["spatialQuadrature"];
+  spectralQuadrature: ReduceSensorSpatioSpectralIrradianceInput["spectralQuadrature"];
+  /** Evidence-backed provider/illumination/material identities, 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. */
+  timeSecondsFromExposureStart: number;
+  /** Complete Cartesian coverage with a unique scene sampleId per node. */
+  samples: readonly SceneSensorQuadratureSample[];
+}
+```
+
+## SceneSensorQuadratureSample
+
+One declared scene query/result for an exact pre-AA spatial/wavelength node.
+
+```ts
+export interface SceneSensorQuadratureSample {
+  node: SensorSpatioSpectralNodeIdentity;
+  sceneRadianceRequest: CalculateSceneRadianceToSensorIrradianceInput["sceneRadianceRequest"];
+  sceneRadianceResult: CalculateSceneRadianceToSensorIrradianceInput["sceneRadianceResult"];
+  fieldThroughput: CalculateSceneRadianceToSensorIrradianceInput["fieldThroughput"];
+}
+```
+
+## SceneToSensorIrradianceQuadrature
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneToSensorIrradianceQuadrature {
+  sourcePlane: "sensor-package-incident";
+  outputMeaning: "pre-sensor-stack-pre-aa-irradiance-quadrature";
+  sourceTargetProjectionVerified: false;
+  sceneProviderExecutionVerified: false;
+  psfRedistributionApplied: false;
+  temporalIntegrationApplied: false;
+  irradianceSamples: ReduceSensorSpatioSpectralIrradianceInput["sampleValues"];
+  reduction: ReturnType<typeof reduceSensorSpatioSpectralIrradiance>;
+  samples: readonly {
+    node: SensorSpatioSpectralNodeIdentity;
+    /** Physical source coordinate before AA redistribution, in mm. */
+    preAntiAliasingSourcePointMm: { x: number; y: number };
+    /** Owned provider target/time declaration; not a verified ray intersection. */
+    request: SceneSensorQuadratureSample["sceneRadianceRequest"];
+    result: SceneSensorQuadratureSample["sceneRadianceResult"];
+    bindings: ReturnType<typeof validateSceneRadianceEvaluationBindings>;
+    optics: ReturnType<typeof calculateSceneRadianceToSensorIrradiance>;
+  }[];
+}
+```

package/docs/api/optics-sensor-environment-query.md

@@ -0,0 +1,58 @@
+# optics/sensor-environment-query.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## calculateSensorEnvironmentRadianceQuery
+
+Generate an environment radiance request from physical sensor support using
+the existing focus-aware ideal projection and analytic inverse camera rotation.
+Native Y is explicitly inverted; the provider direction is opposite the
+exposure-start look ray. No scene intersection, radiance or renderer executes.
+
+```ts
+export function calculateSensorEnvironmentRadianceQuery(
+  input: CalculateSensorEnvironmentRadianceQueryInput
+): CalculationResult<SensorEnvironmentRadianceQuery>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorEnvironmentRadianceQueryInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSensorEnvironmentRadianceQueryInput {
+  /** Pre-AA or pre-PSF optical support, native +X right/+Y down, mm about optical axis. */
+  sourcePointNativeSensorMm: { x: number; y: number };
+  focalLengthMm: number;
+  focus: FocusPlane;
+  angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
+  /** Explicitly maps the shutter opening boundary to the rotation model's t=0. */
+  timeReference: "first-opening-boundary-phase";
+  timeSecondsFromOpeningReference: number;
+  /** Environment request uses radiance propagation toward the camera, opposite the look ray. */
+  environmentDirectionConvention: "outgoing-radiance-toward-camera";
+  request: Omit<SceneRadianceEvaluationRequest, "target" | "timeSecondsFromExposureStart">;
+}
+```
+
+## SensorEnvironmentRadianceQuery
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorEnvironmentRadianceQuery {
+  request: SceneRadianceEvaluationRequest;
+  sourcePointNativeSensorMm: { x: number; y: number };
+  sourcePointImagePlaneMm: { x: number; y: number };
+  referenceLookDirectionUnitVector: { x: number; y: number; z: number };
+  projection: ReturnType<typeof calculateInverseCameraRotationImageMapping>;
+  targetMeaning: "environment-direction-in-exposure-start-camera-axes";
+  directionConvention: "outgoing-radiance-toward-camera";
+  geometricRayProjectionCalculated: true;
+  sceneIntersectionCalculated: false;
+  visibilityCalculated: false;
+  providerExecuted: false;
+}
+```

package/docs/api/optics-sensor-psf-quadrature.md

@@ -0,0 +1,81 @@
+# optics/sensor-psf-quadrature.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## calculateSensorPsfIrradianceQuadrature
+
+Apply each resolved unit-energy PSF as a destination-local inverse sample sum.
+Native +Y-down support converts explicitly to optical +Y-up kernel orientation.
+No boundary extension, missing-support renormalization or extra throughput is
+applied. This approximation is not a field-dependent forward energy transport.
+
+```ts
+export function calculateSensorPsfIrradianceQuadrature(
+  input: CalculateSensorPsfIrradianceQuadratureInput
+): CalculationResult<SensorPsfIrradianceQuadrature>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorPsfIrradianceQuadratureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSensorPsfIrradianceQuadratureInput {
+  /** One instant on the explicitly declared shutter opening reference. */
+  timeSecondsFromOpeningReference: number;
+  spatialQuadrature: ReduceSensorSpatioSpectralIrradianceInput["spatialQuadrature"];
+  spectralQuadrature: ReduceSensorSpatioSpectralIrradianceInput["spectralQuadrature"];
+  /** The adapter owns wavelength and image-plane field position for each node. */
+  psf: Omit<ResolveLensSampledPsfInput, "fieldPointMm" | "wavelengthNm">;
+  /** Schema 0.1.0 PSF profiles lack a basis field; bind that source meaning explicitly. */
+  psfWavelengthBasis: { value: "air" | "vacuum"; evidence: readonly EvidenceProvenance[] };
+  /** Explicit local approximation; a varying PSF grid is not a global convolution. */
+  spatialModel: { kind: "destination-local-shift-invariant-approximation";
+    evidence: readonly EvidenceProvenance[]; limitation: string };
+  inputMeaning: "pre-psf-pre-sensor-stack-pre-aa-spectral-irradiance";
+  /** All nodes and all kernel taps, including zero weights, must be supplied. */
+  samples: readonly { node: SensorSpatioSpectralNodeIdentity; sourceSamples: readonly SensorPsfSourceSample[] }[];
+}
+```
+
+## SensorPsfIrradianceQuadrature
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorPsfIrradianceQuadrature {
+  timeSecondsFromOpeningReference: number;
+  wavelengthBasis: "air" | "vacuum";
+  sourcePlane: "sensor-package-incident";
+  outputMeaning: "post-psf-pre-sensor-stack-pre-aa-irradiance-quadrature";
+  psfRedistributionApplied: true;
+  localShiftInvarianceEstablished: false;
+  globalFieldEnergyConservationEstablished: false;
+  pupilThroughputApplied: false;
+  sceneProviderExecutionVerified: false;
+  spatialModelEvidence: readonly EvidenceProvenance[];
+  wavelengthBasisEvidence: readonly EvidenceProvenance[];
+  spatialModelLimitation: string;
+  irradianceSamples: ReduceSensorSpatioSpectralIrradianceInput["sampleValues"];
+  reduction: ReturnType<typeof reduceSensorSpatioSpectralIrradiance>;
+  samples: readonly { node: SensorSpatioSpectralNodeIdentity;
+    psf: ReturnType<typeof resolveLensSampledPsf>; sourceSamples: readonly SensorPsfSourceSample[] }[];
+}
+```
+
+## SensorPsfSourceSample
+
+One pre-PSF incident irradiance value per explicitly identified kernel tap.
+
+```ts
+export interface SensorPsfSourceSample {
+  timeSecondsFromOpeningReference: number;
+  kernelSampleX: number;
+  kernelSampleY: number;
+  /** Optical-axis origin, +X right/+Y down, millimetres; no native crop clipping. */
+  sourcePointNativeSensorMm: { x: number; y: number };
+  spectralIrradianceWattsPerSquareMeterPerNanometer: number;
+}
+```

package/docs/api/optics-stray-light.md

@@ -0,0 +1,109 @@
+# optics/stray-light.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## calculateLensStrayLightIrradiance
+
+Adds off-path spectral irradiance before sensor/exposure integration, never after tone mapping.
+Source powers are integrated over profile.referenceEntranceAreaMm2 at this instant/wavelength.
+Gaussian templates are independently parameterized approximations, not lens prescription ray tracing.
+
+```ts
+export function calculateLensStrayLightIrradiance(input: {
+  profile: LensStrayLightProfile; state: OpticalProfileState; enabled: boolean;
+  imagePointMm: LensFieldPointMm; wavelengthNm: number; wavelengthBasis: "air" | "vacuum";
+  timeSeconds: number; primarySpectralIrradianceWPerM2PerNm: number;
+  sources: readonly StrayLightSource[]; meterDomain: "primary-only" | "primary-plus-stray";
+}): CalculationResult<StrayLightIrradiance>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## LensStrayLightProfile
+
+Single explicit wavelength and exact generic camera state; clean optics only.
+
+```ts
+export interface LensStrayLightProfile {
+  schemaVersion: "0.1.0";
+  id: string;
+  version: string;
+  state: OpticalProfileState;
+  evidence: GenericOpticalEvidence;
+  interaction: "lens-reflections" | "sensor-lens-reflections";
+  wavelengthNm: number;
+  wavelengthBasis: "air" | "vacuum";
+  maximumSourceAngleDegrees: number;
+  /** Area over which the caller's incident source power was integrated. */
+  referenceEntranceAreaMm2: number;
+  responses: readonly ParametricStrayLightResponse[];
+}
+```
+
+## ParametricStrayLightResponse
+
+One reflected-path or broad scatter response, normalized over the infinite image plane.
+
+```ts
+export interface ParametricStrayLightResponse {
+  id: string;
+  kind: "ghost" | "veil";
+  /** Centroid response in mm per degree of the two declared source field angles. */
+  centroidMmPerDegree: readonly [number, number, number, number];
+  offsetMm: LensFieldPointMm;
+  sigmaMm: number;
+  /** Fraction of source power entering this response at the axis. */
+  axisPowerFraction: number;
+  /** F(rho)=F(0)*(1+slope*rho²), rho=source angle/max angle. */
+  angularSlope: number;
+}
+```
+
+## parseLensStrayLightProfile
+
+Strict generic profile parser; bounds passivity across the whole angular envelope.
+
+```ts
+export function parseLensStrayLightProfile(value: unknown): LensStrayLightProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## StrayLightIrradiance
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface StrayLightIrradiance {
+  profileId: string;
+  profileVersion: string;
+  interaction: LensStrayLightProfile["interaction"];
+  imagePointMm: LensFieldPointMm;
+  wavelengthNm: number;
+  wavelengthBasis: "air" | "vacuum";
+  timeSeconds: number;
+  primarySpectralIrradianceWPerM2PerNm: number;
+  ghostSpectralIrradianceWPerM2PerNm: number;
+  veilSpectralIrradianceWPerM2PerNm: number;
+  totalSpectralIrradianceWPerM2PerNm: number;
+  /** If primary-only, the meter excludes these additions; sensor always receives total. */
+  meterDomain: "primary-only" | "primary-plus-stray";
+  meterSpectralIrradianceWPerM2PerNm: number;
+  contributions: readonly { sourceId: string; responseId: string; kind: "ghost" | "veil"; spectralIrradianceWPerM2PerNm: number }[];
+}
+```
+
+## StrayLightSource
+
+Direction remains available beyond the active frame; no crop clipping.
+
+```ts
+export interface StrayLightSource {
+  id: string;
+  fieldAngleXDegrees: number;
+  fieldAngleYDegrees: number;
+  incidentSpectralPowerWPerNm: number;
+  /** Explicit source/path admission, e.g. a flag/hood decision; not a global hood scalar. */
+  admittedFraction: number;
+}
+```