@photivra/engine 0.5.1 → 1.0.0

package/docs/api/sensor-dark-current.md

@@ -0,0 +1,227 @@
+# sensor/dark-current.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.
+
+## calculateSensorDarkCurrentCharge
+
+Evaluate the declared temperature-dependent dark electron rate and integrate over the exact
+photo-signal local exposure event.
+
+Dark current is an independently declared pre-compensation thermal electron rate. Exact-temperature
+or sampled linear interpolation is supported only within declared applicability; no universal
+doubling-temperature law is inferred. Population means remain approximations and do not model
+hot-pixel/DCNU structure.
+
+```ts
+export function calculateSensorDarkCurrentCharge(
+  input: Omit<CalculateSensorDarkCurrentChargeInput, "exposure"> & { exposure: SensorEqeExposureIntegration }
+): CalculationResult<SensorDarkCurrentCharge>;
+```
+
+```ts
+export function calculateSensorDarkCurrentCharge(
+  input: Omit<CalculateSensorDarkCurrentChargeInput, "exposure"> & { exposure: SensorEqeTemporalPhotoSignal }
+): CalculationResult<SensorTemporalDarkCurrentCharge>;
+```
+
+```ts
+export function calculateSensorDarkCurrentCharge(
+  input: CalculateSensorDarkCurrentChargeInput<SensorEqePhotoExposure>
+): CalculationResult<SensorPhotoDarkCurrentCharge>;
+```
+
+```ts
+export function calculateSensorDarkCurrentCharge(
+  input:
+    CalculateSensorDarkCurrentChargeInput<SensorEqePhotoExposure>
+): CalculationResult<SensorPhotoDarkCurrentCharge>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorDarkCurrentChargeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSensorDarkCurrentChargeInput<Exposure extends SensorEqePhotoExposure = SensorEqeExposureIntegration> {
+  exposure:
+    Exposure;
+  darkCurrentProfile:
+    SensorDarkCurrentProfile;
+  operatingTemperatureC: number;
+}
+```
+
+## parseSensorDarkCurrentProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Dark current is an independently declared pre-compensation thermal electron rate. Exact-temperature
+or sampled linear interpolation is supported only within declared applicability; no universal
+doubling-temperature law is inferred. Population means remain approximations and do not model
+hot-pixel/DCNU structure.
+
+```ts
+export function parseSensorDarkCurrentProfile(
+  value: unknown
+): SensorDarkCurrentProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SensorDarkCurrentCharge
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorDarkCurrentCharge {
+  darkCurrentProfileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  site: {
+    x: number;
+    y: number;
+  };
+  bindingId: string;
+  stationarityProfileId: string;
+  temporalIntegrationId?: never;
+  timeReference:
+    "first-opening-boundary-phase";
+  startOffsetSecondsFromOpeningReference:
+    number;
+  endOffsetSecondsFromOpeningReference:
+    number;
+  operatingTemperatureC: number;
+  temperatureModel:
+    SensorDarkCurrentTemperatureModel["kind"];
+  temperatureInterpolationUsed:
+    boolean;
+  darkCurrentElectronsPerSecond:
+    number;
+  localExposureDurationSeconds:
+    number;
+  expectedDarkElectronCount:
+    number;
+  countMeaning:
+    "expected-thermally-generated-electrons";
+  expectationValueOnly: true;
+  integerDarkElectronCountSampled:
+    false;
+  darkShotNoiseApplied: false;
+  darkCurrentCompensationApplied:
+    false;
+  spatialDarkCurrentNonuniformityModeled:
+    boolean;
+  photoSignalIncluded: false;
+  otherChargeIncluded: false;
+  physicalFullWellAssessmentAuthorized:
+    false;
+  saturationAssessed: false;
+  componentEvidence: {
+    darkCurrent:
+      readonly EvidenceProvenance[];
+    siteApproximation:
+      readonly EvidenceProvenance[];
+    exposure:
+      SensorEqeExposureIntegration["componentEvidence"];
+  };
+}
+```
+
+## SensorDarkCurrentProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorDarkCurrentProfile {
+  schemaVersion: "0.1.0";
+  profileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  scientificStatus:
+    SensorSpectralResponseScientificStatus;
+  uncertainty:
+    SensorSpectralResponseUncertainty;
+  evidence: readonly EvidenceProvenance[];
+  chargeMeaning:
+    "pre-compensation-thermally-generated-electrons";
+  siteApplicability:
+    SensorDarkCurrentSiteApplicability;
+  temperatureModel:
+    SensorDarkCurrentTemperatureModel;
+  darkCurrentCompensationIncluded: false;
+  spatialDarkCurrentNonuniformityModeled:
+    boolean;
+}
+```
+
+## SensorDarkCurrentSiteApplicability
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorDarkCurrentSiteApplicability =
+  | {
+      kind: "exact-site";
+      site: {
+        x: number;
+        y: number;
+      };
+    }
+  | {
+      kind:
+        "uniform-site-mean-approximation";
+      limitation: string;
+      evidence:
+        readonly EvidenceProvenance[];
+    };
+```
+
+## SensorDarkCurrentTemperatureModel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorDarkCurrentTemperatureModel =
+  | {
+      kind:
+        "fixed-reference-temperature";
+      referenceTemperatureC: number;
+      darkCurrentElectronsPerSecond:
+        number;
+    }
+  | {
+      kind:
+        "piecewise-linear-temperature-table";
+      interpolation: "piecewise-linear";
+      outsideRangeBehavior:
+        "fail-closed";
+      samples: readonly {
+        temperatureC: number;
+        darkCurrentElectronsPerSecond:
+          number;
+      }[];
+    };
+```
+
+## SensorPhotoDarkCurrentCharge
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorPhotoDarkCurrentCharge = SensorDarkCurrentCharge | SensorTemporalDarkCurrentCharge;
+```
+
+## SensorTemporalDarkCurrentCharge
+
+Dark charge shares the exact temporal photo event, without a stationarity ID.
+
+```ts
+export type SensorTemporalDarkCurrentCharge = Omit<SensorDarkCurrentCharge, "stationarityProfileId" | "temporalIntegrationId" | "componentEvidence"> & {
+  stationarityProfileId?: never;
+  temporalIntegrationId: string;
+  componentEvidence: Omit<SensorDarkCurrentCharge["componentEvidence"], "exposure"> & { exposure: SensorEqeTemporalPhotoSignal["componentEvidence"] };
+};
+```

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

