@photivra/engine 1.2.0 → 1.4.0

package/docs/api/capture-native-raw.md

@@ -0,0 +1,157 @@
+# capture/native-raw.ts public contracts
+
+Package **1.4.0**, root API **1.4.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.
+
+## calculateNativeRawPlan
+
+Full raster/resource/profile admission before callbacks or output allocation; no placeholder plane.
+
+```ts
+export function calculateNativeRawPlan(input: NativeRawInput): NativeRawPlan;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createNativeRawTask
+
+Executes validated EQE/dark/completeness events through the shared reference scalar physics.
+
+```ts
+export function createNativeRawTask(input: NativeRawInput,provider: NativeRawProvider): NativeRawTask;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## NATIVE_RAW_LIMITS
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+NATIVE_RAW_LIMITS = Object.freeze({ maximumPixels: 24_000_000, maximumDimension: 16_384,
+  tileWidth: 256, tileHeight: 1, outputBytesPerPixel: 7 })
+```
+
+## NATIVE_RAW_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+NATIVE_RAW_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## NativeRawExposure
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type NativeRawExposure = Omit<SimulatedCapture, "schemaVersion" | "planes" | "source"> & {source:CaptureExposureSource};
+```
+
+## NativeRawExposureInput
+
+A shooting event and source provenance, not a produced float master or committed RAW frame.
+
+```ts
+export type NativeRawExposureInput = Omit<SimulatedCaptureInput, "planes" | "source"> & {source:CaptureExposureSource};
+```
+
+## NativeRawInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeRawInput {
+  exposure: NativeRawExposureInput;
+  frameId: string;
+  modeId: string;
+  captureModeProfile: NativeRawProducerFrameContext["captureModeProfile"];
+  colorSamplingProfile: NativeRawProducerFrameContext["colorSamplingProfile"];
+  bindingProfile: NativeRawProducerFrameContext["bindingProfile"];
+  exposureWindow?: SensorRawProducerExposureWindowInput;
+  maximumOutputBytes: number;
+}
+```
+
+## NativeRawOutput
+
+Sole-owner row-major arrays. They are not attachable to the bounded SensorRawFrame contract.
+
+```ts
+export interface NativeRawOutput {
+  plan: NativeRawPlan;
+  codes: Uint16Array;
+  blackLevels: Uint16Array;
+  digitalSaturationCodes: Uint16Array;
+  /** Bits 0,1,2: physical scalar clamp, pre-ADC clamp, digital saturation respectively. */
+  saturationFlags: Uint8Array;
+}
+```
+
+## NativeRawPlan
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeRawPlan {
+  schemaVersion: typeof NATIVE_RAW_SCHEMA_VERSION;
+  exposure: NativeRawExposure;
+  frame: NativeRawProducerFrameContext;
+  exposureWindow?: SensorRawProducerExposureWindowInput;
+  pixelCount: number;
+  outputBytes: number;
+  tileCount: number;
+  upstreamRadiometryVerified: false;
+  seedSchedule: "capture-seed-plus-two-native-index-modulo-2-to-32-v1";
+}
+```
+
+## NativeRawProvider
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeRawProvider {
+  readTile(request: Readonly<NativeRawTileRequest>, signal: AbortSignal): Promise<NativeRawTile>;
+  yieldControl(signal: AbortSignal): Promise<void>;
+}
+```
+
+## NativeRawTask
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeRawTask {
+  readonly plan: NativeRawPlan;
+  readonly state: NativeRawTaskState;
+  readonly completedTileCount: number;
+  run(): Promise<void>;
+  cancel(): void;
+  dispose(): void;
+  takeOutput(): NativeRawOutput;
+}
+```
+
+## NativeRawTaskState
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type NativeRawTaskState = "ready" | "running" | "completed" | "cancelled" | "failed" | "disposed" | "transferred";
+```
+
+## NativeRawTile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeRawTile extends NativeRawTileRequest { sites: readonly SensorRawProducerSiteInput[] }
+```
+
+## NativeRawTileRequest
+
+Rectangle is absolute full-native CFA space, before orientation, active crop or output scaling.
+
+```ts
+export interface NativeRawTileRequest { captureId: string; frameId: string; x: number; y: number; width: number; height: number }
+```

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

@@ -1,6 +1,6 @@
 # capture/photographic-export.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## calculateProcessedSensorRaw
 

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

@@ -1,6 +1,6 @@
 # capture/raw-frame-reconstruction.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## parseRawFrameReconstructionInput
 

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

@@ -1,6 +1,6 @@
 # capture/release-sequence.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## CancelledReleaseSequence
 

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

@@ -1,6 +1,6 @@
 # capture/sensor-raw-frame.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## createSensorRawFrame
 

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

