@photivra/engine 0.6.0 → 1.0.1

package/docs/api/capture-photographic-export.md

@@ -0,0 +1,172 @@
+# capture/photographic-export.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.
+
+## calculateProcessedSensorRaw
+
+Reconstruct exact attached RAW, develop color/WB once, correct, orient/crop and encode SDR; no file/display IO.
+
+```ts
+export function calculateProcessedSensorRaw(input: ProcessedSensorRawInput): CalculationResult<ProcessedSensorRawResult>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createPhotographicExportPair
+
+Serialize one authoritative RAW capture to a lossless uncompressed CFA DNG and an independently
+packed baseline JPEG. Shared metadata comes from the committed capture; orientation/WB/rendering
+never rewrite native RAW codes.
+
+Paired export preserves one revalidated native post-ADC RAW frame for DNG and develops that same
+frame through explicit reconstruction, approximate sensor-channel color/WB and SDR policy for JPEG.
+File identity and RAW data identity are distinct. Hashing is asynchronous; input data is copied
+before the first await. Full-native execution is limited to 4096 sites.
+
+```ts
+export async function createPhotographicExportPair(input: PhotographicExportInput): Promise<PhotographicExportPair>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
+## ExportSensorColorProfile
+
+Explicit approximation of normalized camera-channel -> scene XYZ/D65, never inferred from RGB/CFA names.
+
+```ts
+export interface ExportSensorColorProfile {
+  schemaVersion: "0.1.0";
+  profileId: string;
+  profileVersion: string;
+  colorSamplingProfileId: string;
+  channelIds: readonly ["red", "green", "blue"];
+  scientificStatus: "approximation";
+  referenceIlluminant: "D65";
+  normalizedCameraChannelsToXyz: Matrix;
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## parseExportSensorColorProfile
+
+Validates independently supplied numeric profile evidence and binds the approximation to the exact CFA profile.
+
+```ts
+export function parseExportSensorColorProfile(value: unknown): ExportSensorColorProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parsePhotographicExportInput
+
+Adds file metadata/encoding validation to the shared processed RAW policy.
+
+```ts
+export function parsePhotographicExportInput(value: unknown): PhotographicExportInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseProcessedSensorRawInput
+
+Revalidates one attached RAW snapshot and explicit processing policy.
+Crop sampling and reconstruction coverage fail here before
+per-pixel execution. Successful parsing does not establish kernel edge support,
+correction support or container encoding readiness; those retain execution
+checks. Input is copied; no file or display backend runs.
+
+```ts
+export function parseProcessedSensorRawInput(value: unknown): ProcessedSensorRawInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PHOTOGRAPHIC_EXPORT_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+PHOTOGRAPHIC_EXPORT_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## PhotographicExportInput
+
+Optional explicit exporter boundary; no files, clocks, randomness, network or encoder dependency.
+
+```ts
+export interface PhotographicExportInput {
+  reconstruction: RawFrameReconstructionInput;
+  colorProfile: ExportSensorColorProfile;
+  whiteBalance: "not-required" | "apply-resolved-sensor-gains";
+  rendering: SdrRenderingProfile;
+  metadata: Omit<CaptureExportMetadataInput, "capture">;
+  /** Caller-declared public scene/version, explicitly bound to the committed scene state. */
+  sceneProfile: { id: string; version: string; sceneStateId: string };
+  /** JPEG constant quantization step 1..255, not an emulated manufacturer's 'quality' scale. */
+  jpegQuantizationStep: number;
+  /** Optional native-optical post-color correction; JPEG only, RAW records informational intent. */
+  correction?: CaptureCorrectedSdrInput["correction"];
+}
+```
+
+## PhotographicExportPair
+
+Owned byte arrays are mutable; identities/hashes refer to the exact bytes returned at creation.
+
+```ts
+export interface PhotographicExportPair {
+  schemaVersion: typeof PHOTOGRAPHIC_EXPORT_SCHEMA_VERSION;
+  metadata: CaptureExportMetadataPair;
+  simulationHashAlgorithm: "sha-256";
+  simulationHash: string;
+  rawDataUniqueId: string;
+  uniqueCameraModel: string;
+  source: CalculationResult<RawFrameReconstruction>;
+  rendering: CalculationResult<SdrRenderingResult>;
+  nativeDefaultCrop: RasterRect;
+  /** Derived JPEG rectangle in the declared oriented output; never replaces the RAW default crop. */
+  processedOutputView: { rect: RasterRect; pixelWidth: number; pixelHeight: number };
+  correction: CalculationResult<CaptureCorrectedSdrResult> | null;
+  rawCorrectionIntent: CalculationResult<ResolvedLensCorrectionPlan> | null;
+  imageDataPairing: "jpeg-generated-from-exact-attached-raw";
+  dng: { mediaType: "image/dng"; bytes: Uint8Array; sha256: string };
+  jpeg: { mediaType: "image/jpeg"; bytes: Uint8Array; sha256: string };
+  interoperability: "independent-decode-required-editor-validation-pending";
+}
+```
+
+## ProcessedSensorRawInput
+
+Explicit post-ADC RAW development policy shared by preview and file output.
+
+```ts
+export type ProcessedSensorRawInput = Pick<PhotographicExportInput,
+  "reconstruction" | "colorProfile" | "whiteBalance" | "rendering" | "correction">;
+```
+
+## ProcessedSensorRawResult
+
+Owned derived preview/JPEG processing record for the exact attached native RAW.
+Child reconstruction/color/WB/correction/rendering results expose their input
+and output domains and independent clipping/cost diagnostics. The output view is
+oriented/cropped SDR, while the native default crop and physical capture history
+remain unchanged. Returned arrays are pre-file pixels, not a lossy JPEG decode.
+
+```ts
+export interface ProcessedSensorRawResult {
+  inputDomain: "post-adc-native-sensor-raw";
+  colorProfile: ExportSensorColorProfile;
+  whiteBalancePolicy: ProcessedSensorRawInput["whiteBalance"];
+  outputDomain: "output-referred-srgb-d65-sdr";
+  physicalCaptureModified: false;
+  displayAdaptationApplied: false;
+  whiteBalance: "applied-here" | "not-required";
+  source: CalculationResult<RawFrameReconstruction>;
+  rendering: CalculationResult<SdrRenderingResult>;
+  nativeDefaultCrop: RasterRect;
+  processedOutputView: PhotographicExportPair["processedOutputView"];
+  correction: CalculationResult<CaptureCorrectedSdrResult> | null;
+  rawCorrectionIntent: CalculationResult<ResolvedLensCorrectionPlan> | null;
+}
+```

