@photivra/engine 0.5.1 → 1.0.0

package/docs/api/sensor-response-application-compatibility.md

@@ -0,0 +1,256 @@
+# sensor/response-application-compatibility.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.
+
+## assessSensorResponseApplicationCompatibility
+
+Assess whether exact source-plane, area, profile/channel and reference-condition bindings permit the
+selected response application path.
+
+Response application checks exact profile/channel, source plane, incident-area basis, spatial
+uniformity and reference conditions. Structural compatibility alone does not authorize signal
+conversion; per-bin operating-range validity and the typed EQE/A-W path are separate gates.
+
+```ts
+export function assessSensorResponseApplicationCompatibility(
+  input:
+    AssessSensorResponseApplicationCompatibilityInput
+): CalculationResult<SensorResponseApplicationCompatibilityAssessment>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## AssessSensorResponseApplicationCompatibilityInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AssessSensorResponseApplicationCompatibilityInput {
+  reduction:
+    SensorSpatioSpectralIrradianceReduction;
+  applicationProfile:
+    SensorResponseApplicationProfile;
+  sourcePlane:
+    SourcedSensorResponseSourcePlane;
+  operatingConditions?:
+    SensorSpectralReferenceConditions;
+}
+```
+
+## parseSensorResponseApplicationProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Response application checks exact profile/channel, source plane, incident-area basis, spatial
+uniformity and reference conditions. Structural compatibility alone does not authorize signal
+conversion; per-bin operating-range validity and the typed EQE/A-W path are separate gates.
+
+```ts
+export function parseSensorResponseApplicationProfile(
+  value: unknown
+): SensorResponseApplicationProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SensorResponseApplicationCompatibilityAssessment
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorResponseApplicationCompatibilityAssessment {
+  applicationProfileId: string;
+  spectralResponseProfileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  responseScope:
+    SensorSpatioSpectralIrradianceReduction["responseScope"];
+  requiredSourcePlane:
+    SensorResponseSourcePlane;
+  suppliedSourcePlane:
+    SensorResponseSourcePlane;
+  sourcePlaneMatched: boolean;
+  responseIncidentAreaBasis:
+    SensorResponseIncidentAreaBasis;
+  currentlyIntegratedAreaBasis:
+    "geometric-sensitive-aperture";
+  geometricApertureAreaSquareMicrometers:
+    number;
+  nominalSiteCellAreaSquareMicrometers?:
+    number;
+  spatialResponseModel:
+    SensorResponseSpatialModel;
+  referenceConditionPolicy:
+    SensorResponseReferenceConditionPolicy;
+  responseReferenceConditions?:
+    SensorSpectralReferenceConditions;
+  operatingConditions?:
+    SensorSpectralReferenceConditions;
+  structuralCompatibilityEstablished:
+    boolean;
+  compatibilityStatus:
+    | "compatible"
+    | "compatible-approximation"
+    | "blocked";
+  blockers:
+    readonly SensorResponseApplicationCompatibilityBlocker[];
+  requiredSignalPath:
+    SensorResponseSignalPath;
+  quantifiedResponseUncertaintyAvailable:
+    boolean;
+  responseApplicationPerformed: false;
+  signalConversionAuthorized: false;
+  temporalIntegrationAuthorized: false;
+  photonConversionPerformed: false;
+  electronConversionPerformed: false;
+  currentConversionPerformed: false;
+  operatingRangeCompatibilityAssessed: false;
+  spatiallyVaryingResponseSupported: false;
+  componentEvidence: {
+    applicationProfile:
+      readonly EvidenceProvenance[];
+    sourcePlane:
+      readonly EvidenceProvenance[];
+    spatialResponse:
+      readonly EvidenceProvenance[];
+    referenceConditionAssumption:
+      readonly EvidenceProvenance[];
+    response:
+      SensorSpatioSpectralIrradianceReduction["componentEvidence"]["spectral"];
+  };
+}
+```
+
+## SensorResponseApplicationCompatibilityBlocker
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorResponseApplicationCompatibilityBlocker =
+  | "spectral-response-profile-id-mismatch"
+  | "color-sampling-profile-id-mismatch"
+  | "channel-id-mismatch"
+  | "sampling-aperture-profile-id-missing"
+  | "sampling-aperture-profile-id-mismatch"
+  | "optical-stack-profile-id-missing"
+  | "optical-stack-profile-id-mismatch"
+  | "source-plane-mismatch"
+  | "wavelength-basis-unresolved"
+  | "incident-area-basis-not-currently-integrated"
+  | "incident-area-mismatch"
+  | "spatial-response-uniformity-not-established"
+  | "response-reference-conditions-not-declared"
+  | "operating-conditions-not-declared"
+  | "operating-conditions-mismatch";
+```
+
+## SensorResponseApplicationProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorResponseApplicationProfile {
+  schemaVersion: "0.1.0";
+  profileId: string;
+  spectralResponseProfileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  samplingApertureProfileId: string;
+  opticalStackProfileId: string;
+  evidence: readonly EvidenceProvenance[];
+  incidentAreaBasis:
+    SensorResponseIncidentAreaBasis;
+  spatialResponseModel:
+    SensorResponseSpatialModel;
+  referenceConditionPolicy:
+    SensorResponseReferenceConditionPolicy;
+}
+```
+
+## SensorResponseIncidentAreaBasis
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorResponseIncidentAreaBasis =
+  | {
+      kind: "geometric-sensitive-aperture";
+      areaSquareMicrometers: number;
+    }
+  | {
+      kind: "full-site-cell";
+      areaSquareMicrometers: number;
+    }
+  | {
+      kind: "effective-collection-area";
+      areaSquareMicrometers: number;
+    };
+```
+
+## SensorResponseReferenceConditionPolicy
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorResponseReferenceConditionPolicy =
+  | {
+      kind: "exact-match-required";
+    }
+  | {
+      kind: "assume-compatible";
+      limitation: string;
+      evidence: readonly EvidenceProvenance[];
+    };
+```
+
+## SensorResponseSignalPath
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorResponseSignalPath =
+  | "photon-rate-to-electrons"
+  | "radiant-power-to-current";
+```
+
+## SensorResponseSourcePlane
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorResponseSourcePlane =
+  | "sensor-package-incident"
+  | "site-incident";
+```
+
+## SensorResponseSpatialModel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorResponseSpatialModel =
+  | {
+      kind:
+        "uniform-over-geometric-sensitive-aperture";
+      scientificStatus:
+        SensorSpectralResponseScientificStatus;
+      evidence: readonly EvidenceProvenance[];
+      limitation?: string;
+    }
+  | {
+      kind: "not-established";
+      limitation: string;
+    };
+```
+
+## SourcedSensorResponseSourcePlane
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SourcedSensorResponseSourcePlane {
+  value: SensorResponseSourcePlane;
+  evidence: readonly EvidenceProvenance[];
+}
+```

