@photivra/engine 0.6.0 → 1.0.1

package/docs/api/sensor-capture-mode.md

@@ -0,0 +1,321 @@
+# sensor/capture-mode.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## CaptureModeAcquisition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type CaptureModeAcquisition =
+  | SingleFrameCaptureAcquisition
+  | FixedMultiFrameCaptureAcquisition
+  | VariableMultiFrameCaptureAcquisition;
+```
+
+## CaptureModeDefinition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureModeDefinition {
+  modeId: string;
+  /**
+   * Evidence supporting the existence/overall acquisition behavior of this
+   * mode. Field-level facts below retain their own evidence when needed.
+   */
+  evidence: readonly EvidenceProvenance[];
+  acquisition: CaptureModeAcquisition;
+  perFrameSampling: CaptureModePerFrameSampling;
+  /**
+   * Optional ordered sensor-displacement sequence for fixed multi-frame modes.
+   * The whole sequence is one evidence-backed fact because published mode
+   * documentation commonly describes the sequence as a unit.
+   */
+  interFrameSensorOffsetsNativeSamples?: SourcedCaptureModeFact<
+    readonly CaptureModeSensorOffsetNativeSamples[]
+  >;
+  /**
+   * Ordered reconstruction/combination stages owned by later reconstruction
+   * work. These labels reserve semantics; they do not implement algorithms.
+   */
+  reconstructionStages?: readonly SourcedCaptureModeFact<CaptureModeReconstructionStage>[];
+  /**
+   * Image raster produced by the capture-mode/reconstruction pipeline before
+   * final output crop/resampling.
+   *
+   * This raster does not redefine physical sensor geometry or field of view.
+   */
+  processedImageRaster: SourcedCaptureModeFact<RasterDimensions>;
+  /**
+   * Explicit downstream scientific/model dependencies for this mode.
+   */
+  dependencies?: readonly CaptureModeDependency[];
+}
+```
+
+## CaptureModeDependency
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type CaptureModeDependency =
+  | "color-sampling-model"
+  | "mode-specific-readout-timing"
+  | "radiometric-calibration"
+  | "inter-frame-registration";
+```
+
+## CaptureModePerFrameSampling
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type CaptureModePerFrameSampling =
+  | NativeEffectiveCaptureSampling
+  | GroupedNativeCaptureSampling
+  | DeclaredEffectiveCaptureSampling;
+```
+
+## CaptureModeProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureModeProfile {
+  schemaVersion: "0.1.0";
+  modes: readonly CaptureModeDefinition[];
+}
+```
+
+## CaptureModeReconstructionStage
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type CaptureModeReconstructionStage =
+  | "remosaic"
+  | "pixel-shift-combination"
+  | "multi-frame-computational-combination";
+```
+
+## CaptureModeSampleCombinationDomain
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type CaptureModeSampleCombinationDomain =
+  | "charge-domain"
+  | "pre-conversion-analog"
+  | "post-conversion-digital";
+```
+
+## CaptureModeSensorOffsetNativeSamples
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureModeSensorOffsetNativeSamples {
+  /**
+   * Horizontal sensor displacement in units of the native effective sampling
+   * pitch. This is not a claim about physical photodiode pitch.
+   */
+  x: number;
+  /**
+   * Vertical sensor displacement in units of the native effective sampling
+   * pitch. This is not a claim about physical photodiode pitch.
+   */
+  y: number;
+}
+```
+
+## DeclaredEffectiveCaptureSampling
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DeclaredEffectiveCaptureSampling {
+  kind: "declared-effective-raster";
+  /**
+   * Per-frame effective sampling raster for a mode whose sampling relationship
+   * to the native grid is not safely expressible as simple integer grouping.
+   */
+  raster: SourcedCaptureModeFact<RasterDimensions>;
+}
+```
+
+## FixedMultiFrameCaptureAcquisition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FixedMultiFrameCaptureAcquisition {
+  kind: "fixed-multi-frame";
+  frameCount: SourcedCaptureModeFact<number>;
+}
+```
+
+## GroupedNativeCaptureSampling
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GroupedNativeCaptureSampling {
+  kind: "grouped-native-samples";
+  groupWidthSamples: SourcedCaptureModeFact<number>;
+  groupHeightSamples: SourcedCaptureModeFact<number>;
+  /**
+   * Omitted means unknown/unasserted. Do not infer where combination occurs
+   * from the word "binning" or from the raster ratio.
+   */
+  combinationDomain?: SourcedCaptureModeFact<CaptureModeSampleCombinationDomain>;
+}
+```
+
+## NativeEffectiveCaptureSampling
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeEffectiveCaptureSampling {
+  kind: "native-effective-raster";
+}
+```
+
+## parseCaptureModeProfile
+
+Parses a capture-mode profile without inferring sensor physics from output
+resolution or marketing mode names.
+
+The profile is intentionally orthogonal: acquisition frame sequence,
+per-frame sampling, optional inter-frame sensor shift, reconstruction stages,
+processed raster and downstream dependencies are independent axes.
+
+```ts
+export function parseCaptureModeProfile(
+  value: unknown
+): CaptureModeProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## resolveCaptureMode
+
+Resolves one capture mode against the selected sensor's native effective
+image-sampling raster.
+
+Resolution changes do not mutate physical sensor geometry. The returned
+processed raster is pre-output geometry and must not be used to infer crop
+factor, field of view or physical photosite count.
+
+```ts
+export function resolveCaptureMode(
+  input: ResolveCaptureModeInput
+): ResolvedCaptureMode;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveCaptureModeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveCaptureModeInput {
+  nativeRaster: NativeImageRaster;
+  profile: CaptureModeProfile;
+  modeId: string;
+}
+```
+
+## ResolvedCaptureMode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedCaptureMode {
+  modeId: string;
+  modeEvidence: readonly EvidenceProvenance[];
+  nativeRaster: NativeImageRaster;
+  nativeRasterSemantic:
+    "effective-image-sampling-grid-not-photosite-count";
+  acquisition:
+    | {
+        kind: "single-frame";
+        frameCount: 1;
+      }
+    | {
+        kind: "fixed-multi-frame";
+        frameCount: SourcedCaptureModeFact<number>;
+      }
+    | {
+        kind: "variable-multi-frame";
+        evidence: readonly EvidenceProvenance[];
+        minimumFrameCount?: SourcedCaptureModeFact<number>;
+        maximumFrameCount?: SourcedCaptureModeFact<number>;
+      };
+  perFrameSampling:
+    | {
+        kind: "native-effective-raster";
+        raster: NativeImageRaster;
+      }
+    | {
+        kind: "grouped-native-samples";
+        raster: RasterDimensions;
+        groupWidthSamples: SourcedCaptureModeFact<number>;
+        groupHeightSamples: SourcedCaptureModeFact<number>;
+        combinationDomain?: SourcedCaptureModeFact<CaptureModeSampleCombinationDomain>;
+      }
+    | {
+        kind: "declared-effective-raster";
+        raster: SourcedCaptureModeFact<RasterDimensions>;
+      };
+  interFrameSensorOffsetsNativeSamples?: SourcedCaptureModeFact<
+    readonly CaptureModeSensorOffsetNativeSamples[]
+  >;
+  reconstructionStages: readonly SourcedCaptureModeFact<CaptureModeReconstructionStage>[];
+  processedImageRaster: SourcedCaptureModeFact<RasterDimensions>;
+  processedImageMegapixels: number;
+  dependencies: readonly CaptureModeDependency[];
+  physicalSensorGeometryMutation: false;
+  photositeCountInference:
+    "not-permitted-from-native-or-processed-raster";
+  finalOutputRasterOwnership:
+    "downstream-capture-output-geometry";
+}
+```
+
+## SingleFrameCaptureAcquisition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SingleFrameCaptureAcquisition {
+  kind: "single-frame";
+}
+```
+
+## SourcedCaptureModeFact
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SourcedCaptureModeFact<T> = EvidenceBackedFact<T>;
+```
+
+## VariableMultiFrameCaptureAcquisition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface VariableMultiFrameCaptureAcquisition {
+  kind: "variable-multi-frame";
+  /**
+   * Evidence that the mode is variable/multi-frame, even when exact count
+   * bounds are not published.
+   */
+  evidence: readonly EvidenceProvenance[];
+  minimumFrameCount?: SourcedCaptureModeFact<number>;
+  maximumFrameCount?: SourcedCaptureModeFact<number>;
+}
+```

package/docs/api/sensor-color-sampling.md

@@ -0,0 +1,228 @@
+# sensor/color-sampling.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## LayeredColorSamplingLayout
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LayeredColorSamplingLayout {
+  kind: "layered";
+  /**
+   * Semantic layer/channel identifiers only. They do not define spectral
+   * response, depth ordering, spatial sampling density, or registration.
+   */
+  layerChannelIds: readonly string[];
+  /**
+   * The first layered representation is deliberately structural only because
+   * real layered sensors may use unequal per-layer spatial sampling.
+   */
+  spatialSamplingRelationship: "not-resolved";
+}
+```
+
+## MonochromeColorSamplingLayout
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface MonochromeColorSamplingLayout {
+  kind: "monochrome";
+  /**
+   * Semantic measurement-channel identifier only. It is not a spectral
+   * response curve, wavelength, colorimetric primary, or calibration.
+   */
+  channelId: string;
+}
+```
+
+## NativeColorSamplingSiteCoordinateSystem
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type NativeColorSamplingSiteCoordinateSystem =
+  "native-sensor-color-sampling-site-index";
+```
+
+## NativeColorSamplingSiteIndex
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeColorSamplingSiteIndex {
+  /**
+   * Zero-based integer site index from the native sensor's left edge.
+   *
+   * This is an abstract color-sampling-site lattice index. It is not a
+   * NativeImageRaster coordinate and does not assert one site = one physical
+   * photodiode.
+   */
+  x: number;
+  /**
+   * Zero-based integer site index from the native sensor's top edge.
+   *
+   * +Y points downward in native sensor-facing coordinates.
+   */
+  y: number;
+}
+```
+
+## parseSensorColorSamplingProfile
+
+Parses an exact color-sampling topology declaration without binding it to
+NativeImageRaster, physical photodiodes, spectral response, or a
+manufacturer-specific family enum.
+
+Periodic mosaics use an abstract native sensor color-sampling-site lattice
+with zero-based integer indices, top-left origin, +X right and +Y down.
+The repeat phase is anchored to the sensor lattice, so later active crops or
+orientation transforms must preserve the original native site indices.
+
+Layered layouts are structural-only in this first contract because real
+layered sensors may use unequal spatial sampling density/registration across
+layers. No per-site layered resolver is exposed until that relationship is
+modeled explicitly.
+
+```ts
+export function parseSensorColorSamplingProfile(
+  value: unknown
+): SensorColorSamplingProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PeriodicMosaicColorSamplingLayout
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PeriodicMosaicColorSamplingLayout {
+  kind: "periodic-mosaic";
+  /**
+   * Number of color-sampling sites in one horizontal repeat period.
+   */
+  repeatWidthSites: number;
+  /**
+   * Number of color-sampling sites in one vertical repeat period.
+   */
+  repeatHeightSites: number;
+  /**
+   * Row-major semantic channel IDs for one repeating tile.
+   *
+   * Length must equal repeatWidthSites × repeatHeightSites.
+   */
+  siteChannelIds: readonly string[];
+  /**
+   * The repeat tile is anchored at native sensor sampling-site index (0, 0).
+   *
+   * Active crops and physical orientation must not silently reset this phase.
+   */
+  anchor: "native-sensor-top-left-site";
+}
+```
+
+## resolveColorSamplingSite
+
+Resolves the semantic measurement-channel assignment at one abstract native
+sensor color-sampling-site index for monochrome or periodic-mosaic layouts.
+
+This API intentionally has no NativeImageRaster input. A later explicit
+binding must establish how a selected capture mode's effective raster maps
+to this color-sampling-site lattice before RAW/CFA sampling can be simulated.
+
+Layered layouts fail closed because their per-layer spatial relationship is
+not resolved by the first structural contract.
+
+```ts
+export function resolveColorSamplingSite(
+  input: ResolveColorSamplingSiteInput
+): ResolvedColorSamplingSite;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveColorSamplingSiteInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveColorSamplingSiteInput {
+  profile: SensorColorSamplingProfile;
+  site: NativeColorSamplingSiteIndex;
+}
+```
+
+## ResolvedColorSamplingSite
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedColorSamplingSite {
+  profileId: string;
+  coordinateSystem: NativeColorSamplingSiteCoordinateSystem;
+  site: NativeColorSamplingSiteIndex;
+  mapping:
+    | {
+        kind: "monochrome";
+        channelId: string;
+      }
+    | {
+        kind: "periodic-mosaic";
+        channelId: string;
+        repeatCoordinate: {
+          x: number;
+          y: number;
+        };
+        repeatWidthSites: number;
+        repeatHeightSites: number;
+      };
+  /**
+   * Explicit scientific boundaries for downstream consumers.
+   */
+  spectralResponseEstablished: false;
+  nativeImageRasterBindingEstablished: false;
+  physicalPhotodiodeBindingEstablished: false;
+}
+```
+
+## SensorColorSamplingLayout
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorColorSamplingLayout =
+  | MonochromeColorSamplingLayout
+  | PeriodicMosaicColorSamplingLayout
+  | LayeredColorSamplingLayout;
+```
+
+## SensorColorSamplingProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorColorSamplingProfile {
+  schemaVersion: "0.1.0";
+  profileId: string;
+  /**
+   * Evidence supporting this exact topology declaration.
+   *
+   * Descriptive architecture-family metadata remains a separate contract.
+   */
+  evidence: readonly EvidenceProvenance[];
+  coordinateSystem: SensorColorSamplingProfileCoordinateSystem;
+  layout: SensorColorSamplingLayout;
+}
+```
+
+## SensorColorSamplingProfileCoordinateSystem
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorColorSamplingProfileCoordinateSystem =
+  | NativeColorSamplingSiteCoordinateSystem
+  | "native-sensor-layered-spatial-relationship-not-resolved";
+```

package/docs/api/sensor-constant-rate-temporal-integration.md

@@ -0,0 +1,152 @@
+# sensor/constant-rate-temporal-integration.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## IntegrateStationarySensorRateInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IntegrateStationarySensorRateInput {
+  rate:
+    SensorInstantaneousRateResult;
+  exposureBinding:
+    SensorRateLocalExposureBinding;
+  stationarityProfile:
+    SensorRateTemporalStationarityProfile;
+}
+```
+
+## integrateStationarySensorRateOverLocalExposure
+
+Integrates one explicitly stationary response-rate result over its exact
+bound local exposure window.
+
+This function is intentionally limited to the constant-rate approximation.
+It does not sample or integrate a time-varying signal.
+
+```ts
+export function integrateStationarySensorRateOverLocalExposure(
+  input:
+    IntegrateStationarySensorRateInput
+): CalculationResult<SensorStationaryRateExposureIntegration>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSensorRateTemporalStationarityProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Rate times duration is allowed only by explicit stationarity bound to the exact site and local
+shutter interval. EQE integrates to expected photons/electrons; A/W integrates current magnitude to
+coulombs without an implicit carrier mapping. Counts remain fractional expectations before
+stochastic sampling.
+
+```ts
+export function parseSensorRateTemporalStationarityProfile(
+  value: unknown
+): SensorRateTemporalStationarityProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SensorEqeExposureIntegration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorEqeExposureIntegration
+  extends SensorTemporalIntegrationCommon {
+  kind: "eqe-expected-counts";
+  incidentPhotonRatePerSecond: number;
+  expectedGeneratedElectronRatePerSecond:
+    number;
+  expectedIncidentPhotonCount: number;
+  expectedGeneratedElectronCount:
+    number;
+  countsAreExpectationValues: true;
+  integerPhotonCountSampled: false;
+  integerElectronCountSampled: false;
+  chargeCalculated: false;
+  currentCalculated: false;
+}
+```
+
+## SensorRateStationarityStatus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorRateStationarityStatus =
+  | "established"
+  | "approximation";
+```
+
+## SensorRateTemporalStationarityProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorRateTemporalStationarityProfile {
+  schemaVersion: "0.1.0";
+  profileId: string;
+  rateDomain:
+    SensorRateLocalExposureBinding["rateDomain"];
+  colorSamplingProfileId: string;
+  channelId: string;
+  site: {
+    x: number;
+    y: number;
+  };
+  bindingId: string;
+  localExposureWindow: {
+    timeReference:
+      "first-opening-boundary-phase";
+    startOffsetSecondsFromOpeningReference:
+      number;
+    endOffsetSecondsFromOpeningReference:
+      number;
+  };
+  stationarityMeaning:
+    "reported-rate-constant-through-bound-local-exposure";
+  status:
+    SensorRateStationarityStatus;
+  evidence: readonly EvidenceProvenance[];
+  limitation?: string;
+}
+```
+
+## SensorResponsivityExposureIntegration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorResponsivityExposureIntegration
+  extends SensorTemporalIntegrationCommon {
+  kind:
+    "responsivity-photocurrent-charge";
+  photocurrentMagnitudeAmperes: number;
+  photochargeMagnitudeCoulombs:
+    number;
+  currentSignConvention:
+    "magnitude-only-no-circuit-polarity";
+  chargeSignConvention:
+    "magnitude-only-no-carrier-or-circuit-polarity";
+  carrierCountInferred: false;
+  electronCountCalculated: false;
+  photonCountCalculated: false;
+  detectorBandwidthModeled: false;
+}
+```
+
+## SensorStationaryRateExposureIntegration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorStationaryRateExposureIntegration =
+  | SensorEqeExposureIntegration
+  | SensorResponsivityExposureIntegration;
+```