@photivra/engine 0.6.0 → 1.0.1

package/docs/api/sensor-raw-reconstruction.md

@@ -0,0 +1,260 @@
+# sensor/raw-reconstruction.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.
+
+## createSensorRawCaptureSample
+
+Commit one validated native RAW sample with exact site/channel/event identity for declared
+reconstruction.
+
+Reconstruction consumes explicitly bound native post-ADC samples and declared normalized channel
+kernels. Native CFA phase is absolute and orientation/crop remain downstream. This structural linear
+reconstruction does not infer spectral sensor primaries, calibrated color or a complete arbitrary
+demosaic algorithm.
+
+```ts
+export function createSensorRawCaptureSample(
+  input:
+    CreateSensorRawCaptureSampleInput
+): SensorRawCaptureSample;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateSensorRawCaptureSampleInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateSensorRawCaptureSampleInput {
+  rawCode:
+    SensorRawCodeSample;
+  contributors:
+    ResolvedCaptureModeColorSamplingContributors;
+}
+```
+
+## parseSensorRawReconstructionProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Reconstruction consumes explicitly bound native post-ADC samples and declared normalized channel
+kernels. Native CFA phase is absolute and orientation/crop remain downstream. This structural linear
+reconstruction does not infer spectral sensor primaries, calibrated color or a complete arbitrary
+demosaic algorithm.
+
+```ts
+export function parseSensorRawReconstructionProfile(
+  value: unknown
+): SensorRawReconstructionProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## resolveSensorRawReconstruction
+
+Gather exactly supplied native channel contributions through explicit normalized kernels while
+preserving CFA identity and signed black-subtracted values.
+
+Reconstruction consumes explicitly bound native post-ADC samples and declared normalized channel
+kernels. Native CFA phase is absolute and orientation/crop remain downstream. This structural linear
+reconstruction does not infer spectral sensor primaries, calibrated color or a complete arbitrary
+demosaic algorithm.
+
+```ts
+export function resolveSensorRawReconstruction(
+  input:
+    ResolveSensorRawReconstructionInput
+): CalculationResult<SensorRawReconstructedPixel>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveSensorRawReconstructionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveSensorRawReconstructionInput {
+  profile:
+    SensorRawReconstructionProfile;
+  colorSamplingProfile:
+    SensorColorSamplingProfile;
+  centerSite: {
+    x: number;
+    y: number;
+  };
+  samples:
+    readonly SensorRawCaptureSample[];
+}
+```
+
+## SENSOR_RAW_CAPTURE_SAMPLE_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SENSOR_RAW_CAPTURE_SAMPLE_VERSION =
+  "0.1.0" as const
+```
+
+## SENSOR_RAW_RECONSTRUCTION_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SENSOR_RAW_RECONSTRUCTION_PROFILE_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## SensorRawCaptureSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorRawCaptureSample {
+  version:
+    typeof SENSOR_RAW_CAPTURE_SAMPLE_VERSION;
+  captureModeId: string;
+  modeSampleCoordinateSystem:
+    "capture-mode-full-frame-effective-sample-index";
+  modeSampleIndexFullFrame: {
+    x: number;
+    y: number;
+  };
+  colorSamplingProfileId: string;
+  colorSamplingSite: {
+    x: number;
+    y: number;
+  };
+  channelId: string;
+  rawCode: number;
+  blackLevelCode: number;
+  digitalSaturationCode: number;
+  blackSubtractedNormalizedCode:
+    number;
+  readoutProfileId: string;
+  readoutRegimeId: string;
+  sourceChargeSeedUint32: number;
+  sourceReadNoiseSeedUint32: number;
+  physicalScalarSaturationApplied:
+    boolean;
+  digitalSaturationApplied:
+    boolean;
+  cfaPhasePreservedInNativeCoordinates:
+    true;
+  physicalOrientationApplied:
+    false;
+  outputRotationApplied:
+    false;
+  groupedModeCombinationApplied:
+    false;
+  reconstructionApplied: false;
+  aliasingModeled: false;
+  moireModeled: false;
+}
+```
+
+## SensorRawReconstructedPixel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorRawReconstructedPixel {
+  reconstructionProfileId:
+    string;
+  reconstructionProfileVersion:
+    string;
+  captureModeId: string;
+  colorSamplingProfileId: string;
+  centerSite: {
+    x: number;
+    y: number;
+  };
+  outputChannels:
+    readonly {
+      channelId: string;
+      linearBlackSubtractedNormalizedValue:
+        number;
+      sourceContributions:
+        readonly {
+          site: {
+            x: number;
+            y: number;
+          };
+          sourceChannelId: string;
+          weight: number;
+          sourceValue: number;
+        }[];
+    }[];
+  method:
+    "explicit-linear-native-neighborhood";
+  cfaAware: true;
+  captureModeAware: true;
+  physicalOrientationApplied:
+    false;
+  outputRotationApplied: false;
+  sharpeningApplied: false;
+  denoisingApplied: false;
+  aliasingModeled: false;
+  moireModeled: false;
+  preSamplingOpticalTransferAdequacyEstablished:
+    false;
+  reconstructionDoesNotModifyRawSamples:
+    true;
+}
+```
+
+## SensorRawReconstructionChannelKernel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorRawReconstructionChannelKernel {
+  outputChannelId: string;
+  contributions:
+    readonly SensorRawReconstructionKernelContribution[];
+}
+```
+
+## SensorRawReconstructionKernelContribution
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorRawReconstructionKernelContribution {
+  offsetX: number;
+  offsetY: number;
+  sourceChannelId: string;
+  weight: number;
+}
+```
+
+## SensorRawReconstructionProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorRawReconstructionProfile {
+  schemaVersion:
+    typeof SENSOR_RAW_RECONSTRUCTION_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  captureModeId: string;
+  colorSamplingProfileId: string;
+  scientificStatus:
+    SensorSpectralResponseScientificStatus;
+  method:
+    "explicit-linear-native-neighborhood";
+  normalization:
+    "weights-sum-to-one-per-output-channel";
+  negativeBlackSubtractedValuesAllowed:
+    true;
+  kernels:
+    readonly SensorRawReconstructionChannelKernel[];
+  evidence:
+    readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```

package/docs/api/sensor-readout-exposure-linkage.md

@@ -0,0 +1,172 @@
+# sensor/readout-exposure-linkage.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.
+
+## assessReadoutExposureTimingLinkage
+
+Assesses an explicitly declared relationship between rolling sensor readout
+spatial phase and one or more electronic exposure-boundary scans.
+
+This contract is deliberately weaker than temporal synchronization. It can
+establish that two schedules traverse the same native spatial phase ordering
+(or its reverse), but it does not establish when sensor data readout occurs
+relative to exposure start/end.
+
+The total capture data-readout duration is preserved diagnostically and is
+never used to validate the relationship. Different rolling-readout spatial
+skew and exposure-boundary traversal durations are allowed; their ratio is
+reported without implying a shared clock origin.
+
+```ts
+export function assessReadoutExposureTimingLinkage(
+  input: AssessReadoutExposureTimingLinkageInput
+): CalculationResult<ReadoutExposureTimingLinkageAssessment>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## AssessReadoutExposureTimingLinkageInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AssessReadoutExposureTimingLinkageInput {
+  nativeRaster: NativeImageRaster;
+  activeCaptureRect?: RasterRect;
+  shutterMechanism: CaptureShutterMechanism;
+  readout: SensorReadoutTimingDeclaration;
+  nominalExposureDurationSeconds: SourcedCaptureTimingSeconds;
+  opening: ExposureBoundarySchedule;
+  closing: ExposureBoundarySchedule;
+  linkage: ReadoutExposureTimingLinkageDeclaration;
+  samplePointsNative?: readonly RasterPoint[];
+}
+```
+
+## ReadoutExposureBoundaryId
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ReadoutExposureBoundaryId = "opening" | "closing";
+```
+
+## ReadoutExposureBoundarySpatialLink
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ReadoutExposureBoundarySpatialLink {
+  boundary: ReadoutExposureBoundaryId;
+  /**
+   * Relationship between normalized rolling-readout scan phase and the
+   * selected electronic exposure-boundary scan phase.
+   *
+   * "same": boundary normalized phase = readout normalized phase.
+   * "reversed": boundary normalized phase = 1 - readout normalized phase.
+   *
+   * This does not establish absolute temporal synchronization.
+   */
+  phaseOrientation: ReadoutExposureSpatialPhaseOrientation;
+  /**
+   * Evidence supporting the relationship itself.
+   *
+   * The readout direction/timing and exposure-boundary direction/timing retain
+   * their own separate evidence.
+   */
+  evidence: readonly EvidenceProvenance[];
+}
+```
+
+## ReadoutExposureBoundarySpatialLinkAssessment
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ReadoutExposureBoundarySpatialLinkAssessment {
+  boundary: ReadoutExposureBoundaryId;
+  boundaryActuator: "electronic";
+  phaseOrientation: ReadoutExposureSpatialPhaseOrientation;
+  normalizedPhaseRelationship:
+    | "boundary-phase-equals-readout-phase"
+    | "boundary-phase-equals-one-minus-readout-phase";
+  relationshipEvidence: readonly EvidenceProvenance[];
+  readoutDirectionNative: NativeSensorReadoutScanDirection;
+  boundaryDirectionNative: NativeSensorReadoutScanDirection;
+  /**
+   * First-to-last rolling sensor spatial sampling skew.
+   */
+  readoutSpatialSamplingSkewSeconds: SourcedSensorTimingSeconds;
+  /**
+   * First-to-last exposure-boundary traversal duration.
+   */
+  boundaryTraversalDurationSeconds: SourcedCaptureTimingSeconds;
+  /**
+   * Derived descriptive ratio only. A value of 1 does not prove temporal
+   * synchronization or a common clock origin.
+   */
+  boundaryTraversalToReadoutSpatialSkewRatio: number;
+  absoluteTemporalAlignment: "not-established";
+}
+```
+
+## ReadoutExposureSpatialPhaseOrientation
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ReadoutExposureSpatialPhaseOrientation =
+  | "same"
+  | "reversed";
+```
+
+## ReadoutExposureTimingLinkageAssessment
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ReadoutExposureTimingLinkageAssessment {
+  linkageKind: ReadoutExposureTimingLinkageDeclaration["kind"];
+  relationshipMeaning:
+    | "no-readout-exposure-relationship-asserted"
+    | "normalized-spatial-phase-relationship-asserted";
+  readoutMode: "rolling" | "global";
+  shutterMechanism: CaptureShutterMechanism;
+  activeCaptureRect: RasterRect;
+  absoluteTemporalAlignment: "not-established";
+  /**
+   * Capture data-readout duration is preserved for diagnostics but is not used
+   * to validate any exposure-boundary linkage.
+   */
+  captureReadoutDurationSeconds: SourcedSensorTimingSeconds;
+  links: readonly ReadoutExposureBoundarySpatialLinkAssessment[];
+  componentProvenance: {
+    sensorReadout: CalculationProvenance;
+    exposureWindows: CalculationProvenance;
+  };
+}
+```
+
+## ReadoutExposureTimingLinkageDeclaration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ReadoutExposureTimingLinkageDeclaration =
+  | {
+      /**
+       * Photivra asserts no readout↔exposure relationship for this capture.
+       * This is not evidence that the physical processes are independent.
+       */
+      kind: "unlinked";
+      links?: never;
+    }
+  | {
+      /**
+       * One or more exposure boundaries are explicitly related to rolling
+       * readout by normalized native-sensor spatial phase.
+       */
+      kind: "spatial-phase-linked";
+      links: readonly ReadoutExposureBoundarySpatialLink[];
+    };
+```

package/docs/api/sensor-readout-timing.md

@@ -0,0 +1,209 @@
+# sensor/readout-timing.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.
+
+## calculateSensorReadoutTiming
+
+Resolves a capture-specific native sensor readout scan schedule.
+
+Rolling readout uses a uniform-linear single-axis approximation across the
+declared active capture. The caller supplies the spatial timing span
+explicitly; it is never inferred from total data-readout duration, active
+crop dimensions, native raster density, output resolution, sensor
+architecture metadata, or shutter mechanism.
+
+Global readout has no spatial phase skew in this model even when a non-zero
+data-readout duration is declared.
+
+This foundation does not define local exposure start/end times, mechanical
+curtain travel, EFCS curtain behavior, rolling-shutter image distortion,
+flash/flicker interactions, or motion integration.
+
+```ts
+export function calculateSensorReadoutTiming(
+  input: CalculateSensorReadoutTimingInput
+): CalculationResult<SensorReadoutTiming>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorReadoutTimingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSensorReadoutTimingInput {
+  nativeRaster: NativeImageRaster;
+  /**
+   * Active capture rectangle in invariant native raster coordinates.
+   *
+   * Defaults to the complete native raster. Timing is never inferred by
+   * scaling a full-frame value to this rectangle.
+   */
+  activeCaptureRect?: RasterRect;
+  /**
+   * Selected shutter mechanism for the capture.
+   *
+   * It is reported independently and does not modify the sensor timing
+   * schedule in this foundation.
+   */
+  shutterMechanism: CaptureShutterMechanism;
+  readout: SensorReadoutTimingDeclaration;
+  /**
+   * Optional continuous native raster edge-coordinate points for timing
+   * diagnostics. Pixel centers may be represented with +0.5 offsets.
+   */
+  samplePointsNative?: readonly RasterPoint[];
+}
+```
+
+## CaptureShutterMechanism
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type CaptureShutterMechanism =
+  | "mechanical"
+  | "electronic-first-curtain"
+  | "electronic";
+```
+
+## GlobalSensorReadoutTimingDeclaration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GlobalSensorReadoutTimingDeclaration {
+  readoutMode: "global";
+  /**
+   * Capture-specific sensor data-readout duration.
+   *
+   * This is deliberately not interpreted as spatial exposure/readout skew.
+   */
+  captureReadoutDurationSeconds: SourcedSensorTimingSeconds;
+  scanDirectionNative?: never;
+  spatialSamplingSkewSeconds?: never;
+}
+```
+
+## NativeSensorReadoutScanDirection
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type NativeSensorReadoutScanDirection =
+  | "top-to-bottom"
+  | "bottom-to-top"
+  | "left-to-right"
+  | "right-to-left";
+```
+
+## RollingSensorReadoutTimingDeclaration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface RollingSensorReadoutTimingDeclaration {
+  readoutMode: "rolling";
+  /**
+   * Capture-specific sensor data-readout duration.
+   *
+   * This fact is retained independently from spatial sampling skew because
+   * published/declared readout duration and the spatial timing span need not be
+   * treated as the same quantity.
+   */
+  captureReadoutDurationSeconds: SourcedSensorTimingSeconds;
+  /**
+   * Native-sensor scan direction for the selected capture mode.
+   */
+  scanDirectionNative: SourcedSensorReadoutFact<NativeSensorReadoutScanDirection>;
+  /**
+   * Time difference between the first and last spatial scan positions in the
+   * uniform-linear timing approximation.
+   */
+  spatialSamplingSkewSeconds: SourcedSensorTimingSeconds;
+}
+```
+
+## SensorReadoutMode
+
+Readout architecture selected for one capture.
+
+This reuses the architecture vocabulary but is not a hardware-capability
+assertion. SensorArchitectureProfile.readoutCapabilities remains descriptive
+metadata and is not consulted automatically.
+
+```ts
+export type SensorReadoutMode = SensorReadoutArchitecture;
+```
+
+## SensorReadoutTiming
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorReadoutTiming {
+  readoutMode: SensorReadoutMode;
+  shutterMechanism: CaptureShutterMechanism;
+  nativeRaster: NativeImageRaster;
+  activeCaptureRect: RasterRect;
+  captureReadoutDurationSeconds: SourcedSensorTimingSeconds;
+  maximumSpatialSamplingSkewSeconds: number;
+  scan:
+    | {
+        pattern: "uniform-linear-single-axis";
+        directionNative: SourcedSensorReadoutFact<NativeSensorReadoutScanDirection>;
+        unitVectorNative: { x: number; y: number };
+        spatialSamplingSkewSeconds: SourcedSensorTimingSeconds;
+      }
+    | null;
+  samples: readonly SensorReadoutTimingSample[];
+}
+```
+
+## SensorReadoutTimingDeclaration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorReadoutTimingDeclaration =
+  | GlobalSensorReadoutTimingDeclaration
+  | RollingSensorReadoutTimingDeclaration;
+```
+
+## SensorReadoutTimingSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorReadoutTimingSample {
+  pointNative: RasterPoint;
+  normalizedScanPosition: number | null;
+  /**
+   * Relative native-sensor readout phase in seconds.
+   *
+   * Zero is the first spatial scan position. This is not automatically an
+   * exposure-start time or shutter-curtain time.
+   */
+  readoutPhaseOffsetSeconds: number;
+}
+```
+
+## SourcedSensorReadoutFact
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SourcedSensorReadoutFact<T> = EvidenceBackedFact<T>;
+```
+
+## SourcedSensorTimingSeconds
+
+Evidence-backed timing value with an explicit seconds unit.
+
+```ts
+export interface SourcedSensorTimingSeconds
+  extends EvidenceBackedFact<number> {
+  unit: "s";
+}
+```