@photivra/engine 0.5.1 → 1.0.0

package/docs/api/sensor-exposure-window.md

@@ -0,0 +1,183 @@
+# sensor/exposure-window.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.
+
+## calculateCaptureExposureWindows
+
+Resolves local capture exposure windows from independent opening and closing
+boundary schedules.
+
+The returned time basis is seconds from the first opening-boundary phase.
+This is intentionally not the existing camera-rotation API's global
+"exposure start" semantic; a later integration layer must bind those time
+bases explicitly.
+
+The mechanism identifies whether each boundary is mechanical or electronic,
+but does not supply any traversal duration or direction. Every non-simultaneous
+timing value and direction is caller-declared with evidence.
+
+The first model supports simultaneous boundaries and uniform-linear
+single-axis native-sensor scans only. It does not model curtain acceleration,
+segmented/nonlinear electronic schedules, flash/flicker, rolling-shutter
+image distortion, shutter shock, or EFCS-specific pupil/bokeh behavior.
+
+```ts
+export function calculateCaptureExposureWindows(
+  input: CalculateCaptureExposureWindowsInput
+): CalculationResult<CaptureExposureWindows>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateCaptureExposureWindowsInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateCaptureExposureWindowsInput {
+  nativeRaster: NativeImageRaster;
+  /**
+   * Active capture rectangle in invariant native-raster coordinates.
+   *
+   * Defaults to the complete native raster. Boundary traversal timing is never
+   * inferred by scaling a full-frame timing value to this rectangle.
+   */
+  activeCaptureRect?: RasterRect;
+  shutterMechanism: CaptureShutterMechanism;
+  /**
+   * Nominal interval between the zero-phase opening and closing references.
+   *
+   * Local exposure duration may differ from this value when opening and closing
+   * boundary schedules have different spatial phase behavior.
+   */
+  nominalExposureDurationSeconds: SourcedCaptureTimingSeconds;
+  opening: ExposureBoundarySchedule;
+  closing: ExposureBoundarySchedule;
+  /**
+   * Optional continuous native raster edge-coordinate points for diagnostics.
+   * Pixel centers may be represented with +0.5 offsets.
+   */
+  samplePointsNative?: readonly RasterPoint[];
+}
+```
+
+## CaptureExposureBoundaryActuator
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type CaptureExposureBoundaryActuator = "mechanical" | "electronic";
+```
+
+## CaptureExposureWindows
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureExposureWindows {
+  shutterMechanism: CaptureShutterMechanism;
+  timeReference: "first-opening-boundary-phase";
+  nativeRaster: NativeImageRaster;
+  activeCaptureRect: RasterRect;
+  nominalExposureDurationSeconds: SourcedCaptureTimingSeconds;
+  opening: ResolvedCaptureExposureBoundary;
+  closing: ResolvedCaptureExposureBoundary;
+  localExposureDurationRangeSeconds: {
+    minimum: number;
+    maximum: number;
+  };
+  samples: readonly CaptureExposureWindowSample[];
+}
+```
+
+## CaptureExposureWindowSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureExposureWindowSample {
+  pointNative: RasterPoint;
+  openingNormalizedScanPosition: number | null;
+  closingNormalizedScanPosition: number | null;
+  /**
+   * Seconds from the first opening-boundary phase.
+   */
+  startOffsetSecondsFromOpeningReference: number;
+  /**
+   * Seconds from the first opening-boundary phase.
+   */
+  endOffsetSecondsFromOpeningReference: number;
+  localExposureDurationSeconds: number;
+}
+```
+
+## ExposureBoundarySchedule
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ExposureBoundarySchedule =
+  | SimultaneousExposureBoundarySchedule
+  | UniformLinearExposureBoundarySchedule;
+```
+
+## ResolvedCaptureExposureBoundary
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedCaptureExposureBoundary {
+  actuator: CaptureExposureBoundaryActuator;
+  schedule:
+    | {
+        kind: "simultaneous";
+      }
+    | {
+        kind: "uniform-linear-native-scan";
+        directionNative: SourcedCaptureBoundaryDirection;
+        unitVectorNative: RasterVector;
+        traversalDurationSeconds: SourcedCaptureTimingSeconds;
+      };
+}
+```
+
+## SimultaneousExposureBoundarySchedule
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SimultaneousExposureBoundarySchedule {
+  kind: "simultaneous";
+  directionNative?: never;
+  traversalDurationSeconds?: never;
+}
+```
+
+## SourcedCaptureBoundaryDirection
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SourcedCaptureBoundaryDirection =
+  EvidenceBackedFact<NativeSensorReadoutScanDirection>;
+```
+
+## SourcedCaptureTimingSeconds
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SourcedCaptureTimingSeconds = SourcedSensorTimingSeconds;
+```
+
+## UniformLinearExposureBoundarySchedule
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface UniformLinearExposureBoundarySchedule {
+  kind: "uniform-linear-native-scan";
+  directionNative: SourcedCaptureBoundaryDirection;
+  traversalDurationSeconds: SourcedCaptureTimingSeconds;
+}
+```

package/docs/api/sensor-iso-signal-chain.md

@@ -0,0 +1,264 @@
+# sensor/iso-signal-chain.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.
+
+## GENERIC_ISO_SIGNAL_CHAIN_PRESET_CATALOG_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+GENERIC_ISO_SIGNAL_CHAIN_PRESET_CATALOG_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## GENERIC_ISO_SIGNAL_CHAIN_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+GENERIC_ISO_SIGNAL_CHAIN_PROFILE_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## GenericIsoCaptureModeSignalChainBinding
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericIsoCaptureModeSignalChainBinding {
+  captureModeId: string;
+  standardRegimeBands:
+    readonly GenericIsoStandardRegimeBand[];
+  expandedRegimeBindings:
+    readonly GenericIsoExpandedRegimeBinding[];
+  evidence:
+    readonly EvidenceProvenance[];
+}
+```
+
+## GenericIsoExpandedRegimeBinding
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericIsoExpandedRegimeBinding {
+  expandedSettingId: string;
+  readoutRegimeId: string;
+}
+```
+
+## GenericIsoSignalChainPreset
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type GenericIsoSignalChainPreset =
+  | "good"
+  | "better"
+  | "best";
+```
+
+## GenericIsoSignalChainPresetCatalog
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericIsoSignalChainPresetCatalog {
+  schemaVersion:
+    typeof GENERIC_ISO_SIGNAL_CHAIN_PRESET_CATALOG_SCHEMA_VERSION;
+  catalogId: string;
+  catalogVersion: string;
+  entries: readonly {
+    preset:
+      GenericIsoSignalChainPreset;
+    signalChainProfileId:
+      string;
+    evidence:
+      readonly EvidenceProvenance[];
+  }[];
+  performanceOrderingClaimed:
+    false;
+  realCameraRankingClaimed:
+    false;
+}
+```
+
+## GenericIsoSignalChainProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericIsoSignalChainProfile {
+  schemaVersion:
+    typeof GENERIC_ISO_SIGNAL_CHAIN_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  scientificStatus: "approximation";
+  isoCapabilityProfileId: string;
+  readoutProfileId: string;
+  behaviorMeaning:
+    "iso-state-selects-explicit-readout-regime-not-noise-equation";
+  captureModeBindings:
+    readonly GenericIsoCaptureModeSignalChainBinding[];
+  photonShotNoiseOwnedUpstream:
+    true;
+  processedImageBehaviorIncluded:
+    false;
+  fixedPatternNoiseModeled:
+    false;
+  lowSignalColorDegradationModeled:
+    false;
+  evidence:
+    readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## GenericIsoStandardRegimeBand
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericIsoStandardRegimeBand {
+  minimumExposureIndex: number;
+  maximumExposureIndex: number;
+  readoutRegimeId: string;
+}
+```
+
+## parseGenericIsoSignalChainPresetCatalog
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+The selected ISO/capture-mode state binds an explicit generic readout regime. Photons and photo/dark
+shot-noise expectations remain upstream; regime gain, read noise and clipping are separately
+declared. Generic tier labels do not calibrate or rank commercial equipment.
+
+```ts
+export function parseGenericIsoSignalChainPresetCatalog(
+  value: unknown
+): GenericIsoSignalChainPresetCatalog;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseGenericIsoSignalChainProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+The selected ISO/capture-mode state binds an explicit generic readout regime. Photons and photo/dark
+shot-noise expectations remain upstream; regime gain, read noise and clipping are separately
+declared. Generic tier labels do not calibrate or rank commercial equipment.
+
+```ts
+export function parseGenericIsoSignalChainProfile(
+  value: unknown
+): GenericIsoSignalChainProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvedGenericIsoSignalChain
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedGenericIsoSignalChain {
+  profileId: string;
+  profileVersion: string;
+  scientificStatus:
+    "approximation";
+  captureModeId: string;
+  iso:
+    ResolvedIsoCapability;
+  readout:
+    ResolvedSensorReadoutRegime;
+  regimeSelectionReason:
+    | "standard-exposure-index-band"
+    | "expanded-setting-binding";
+  capturedPhotonExpectationModified:
+    false;
+  photonShotNoiseStatisticsModified:
+    false;
+  sensorGeometryModified: false;
+  processedImageBehaviorApplied:
+    false;
+  fixedPatternNoiseApplied:
+    false;
+  lowSignalColorDegradationApplied:
+    false;
+  isoUsedAsDirectNoiseEquation:
+    false;
+  exactCommercialCameraBehaviorClaimed:
+    false;
+}
+```
+
+## resolveGenericIsoSignalChain
+
+Select the explicit readout regime bound to the resolved ISO and capture-mode state; do not derive
+gain/noise from an ISO number.
+
+The selected ISO/capture-mode state binds an explicit generic readout regime. Photons and photo/dark
+shot-noise expectations remain upstream; regime gain, read noise and clipping are separately
+declared. Generic tier labels do not calibrate or rank commercial equipment.
+
+```ts
+export function resolveGenericIsoSignalChain(
+  input:
+    ResolveGenericIsoSignalChainInput
+): ResolvedGenericIsoSignalChain;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveGenericIsoSignalChainInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveGenericIsoSignalChainInput {
+  profile:
+    GenericIsoSignalChainProfile;
+  isoCapability:
+    IsoCapabilityProfile;
+  requestedIsoSetting:
+    RequestedIsoSetting;
+  captureModeId: string;
+  readoutProfile:
+    SensorReadoutConversionProfile;
+}
+```
+
+## resolveGenericIsoSignalChainPreset
+
+Select a generic catalog preset and return its explicit profile binding without claiming
+manufacturer calibration.
+
+The selected ISO/capture-mode state binds an explicit generic readout regime. Photons and photo/dark
+shot-noise expectations remain upstream; regime gain, read noise and clipping are separately
+declared. Generic tier labels do not calibrate or rank commercial equipment.
+
+```ts
+export function resolveGenericIsoSignalChainPreset(
+  input: {
+    catalog:
+      GenericIsoSignalChainPresetCatalog;
+    preset:
+      GenericIsoSignalChainPreset;
+  }
+): {
+  preset:
+    GenericIsoSignalChainPreset;
+  signalChainProfileId:
+    string;
+  performanceOrderingClaimed:
+    false;
+  realCameraRankingClaimed:
+    false;
+};
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

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