package/docs/api/capture-raw-frame-reconstruction.md

@@ -0,0 +1,87 @@
+# capture/raw-frame-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.
+
+## parseRawFrameReconstructionInput
+
+Revalidates committed RAW codes/geometry and complete phase dispatch; no external plane may supply output values.
+
+```ts
+export function parseRawFrameReconstructionInput(value: unknown): RawFrameReconstructionInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## RAW_FRAME_RECONSTRUCTION_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+RAW_FRAME_RECONSTRUCTION_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## RawFrameReconstruction
+
+Traceable virtual sensor-channel values, not colorimetric RGB or a rendered photograph.
+
+```ts
+export interface RawFrameReconstruction {
+  schemaVersion: typeof RAW_FRAME_RECONSTRUCTION_SCHEMA_VERSION;
+  rawFrame: SensorRawFrame;
+  phaseProfiles: readonly RawFrameReconstructionPhaseProfile[];
+  region: RasterRect;
+  linearPlane: {
+    imageState: "virtual-sensor-channels";
+    rasterBinding: "native-reconstruction-region";
+    pixelWidth: number;
+    pixelHeight: number;
+    channelIds: readonly string[];
+    /** Interleaved native-region row-major values; black-subtracted normalization, signed. */
+    samples: readonly number[];
+  };
+  /** Child envelopes and exact weighted RAW contributions, in matching native-region row-major order. */
+  pixels: readonly CalculationResult<SensorRawReconstructedPixel>[];
+  lineage: "engine-reconstructed-from-attached-raw";
+  producerOriginVerified: false;
+  whiteBalanceApplied: false;
+  colorTransformApplied: false;
+  physicalOrientationApplied: false;
+  outputCropApplied: false;
+  sharpeningApplied: false;
+  denoisingApplied: false;
+}
+```
+
+## RawFrameReconstructionInput
+
+Bounded reference handoff; region coordinates stay in the full native sensor frame.
+
+```ts
+export interface RawFrameReconstructionInput {
+  rawFrame: SensorRawFrame;
+  region: RasterRect;
+  phaseProfiles: readonly RawFrameReconstructionPhaseProfile[];
+}
+```
+
+## RawFrameReconstructionPhaseProfile
+
+Kernel selection is explicit per absolute native CFA repeat phase, not guessed from channel names.
+
+```ts
+export interface RawFrameReconstructionPhaseProfile {
+  phaseX: number;
+  phaseY: number;
+  profile: SensorRawReconstructionProfile;
+}
+```
+
+## resolveRawFrameReconstruction
+
+Delegates each pixel to #14's explicit linear reconstruction using only the attached native RAW samples.
+
+```ts
+export function resolveRawFrameReconstruction(input: RawFrameReconstructionInput): CalculationResult<RawFrameReconstruction>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/capture-release-sequence.md

