@photivra/engine 1.5.0 → 2.0.0

package/docs/api/motion-capture-rotation-trajectory.md

@@ -1,26 +1,26 @@
 # motion/capture-rotation-trajectory.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.
 
 ## calculateCaptureRotationTrajectories
 
 Evaluates pure-camera-rotation trajectories for stationary reference rays
 over each point's local exposure window.
 
-This is a temporal-geometry bridge, not a finished rolling-shutter image
-mapping. The native sample point defines where a stationary world ray would
-land in the reference global-shutter image at the first opening-boundary
-phase. The existing camera-rotation model is then evaluated at that point's
-local exposure start and end.
+This links timing to geometry. It is not a finished rolling-shutter image
+mapping. The native sample point sets where a still world ray would land in
+the reference global-shutter image at the first opening-boundary phase. The
+existing camera-rotation model is then evaluated at that point's local
+exposure start and end.
 
-Sensor data-readout timing is intentionally absent. A camera/mode-specific
-relationship between sensor readout and exposure boundaries requires a
-separate explicit contract; this function never assumes one.
+Sensor data-readout timing is deliberately not used. How readout relates to
+exposure boundaries depends on the camera and mode, and needs its own
+explicit contract. This function never assumes one.
 
-A later renderer-facing rolling-shutter warp must solve the image mapping
-consistently with capture-location-dependent time and integrate over the
-local exposure interval. The endpoint chord returned here must not be treated
-as a blur kernel or as an inverse destination-to-source sampling map.
+A future rolling-shutter warp for renderers must solve the image mapping
+with time that depends on capture location, and must integrate over the
+local exposure interval. Do not treat the endpoint chord returned here as a
+blur kernel or as an inverse destination-to-source sampling map.
 
 ```ts
 export function calculateCaptureRotationTrajectories(
@@ -51,8 +51,8 @@ export interface CalculateCaptureRotationTrajectoriesInput
    */
   angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
   /**
-   * Native points whose stationary-reference-ray trajectories should be
-   * evaluated. Required and non-empty for this trajectory API.
+   * Native points whose still-ray paths to evaluate. Required, and must not be
+   * empty.
    */
   samplePointsNative: readonly RasterPoint[];
 }

package/docs/api/motion-capture-translation-parallax-temporal-quadrature.md

@@ -1,15 +1,16 @@
 # motion/capture-translation-parallax-temporal-quadrature.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.
 
 ## calculateCaptureTranslationParallaxTemporalQuadrature
 
-Evaluates depth-dependent translational parallax at deterministic midpoint
-nodes over each scene point's authoritative local exposure window.
+Evaluates depth-dependent parallax from camera movement at deterministic
+midpoint time samples across each scene point's local exposure window.
 
-The model is deliberately per point. Camera translation and optional subject
-translation coexist through relative linear motion; neither is redefined as
-the other. Camera rotation and visibility/occlusion remain separate models.
+The model works point by point, on purpose. Camera movement and optional
+subject movement combine as relative linear motion; neither is recast as
+the other. Camera rotation, and visibility or occlusion, are separate
+models.
 
 ```ts
 export function calculateCaptureTranslationParallaxTemporalQuadrature(
@@ -35,8 +36,8 @@ export interface CalculateCaptureTranslationParallaxTemporalQuadratureInput {
   orientation:
     CaptureOrientation;
   /**
-   * Constant physical camera-center translation in camera axes at the capture
-   * reference phase. Rotation is intentionally separate.
+   * Constant movement of the camera centre, in camera axes at the capture
+   * reference phase. Rotation is handled separately, on purpose.
    */
   cameraTranslationVelocityMps:
     Vector3;
@@ -54,19 +55,19 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface CaptureTranslationParallaxSceneSample {
   sampleId: string;
   /**
-   * Native destination point whose authoritative local exposure window applies
-   * to this scene sample.
+   * Native destination point. Its local exposure window applies to this scene
+   * sample.
    */
   destinationPointNative:
     RasterPoint;
   /**
-   * Metric point position in the camera axes at the first-opening-boundary
-   * phase. +X right, +Y up, +Z forward/away from the camera.
+   * Point position in metres, in the camera axes at the first opening-boundary
+   * phase. +X right, +Y up, +Z forward (away from the camera).
    */
   positionCameraM: Vector3;
   /**
-   * Optional constant subject/world-point velocity in the same initial camera
-   * axes. Omitted means stationary world point.
+   * Optional constant velocity of the subject (world point), in the same
+   * starting camera axes. If omitted, the world point is still.
    */
   subjectVelocityMps?: Vector3;
 }

package/docs/api/motion-extended-object-projection.md

@@ -1,11 +1,12 @@
 # motion/extended-object-projection.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.
 
 ## calculateCaptureExtendedObjectTemporalProjection
 
-Evaluates extended-object projection at deterministic midpoint nodes inside
-each point's authoritative #12 local exposure window.
+Evaluates extended-object projection at deterministic midpoint time samples
+inside each point's local exposure window (from the capture exposure
+schedule).
 
 ```ts
 export function calculateCaptureExtendedObjectTemporalProjection(
@@ -44,8 +45,9 @@ export interface CalculateCaptureExtendedObjectTemporalProjectionInput {
 Evaluates multiple explicit metric points on one rigidly translating object
 at deterministic physical times.
 
-This is geometry only. It does not synthesize a blur kernel, visibility,
-radiance integration, deformation, camera rotation or a universal scale.
+This is geometry only. It does not build a blur kernel, decide visibility,
+integrate radiance, deform the object, rotate the camera or apply a
+universal scale.
 
 ```ts
 export function calculateExtendedObjectProjectionTrajectory(
@@ -86,8 +88,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface CaptureExtendedObjectMetricPoint
   extends ExtendedObjectMetricPoint {
   /**
-   * Native destination point selecting the authoritative #12 local exposure
-   * window for this object point.
+   * Native destination point. It selects the local exposure window (from the
+   * capture exposure schedule) for this object point.
    */
   destinationPointNative:
     RasterPoint;
@@ -198,7 +200,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface ExtendedObjectMetricPoint {
   pointId: string;
   /**
-   * Metric camera-space point at the common reference phase.
+   * Point in camera space, in metres, at the shared reference phase.
    *
    * +X right, +Y up, +Z forward/away from the camera.
    */

package/docs/api/motion-projected-motion.md

@@ -1,20 +1,20 @@
 # motion/projected-motion.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.
 
 ## calculateProjectedMotionBlur
 
 Calculates sensor-plane motion during an exposure using ideal rectilinear
 projection and constant linear object velocity.
 
-Without focusDistanceM, nominal focal length is the backwards-compatible
-pinhole projection distance. With focusDistanceM, the selected thin-lens
-sensor-plane image distance is used.
+Without focusDistanceM, the projection distance is the nominal focal length
+(the older pinhole behaviour). With focusDistanceM, it is the thin-lens
+image distance for that focus.
 
-The calculation projects the object's shutter-open and shutter-close
-positions onto the image plane and measures the displacement between them.
-It therefore handles lateral and depth-direction motion without relying on a
-generic "subject speed" category.
+The object's positions when the shutter opens and closes are both projected
+onto the image plane, and the distance between them is measured. So
+sideways motion and motion toward or away from the camera are both handled,
+without a generic "subject speed" category.
 
 ```ts
 export function calculateProjectedMotionBlur(

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;
+}
+```