@@ -0,0 +1,126 @@
+# sensor/local-exposure-binding.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.
+
+## bindSensorRateToLocalExposure
+
+Binds one engine-produced sensor response-rate result to the local exposure
+window at the same color-sampling site.
+
+This first temporal binding supports only the explicit one-to-one
+native-effective-sample ↔ color-site relationship. A multi-site block
+binding proves contributor membership but does not prove each color site's
+sub-sample timing coordinate, so spatially varying shutter timing fails
+closed rather than inventing fractional positions.
+
+The result establishes timing only. It deliberately does not establish that
+the optical/electrical rate is stationary through the local exposure window,
+so rate×duration integration remains unauthorized.
+
+```ts
+export function bindSensorRateToLocalExposure(
+  input:
+    BindSensorRateToLocalExposureInput
+): CalculationResult<SensorRateLocalExposureBinding>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## BindSensorRateToLocalExposureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BindSensorRateToLocalExposureInput {
+  rate:
+    SensorInstantaneousRateResult;
+  colorSamplingProfile:
+    SensorColorSamplingProfile;
+  bindingProfile:
+    NativeEffectiveRasterColorSamplingBindingProfile;
+  /**
+   * One capture/exposure event. samplePointsNative is owned by this binding
+   * function and therefore intentionally excluded.
+   */
+  exposureWindowInput:
+    Omit<
+      CalculateCaptureExposureWindowsInput,
+      "samplePointsNative"
+    >;
+}
+```
+
+## SensorInstantaneousRateResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorInstantaneousRateResult =
+  | SensorEqeElectronRate
+  | SensorResponsivityPhotocurrent;
+```
+
+## SensorRateLocalExposureBinding
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorRateLocalExposureBinding {
+  rateDomain:
+    | "eqe-electron-rate"
+    | "responsivity-photocurrent";
+  rateIdentity: {
+    responseProfileId: string;
+    responseApplicationProfileId: string;
+    operatingRangeProfileId: string;
+    electricalApplicabilityProfileId?: string;
+  };
+  colorSamplingProfileId: string;
+  channelId: string;
+  site: {
+    x: number;
+    y: number;
+  };
+  bindingId: string;
+  bindingRelationship:
+    "one-native-effective-sample-to-one-color-site";
+  timingCoordinateRule:
+    "one-to-one-color-site-center-equals-native-effective-sample-center";
+  nativeRasterPoint: {
+    x: number;
+    y: number;
+  };
+  shutterMechanism:
+    CalculateCaptureExposureWindowsInput["shutterMechanism"];
+  timeReference:
+    "first-opening-boundary-phase";
+  localExposureWindow:
+    CaptureExposureWindowSample;
+  localExposureDurationSeconds:
+    number;
+  exposureEventMeaning:
+    "single-capture-local-exposure-window";
+  nativeImageRasterBindingEstablished: true;
+  channelAtSiteValidated: true;
+  physicalPhotodiodeTimingRegistrationEstablished:
+    false;
+  multiFrameSequenceBindingEstablished:
+    false;
+  timeStationarityEstablished: false;
+  constantRateTemporalIntegrationAuthorized:
+    false;
+  temporalIntegrationApplied: false;
+  componentEvidence: {
+    binding:
+      readonly EvidenceProvenance[];
+    colorSamplingProfile:
+      readonly EvidenceProvenance[];
+    nominalExposureDuration:
+      readonly EvidenceProvenance[];
+    openingBoundary:
+      readonly EvidenceProvenance[];
+    closingBoundary:
+      readonly EvidenceProvenance[];
+  };
+}
+```