@photivra/engine 0.5.1 → 1.0.0

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

@@ -0,0 +1,183 @@
+# sensor/spectral-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.
+
+## calculateSensorSpectralQuadrature
+
+Builds deterministic wavelength quadrature nodes for one exact sensor
+response channel without applying the response to a source spectrum.
+
+The requested wavelength range must lie fully inside the response channel's
+declared usable range. Response-curve knots and optional caller-provided
+continuous-spectrum/optics breakpoints partition that range. Each segment is
+then subdivided so no midpoint subinterval exceeds
+maximumSubintervalWidthNanometers.
+
+wavelengthMeasureNanometers is d-lambda in nanometres. It is not a
+dimensionless response weight. Future integration must use a source spectral
+density expressed per nanometre or explicitly convert units before
+multiplying by this measure.
+
+This function deliberately does not apply QE or A/W responsivity. Those
+representations have different compatible downstream signal domains: QE is
+photon-to-electron efficiency, while A/W responsivity relates incident
+radiant power to electrical current. A later versioned composition must also
+match responseScope to the source plane and collection-area semantics before
+integrating any signal.
+
+```ts
+export function calculateSensorSpectralQuadrature(
+  input:
+    CalculateSensorSpectralQuadratureInput
+): CalculationResult<SensorSpectralQuadrature>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorSpectralQuadratureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSensorSpectralQuadratureInput {
+  colorSamplingProfile: SensorColorSamplingProfile;
+  spectralResponseProfile: SensorSpectralResponseProfile;
+  channelId: string;
+  wavelengthBasis: SpectralWavelengthBasis;
+  /**
+   * Explicit wavelength interval to sample. This API validates the interval
+   * against sensor-response support only; it does not establish scene-spectrum
+   * or optical-transmission coverage.
+   */
+  wavelengthRangeNanometers:
+    SensorSpectralWavelengthRangeNanometers;
+  /**
+   * Hard upper bound on each midpoint subinterval width.
+   *
+   * Response knots and optional additional breakpoints split the requested
+   * range first; each resulting segment is then subdivided until every
+   * subinterval is no wider than this value.
+   */
+  maximumSubintervalWidthNanometers: number;
+  /**
+   * Optional strictly increasing wavelength breakpoints from other continuous
+   * spectral factors, such as scene spectral-density or optical-transmission
+   * interpolation knots. Values must lie strictly inside the requested range.
+   *
+   * These coordinates do not assert that those external factors are actually
+   * available or valid over the requested range.
+   */
+  additionalBreakpointsNanometers?:
+    readonly number[];
+}
+```
+
+## SensorSpectralQuadrature
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSpectralQuadrature {
+  profileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  sourceResponseKind:
+    SensorSpectralResponseProfile["channels"][number]["kind"];
+  responseScope:
+    SensorSpectralResponseProfile["channels"][number]["responseScope"];
+  responseScientificStatus:
+    SensorSpectralResponseScientificStatus;
+  responseUncertainty:
+    SensorSpectralResponseUncertainty;
+  responseChannelBinding?: import("./spectral-response.js").SensorSpectralResponseChannelBinding;
+  responseReferenceConditions?:
+    SensorSpectralReferenceConditions;
+  wavelengthBasis: SpectralWavelengthBasis;
+  wavelengthBasisResolved: boolean;
+  wavelengthRangeNanometers:
+    SensorSpectralWavelengthRangeNanometers;
+  responseDeclaredWavelengthRangeNanometers:
+    SensorSpectralWavelengthRangeNanometers;
+  quadratureScheme:
+    "response-breakpoint-aware-bounded-midpoint";
+  segmentBoundarySource:
+    "requested-range-plus-response-knots-plus-optional-additional-breakpoints";
+  /**
+   * Ordered unique segment boundaries, including requested range endpoints.
+   */
+  segmentBoundariesNanometers:
+    readonly number[];
+  maximumSubintervalWidthNanometers: number;
+  segmentCount: number;
+  totalNodeCount: number;
+  normalizedWavelengthWeightSum: number;
+  wavelengthMeasureSumNanometers: number;
+  nodes: readonly SensorSpectralQuadratureNode[];
+  responseKnotAlignmentIncluded: true;
+  componentEvidence: {
+    colorSamplingProfile: readonly EvidenceProvenance[];
+    profile: readonly EvidenceProvenance[];
+    channel: readonly EvidenceProvenance[];
+    curves:
+      readonly (readonly EvidenceProvenance[])[];
+  };
+  /**
+   * Hard scientific boundaries.
+   */
+  responseValuesIncluded: false;
+  responseApplicationPerformed: false;
+  sourceSpectralValuesIncluded: false;
+  spectralIrradianceIncluded: false;
+  spectralPhotonIrradianceIncluded: false;
+  commonSpectralCoverageValidated: false;
+  continuousSpectralDensityQuadratureOnly: true;
+  discreteLineSpectrumIncluded: false;
+  opticalTransmissionIncludedByQuadrature: false;
+  wavelengthIntegrationPerformed: false;
+  spatialIntegrationPerformed: false;
+  temporalIntegrationPerformed: false;
+  photonsCalculated: false;
+  electronsCalculated: false;
+  rawCodeValueProduced: false;
+  convergenceErrorEstimated: false;
+}
+```
+
+## SensorSpectralQuadratureNode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSpectralQuadratureNode {
+  spectralSampleIndex: number;
+  segmentIndex: number;
+  subdivisionIndex: number;
+  segmentSubdivisionCount: number;
+  /**
+   * Midpoint wavelength for this subinterval. Units: nm in wavelengthBasis.
+   */
+  wavelengthNanometers: number;
+  /**
+   * d-lambda represented by this node. Units: nm.
+   *
+   * This is wavelength measure only. It is not response-weighted throughput,
+   * photon count, radiant energy, current, or a dimensionless probability.
+   */
+  wavelengthMeasureNanometers: number;
+  /**
+   * Dimensionless wavelength measure normalized by the requested range width.
+   *
+   * This may be useful for averages, but it is not a sensor-response weight.
+   */
+  normalizedWavelengthWeight: number;
+}
+```
+
+## SensorSpectralWavelengthRangeNanometers
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorSpectralWavelengthRangeNanometers =
+  SpectralWavelengthRangeNanometers;
+```

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

@@ -0,0 +1,291 @@
+# sensor/spectral-response.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.
+
+## EffectiveSensorResponseScope
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type EffectiveSensorResponseScope =
+  | "site-incident-effective-channel-response"
+  | "sensor-package-incident-effective-channel-response";
+```
+
+## parseSensorSpectralResponseProfile
+
+Parses reusable wavelength-dependent response data for semantic sensor
+channels without inferring response from channel names or CFA family.
+
+Embedded multi-point curves require reusable-data or Photivra-owned evidence.
+Public/factual references without reuse permission may support metadata but
+cannot by themselves authorize copying numeric curve data into the engine.
+
+```ts
+export function parseSensorSpectralResponseProfile(
+  value: unknown
+): SensorSpectralResponseProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvedSensorSpectralResponse
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedSensorSpectralResponse {
+  profileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  sourceResponseKind:
+    SensorSpectralChannelResponse["kind"];
+  responseScope:
+    SensorSpectralChannelResponse["responseScope"];
+  scientificStatus:
+    SensorSpectralResponseScientificStatus;
+  uncertainty:
+    SensorSpectralResponseUncertainty;
+  wavelengthNanometers: number;
+  wavelengthBasis: SpectralWavelengthBasis;
+  wavelengthBasisResolved: boolean;
+  declaredWavelengthRangeNanometers: {
+    minimum: number;
+    maximum: number;
+  };
+  interpolation:
+    "piecewise-linear";
+  interpolationUsed: boolean;
+  outsideRangeBehavior:
+    "fail-closed";
+  response:
+    ResolvedSensorSpectralResponseValue;
+  referenceConditions?:
+    SensorSpectralReferenceConditions;
+  conditionDependenceModeled: false;
+  fieldAngleDependenceModeled: false;
+  temperatureDependenceModeled: false;
+  polarizationDependenceModeled: false;
+  spectralIrradianceIntegrated: false;
+  wavelengthIntegrationPerformed: false;
+  qeResponsivityConversionPerformed: false;
+  photonsCalculated: false;
+  electronsCalculated: false;
+  rawCodeValueProduced: false;
+  componentEvidence: {
+    profile: readonly EvidenceProvenance[];
+    channel: readonly EvidenceProvenance[];
+    curves:
+      readonly (readonly EvidenceProvenance[])[];
+  };
+}
+```
+
+## ResolvedSensorSpectralResponseValue
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ResolvedSensorSpectralResponseValue =
+  | {
+      kind:
+        "effective-external-quantum-efficiency";
+      externalQuantumEfficiency: number;
+      composition:
+        | "direct-effective-response"
+        | "channel-filter-transmittance-times-detector-eqe";
+      channelFilterTransmittance?: number;
+      detectorExternalQuantumEfficiency?: number;
+    }
+  | {
+      kind:
+        "effective-spectral-responsivity";
+      amperesPerWatt: number;
+      composition:
+        "direct-effective-response";
+    };
+```
+
+## resolveSensorSpectralResponseAtWavelength
+
+Public spectral-response resolver for untrusted/raw profile inputs.
+
+Profiles are parsed once here. Internal composition code that has already
+parsed both profiles may use resolveParsedSensorSpectralResponseAtWavelength
+to avoid repeating full profile parsing for every wavelength node.
+
+```ts
+export function resolveSensorSpectralResponseAtWavelength(
+  input:
+    ResolveSensorSpectralResponseAtWavelengthInput
+): CalculationResult<ResolvedSensorSpectralResponse>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveSensorSpectralResponseAtWavelengthInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveSensorSpectralResponseAtWavelengthInput {
+  colorSamplingProfile:
+    SensorColorSamplingProfile;
+  spectralResponseProfile:
+    SensorSpectralResponseProfile;
+  channelId: string;
+  wavelengthNanometers: number;
+  wavelengthBasis: SpectralWavelengthBasis;
+}
+```
+
+## SensorSpectralChannelResponse
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorSpectralChannelResponse =
+  | (SensorSpectralChannelResponseBase & {
+      kind:
+        "effective-external-quantum-efficiency";
+      responseScope:
+        EffectiveSensorResponseScope;
+      externalQuantumEfficiency:
+        SpectralFractionCurve;
+    })
+  | (SensorSpectralChannelResponseBase & {
+      kind:
+        "effective-spectral-responsivity";
+      responseScope:
+        EffectiveSensorResponseScope;
+      spectralResponsivity:
+        SpectralResponsivityCurve;
+    })
+  | (SensorSpectralChannelResponseBase & {
+      kind:
+        "separable-channel-filter-and-detector-eqe";
+      responseScope:
+        "site-incident-channel-filter-times-detector-eqe";
+      combinationRule: "multiply";
+      channelFilterTransmittance:
+        SpectralFractionCurve;
+      detectorExternalQuantumEfficiency:
+        SpectralFractionCurve;
+    });
+```
+
+## SensorSpectralReferenceConditions
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSpectralReferenceConditions {
+  temperatureC?: number;
+  incidenceAngleDegreesFromNormal?: number;
+  polarization?:
+    | "unpolarized"
+    | "unspecified";
+}
+```
+
+## SensorSpectralResponseChannelBinding
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSpectralResponseChannelBinding {
+  format:
+    "photivra-spectral-channel-response-canonical-json-v1";
+  canonicalJson: string;
+}
+```
+
+## SensorSpectralResponseProfile
+
+Versioned channel-response data linked to one exact color-sampling profile.
+Each channel declares effective EQE, effective A/W response or separable filter
+and detector EQE, sampled support/interpolation and an explicit wavelength basis.
+Reference conditions, evidence and uncertainty retain their own validity. Names
+such as red/green/blue never supply missing curves or justify extrapolation.
+
+```ts
+export interface SensorSpectralResponseProfile {
+  schemaVersion: "0.1.0";
+  profileId: string;
+  colorSamplingProfileId: string;
+  evidence: readonly EvidenceProvenance[];
+  channels:
+    readonly SensorSpectralChannelResponse[];
+}
+```
+
+## SensorSpectralResponseScientificStatus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorSpectralResponseScientificStatus =
+  | "calibrated"
+  | "approximation";
+```
+
+## SensorSpectralResponseUncertainty
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorSpectralResponseUncertainty =
+  | {
+      kind: "relative";
+      fraction: number;
+      basis: string;
+    }
+  | {
+      kind: "not-quantified";
+      limitation: string;
+    };
+```
+
+## SpectralFractionCurve
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SpectralFractionCurve
+  extends SpectralCurveBase {
+  samples: readonly SpectralFractionSample[];
+}
+```
+
+## SpectralFractionSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SpectralFractionSample
+  extends SpectralWavelengthSample {
+  value: number;
+}
+```
+
+## SpectralResponsivityCurve
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SpectralResponsivityCurve
+  extends SpectralCurveBase {
+  samples: readonly SpectralResponsivitySample[];
+}
+```
+
+## SpectralResponsivitySample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SpectralResponsivitySample
+  extends SpectralWavelengthSample {
+  amperesPerWatt: number;
+}
+```

