@photivra/engine 0.5.1 → 1.0.0

package/docs/api/sensor-signal-noise.md

@@ -0,0 +1,75 @@
+# sensor/signal-noise.ts public contracts
+
+Package **1.0.0**, root API **0.116.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.
+
+## calculatePhotoelectrons
+
+Converts mean incident photon count to mean photoelectron count.
+
+This is an expectation value; the stochastic shot-noise realization is not
+generated by this deterministic calculation.
+
+```ts
+export function calculatePhotoelectrons(
+  input: CalculatePhotoelectronsInput
+): CalculationResult<number>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculatePhotoelectronsInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculatePhotoelectronsInput {
+  /** Mean photons incident on the photosite/measurement region. */
+  incidentPhotons: number;
+  /** Quantum efficiency from 0 to 1 inclusive. */
+  quantumEfficiency: number;
+}
+```
+
+## calculateSignalToNoise
+
+Calculates expected SNR from Poisson shot noise and independent RMS read
+noise.
+
+Variances are combined as signalElectrons + readNoiseElectrons^2.
+Dark current, fixed-pattern noise, quantization, clipping, and downstream
+processing are intentionally outside this primitive.
+
+```ts
+export function calculateSignalToNoise(
+  input: CalculateSignalToNoiseInput
+): CalculationResult<SignalToNoise>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSignalToNoiseInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSignalToNoiseInput {
+  /** Mean signal in electrons. */
+  signalElectrons: number;
+  /** RMS read noise in electrons. */
+  readNoiseElectrons: number;
+}
+```
+
+## SignalToNoise
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SignalToNoise {
+  shotNoiseStdElectrons: number;
+  combinedNoiseStdElectrons: number;
+  snrLinear: number;
+  /** Null when the signal is zero because -Infinity dB is not JSON-safe. */
+  snrDb: number | null;
+}
+```

package/docs/api/sensor-spatial-sample-reduction.md

@@ -0,0 +1,186 @@
+# sensor/spatial-sample-reduction.ts public contracts
+
+Package **1.0.0**, root API **0.116.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.
+
+## reduceSensorSpatialSamplingQuadrature
+
+Reduces explicitly identified nonnegative linear scalar values over a
+validated sensor spatial quadrature.
+
+This function does not sample a renderer or optical model itself. Callers
+evaluate one value at every quadrature node's preAntiAliasingSourcePointMm
+and provide those values with exact node identity. Ordering is deliberately
+irrelevant.
+
+Two domains are supported:
+
+- relative-linear: dimensionless nonnegative irradiance-like proxy for
+  deterministic renderer/science regression;
+- radiometric-irradiance: physical sensor-plane irradiance in W/m^2.
+
+The destination site's channelId is metadata only. No CFA spectral
+transmittance/sensitivity is applied, so the output must not be called a
+physically color-filtered mosaic sample or RAW value.
+
+```ts
+export function reduceSensorSpatialSamplingQuadrature(
+  input: ReduceSensorSpatialSamplingQuadratureInput
+): CalculationResult<SensorSpatialSampleReduction>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ReduceSensorSpatialSamplingQuadratureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ReduceSensorSpatialSamplingQuadratureInput {
+  quadrature: SensorSpatialSamplingQuadrature;
+  valueDomain: SensorSpatialSampleValueDomain;
+  /**
+   * Exactly one explicitly identified value per quadrature node.
+   *
+   * Ordering is not significant; node identity is.
+   */
+  nodeValues: readonly SensorSpatialQuadratureNodeValue[];
+}
+```
+
+## SensorSpatialQuadratureNodeIdentity
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSpatialQuadratureNodeIdentity {
+  antiAliasingComponentIndex: number;
+  apertureSampleXIndex: number;
+  apertureSampleYIndex: number;
+}
+```
+
+## SensorSpatialQuadratureNodeValue
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSpatialQuadratureNodeValue {
+  node: SensorSpatialQuadratureNodeIdentity;
+  /**
+   * Nonnegative finite scalar in the declared value domain.
+   *
+   * Values are evaluated at the corresponding quadrature node's
+   * preAntiAliasingSourcePointMm.
+   */
+  value: number;
+}
+```
+
+## SensorSpatialSampleReduction
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSpatialSampleReduction {
+  site: {
+    x: number;
+    y: number;
+  };
+  /**
+   * Semantic destination CFA/color-site label only.
+   *
+   * No spectral filter response is applied by this reducer.
+   */
+  channelId: string;
+  outputMeaning:
+    "channel-tagged-pre-response-spatial-sample";
+  valueDomain: SensorSpatialSampleValueDomain;
+  nodeCount: number;
+  sourceValuesMatchedBy:
+    "quadrature-node-identity";
+  sourceValuesSuppliedForAllNodes: true;
+  outsideImagingAreaSourceValuesRequired: boolean;
+  normalizedSpatialWeightSum: number;
+  geometricApertureAreaSquareMicrometers: number;
+  reducedValue: SensorSpatialSampleReductionValue;
+  cfaSpectralFilteringApplied: false;
+  channelIdIsSpectralResponse: false;
+  temporalIntegrationApplied: false;
+  exposureDurationApplied: false;
+  quantumEfficiencyApplied: false;
+  microlensResponseApplied: false;
+  opticalThroughputAppliedByReducer: false;
+  photonsCalculated: false;
+  electronsCalculated: false;
+  shotNoiseApplied: false;
+  readNoiseApplied: false;
+  adcQuantizationApplied: false;
+  blackLevelApplied: false;
+  saturationApplied: false;
+  rawCodeValueProduced: false;
+  demosaicOrReconstructionApplied: false;
+}
+```
+
+## SensorSpatialSampleReductionValue
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorSpatialSampleReductionValue =
+  | {
+      kind: "relative-linear";
+      unit: "relative";
+      semantic:
+        "nonnegative-sensor-plane-irradiance-proxy";
+      /**
+       * Dimensionless weighted spatial average in the same relative domain.
+       */
+      normalizedSpatialAverageRelative: number;
+      /**
+       * Relative value × square micrometres.
+       *
+       * This is a geometric area-weighted diagnostic, not radiometric power.
+       */
+      geometricAreaIntegralRelativeSquareMicrometers: number;
+    }
+  | {
+      kind: "radiometric-irradiance";
+      unit: "W/m^2";
+      semantic: "sensor-plane-irradiance";
+      /**
+       * Weighted mean irradiance over the geometric aperture after applying
+       * the declared normalized AA spatial redistribution.
+       */
+      normalizedSpatialAverageIrradianceWattsPerSquareMeter: number;
+      /**
+       * Incident radiant flux represented by integrating the supplied
+       * irradiance over the geometric aperture under the declared normalized
+       * AA redistribution. Units: watts.
+       *
+       * This remains pre-CFA-response, pre-QE, pre-microlens-response and
+       * excludes any optical-stack throughput not already present in the
+       * caller-supplied irradiance values.
+       */
+      geometricApertureIncidentFluxWatts: number;
+    };
+```
+
+## SensorSpatialSampleValueDomain
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorSpatialSampleValueDomain =
+  | {
+      kind: "relative-linear";
+      unit: "relative";
+      semantic:
+        "nonnegative-sensor-plane-irradiance-proxy";
+    }
+  | {
+      kind: "radiometric-irradiance";
+      unit: "W/m^2";
+      semantic: "sensor-plane-irradiance";
+    };
+```

