@photivra/engine 0.6.0 → 1.0.0

package/docs/api/sensor-optical-stack.md

@@ -0,0 +1,211 @@
+# sensor/optical-stack.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.
+
+## AntiAliasingPointSplitComponent
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AntiAliasingPointSplitComponent {
+  /**
+   * Native sensor physical offset from the nominal landing point.
+   * +X right, +Y down. Units: micrometres.
+   */
+  offsetMicrometers: {
+    x: number;
+    y: number;
+  };
+  /**
+   * Dimensionless normalized spatial weight. Point-splitting kernels describe
+   * spatial redistribution only; total stack throughput is outside this field.
+   */
+  normalizedWeight: number;
+}
+```
+
+## parseSensorOpticalStackProfile
+
+Parses descriptive sensor optical-stack metadata plus an optional explicitly
+declared effective anti-aliasing spatial response.
+
+Unknown facts are omitted instead of inferred. Physical component presence
+is intentionally separate from effective anti-aliasing response so the
+schema can represent cancellation/neutralization designs without claiming
+the physical assembly is absent.
+
+Cover/filter-stack and microlens presence do not create optical effects in
+schema 0.1.0. Thickness, refractive index, spectral transmission, angular
+acceptance, focus shift and microlens collection behavior require later
+explicit models/calibration.
+
+```ts
+export function parseSensorOpticalStackProfile(
+  value: unknown
+): SensorOpticalStackProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## resolveAntiAliasingSpatialKernel
+
+Resolves only the effective anti-aliasing spatial kernel.
+
+This is not a whole optical-stack PSF. Cover/filter transmission, refraction,
+microlens behavior, field/wavelength/polarization dependence, and total
+throughput remain excluded.
+
+A documented absent effective anti-aliasing response resolves to an identity
+component at zero offset. An unknown response (field omitted) or a
+present-but-unresolved response fails closed.
+
+```ts
+export function resolveAntiAliasingSpatialKernel(
+  profileInput: SensorOpticalStackProfile
+): ResolvedAntiAliasingSpatialKernel;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvedAntiAliasingSpatialKernel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedAntiAliasingSpatialKernel {
+  profileId: string;
+  effectiveResponse:
+    | "absent"
+    | "normalized-point-splitting-kernel";
+  coordinateSystem: "native-sensor-physical";
+  components: readonly AntiAliasingPointSplitComponent[];
+  normalizedWeightSum: number;
+  throughputIncluded: false;
+  spectralTransmissionIncluded: false;
+  fieldDependenceIncluded: false;
+  wavelengthDependenceIncluded: false;
+  polarizationDependenceIncluded: false;
+  microlensResponseIncluded: false;
+  coverFilterStackEffectsIncluded: false;
+  wholeSensorOpticalStackResponse: false;
+  provenance: {
+    profile: readonly EvidenceProvenance[];
+    antiAliasingResponse: readonly EvidenceProvenance[];
+  };
+}
+```
+
+## SensorEffectiveAntiAliasingSpatialResponse
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorEffectiveAntiAliasingSpatialResponse =
+  | {
+      /**
+       * Documented absence/cancellation of intentional anti-aliasing spatial
+       * splitting. This does not mean the whole sensor stack is optically
+       * identity.
+       */
+      kind: "absent";
+      evidence: readonly EvidenceProvenance[];
+    }
+  | {
+      /**
+       * An effective anti-aliasing response is known to exist, but its spatial
+       * response is not defensibly specified.
+       */
+      kind: "present-unresolved";
+      evidence: readonly EvidenceProvenance[];
+    }
+  | {
+      /**
+       * Generic normalized point-splitting approximation in native sensor
+       * physical coordinates.
+       */
+      kind: "normalized-point-splitting-kernel";
+      evidence: readonly EvidenceProvenance[];
+      coordinateSystem: "native-sensor-physical";
+      scope:
+        "field-wavelength-polarization-invariant-approximation";
+      components: readonly AntiAliasingPointSplitComponent[];
+    };
+```
+
+## SensorMicrolensDeclaration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorMicrolensDeclaration {
+  presence: "present" | "absent";
+  evidence: readonly EvidenceProvenance[];
+  /**
+   * Presence alone does not establish an angular, spectral, fill-factor, or
+   * collection-efficiency model.
+   */
+  opticalEffectModel: "unresolved";
+}
+```
+
+## SensorOpticalStackComponent
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorOpticalStackComponent {
+  componentId: string;
+  /**
+   * Roles may be combined because one physical element can provide multiple
+   * optical/filter functions.
+   */
+  roles: readonly SensorOpticalStackComponentRole[];
+  evidence: readonly EvidenceProvenance[];
+}
+```
+
+## SensorOpticalStackComponentRole
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorOpticalStackComponentRole =
+  | "cover-glass"
+  | "infrared-cut"
+  | "ultraviolet-cut"
+  | "anti-reflection"
+  | "birefringent-low-pass"
+  | "wave-plate"
+  | "other-optical-filter";
+```
+
+## SensorOpticalStackProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorOpticalStackProfile {
+  schemaVersion: "0.1.0";
+  profileId: string;
+  evidence: readonly EvidenceProvenance[];
+  /**
+   * Ordered from incident-light side toward the sensor.
+   *
+   * These components are descriptive metadata only. Their presence does not
+   * create transmission, focus-shift, aberration, or spectral effects.
+   */
+  orderedComponents?: readonly SensorOpticalStackComponent[];
+  /**
+   * Omitted means unknown/unasserted.
+   *
+   * This is intentionally separate from physical component presence so a
+   * stack can contain low-pass-related hardware while its net effective
+   * anti-aliasing response is absent/cancelled.
+   */
+  effectiveAntiAliasingSpatialResponse?: SensorEffectiveAntiAliasingSpatialResponse;
+  /**
+   * Omitted means unknown/unasserted.
+   */
+  microlens?: SensorMicrolensDeclaration;
+}
+```

package/docs/api/sensor-photon-energy.md

@@ -0,0 +1,149 @@
+# sensor/photon-energy.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.
+
+## AirRefractiveIndexConditionPolicy
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type AirRefractiveIndexConditionPolicy =
+  | {
+      kind: "exact-match-required";
+    }
+  | {
+      kind: "assume-compatible";
+      limitation: string;
+      evidence: readonly EvidenceProvenance[];
+    };
+```
+
+## AirRefractiveIndexReferenceConditions
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AirRefractiveIndexReferenceConditions {
+  temperatureC: number;
+  pressurePascal: number;
+  relativeHumidityFraction?: number;
+  carbonDioxideMoleFraction?: number;
+}
+```
+
+## calculatePhotonEnergyFromWavelength
+
+Convert a valid vacuum wavelength, or explicitly atmosphere-bound air wavelength, into optical
+frequency and photon energy using exact SI constants.
+
+Photon energy uses exact SI h and c with vacuum wavelength. Air wavelength requires an
+exact-wavelength sourced phase index and atmosphere compatibility; lambdaVacuum = n*lambdaAir.
+Retained refractive-index uncertainty is not an automatically propagated photon-energy uncertainty.
+
+```ts
+export function calculatePhotonEnergyFromWavelength(
+  input:
+    CalculatePhotonEnergyFromWavelengthInput
+): CalculationResult<PhotonEnergyFromWavelength>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculatePhotonEnergyFromWavelengthInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculatePhotonEnergyFromWavelengthInput {
+  wavelengthNanometers: number;
+  wavelengthBasis:
+    SpectralWavelengthBasis;
+  airPhaseRefractiveIndex?:
+    SourcedAirPhaseRefractiveIndex;
+  airOperatingConditions?:
+    AirRefractiveIndexReferenceConditions;
+  airConditionPolicy?:
+    AirRefractiveIndexConditionPolicy;
+}
+```
+
+## parseSourcedAirPhaseRefractiveIndex
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Photon energy uses exact SI h and c with vacuum wavelength. Air wavelength requires an
+exact-wavelength sourced phase index and atmosphere compatibility; lambdaVacuum = n*lambdaAir.
+Retained refractive-index uncertainty is not an automatically propagated photon-energy uncertainty.
+
+```ts
+export function parseSourcedAirPhaseRefractiveIndex(
+  value: unknown
+): SourcedAirPhaseRefractiveIndex;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PhotonEnergyFromWavelength
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PhotonEnergyFromWavelength {
+  inputWavelengthNanometers: number;
+  inputWavelengthBasis:
+    Exclude<SpectralWavelengthBasis, "unspecified">;
+  vacuumWavelengthNanometers: number;
+  frequencyHertz: number;
+  photonEnergyJoules: number;
+  wavelengthConversion:
+    | "vacuum-identity"
+    | "air-to-vacuum-via-phase-refractive-index";
+  exactSiConstants: {
+    planckConstantJouleSeconds:
+      6.62607015e-34;
+    speedOfLightMetersPerSecond:
+      299792458;
+  };
+  phaseRefractiveIndexUsed?: number;
+  airRefractiveIndexScientificStatus?:
+    SensorSpectralResponseScientificStatus;
+  airRefractiveIndexUncertainty?:
+    SensorSpectralResponseUncertainty;
+  airRefractiveIndexReferenceConditions?:
+    AirRefractiveIndexReferenceConditions;
+  airRefractiveIndexEvidence?:
+    readonly EvidenceProvenance[];
+  airOperatingConditions?:
+    AirRefractiveIndexReferenceConditions;
+  airConditionPolicy?:
+    AirRefractiveIndexConditionPolicy;
+  airConditionCompatibility?:
+    | "exact-match"
+    | "assumed-compatible";
+  airConditionAssumptionEvidence?:
+    readonly EvidenceProvenance[];
+  inputUncertaintyPropagated: false;
+}
+```
+
+## SourcedAirPhaseRefractiveIndex
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SourcedAirPhaseRefractiveIndex {
+  wavelengthNanometers: number;
+  wavelengthBasis: "air";
+  definition:
+    "vacuum-wavelength-divided-by-air-wavelength";
+  phaseRefractiveIndex: number;
+  scientificStatus:
+    SensorSpectralResponseScientificStatus;
+  uncertainty:
+    SensorSpectralResponseUncertainty;
+  evidence: readonly EvidenceProvenance[];
+  referenceConditions?:
+    AirRefractiveIndexReferenceConditions;
+}
+```