package/docs/api/sensor-response-operating-range.md

@@ -0,0 +1,293 @@
+# sensor/response-operating-range.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.
+
+## assessSensorResponseOperatingRange
+
+Assess every declared spectral-bin input against operating applicability and superposition before
+authorizing instantaneous response conversion.
+
+Operating-range assessment preserves incident power versus irradiance, wavelength support, reference
+conditions and declared nonlinearity criterion. Per-bin conversion requires spectral-bin
+applicability and spatial linear superposition. Valid mean input must not conceal an invalid bright
+local sub-aperture.
+
+```ts
+export function assessSensorResponseOperatingRange(
+  input:
+    AssessSensorResponseOperatingRangeInput
+): CalculationResult<SensorResponseOperatingRangeAssessment>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## AssessSensorResponseOperatingRangeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AssessSensorResponseOperatingRangeInput {
+  reduction:
+    SensorSpatioSpectralIrradianceReduction;
+  compatibility:
+    SensorResponseApplicationCompatibilityAssessment;
+  operatingRangeProfile:
+    SensorResponseOperatingRangeProfile;
+}
+```
+
+## parseSensorResponseOperatingRangeProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Operating-range assessment preserves incident power versus irradiance, wavelength support, reference
+conditions and declared nonlinearity criterion. Per-bin conversion requires spectral-bin
+applicability and spatial linear superposition. Valid mean input must not conceal an invalid bright
+local sub-aperture.
+
+```ts
+export function parseSensorResponseOperatingRangeProfile(
+  value: unknown
+): SensorResponseOperatingRangeProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SensorResponseLinearityCriterion
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorResponseLinearityCriterion {
+  maximumAbsoluteRelativeDeviation: number;
+}
+```
+
+## SensorResponseOperatingInputRange
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorResponseOperatingInputRange =
+  | {
+      kind:
+        "wavelength-integrated-geometric-aperture-radiant-power";
+      unit: "W";
+      minimumInclusive: number;
+      maximumInclusive: number;
+    }
+  | {
+      kind:
+        "wavelength-integrated-spatial-average-irradiance";
+      unit: "W/m^2";
+      minimumInclusive: number;
+      maximumInclusive: number;
+    };
+```
+
+## SensorResponseOperatingRangeAssessment
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorResponseOperatingRangeAssessment {
+  operatingRangeProfileId: string;
+  responseApplicationProfileId: string;
+  spectralResponseProfileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  requiredSignalPath:
+    SensorResponseSignalPath;
+  inputRange:
+    SensorResponseOperatingInputRange;
+  evaluatedInput: {
+    kind:
+      SensorResponseOperatingInputRange["kind"];
+    unit:
+      SensorResponseOperatingInputRange["unit"];
+    value: number;
+  };
+  wavelengthApplicability:
+    SensorResponseOperatingWavelengthApplicability;
+  evaluatedWavelengthRangeNanometers: {
+    minimum: number;
+    maximum: number;
+  };
+  linearityCriterion:
+    SensorResponseLinearityCriterion;
+  spectralInputModel:
+    SensorResponseOperatingSpectralInputModel;
+  evaluatedSpectralNodeInputs?:
+    readonly {
+      spectralSampleIndex: number;
+      wavelengthNanometers: number;
+      wavelengthMeasureNanometers: number;
+      kind:
+        SensorResponseOperatingInputRange["kind"];
+      unit:
+        SensorResponseOperatingInputRange["unit"];
+      value: number;
+    }[];
+  spectralNodeRangeCompatibilityAssessed:
+    boolean;
+  spatialLinearityModel:
+    SensorResponseOperatingSpatialLinearityModel;
+  referenceConditionPolicy:
+    SensorResponseReferenceConditionPolicy;
+  referenceConditions?:
+    SensorSpectralReferenceConditions;
+  operatingConditions?:
+    SensorSpectralReferenceConditions;
+  operatingRangeCompatibilityAssessed: true;
+  instantaneousResponseRangeCompatible: boolean;
+  status:
+    | "broadband-range-compatible"
+    | "broadband-range-compatible-approximation"
+    | "rate-conversion-authorized"
+    | "rate-conversion-authorized-approximation"
+    | "blocked";
+  blockers:
+    readonly SensorResponseOperatingRangeBlocker[];
+  responseRateConversionAuthorized: boolean;
+  responseApplicationPerformed: false;
+  temporalIntegrationAuthorized: false;
+  exposureDomainLinearityAssessed: false;
+  accumulatedChargeLinearityAssessed: false;
+  saturationAssessed: false;
+  photonConversionPerformed: false;
+  electronConversionPerformed: false;
+  currentConversionPerformed: false;
+  componentEvidence: {
+    operatingRange:
+      readonly EvidenceProvenance[];
+    referenceConditionAssumption:
+      readonly EvidenceProvenance[];
+    spatialLinearity:
+      readonly EvidenceProvenance[];
+    structuralCompatibility:
+      SensorResponseApplicationCompatibilityAssessment["componentEvidence"];
+  };
+}
+```
+
+## SensorResponseOperatingRangeBlocker
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorResponseOperatingRangeBlocker =
+  | "structural-compatibility-not-established"
+  | "response-application-profile-id-mismatch"
+  | "spectral-response-profile-id-mismatch"
+  | "color-sampling-profile-id-mismatch"
+  | "channel-id-mismatch"
+  | "wavelength-basis-unresolved"
+  | "wavelength-basis-mismatch"
+  | "wavelength-range-outside-linearity-applicability"
+  | "input-below-linearity-range"
+  | "input-above-linearity-range"
+  | "spectral-bin-width-outside-linearity-applicability"
+  | "spectral-bin-input-below-linearity-range"
+  | "spectral-bin-input-above-linearity-range"
+  | "spatial-linearity-superposition-not-established"
+  | "operating-conditions-not-declared"
+  | "linearity-operating-conditions-mismatch";
+```
+
+## SensorResponseOperatingRangeProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorResponseOperatingRangeProfile {
+  schemaVersion: "0.1.0";
+  profileId: string;
+  responseApplicationProfileId: string;
+  spectralResponseProfileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  scientificStatus:
+    SensorSpectralResponseScientificStatus;
+  uncertainty:
+    SensorSpectralResponseUncertainty;
+  evidence: readonly EvidenceProvenance[];
+  inputRange:
+    SensorResponseOperatingInputRange;
+  wavelengthApplicability:
+    SensorResponseOperatingWavelengthApplicability;
+  linearityCriterion:
+    SensorResponseLinearityCriterion;
+  /**
+   * Optional for backward compatibility. Omission parses as not-established
+   * and blocks new response-rate authorization.
+   */
+  spatialLinearityModel?:
+    SensorResponseOperatingSpatialLinearityModel;
+  /**
+   * Optional for backward compatibility. Omission means the calibration only
+   * establishes a broadband-integrated operating range and cannot authorize
+   * wavelength-by-wavelength response conversion.
+   */
+  spectralInputModel?:
+    SensorResponseOperatingSpectralInputModel;
+  referenceConditions?:
+    SensorSpectralReferenceConditions;
+  referenceConditionPolicy:
+    SensorResponseReferenceConditionPolicy;
+}
+```
+
+## SensorResponseOperatingSpatialLinearityModel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorResponseOperatingSpatialLinearityModel =
+  | {
+      kind:
+        "linear-superposition-over-geometric-aperture";
+      scientificStatus:
+        SensorSpectralResponseScientificStatus;
+      evidence: readonly EvidenceProvenance[];
+      limitation?: string;
+    }
+  | {
+      kind: "not-established";
+      limitation: string;
+    };
+```
+
+## SensorResponseOperatingSpectralInputModel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorResponseOperatingSpectralInputModel =
+  | {
+      kind: "broadband-integrated-only";
+    }
+  | {
+      kind: "per-spectral-bin";
+      maximumBinWidthNanometers: number;
+      scientificStatus:
+        SensorSpectralResponseScientificStatus;
+      evidence: readonly EvidenceProvenance[];
+      limitation?: string;
+    };
+```
+
+## SensorResponseOperatingWavelengthApplicability
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorResponseOperatingWavelengthApplicability {
+  wavelengthBasis:
+    Exclude<SpectralWavelengthBasis, "unspecified">;
+  minimumNanometers: number;
+  maximumNanometers: number;
+  containment:
+    "requested-range-must-be-contained";
+}
+```