@@ -1,6 +1,6 @@
 # capture/sensor-raw-producer.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## parseSensorRawProducerInput
 

package/docs/api/capture-simulated-capture.md

@@ -1,6 +1,14 @@
 # capture/simulated-capture.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
+
+## CaptureExposureSource
+
+A procedural/physical source identity without a manufactured linear-master plane.
+
+```ts
+export type CaptureExposureSource = SimulatedCaptureInput["source"] | (Omit<SimulatedCaptureInput["source"], "kind"> & {kind:"scene-radiance-source"});
+```
 
 ## CaptureFloatStorage
 

package/docs/api/color-capture-color.md

@@ -1,6 +1,6 @@
 # color/capture-color.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## calculateCaptureColorTransform
 

package/docs/api/color-srgb-icc.md

@@ -0,0 +1,23 @@
+# color/srgb-icc.ts public contracts
+
+Package **1.4.0**, root API **1.4.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.
+
+## createSrgbIccProfile
+
+Reference: https://registry.color.org/rgb-registry/files/sRGB.pdf and ICC.1:2022.
+This is an original Photivra profile, not a redistributed ICC or operating-system profile.
+Bradford here encodes the D50 profile-connection space; it does not apply shooting WB.
+
+```ts
+export function createSrgbIccProfile():Uint8Array;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SRGB_ICC_PROFILE_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SRGB_ICC_PROFILE_VERSION="0.1.0" as const
+```

package/docs/api/color-white-balance.md

@@ -1,6 +1,6 @@
 # color/white-balance.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## COLOR_TEMPERATURE_WHITE_BALANCE_INTENT_VERSION
 

package/docs/api/composition-image-formation-plan.md

@@ -1,6 +1,6 @@
 # composition/image-formation-plan.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## createProductionCaptureSnapshot
 

package/docs/api/composition-plan-consumer.md

@@ -1,6 +1,6 @@
 # composition/plan-consumer.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## createProductionPlanConsumerManifest
 

package/docs/api/core-calculation-result.md

@@ -1,6 +1,6 @@
 # core/calculation-result.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## AbsoluteUncertaintyEstimate
 

package/docs/api/core-configuration-error.md

@@ -1,6 +1,6 @@
 # core/configuration-error.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## InvalidConfigurationError
 

package/docs/api/core-image-formation.md

@@ -1,6 +1,6 @@
 # core/image-formation.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## getImageFormationContract
 

package/docs/api/core-scientific-assurance.md

@@ -1,6 +1,6 @@
 # core/scientific-assurance.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## ComposedScientificAssurance
 

package/docs/api/core-spectral-composition.md

@@ -1,6 +1,6 @@
 # core/spectral-composition.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## composeSpectralCoverage
 

package/docs/api/core-spectral.md

@@ -1,6 +1,6 @@
 # core/spectral.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## parseSpectralWavelengthBasis
 

package/docs/api/core-validation.md

@@ -1,6 +1,6 @@
 # core/validation.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## InvalidScientificInputError
 

package/docs/api/core-version.md

@@ -1,6 +1,6 @@
 # core/version.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## ENGINE_API_VERSION
 
@@ -10,5 +10,5 @@ POC, schema and model contracts keep their independent versions.
 Release checks enforce equality with package.json and the packed distribution.
 
 ```ts
-ENGINE_API_VERSION = "1.2.0" as const
+ENGINE_API_VERSION = "1.4.0" as const
 ```

package/docs/api/equipment-exposure-capabilities.md

@@ -1,6 +1,6 @@
 # equipment/exposure-capabilities.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## FocalLengthFNumberSample
 

package/docs/api/equipment-generic-tier-assets.md

@@ -1,6 +1,6 @@
 # equipment/generic-tier-assets.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## GenericEquipmentTier
 

package/docs/api/equipment-generic-tier-presets.md

@@ -1,6 +1,6 @@
 # equipment/generic-tier-presets.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## createGenericEquipmentTierSelection
 

package/docs/api/equipment-iso-capabilities.md

@@ -1,6 +1,6 @@
 # equipment/iso-capabilities.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## bindIsoCapabilityToExposureCapabilities
 

package/docs/api/equipment-metering-capabilities.md

@@ -1,6 +1,6 @@
 # equipment/metering-capabilities.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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.
 
 ## assessExposureMeteringProfileCompatibility
 

package/docs/api/equipment-release-capabilities.md

@@ -1,6 +1,6 @@
 # equipment/release-capabilities.ts public contracts
 
-Package **1.2.0**, root API **1.2.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.
+Package **1.4.0**, root API **1.4.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_RELEASE_CAPABILITY_SCHEMA_VERSION