package/docs/api/sensor-physical-charge-capacity.md

@@ -0,0 +1,196 @@
+# sensor/physical-charge-capacity.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.
+
+## assessSensorPhysicalChargeCapacity
+
+Compare complete expected stored electrons to the explicitly applicable physical capacity and report
+expectation-domain headroom without nonlinear storage simulation.
+
+Physical storage capacity is a source-specific total stored-electron limit tied to site, operating
+state and temperature. The assessment compares complete expected charge; it does not clamp
+realizations or infer overflow/blooming. Camera saturation and ADC/readout thresholds remain
+distinct.
+
+```ts
+export function assessSensorPhysicalChargeCapacity(
+  input:
+    AssessSensorPhysicalChargeCapacityInput
+): CalculationResult<SensorPhysicalChargeCapacityAssessment>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## AssessSensorPhysicalChargeCapacityInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AssessSensorPhysicalChargeCapacityInput {
+  accumulatedCharge:
+    SensorAccumulatedChargeComposition;
+  capacityProfile:
+    SensorPhysicalChargeCapacityProfile;
+  operatingStateId: string;
+  operatingTemperatureC: number;
+}
+```
+
+## parseSensorPhysicalChargeCapacityProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Physical storage capacity is a source-specific total stored-electron limit tied to site, operating
+state and temperature. The assessment compares complete expected charge; it does not clamp
+realizations or infer overflow/blooming. Camera saturation and ADC/readout thresholds remain
+distinct.
+
+```ts
+export function parseSensorPhysicalChargeCapacityProfile(
+  value: unknown
+): SensorPhysicalChargeCapacityProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SensorPhysicalChargeCapacityAssessment
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorPhysicalChargeCapacityAssessment {
+  capacityProfileId: string;
+  completenessProfileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  site: {
+    x: number;
+    y: number;
+  };
+  bindingId: string;
+  operatingStateId: string;
+  operatingTemperatureC: number;
+  capacityMeaning:
+    "physical-charge-storage-capacity-electrons";
+  physicalChargeCapacityElectrons:
+    number;
+  totalExpectedStoredElectronCount:
+    number;
+  expectedChargeToCapacityRatio:
+    number;
+  expectedChargeHeadroomElectrons:
+    number;
+  expectedChargeCapacityStatus:
+    | "below-capacity"
+    | "at-capacity"
+    | "above-capacity";
+  expectedChargeExceedsCapacity:
+    boolean;
+  physicalChargeCapacityAssessmentPerformed:
+    true;
+  assessmentMeaning:
+    "expected-charge-vs-physical-storage-capacity";
+  actualStochasticSaturationStateKnown:
+    false;
+  stochasticSaturationProbabilityAssessed:
+    false;
+  storedChargeAfterPhysicalSaturationCalculated:
+    false;
+  overflowChargeCalculated: false;
+  bloomingModeled: false;
+  clampApplied: false;
+  cameraSaturationAssessmentAuthorized:
+    false;
+  adcQuantizationApplied: false;
+  rawCodeValueProduced: false;
+  capacityUncertaintyPropagated:
+    false;
+  accumulatedChargeUncertaintyPropagated:
+    false;
+  componentEvidence: {
+    capacity:
+      readonly EvidenceProvenance[];
+    operatingState:
+      readonly EvidenceProvenance[];
+    siteApproximation:
+      readonly EvidenceProvenance[];
+    temperatureApproximation:
+      readonly EvidenceProvenance[];
+    chargeCompleteness:
+      SensorAccumulatedChargeComposition["componentEvidence"]["completeness"];
+  };
+}
+```
+
+## SensorPhysicalChargeCapacityProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorPhysicalChargeCapacityProfile {
+  schemaVersion: "0.1.0";
+  profileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  capacityMeaning:
+    "physical-charge-storage-capacity-electrons";
+  capacityElectrons: number;
+  scientificStatus:
+    SensorSpectralResponseScientificStatus;
+  uncertainty:
+    SensorSpectralResponseUncertainty;
+  evidence:
+    readonly EvidenceProvenance[];
+  siteApplicability:
+    SensorPhysicalChargeCapacitySiteApplicability;
+  operatingState: {
+    stateId: string;
+    evidence:
+      readonly EvidenceProvenance[];
+  };
+  temperatureApplicability:
+    SensorPhysicalChargeCapacityTemperatureApplicability;
+}
+```
+
+## SensorPhysicalChargeCapacitySiteApplicability
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorPhysicalChargeCapacitySiteApplicability =
+  | {
+      kind: "exact-site";
+      site: {
+        x: number;
+        y: number;
+      };
+    }
+  | {
+      kind:
+        "uniform-site-capacity-approximation";
+      limitation: string;
+      evidence:
+        readonly EvidenceProvenance[];
+    };
+```
+
+## SensorPhysicalChargeCapacityTemperatureApplicability
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorPhysicalChargeCapacityTemperatureApplicability =
+  | {
+      kind:
+        "exact-reference-temperature";
+      temperatureC: number;
+    }
+  | {
+      kind: "not-modeled";
+      limitation: string;
+      evidence:
+        readonly EvidenceProvenance[];
+    };
+```

package/docs/api/sensor-pixel-pitch.md

@@ -0,0 +1,41 @@
+# sensor/pixel-pitch.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.
+
+## calculatePixelPitch
+
+Calculates horizontal pixel pitch from active sensor width and pixel count.
+
+```ts
+export function calculatePixelPitch(
+  input: CalculatePixelPitchInput
+): CalculationResult<PixelPitch>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculatePixelPitchInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculatePixelPitchInput {
+  /** Physical sensor width in millimetres. */
+  sensorWidthMm: number;
+  /** Horizontal active pixel count. */
+  pixelWidth: number;
+}
+```
+
+## PixelPitch
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PixelPitch {
+  /** Horizontal pixel pitch in micrometres. */
+  micrometers: number;
+  /** Horizontal pixel pitch in millimetres. */
+  millimeters: number;
+}
+```