@@ -0,0 +1,77 @@
+# sensor/environment-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.
+
+## calculateEnvironmentSensorPhotoSignal
+
+Generate, evaluate and integrate one site's actual local midpoint environment support.
+
+```ts
+export function calculateEnvironmentSensorPhotoSignal(input: CalculateEnvironmentSensorPhotoSignalInput): CalculationResult<EnvironmentSensorPhotoSignal>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateEnvironmentSensorPhotoSignalInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateEnvironmentSensorPhotoSignalInput {
+  temporalIntegrationId: string;
+  sensor: Omit<CalculateSensorEqeTemporalExposureInput, "samples">;
+  sceneBindings: CalculateSceneToSensorIrradianceQuadratureInput["sceneBindings"];
+  optics: Omit<CalculateSceneRadianceToSensorIrradianceInput,
+    "sceneRadianceRequest" | "sceneRadianceResult" | "imagePointMm" | "fieldThroughput">;
+  motion: Pick<CalculateSensorEnvironmentRadianceQueryInput,
+    "angularVelocityRadPerSec" | "timeReference" | "environmentDirectionConvention">;
+  temporalSampleCount: number;
+  /** Explicit unity field throughput; spatial vignetting is not inferred or applied. */
+  fieldThroughput: { kind: "unity"; evidence: readonly EvidenceProvenance[]; limitation: string };
+  psf: { kind: "not-applied"; evidence: readonly EvidenceProvenance[]; limitation: string } | {
+    kind: "sampled-local";
+    configuration: Pick<CalculateSensorPsfIrradianceQuadratureInput, "psf" | "psfWavelengthBasis" | "spatialModel">;
+  };
+  evaluateRadiance: EnvironmentRadianceEvaluator;
+}
+```
+
+## EnvironmentRadianceEvaluator
+
+Supplied synchronous code executes locally. Invocation does not prove physical transport.
+
+```ts
+export type EnvironmentRadianceEvaluator = (request: Readonly<SceneRadianceEvaluationRequest>) => SceneRadianceEvaluationResult;
+```
+
+## EnvironmentSensorPhotoSignal
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface EnvironmentSensorPhotoSignal {
+  sourceTargetProjectionCalculated: true;
+  providerCallbackExecuted: true;
+  providerTransportVerified: false;
+  sceneVisibilityCalculated: false;
+  productionPlanActivated: false;
+  providerEvaluationCount: number;
+  sourcePlane: "sensor-package-incident";
+  fieldThroughputEvidence: readonly EvidenceProvenance[];
+  fieldThroughputLimitation: string;
+  psfOmission: { evidence: readonly EvidenceProvenance[]; limitation: string } | null;
+  psfRedistributionApplied: boolean;
+  photo: ReturnType<typeof createSensorEqeTemporalPhotoSignal>;
+  instants: readonly {
+    temporalSampleIndex: number;
+    timeSecondsFromOpeningReference: number;
+    psf: ReturnType<typeof calculateSensorPsfIrradianceQuadrature> | null;
+    evaluations: readonly {
+      query: ReturnType<typeof calculateSensorEnvironmentRadianceQuery>;
+      result: SceneRadianceEvaluationResult;
+      bindings: ReturnType<typeof validateSceneRadianceEvaluationBindings>;
+      optics: ReturnType<typeof calculateSceneRadianceToSensorIrradiance>;
+    }[];
+  }[];
+}
+```

package/docs/api/sensor-eqe-electron-rate.md

@@ -0,0 +1,166 @@
+# sensor/eqe-electron-rate.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.
+
+## calculateSensorEqeElectronRate
+
+Converts pre-response geometric-aperture spectral radiant power into
+incident-photon rate and expected generated-electron rate.
+
+This function applies response per wavelength node. It never applies one
+broadband-average QE to total radiant power.
+
+Temporal exposure integration remains downstream, so all outputs are rates
+(per second), not photon/electron counts.
+
+```ts
+export function calculateSensorEqeElectronRate(
+  input:
+    CalculateSensorEqeElectronRateInput
+): CalculationResult<SensorEqeElectronRate>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorEqeElectronRateInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSensorEqeElectronRateInput {
+  reduction:
+    SensorSpatioSpectralIrradianceReduction;
+  compatibility:
+    SensorResponseApplicationCompatibilityAssessment;
+  operatingRange:
+    SensorResponseOperatingRangeAssessment;
+  colorSamplingProfile:
+    SensorColorSamplingProfile;
+  spectralResponseProfile:
+    SensorSpectralResponseProfile;
+  airPhotonEnergyContext?:
+    SensorEqeAirPhotonEnergyContext;
+}
+```
+
+## SensorEqeAirPhotonEnergyContext
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorEqeAirPhotonEnergyContext {
+  samples:
+    readonly SensorEqeAirRefractiveIndexSample[];
+  operatingConditions?:
+    AirRefractiveIndexReferenceConditions;
+  conditionPolicy:
+    AirRefractiveIndexConditionPolicy;
+}
+```
+
+## SensorEqeAirRefractiveIndexSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorEqeAirRefractiveIndexSample {
+  spectralSampleIndex: number;
+  refractiveIndex:
+    SourcedAirPhaseRefractiveIndex;
+}
+```
+
+## SensorEqeElectronRate
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorEqeElectronRate {
+  colorSamplingProfileId: string;
+  responseProfileId: string;
+  responseApplicationProfileId: string;
+  operatingRangeProfileId: string;
+  /** Engine-produced results populate the exact source color site. */
+  site?: {
+    x: number;
+    y: number;
+  };
+  channelId: string;
+  sourceResponseKind:
+    | "effective-external-quantum-efficiency"
+    | "separable-channel-filter-and-detector-eqe";
+  responseScope:
+    SensorSpatioSpectralIrradianceReduction["responseScope"];
+  responseReferencePlane:
+    SensorResponseApplicationCompatibilityAssessment["requiredSourcePlane"];
+  wavelengthBasis:
+    SensorSpatioSpectralIrradianceReduction["wavelengthBasis"];
+  wavelengthRangeNanometers:
+    SensorSpatioSpectralIrradianceReduction["wavelengthRangeNanometers"];
+  spectralNodeCount: number;
+  perWavelength:
+    readonly SensorEqeWavelengthRateContribution[];
+  incidentPhotonRatePerSecond: number;
+  expectedGeneratedElectronRatePerSecond:
+    number;
+  summationMethod:
+    "kahan-compensated";
+  responseApplicationPerformed: true;
+  quantumEfficiencyApplied: true;
+  spectralResponsivityApplied: false;
+  channelFilterTransmissionApplied:
+    boolean;
+  photonRateCalculated: true;
+  electronRateCalculated: true;
+  photonCountCalculated: false;
+  electronCountCalculated: false;
+  currentCalculated: false;
+  temporalIntegrationApplied: false;
+  exposureDurationApplied: false;
+  saturationAssessed: false;
+  shotNoiseApplied: false;
+  readNoiseApplied: false;
+  adcQuantizationApplied: false;
+  rawCodeValueProduced: false;
+  responseUncertaintyPropagated: false;
+  photonEnergyUncertaintyPropagated: false;
+  quadratureConvergenceErrorEstimated:
+    false;
+}
+```
+
+## SensorEqeWavelengthRateContribution
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorEqeWavelengthRateContribution {
+  spectralSampleIndex: number;
+  wavelengthNanometers: number;
+  wavelengthMeasureNanometers: number;
+  geometricApertureIncidentSpectralFluxWattsPerNanometer:
+    number;
+  radiantPowerContributionWatts: number;
+  vacuumWavelengthNanometers: number;
+  photonEnergyJoules: number;
+  wavelengthConversion:
+    | "vacuum-identity"
+    | "air-to-vacuum-via-phase-refractive-index";
+  phaseRefractiveIndexUsed?: number;
+  airConditionCompatibility?:
+    | "exact-match"
+    | "assumed-compatible";
+  airRefractiveIndexEvidence?:
+    readonly EvidenceProvenance[];
+  incidentPhotonRatePerSecond: number;
+  effectiveExternalQuantumEfficiency: number;
+  responseComposition:
+    | "direct-effective-response"
+    | "channel-filter-transmittance-times-detector-eqe";
+  channelFilterTransmittance?: number;
+  detectorExternalQuantumEfficiency?: number;
+  responseInterpolationUsed: boolean;
+  expectedGeneratedElectronRatePerSecond:
+    number;
+}
+```

package/docs/api/sensor-eqe-local-exposure.md

@@ -0,0 +1,68 @@
+# sensor/eqe-local-exposure.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.
+
+## calculateSensorEqeLocalExposure
+
+Compose validated irradiance reduction, response applicability/range, EQE
+conversion and stationary local integration. The exposure value is suitable
+for accumulated-charge photoSignal; dark/completeness/capacity/readout remain
+explicit downstream inputs. Invalid or unsupported evidence fails closed.
+
+```ts
+export function calculateSensorEqeLocalExposure(
+  input: CalculateSensorEqeLocalExposureInput
+): CalculationResult<SensorEqeLocalExposure>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorEqeLocalExposureInput
+
+Explicit post-optics irradiance samples and evidence; no renderer or RGB conversion.
+
+```ts
+export interface CalculateSensorEqeLocalExposureInput {
+  /** Physical area, registered aperture/lattice, AA support and destination site. */
+  spatialSampling: Omit<CalculateSensorSpatialSamplingQuadratureInput,
+    "colorSamplingProfile" | "colorSamplingBindingProfile" | "nativeRaster">;
+  /** Explicit wavelength basis/range, channel and midpoint subdivision budget. */
+  spectralSampling: Omit<CalculateSensorSpectralQuadratureInput,
+    "colorSamplingProfile" | "spectralResponseProfile">;
+  /** One W/m²/nm value per identified pre-AA spatial/spectral node. */
+  irradianceSamples: ReduceSensorSpatioSpectralIrradianceInput["sampleValues"];
+  /** Source-plane, collection-area and reference-condition evidence. */
+  responseApplication: Omit<AssessSensorResponseApplicationCompatibilityInput, "reduction">;
+  /** Evidence-backed linear response domain; no extrapolation is authorized. */
+  operatingRangeProfile: AssessSensorResponseOperatingRangeInput["operatingRangeProfile"];
+  /** Destination CFA/channel identity shared by every composed step. */
+  colorSamplingProfile: CalculateSensorEqeElectronRateInput["colorSamplingProfile"];
+  /** Direct or separable EQE response; A/W responsivity is unsupported here. */
+  spectralResponseProfile: CalculateSensorEqeElectronRateInput["spectralResponseProfile"];
+  /** Required explicit photon-energy conversion context for air wavelengths. */
+  airPhotonEnergyContext?: CalculateSensorEqeElectronRateInput["airPhotonEnergyContext"];
+  /** Native one-to-one site binding and one opening/closing shutter event. */
+  localExposure: Omit<BindSensorRateToLocalExposureInput, "rate" | "colorSamplingProfile">;
+  /** Separate declaration authorizing a constant rate across this exact window. */
+  stationarityProfile: SensorRateTemporalStationarityProfile;
+}
+```
+
+## SensorEqeLocalExposure
+
+Child envelopes retain separate provenance, validity and unpropagated uncertainty.
+
+```ts
+export interface SensorEqeLocalExposure {
+  upstreamOrigin: "declared-spatio-spectral-irradiance-samples";
+  upstreamSceneAndOpticsVerified: false;
+  spatialQuadrature: ReturnType<typeof calculateSensorSpatialSamplingQuadrature>;
+  spectralQuadrature: ReturnType<typeof calculateSensorSpectralQuadrature>;
+  reduction: ReturnType<typeof reduceSensorSpatioSpectralIrradiance>;
+  compatibility: ReturnType<typeof assessSensorResponseApplicationCompatibility>;
+  operatingRange: ReturnType<typeof assessSensorResponseOperatingRange>;
+  electronRate: ReturnType<typeof calculateSensorEqeElectronRate>;
+  exposureBinding: ReturnType<typeof bindSensorRateToLocalExposure>;
+  exposure: CalculationResult<SensorEqeExposureIntegration>;
+}
+```