package/docs/api/sensor-spatial-sampling-quadrature.md

@@ -0,0 +1,188 @@
+# sensor/spatial-sampling-quadrature.ts public contracts
+
+Package **1.0.0**, root API **0.116.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.
+
+## calculateSensorSpatialSamplingQuadrature
+
+Builds deterministic spatial quadrature nodes for one CFA/color-sampling site.
+
+The quadrature composes:
+
+1. the resolved geometric sensitive aperture from the sampling-aperture
+   foundation; and
+2. the resolved effective AA point-splitting kernel from the optical-stack
+   foundation.
+
+The first aperture integration uses a tensor-product uniform midpoint rule.
+For an AA component that moves optical energy by +delta on the sensor plane,
+a destination aperture point samples the pre-AA optical field at
+destination - delta. This inverse-source convention prevents applying the AA
+shift twice.
+
+The destination sensor site's CFA channel applies to every node. The
+pre-AA source coordinate is an optical-field location, not another CFA site;
+therefore shifted source coordinates never reassign the destination channel.
+
+Nodes whose pre-AA source coordinates fall outside the active imaging area
+are retained. They are neither clamped nor dropped/renormalized. A renderer
+or optical-field provider owns source-coverage policy.
+
+normalized weights approximate a spatial average. Square-micrometre measures
+approximate a geometric area integral. Neither includes radiometric
+throughput, QE, photon conversion, microlenses, diffusion/crosstalk, or
+temporal integration.
+
+```ts
+export function calculateSensorSpatialSamplingQuadrature(
+  input: CalculateSensorSpatialSamplingQuadratureInput
+): CalculationResult<SensorSpatialSamplingQuadrature>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorSpatialSamplingQuadratureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSensorSpatialSamplingQuadratureInput {
+  imagingArea: SensorImagingArea;
+  nativeRaster: NativeImageRaster;
+  colorSamplingProfile: SensorColorSamplingProfile;
+  colorSamplingBindingProfile: NativeEffectiveRasterColorSamplingBindingProfile;
+  samplingApertureProfile: SensorSamplingApertureProfile;
+  opticalStackProfile: SensorOpticalStackProfile;
+  site: NativeColorSamplingSiteIndex;
+  /** Number of midpoint cells across the geometric aperture width. */
+  spatialSampleCountX: number;
+  /** Number of midpoint cells across the geometric aperture height. */
+  spatialSampleCountY: number;
+}
+```
+
+## SensorSpatialSamplingQuadrature
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSpatialSamplingQuadrature {
+  coordinateSystem: "native-sensor-physical";
+  colorSamplingProfileId?: string;
+  samplingApertureProfileId?: string;
+  opticalStackProfileId?: string;
+  site: NativeColorSamplingSiteIndex;
+  channelId: string;
+  quadratureScheme:
+    "tensor-product-uniform-midpoint";
+  outputMeaning:
+    "pre-aa-optical-field-spatial-quadrature-nodes";
+  spatialSampleCountX: number;
+  spatialSampleCountY: number;
+  antiAliasingComponentCount: number;
+  totalNodeCount: number;
+  geometricApertureAreaSquareMicrometers: number;
+  nominalSiteCellAreaSquareMicrometers?: number;
+  geometricSensitiveAreaFractionOfLatticeCell?: number;
+  normalizedSpatialWeightSum: number;
+  combinedAreaMeasureSumSquareMicrometers: number;
+  preAntiAliasingSourceOutsideImagingAreaNodeCount: number;
+  sourcePointRule:
+    "pre-aa-source-equals-destination-minus-aa-offset";
+  destinationCfaChannelAppliesToAllNodes: true;
+  cfaReassignmentBySourceCoordinate: false;
+  sourceCoveragePolicy: "not-applied";
+  nodes: readonly SensorSpatialSamplingQuadratureNode[];
+  /**
+   * Hard scientific boundaries.
+   */
+  opticalFieldValuesIncluded: false;
+  radianceIncluded: false;
+  photonsIncluded: false;
+  electronsIncluded: false;
+  spectralResponseIncluded: false;
+  quantumEfficiencyIncluded: false;
+  opticalThroughputIncluded: false;
+  microlensResponseIncluded: false;
+  chargeDiffusionIncluded: false;
+  electricalCrosstalkIncluded: false;
+  temporalIntegrationIncluded: false;
+  rawSampleValueIncluded: false;
+  reconstructedPixelValueIncluded: false;
+  geometricAreaMeasureIsRadiometricCollectionArea: false;
+  componentEvidence: {
+    samplingApertureProfile: readonly import("../core/evidence-provenance.js").EvidenceProvenance[];
+    samplingApertureLattice: readonly import("../core/evidence-provenance.js").EvidenceProvenance[];
+    geometricSensitiveAperture: readonly import("../core/evidence-provenance.js").EvidenceProvenance[];
+    opticalStackProfile: readonly import("../core/evidence-provenance.js").EvidenceProvenance[];
+    antiAliasingResponse: readonly import("../core/evidence-provenance.js").EvidenceProvenance[];
+  };
+}
+```
+
+## SensorSpatialSamplingQuadratureNode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSpatialSamplingQuadratureNode {
+  antiAliasingComponentIndex: number;
+  apertureSampleXIndex: number;
+  apertureSampleYIndex: number;
+  /**
+   * Destination point inside the geometric sensitive aperture after the
+   * declared AA point-splitting response.
+   *
+   * Native sensor physical coordinates, millimetres from the optical axis.
+   */
+  destinationAperturePointMm: {
+    x: number;
+    y: number;
+  };
+  /**
+   * Declared AA displacement of optical energy on the sensor plane.
+   *
+   * +X right, +Y down; micrometres.
+   */
+  antiAliasingOffsetMicrometers: {
+    x: number;
+    y: number;
+  };
+  /**
+   * Pre-AA source point that maps to destinationAperturePointMm under the
+   * declared split component:
+   *
+   * source = destination - AA offset
+   */
+  preAntiAliasingSourcePointMm: {
+    x: number;
+    y: number;
+  };
+  /**
+   * Whether the pre-AA source point lies inside the active physical imaging
+   * area. False is not an error; downstream source-coverage policy decides how
+   * to handle valid optical support outside the active sampling area.
+   */
+  preAntiAliasingSourceInsideImagingArea: boolean;
+  /** Dimensionless midpoint weight for the aperture-area average. */
+  normalizedApertureWeight: number;
+  /** Dimensionless normalized weight from the AA split component. */
+  normalizedAntiAliasingWeight: number;
+  /**
+   * Dimensionless product used for a spatial average of a downstream optical
+   * field under this quadrature approximation.
+   */
+  combinedNormalizedSpatialWeight: number;
+  /**
+   * Geometric area measure represented by this aperture midpoint before the
+   * AA component weight is applied. Units: square micrometres.
+   */
+  apertureAreaMeasureSquareMicrometers: number;
+  /**
+   * Geometric area measure multiplied by the dimensionless AA component
+   * weight. Units remain square micrometres.
+   *
+   * This is not an effective radiometric collection area.
+   */
+  combinedAreaMeasureSquareMicrometers: number;
+}
+```

