@photivra/engine 0.6.0 → 1.0.0

package/docs/api/sensor-camera-saturation-capacity.md

@@ -0,0 +1,215 @@
+# sensor/camera-saturation-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.
+
+## assessSensorCameraSaturationCapacity
+
+Compare dark-corrected expected photo signal with the declared camera response-chain capacity
+without adding dark charge or identifying a hardware clamp.
+
+Camera saturation capacity is a dark-corrected photo-signal electron-equivalent limit. It is not
+physical total-charge storage capacity, ADC maximum or evidence of the limiting hardware stage. This
+assessment compares expectations and does not synthesize post-saturation codes.
+
+```ts
+export function assessSensorCameraSaturationCapacity(
+  input:
+    AssessSensorCameraSaturationCapacityInput
+): CalculationResult<SensorCameraSaturationCapacityAssessment>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## AssessSensorCameraSaturationCapacityInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AssessSensorCameraSaturationCapacityInput {
+  accumulatedCharge:
+    SensorAccumulatedChargeComposition;
+  saturationProfile:
+    SensorCameraSaturationCapacityProfile;
+  operatingStateId: string;
+  operatingTemperatureC: number;
+}
+```
+
+## parseSensorCameraSaturationCapacityProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Camera saturation capacity is a dark-corrected photo-signal electron-equivalent limit. It is not
+physical total-charge storage capacity, ADC maximum or evidence of the limiting hardware stage. This
+assessment compares expectations and does not synthesize post-saturation codes.
+
+```ts
+export function parseSensorCameraSaturationCapacityProfile(
+  value: unknown
+): SensorCameraSaturationCapacityProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SensorCameraSaturationCapacityAssessment
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorCameraSaturationCapacityAssessment {
+  saturationProfileId: string;
+  completenessProfileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  site: {
+    x: number;
+    y: number;
+  };
+  bindingId: string;
+  operatingStateId: string;
+  operatingTemperatureC: number;
+  capacityMeaning:
+    "camera-signal-saturation-capacity-electrons";
+  signalDomain:
+    "dark-corrected-photo-generated-electron-equivalent";
+  cameraSignalSaturationCapacityElectrons:
+    number;
+  expectedPhotoSignalElectronCount:
+    number;
+  totalExpectedStoredElectronCountDiagnostic:
+    number;
+  totalStoredChargeUsedForCameraSaturationComparison:
+    false;
+  expectedSignalToCameraSaturationRatio:
+    number;
+  expectedSignalHeadroomElectrons:
+    number;
+  expectedCameraSignalCapacityStatus:
+    | "below-capacity"
+    | "at-capacity"
+    | "above-capacity";
+  expectedPhotoSignalExceedsCameraCapacity:
+    boolean;
+  cameraSaturationCapacityAssessmentPerformed:
+    true;
+  assessmentMeaning:
+    "expected-dark-corrected-photo-signal-vs-camera-saturation-capacity";
+  physicalChargeCapacityUsed:
+    false;
+  limitingSaturationMechanismResolved:
+    false;
+  analogClippingThresholdModeled:
+    false;
+  digitalClippingThresholdModeled:
+    false;
+  adcMaximumCodeUsed:
+    false;
+  actualStochasticSaturationStateKnown:
+    false;
+  stochasticSaturationProbabilityAssessed:
+    false;
+  outputSignalAfterSaturationCalculated:
+    false;
+  clampApplied: false;
+  physicalStoredChargeModified:
+    false;
+  adcQuantizationApplied: false;
+  rawCodeValueProduced: false;
+  saturationCapacityUncertaintyPropagated:
+    false;
+  photoSignalUncertaintyPropagated:
+    false;
+  componentEvidence: {
+    saturationCapacity:
+      readonly EvidenceProvenance[];
+    measurementMethod:
+      readonly EvidenceProvenance[];
+    operatingState:
+      readonly EvidenceProvenance[];
+    siteApproximation:
+      readonly EvidenceProvenance[];
+    temperatureApproximation:
+      readonly EvidenceProvenance[];
+    chargeCompleteness:
+      SensorAccumulatedChargeComposition["componentEvidence"]["completeness"];
+  };
+}
+```
+
+## SensorCameraSaturationCapacityProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorCameraSaturationCapacityProfile {
+  schemaVersion: "0.1.0";
+  profileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  capacityMeaning:
+    "camera-signal-saturation-capacity-electrons";
+  signalDomain:
+    "dark-corrected-photo-generated-electron-equivalent";
+  saturationCapacityElectrons: number;
+  scientificStatus:
+    SensorSpectralResponseScientificStatus;
+  uncertainty:
+    SensorSpectralResponseUncertainty;
+  evidence:
+    readonly EvidenceProvenance[];
+  measurementMethodId: string;
+  measurementMethodEvidence:
+    readonly EvidenceProvenance[];
+  siteApplicability:
+    SensorCameraSaturationSiteApplicability;
+  operatingState: {
+    stateId: string;
+    evidence:
+      readonly EvidenceProvenance[];
+  };
+  temperatureApplicability:
+    SensorCameraSaturationTemperatureApplicability;
+}
+```
+
+## SensorCameraSaturationSiteApplicability
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorCameraSaturationSiteApplicability =
+  | {
+      kind: "exact-site";
+      site: {
+        x: number;
+        y: number;
+      };
+    }
+  | {
+      kind:
+        "channel-population-mean-approximation";
+      limitation: string;
+      evidence:
+        readonly EvidenceProvenance[];
+    };
+```
+
+## SensorCameraSaturationTemperatureApplicability
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorCameraSaturationTemperatureApplicability =
+  | {
+      kind:
+        "exact-reference-temperature";
+      temperatureC: number;
+    }
+  | {
+      kind: "not-modeled";
+      limitation: string;
+      evidence:
+        readonly EvidenceProvenance[];
+    };
+```

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

@@ -0,0 +1,323 @@
+# sensor/capture-color-sampling-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.
+
+## CaptureModeFullFrameSampleIndex
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureModeFullFrameSampleIndex {
+  /**
+   * Zero-based index in the selected mode's full-frame per-frame effective
+   * sampling raster. Crop-local coordinates must be translated to absolute
+   * full-frame mode indices before calling this API.
+   */
+  x: number;
+  y: number;
+}
+```
+
+## ColorSamplingChannelComposition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ColorSamplingChannelComposition =
+  | {
+      kind: "single-channel";
+      channelId: string;
+    }
+  | {
+      kind: "mixed-channels";
+      channelIds: readonly string[];
+    };
+```
+
+## ColorSamplingChannelSiteCount
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ColorSamplingChannelSiteCount {
+  channelId: string;
+  siteCount: number;
+}
+```
+
+## ColorSamplingSiteGridDimensions
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ColorSamplingSiteGridDimensions {
+  widthSites: number;
+  heightSites: number;
+}
+```
+
+## ColorSamplingSiteRect
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ColorSamplingSiteRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+```
+
+## GroupedCaptureModeSamplingAnchorDeclaration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GroupedCaptureModeSamplingAnchorDeclaration {
+  anchor: "native-effective-raster-top-left";
+  evidence: readonly EvidenceProvenance[];
+}
+```
+
+## NativeEffectiveRasterColorSamplingBindingProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeEffectiveRasterColorSamplingBindingProfile {
+  schemaVersion: "0.1.0";
+  bindingId: string;
+  colorSamplingProfileId: string;
+  /**
+   * Exact canonical native effective raster this binding was evidenced for.
+   * The binding must not be reused against a different raster merely because
+   * another sensor/mode has similar dimensions or a matching aspect ratio.
+   */
+  nativeRaster: NativeImageRaster;
+  /**
+   * Evidence supporting the native-effective-grid ↔ color-site-grid
+   * relationship itself.
+   *
+   * Capture-mode and color-topology facts retain separate provenance.
+   */
+  evidence: readonly EvidenceProvenance[];
+  relationship: {
+    kind: "regular-native-effective-sample-blocks";
+    /**
+     * Number of abstract color-sampling sites spanned horizontally by one
+     * native effective image sample.
+     */
+    sitesPerNativeSampleX: number;
+    /**
+     * Number of abstract color-sampling sites spanned vertically by one
+     * native effective image sample.
+     */
+    sitesPerNativeSampleY: number;
+    /**
+     * Both grids are anchored to the same native sensor top-left.
+     *
+     * This keeps phase absolute across later active crops/orientation.
+     */
+    anchor: "shared-native-top-left";
+  };
+}
+```
+
+## NativeEffectiveSampleRect
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeEffectiveSampleRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+```
+
+## parseNativeEffectiveRasterColorSamplingBindingProfile
+
+Parses the explicit relationship between the canonical native effective image
+raster and the separate native sensor color-sampling-site lattice.
+
+This first binding supports only regular rectangular site blocks with a
+shared native top-left anchor. Irregular mappings, sparse exceptions and
+mode-specific declared-effective rasters require later explicit contracts.
+
+```ts
+export function parseNativeEffectiveRasterColorSamplingBindingProfile(
+  value: unknown
+): NativeEffectiveRasterColorSamplingBindingProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## resolveCaptureModeColorSamplingContributors
+
+Resolves which color-sampling sites form the pre-reconstruction structural source region for one selected
+capture-mode effective sample.
+
+The mode sample index is always absolute in the selected mode's full-frame
+per-frame raster. The API intentionally does not accept crop-local indices,
+preventing active-crop origins from silently resetting CFA phase.
+
+For grouped-native-sample modes, the returned site rectangle covers all
+native effective samples in the declared regular group. This is a structural
+pre-reconstruction association only: the engine reports channel-site counts
+but never claims complete downstream digital-pixel dependency or invents
+signal-combination weights, sum/average semantics, spectral response, or
+photon/electron values.
+
+Declared-effective-raster modes fail closed because #68 explicitly says
+their relationship to the native effective grid is not safely expressible as
+simple integer grouping.
+
+Inter-frame sensor shifts are preserved as capture-mode metadata only. The
+sensor and CFA move together, so those offsets do not change site channel
+assignment; their optical-registration effect belongs to a later spatial
+sampling/image-formation contract.
+
+```ts
+export function resolveCaptureModeColorSamplingContributors(
+  input: ResolveCaptureModeColorSamplingContributorsInput
+): ResolvedCaptureModeColorSamplingContributors;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveCaptureModeColorSamplingContributorsInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveCaptureModeColorSamplingContributorsInput {
+  nativeRaster: NativeImageRaster;
+  captureModeProfile: CaptureModeProfile;
+  modeId: string;
+  colorSamplingProfile: SensorColorSamplingProfile;
+  bindingProfile: NativeEffectiveRasterColorSamplingBindingProfile;
+  modeSampleIndexFullFrame: CaptureModeFullFrameSampleIndex;
+  /**
+   * Required for grouped-native-samples modes because #68 declares grouping
+   * factors but does not itself prove the grouping phase/origin.
+   */
+  groupedSamplingAnchor?: GroupedCaptureModeSamplingAnchorDeclaration;
+}
+```
+
+## ResolvedCaptureModeColorSamplingContributors
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedCaptureModeColorSamplingContributors {
+  modeId: string;
+  colorSamplingProfileId: string;
+  modeSampleCoordinateSystem:
+    "capture-mode-full-frame-effective-sample-index";
+  modeSampleIndexFullFrame: CaptureModeFullFrameSampleIndex;
+  modeSampleRaster: {
+    pixelWidth: number;
+    pixelHeight: number;
+  };
+  modeSamplingKind:
+    | "native-effective-raster"
+    | "grouped-native-samples";
+  nativeEffectiveSampleRect: NativeEffectiveSampleRect;
+  colorSamplingSiteRect: ColorSamplingSiteRect;
+  colorSamplingSiteGrid: ColorSamplingSiteGridDimensions;
+  totalContributorSites: number;
+  channelSiteCounts: readonly ColorSamplingChannelSiteCount[];
+  channelComposition: ColorSamplingChannelComposition;
+  /**
+   * Present only when the selected capture mode groups native effective
+   * samples before producing one per-frame effective sample.
+   */
+  grouping:
+    | {
+        groupWidthSamples: SourcedCaptureModeFact<number>;
+        groupHeightSamples: SourcedCaptureModeFact<number>;
+        combinationDomain?: SourcedCaptureModeFact<CaptureModeSampleCombinationDomain>;
+        anchor: "native-effective-raster-top-left";
+        anchorEvidence: readonly EvidenceProvenance[];
+      }
+    | null;
+  /**
+   * Sensor-shift sequence remains attached to the sensor/capture mode.
+   *
+   * The sensor and its CFA move together, so these offsets must not be applied
+   * as changes to color-site channel assignment.
+   */
+  interFrameSensorOffsetsNativeSamples?: SourcedCaptureModeFact<
+    readonly CaptureModeSensorOffsetNativeSamples[]
+  >;
+  sensorShiftChangesColorSiteAssignment: false;
+  sensorShiftOpticalRegistration:
+    "outside-this-contract";
+  structuralSourceStage: "pre-reconstruction";
+  completeDownstreamPixelDependencyEstablished: false;
+  signalCombinationWeightingEstablished: false;
+  spectralResponseEstablished: false;
+  physicalPhotodiodeBindingEstablished: false;
+  physicalPhotodiodeCountInference: "not-permitted";
+  componentEvidence: {
+    binding: readonly EvidenceProvenance[];
+    colorSamplingProfile: readonly EvidenceProvenance[];
+    captureMode: readonly EvidenceProvenance[];
+  };
+}
+```
+
+## ResolvedNativeEffectiveRasterColorSamplingBinding
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedNativeEffectiveRasterColorSamplingBinding {
+  bindingId: string;
+  colorSamplingProfileId: string;
+  nativeRaster: NativeImageRaster;
+  relationshipMeaning:
+    | "one-native-effective-sample-to-one-color-site"
+    | "one-native-effective-sample-to-rectangular-color-site-block";
+  relationship: {
+    kind: "regular-native-effective-sample-blocks";
+    sitesPerNativeSampleX: number;
+    sitesPerNativeSampleY: number;
+    anchor: "shared-native-top-left";
+  };
+  colorSamplingSiteGrid: ColorSamplingSiteGridDimensions;
+  totalColorSamplingSites: number;
+  nativeImageRasterBindingEstablished: true;
+  physicalPhotodiodeBindingEstablished: false;
+  physicalPhotodiodeCountInference: "not-permitted";
+  spectralResponseEstablished: false;
+  componentEvidence: {
+    binding: readonly EvidenceProvenance[];
+    colorSamplingProfile: readonly EvidenceProvenance[];
+  };
+}
+```
+
+## resolveNativeEffectiveRasterColorSamplingBinding
+
+Validates and resolves the sensor-level binding between NativeImageRaster and
+an exact monochrome/periodic color-sampling topology.
+
+Matching dimensions are never treated as proof of a 1:1 relationship. The
+relationship exists only because the caller supplied this evidence-backed
+binding profile.
+
+```ts
+export function resolveNativeEffectiveRasterColorSamplingBinding(
+  input: {
+    nativeRaster: NativeImageRaster;
+    colorSamplingProfile: SensorColorSamplingProfile;
+    bindingProfile: NativeEffectiveRasterColorSamplingBindingProfile;
+  }
+): ResolvedNativeEffectiveRasterColorSamplingBinding;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

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

@@ -0,0 +1,123 @@
+# sensor/capture-mode-timing.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.
+
+## CAPTURE_MODE_TIMING_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+CAPTURE_MODE_TIMING_PROFILE_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## CaptureModeTimingProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureModeTimingProfile {
+  schemaVersion:
+    typeof CAPTURE_MODE_TIMING_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  captureModeId: string;
+  scientificStatus: "approximation";
+  scheduleFamily:
+    "global-or-uniform-linear-native-scan";
+  shutterMechanism:
+    CaptureShutterMechanism;
+  opening:
+    ExposureBoundarySchedule;
+  closing:
+    ExposureBoundarySchedule;
+  readout:
+    SensorReadoutTimingDeclaration;
+  nonUniformScheduleModeled: false;
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## parseCaptureModeTimingProfile
+
+Parses timing facts that are explicitly bound to one exact capture mode.
+
+Schema 0.1.0 intentionally admits only the timing schedule families already
+owned by #12: simultaneous/global or uniform-linear native scans. Unsupported
+non-uniform/segmented schedules fail closed instead of being approximated.
+
+```ts
+export function parseCaptureModeTimingProfile(
+  value: unknown
+): CaptureModeTimingProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## resolveCaptureModeTiming
+
+Resolves the authoritative exposure/readout timing for one exact capture
+mode and timing-profile identity.
+
+Readout timing remains distinct from exposure-boundary timing. No absolute
+readout/exposure synchronization is inferred.
+
+```ts
+export function resolveCaptureModeTiming(
+  input:
+    ResolveCaptureModeTimingInput
+): ResolvedCaptureModeTiming;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveCaptureModeTimingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveCaptureModeTimingInput {
+  captureMode:
+    ResolvedCaptureMode;
+  timingProfile:
+    CaptureModeTimingProfile;
+  nominalExposureDurationSeconds:
+    SourcedCaptureTimingSeconds;
+  activeCaptureRect?: RasterRect;
+  samplePointsNative?:
+    readonly RasterPoint[];
+}
+```
+
+## ResolvedCaptureModeTiming
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedCaptureModeTiming {
+  schemaVersion:
+    typeof CAPTURE_MODE_TIMING_PROFILE_SCHEMA_VERSION;
+  timingProfileId: string;
+  timingProfileVersion: string;
+  captureModeId: string;
+  captureModeTimingIdentity:
+    "exact-mode-and-profile";
+  nativeRaster: NativeImageRaster;
+  modeDeclaresTimingDependency:
+    boolean;
+  scheduleFamily:
+    "global-or-uniform-linear-native-scan";
+  exposureWindows:
+    CaptureExposureWindows;
+  readoutTiming:
+    SensorReadoutTiming;
+  timeReference:
+    "first-opening-boundary-phase";
+  readoutExposureSynchronization:
+    "not-assumed";
+  nonUniformScheduleModeled: false;
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```