package/docs/api/sensor-eqe-temporal-exposure.md

@@ -0,0 +1,73 @@
+# sensor/eqe-temporal-exposure.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.
+
+## calculateSensorEqeTemporalExposure
+
+Evaluate response validity and EQE independently at each declared shutter
+midpoint, then sum rates times seconds. This is quadrature, not a stationarity
+claim or convergence proof. Shared profile/geometry state prevents combining
+rates from different sites or shutter events. No renderer executes here.
+
+```ts
+export function calculateSensorEqeTemporalExposure(
+  input: CalculateSensorEqeTemporalExposureInput
+): CalculationResult<SensorEqeTemporalExposure>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorEqeTemporalExposureInput
+
+Shared response/site/shutter state, with separately evaluated physical light at each time.
+
+```ts
+export interface CalculateSensorEqeTemporalExposureInput
+  extends Omit<CalculateSensorEqeLocalExposureInput, "irradianceSamples" | "stationarityProfile"> {
+  /** Complete uniform-midpoint coverage; array order is not temporal identity. */
+  samples: readonly {
+    temporalSampleIndex: number;
+    /** Seconds on the shutter's first-opening-boundary-phase reference. */
+    timeSecondsFromOpeningReference: number;
+    /** Complete W/m²/nm Cartesian irradiance coverage for this instant. */
+    irradianceSamples: CalculateSensorEqeLocalExposureInput["irradianceSamples"];
+  }[];
+}
+```
+
+## SensorEqeTemporalExposure
+
+Nonstationary photo expectation, deliberately distinct from stationary RAW producer inputs.
+
+```ts
+export interface SensorEqeTemporalExposure {
+  kind: "eqe-temporal-quadrature-expected-counts";
+  colorSamplingProfileId: string;
+  channelId: string;
+  site: { x: number; y: number };
+  bindingId: string;
+  timeReference: "first-opening-boundary-phase";
+  startOffsetSecondsFromOpeningReference: number;
+  endOffsetSecondsFromOpeningReference: number;
+  localExposureDurationSeconds: number;
+  expectedIncidentPhotonCount: number;
+  expectedGeneratedElectronCount: number;
+  integrationMethod: "uniform-midpoint-rate-quadrature";
+  timeStationarityEstablished: false;
+  timeVaryingSignalIntegrated: true;
+  temporalIntegrationApplied: true;
+  upstreamSceneAndOpticsVerified: false;
+  accumulatedSignalCompleteness: "photo-signal-only";
+  physicalFullWellAssessmentAuthorized: false;
+  shotNoiseApplied: false;
+  rawCodeValueProduced: false;
+  /** Canonical order, seconds-valued integration measures and independent child evidence. */
+  samples: readonly {
+    temporalSampleIndex: number;
+    timeSecondsFromOpeningReference: number;
+    integrationMeasureSeconds: number;
+    timeAverageWeight: number;
+    stages: ReturnType<typeof calculateSensorEqeLocalRate>;
+  }[];
+}
+```