@@ -0,0 +1,252 @@
+# capture/release-sequence.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.
+
+## CancelledReleaseSequence
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CancelledReleaseSequence {
+  version:
+    typeof RELEASE_SEQUENCE_VERSION;
+  sequenceId: string;
+  status: "cancelled";
+  cancelledAtSeconds: number;
+  completedFrameCount: number;
+  omittedFrameCount: number;
+  completedFrames:
+    readonly ResolvedReleaseFrame[];
+  sourceSequenceFrameCount: number;
+  sourceSequenceUnmodified: true;
+}
+```
+
+## CancelReleaseSequenceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CancelReleaseSequenceInput {
+  sequence:
+    ResolvedReleaseSequence;
+  completedFrameCount: number;
+  cancelledAtSeconds: number;
+}
+```
+
+## createCancelledReleaseSequence
+
+Produces an explicit cancelled sequence state without mutating the scheduled
+source sequence or leaving the completed/omitted frame boundary ambiguous.
+
+```ts
+export function createCancelledReleaseSequence(
+  input:
+    CancelReleaseSequenceInput
+): CancelledReleaseSequence;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## RELEASE_SEQUENCE_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+RELEASE_SEQUENCE_VERSION =
+  "0.1.0" as const
+```
+
+## ReleaseAutomationState
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ReleaseAutomationState =
+  | "manual"
+  | "locked"
+  | "continuous";
+```
+
+## ReleaseBaseCaptureState
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ReleaseBaseCaptureState {
+  exposure: {
+    aperture: number;
+    shutterSeconds: number;
+    iso: number;
+  };
+  focus: FocusPlane;
+  whiteBalanceStateId?: string;
+  automation: {
+    ae: ReleaseAutomationState;
+    af: ReleaseAutomationState;
+    awb: ReleaseAutomationState;
+  };
+}
+```
+
+## ReleaseBracketPolicy
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ReleaseBracketPolicy =
+  | {
+      kind: "none";
+    }
+  | {
+      kind: "exposure";
+      axis:
+        GenericExposureBracketAxis;
+      offsetsStops:
+        readonly number[];
+    }
+  | {
+      kind: "focus";
+      focusStates:
+        readonly FocusPlane[];
+    };
+```
+
+## ReleaseDrivePolicy
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ReleaseDrivePolicy =
+  | {
+      kind: "single";
+    }
+  | {
+      kind: "burst";
+      frameCount: number;
+    }
+  | {
+      kind: "self-timer";
+      delaySeconds: number;
+      frameCount: number;
+    };
+```
+
+## ReleaseTimingConstraint
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ReleaseTimingConstraint =
+  | "requested-cadence"
+  | "body-maximum-cadence"
+  | "exposure-duration"
+  | "minimum-inter-frame-gap";
+```
+
+## ResolvedReleaseFrame
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedReleaseFrame {
+  sequenceId: string;
+  frameIndex: number;
+  releaseFrameId: string;
+  exposureStartTimeSeconds: number;
+  exposureEndTimeSeconds: number;
+  sceneTimeSecondsFromSequenceStart:
+    number;
+  startIntervalFromPreviousSeconds:
+    number | null;
+  timingConstraints:
+    readonly ReleaseTimingConstraint[];
+  stochasticSeedUint32: number;
+  exposure: {
+    aperture: number;
+    shutterSeconds: number;
+    iso: number;
+  };
+  focus: FocusPlane;
+  exposureBracketOffsetStops?:
+    number;
+  automation:
+    ReleaseBaseCaptureState["automation"];
+  whiteBalanceStateId?: string;
+}
+```
+
+## ResolvedReleaseSequence
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedReleaseSequence {
+  version:
+    typeof RELEASE_SEQUENCE_VERSION;
+  sequenceId: string;
+  status: "scheduled";
+  releaseRequestTimeSeconds: number;
+  selfTimerDelaySeconds: number;
+  requestedCadenceFps:
+    number | null;
+  capabilityMaximumCadenceFps:
+    number;
+  minimumInterFrameGapSeconds:
+    number;
+  requestedFrameCount: number;
+  actualFrameCount: number;
+  sequenceSeedUint32: number;
+  baseStateSnapshot:
+    ReleaseBaseCaptureState;
+  frames:
+    readonly ResolvedReleaseFrame[];
+  sensorCaptureModeOwnership:
+    "separate-logical-capture-contract";
+  whiteBalanceBracketingPhysicalCaptures:
+    false;
+  preReleaseCaptureModeled:
+    false;
+  bufferMediaThermalSlowdownModeled:
+    false;
+}
+```
+
+## resolveReleaseSequence
+
+Resolves one deterministic logical still-release sequence.
+
+Sensor capture-mode internals remain separate. This function schedules
+logical exposures only and never uses render speed/frame rate as capture
+timing.
+
+```ts
+export function resolveReleaseSequence(
+  input:
+    ResolveReleaseSequenceInput
+): ResolvedReleaseSequence;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveReleaseSequenceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveReleaseSequenceInput {
+  sequenceId: string;
+  releaseRequestTimeSeconds: number;
+  sequenceSeedUint32: number;
+  drive: ReleaseDrivePolicy;
+  bracket: ReleaseBracketPolicy;
+  requestedCadenceFps?: number;
+  baseState:
+    ReleaseBaseCaptureState;
+  releaseCapabilities:
+    GenericReleaseCapabilityProfile;
+  exposureCapabilities:
+    ResolvedGenericEquipmentExposureCapabilities;
+}
+```

package/docs/api/capture-sensor-raw-frame.md

@@ -0,0 +1,66 @@
+# capture/sensor-raw-frame.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.
+
+## createSensorRawFrame
+
+Commits native RAW samples and capture metadata; no demosaic, WB, tone or format packing.
+
+```ts
+export function createSensorRawFrame(input: SensorRawFrameInput): SensorRawFrame;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSensorRawFrameInput
+
+Validates dense bounded native coverage and exact CFA/mode/site/code identity, without IO.
+
+```ts
+export function parseSensorRawFrameInput(value: unknown): SensorRawFrameInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SENSOR_RAW_FRAME_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SENSOR_RAW_FRAME_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## SensorRawFrame
+
+Immutable RAW attachment. Structural validation does not prove producer truth or DNG compatibility.
+
+```ts
+export interface SensorRawFrame extends SensorRawFrameInput {
+  schemaVersion: typeof SENSOR_RAW_FRAME_SCHEMA_VERSION;
+  sampleDomain: "native-cfa-raw-code";
+  sampleOrder: "native-row-major";
+  producerBinding: "caller-declared-capture-attachment";
+  reconstructionApplied: false;
+  renderingApplied: false;
+  nativePixelWidth: number;
+  nativePixelHeight: number;
+}
+```
+
+## SensorRawFrameInput
+
+Declared attachment of #14 native CFA samples to a committed photographic capture.
+
+```ts
+export interface SensorRawFrameInput {
+  frameId: string;
+  capture: SimulatedCapture;
+  modeId: string;
+  captureModeProfile: CaptureModeProfile;
+  colorSamplingProfile: SensorColorSamplingProfile;
+  bindingProfile: NativeEffectiveRasterColorSamplingBindingProfile;
+  containerBitDepth: 16;
+  /** Exactly one sample per full native site, row-major; no processed RGB masking. */
+  samples: readonly SensorRawCaptureSample[];
+}
+```

package/docs/api/capture-sensor-raw-producer.md

@@ -0,0 +1,98 @@
+# capture/sensor-raw-producer.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.
+
+## parseSensorRawProducerInput
+
+Validates complete native exposure inputs; no charge/noise/RAW code is accepted as a shortcut.
+
+```ts
+export function parseSensorRawProducerInput(value: unknown): SensorRawProducerInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SENSOR_RAW_PRODUCER_NOISE_MODEL
+
+Capture noise model identity binds the seed schedule and signed electronic readout behavior.
+
+```ts
+SENSOR_RAW_PRODUCER_NOISE_MODEL = Object.freeze({ id: "photivra-native-raw-noise", version: "0.2.0" } as const)
+```
+
+## SENSOR_RAW_PRODUCER_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SENSOR_RAW_PRODUCER_SCHEMA_VERSION = "0.3.0" as const
+```
+
+## SensorRawProducerExposureWindowInput
+
+Full-native exposure schedule; sampling coordinates belong to the producer.
+
+```ts
+export type SensorRawProducerExposureWindowInput = Omit<CalculateCaptureExposureWindowsInput,
+  "nativeRaster" | "activeCaptureRect" | "samplePointsNative">;
+```
+
+## SensorRawProducerInput
+
+Bounded single-frame handoff, never a conversion from independent RGB pixels.
+
+```ts
+export interface SensorRawProducerInput {
+  frame: Omit<SensorRawFrameInput, "samples">;
+  sites: readonly SensorRawProducerSiteInput[];
+  /** Omission preserves the existing global 0..shutterSeconds event contract. */
+  exposureWindow?: SensorRawProducerExposureWindowInput;
+}
+```
+
+## SensorRawProducerResult
+
+Engine-produced codes and child diagnostics; upstream radiance/response truth remains declared.
+
+```ts
+export interface SensorRawProducerResult {
+  schemaVersion: typeof SENSOR_RAW_PRODUCER_SCHEMA_VERSION;
+  codeProducer: "engine-charge-capacity-noise-adc";
+  upstreamOrigin: "declared-eqe-and-dark-exposure-results";
+  upstreamRadiometryVerified: false;
+  seedSchedule: "capture-seed-plus-two-native-index-modulo-2-to-32-v1";
+  frame: SensorRawFrame;
+  localExposureWindows?: CalculationResult<CaptureExposureWindows>;
+  sites: readonly {
+    accumulatedCharge: ReturnType<typeof composeSensorAccumulatedCharge>;
+    capacity: ReturnType<typeof assessSensorPhysicalChargeCapacity>;
+    realization: ReturnType<typeof simulateSensorChargeRealization>;
+    readout: ReturnType<typeof simulateSensorRawCode>;
+  }[];
+}
+```
+
+## SensorRawProducerSiteInput
+
+One declared EQE/dark/completeness event and explicit readout state per native site.
+
+```ts
+export interface SensorRawProducerSiteInput {
+  charge: ComposeSensorAccumulatedChargeInput;
+  samplingProfile: SensorChargeSamplingProfile;
+  capacityProfile: SensorPhysicalChargeCapacityProfile;
+  operatingStateId: string;
+  readoutProfile: SensorReadoutConversionProfile;
+  regimeId: string;
+}
+```
+
+## simulateSensorRawFrame
+
+Composes existing accumulated-charge → capacity → Poisson → read noise/ADC → native sample → immutable frame contracts.
+
+```ts
+export function simulateSensorRawFrame(input: SensorRawProducerInput): CalculationResult<SensorRawProducerResult>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.