package/docs/api/sensor-spatio-spectral-reduction.md

@@ -0,0 +1,217 @@
+# sensor/spatio-spectral-reduction.ts public contracts
+
+Package **1.0.0**, root API **0.116.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.
+
+## reduceSensorSpatioSpectralIrradiance
+
+Reduces explicitly supplied sensor-plane spectral irradiance E_lambda(x,y)
+over the Cartesian product of an existing spatial quadrature and spectral
+quadrature.
+
+The supplied density unit is W/m^2/nm and wavelengthMeasureNanometers is
+d-lambda in nm, so their direct product has units W/m^2. Do not convert
+d-lambda to metres unless the spectral-density denominator is converted
+consistently.
+
+Spatial area integration uses the spatial quadrature's geometric area
+measures converted from square micrometres to square metres. The result is
+geometric-aperture incident radiant flux only; geometric area is not upgraded
+to an effective radiometric collection area.
+
+This reducer deliberately stops before sensor response. The spectral plan was
+derived from a specific response channel so its support/knots are useful, but
+QE, A/W responsivity and channel-filter transmission are not applied here.
+Response-scope/source-plane matching therefore remains an explicit later
+composition step.
+
+```ts
+export function reduceSensorSpatioSpectralIrradiance(
+  input:
+    ReduceSensorSpatioSpectralIrradianceInput
+): CalculationResult<SensorSpatioSpectralIrradianceReduction>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ReduceSensorSpatioSpectralIrradianceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ReduceSensorSpatioSpectralIrradianceInput {
+  spatialQuadrature: SensorSpatialSamplingQuadrature;
+  spectralQuadrature: SensorSpectralQuadrature;
+  /**
+   * Exactly one explicitly identified E_lambda(x,y) value for every Cartesian
+   * product of spatial and spectral quadrature nodes.
+   *
+   * Ordering is not significant; node identity is.
+   */
+  sampleValues: readonly SensorSpatioSpectralIrradianceSample[];
+}
+```
+
+## SensorSpatioSpectralIrradianceReduction
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSpatioSpectralIrradianceReduction {
+  colorSamplingProfileId: string;
+  samplingApertureProfileId?: string;
+  opticalStackProfileId?: string;
+  site: {
+    x: number;
+    y: number;
+  };
+  channelId: string;
+  responseProfileId: string;
+  sourceResponseKind:
+    SensorSpectralQuadrature["sourceResponseKind"];
+  responseScope:
+    SensorSpectralQuadrature["responseScope"];
+  responseScientificStatus:
+    SensorSpectralQuadrature["responseScientificStatus"];
+  responseUncertainty:
+    SensorSpectralQuadrature["responseUncertainty"];
+  responseChannelBinding?:
+    SensorSpectralQuadrature["responseChannelBinding"];
+  responseReferenceConditions?:
+    SensorSpectralQuadrature["responseReferenceConditions"];
+  wavelengthBasis:
+    SensorSpectralQuadrature["wavelengthBasis"];
+  wavelengthBasisResolved: boolean;
+  wavelengthRangeNanometers:
+    SensorSpectralQuadrature["wavelengthRangeNanometers"];
+  responseDeclaredWavelengthRangeNanometers:
+    SensorSpectralQuadrature["responseDeclaredWavelengthRangeNanometers"];
+  outputMeaning:
+    "pre-response-spatio-spectral-radiometric-reduction";
+  inputValueDomain: {
+    kind: "radiometric-spectral-irradiance";
+    unit: "W/m^2/nm";
+    semantic:
+      "pre-aa-pre-response-sensor-plane-spectral-irradiance";
+  };
+  spatialNodeCount: number;
+  spectralNodeCount: number;
+  combinedSampleCount: number;
+  sourceValuesMatchedBy:
+    "spatial-node-identity-plus-spectral-sample-index-and-wavelength";
+  sourceValuesSuppliedForAllCombinedNodes: true;
+  outsideImagingAreaSourceValuesRequired: boolean;
+  geometricApertureAreaSquareMicrometers?: number;
+  nominalSiteCellAreaSquareMicrometers?: number;
+  geometricSensitiveAreaFractionOfLatticeCell?: number;
+  perWavelength:
+    readonly SensorSpatioSpectralWavelengthReduction[];
+  /**
+   * Integral over the requested wavelength interval of the spatially averaged
+   * spectral irradiance. Units: W/m^2.
+   */
+  wavelengthIntegratedSpatialAverageIrradianceWattsPerSquareMeter:
+    number;
+  /**
+   * Integral over the requested wavelength interval and geometric aperture
+   * area. Units: W.
+   *
+   * This is pre-sensor-response incident radiant flux over the declared
+   * wavelength interval, not collected optical power or generated charge.
+   */
+  wavelengthIntegratedGeometricApertureIncidentFluxWatts:
+    number;
+  spatialIntegrationApplied: true;
+  wavelengthIntegrationApplied: true;
+  spectralResponsePlanUsedForWavelengthSupport: true;
+  spectralResponseApplicationPerformed: false;
+  responseScopeMatchedToSourcePlane: false;
+  quantumEfficiencyApplied: false;
+  spectralResponsivityApplied: false;
+  channelFilterTransmissionApplied: false;
+  opticalTransmissionAppliedByReducer: false;
+  radiometricCollectionAreaEstablished: false;
+  temporalIntegrationApplied: false;
+  exposureDurationApplied: false;
+  photonsCalculated: false;
+  electronsCalculated: false;
+  currentCalculated: false;
+  shotNoiseApplied: false;
+  readNoiseApplied: false;
+  adcQuantizationApplied: false;
+  rawCodeValueProduced: false;
+  demosaicOrReconstructionApplied: false;
+  convergenceErrorEstimated: false;
+  componentEvidence: {
+    spatial:
+      SensorSpatialSamplingQuadrature["componentEvidence"];
+    spectral:
+      SensorSpectralQuadrature["componentEvidence"];
+  };
+}
+```
+
+## SensorSpatioSpectralIrradianceSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSpatioSpectralIrradianceSample {
+  node: SensorSpatioSpectralNodeIdentity;
+  /**
+   * Spectral irradiance evaluated at the spatial quadrature node's
+   * preAntiAliasingSourcePointMm and this spectral node's wavelength.
+   *
+   * Units: W/m^2/nm.
+   */
+  spectralIrradianceWattsPerSquareMeterPerNanometer: number;
+}
+```
+
+## SensorSpatioSpectralNodeIdentity
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSpatioSpectralNodeIdentity {
+  spatialNode: SensorSpatialQuadratureNodeIdentity;
+  spectralSampleIndex: number;
+  wavelengthNanometers: number;
+}
+```
+
+## SensorSpatioSpectralWavelengthReduction
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSpatioSpectralWavelengthReduction {
+  spectralSampleIndex: number;
+  wavelengthNanometers: number;
+  wavelengthMeasureNanometers: number;
+  normalizedWavelengthWeight: number;
+  /**
+   * Spatially reduced spectral irradiance at this wavelength.
+   * Units: W/m^2/nm.
+   */
+  normalizedSpatialAverageSpectralIrradianceWattsPerSquareMeterPerNanometer:
+    number;
+  /**
+   * Spectral radiant flux density incident over the geometric sensitive
+   * aperture after the declared normalized AA redistribution.
+   * Units: W/nm.
+   *
+   * This uses geometric area, not an established radiometric collection area.
+   */
+  geometricApertureIncidentSpectralFluxWattsPerNanometer: number;
+  /**
+   * Contribution to the wavelength-integrated spatial average.
+   * Units: W/m^2.
+   */
+  wavelengthIntegratedSpatialAverageContributionWattsPerSquareMeter: number;
+  /**
+   * Contribution to wavelength-integrated geometric-aperture incident flux.
+   * Units: W.
+   */
+  wavelengthIntegratedGeometricApertureIncidentFluxContributionWatts: number;
+}
+```

package/docs/api/sensor-spectral-coverage.md

@@ -0,0 +1,33 @@
+# sensor/spectral-coverage.ts public contracts
+
+Package **1.0.0**, root API **0.116.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.
+
+## createSensorSpectralCoverageParticipant
+
+Adapts one parsed sensor response channel into the shared continuous
+spectral-coverage contract.
+
+This exposes support and interpolation knots only. It does not apply QE or
+A/W responsivity and does not establish scene/optics coverage.
+
+```ts
+export function createSensorSpectralCoverageParticipant(
+  input:
+    CreateSensorSpectralCoverageParticipantInput
+): SpectralCoverageParticipant;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateSensorSpectralCoverageParticipantInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateSensorSpectralCoverageParticipantInput {
+  spectralResponseProfile:
+    SensorSpectralResponseProfile;
+  channelId: string;
+  participantId?: string;
+}
+```