package/docs/api/sensor-temporal-photo-signal.md

@@ -0,0 +1,62 @@
+# sensor/temporal-photo-signal.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.
+
+## createSensorEqeTemporalPhotoSignal
+
+Re-evaluate physical input at every time before committing an owned compact
+photo signal. Detailed child evidence/uncertainty stays in the returned
+exposure diagnostics. This does not establish renderer/source execution.
+
+```ts
+export function createSensorEqeTemporalPhotoSignal(input: {
+  temporalIntegrationId: string;
+  exposure: CalculateSensorEqeTemporalExposureInput;
+}): CalculationResult<{ photoSignal: SensorEqeTemporalPhotoSignal; exposure: ReturnType<typeof calculateSensorEqeTemporalExposure> }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSensorEqeTemporalPhotoSignal
+
+Recompute exact midpoint count sums; declarations do not prove source truth.
+
+```ts
+export function parseSensorEqeTemporalPhotoSignal(value: unknown): SensorEqeTemporalPhotoSignal;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SensorEqePhotoExposure
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorEqePhotoExposure = SensorEqeExposureIntegration | SensorEqeTemporalPhotoSignal;
+```
+
+## SensorEqeTemporalPhotoSignal
+
+Compact untreated photo expectation; temporal identity is not stationarity evidence.
+
+```ts
+export interface SensorEqeTemporalPhotoSignal extends Omit<SensorEqeExposureIntegration,
+  "kind" | "stationarityProfileId" | "stationarityStatus" | "integrationMethod" | "timeStationarityEstablished" |
+  "timeVaryingSignalIntegrated" | "incidentPhotonRatePerSecond" | "expectedGeneratedElectronRatePerSecond" | "componentEvidence"> {
+  kind: "eqe-temporal-photo-signal";
+  temporalIntegrationId: string;
+  stationarityProfileId?: never;
+  integrationMethod: "uniform-midpoint-rate-quadrature";
+  timeStationarityEstablished: false;
+  timeVaryingSignalIntegrated: true;
+  temporalSamples: readonly {
+    timeSecondsFromOpeningReference: number;
+    incidentPhotonRatePerSecond: number;
+    expectedGeneratedElectronRatePerSecond: number;
+  }[];
+  componentEvidence: {
+    temporalResponse: readonly EvidenceProvenance[];
+    exposureBinding: SensorEqeExposureIntegration["componentEvidence"]["exposureBinding"];
+  };
+}
+```