@photivra/engine 1.5.0 → 2.1.0

package/docs/api/camera-equivalent-focal-length.md

@@ -1,16 +1,15 @@
 # camera/equivalent-focal-length.ts public contracts
 
-Package **1.5.0**, root API **1.5.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.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/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.
 
 ## calculateEquivalentFocalLength35Mm
 
-Calculates conventional 35 mm-equivalent focal length from physical focal
-length and the effective active-capture diagonal.
+Calculates the conventional 35 mm-equivalent focal length from the physical
+focal length and the diagonal of the active capture area.
 
-The physical focal length remains unchanged and continues to be the optical
-input for projection and depth-of-field calculations. Focus distance and
-later digital/output crops are deliberately excluded from this conventional
-equivalence quantity.
+The physical focal length is not changed. It stays the optical input for
+projection and depth-of-field calculations. Focus distance and later digital
+or output crops are deliberately left out of this conventional equivalence.
 
 ```ts
 export function calculateEquivalentFocalLength35Mm(

package/docs/api/camera-field-of-view.md

@@ -1,14 +1,14 @@
 # camera/field-of-view.ts public contracts
 
-Package **1.5.0**, root API **1.5.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.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/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.
 
 ## calculateFieldOfView
 
-Calculates rectilinear angular field of view as
+Calculates the rectilinear angular field of view as
 2 * atan(sensorDimension / (2 * projectionDistance)).
 
-Without focusDistanceM, projectionDistance is nominal focal length for
-backwards-compatible infinity-focus/pinhole behavior. With focusDistanceM,
+Without focusDistanceM, projectionDistance is the nominal focal length. This
+keeps the older infinity-focus (pinhole) behaviour. With focusDistanceM,
 projectionDistance is the ideal Gaussian thin-lens image distance for that
 focus plane.
 
@@ -24,11 +24,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## calculateFieldOfViewBounds
 
-Calculates an asymmetric rectilinear FOV span from signed sensor-plane
-bounds relative to the optical axis.
+Calculates an asymmetric rectilinear field-of-view span from signed
+sensor-plane bounds measured from the optical axis.
 
-This is required for off-center active sensor crops where the optical axis
-is not at the center of the retained rectangle.
+Use it for off-centre sensor crops, where the optical axis is not at the
+centre of the kept rectangle.
 
 ```ts
 export function calculateFieldOfViewBounds(
@@ -58,6 +58,8 @@ export interface CalculateFieldOfViewBoundsInput {
   maximumSensorCoordinateMm: number;
   /** Optional focus distance in metres. */
   focusDistanceM?: number;
+  /** Ideal projection model; omitted or `"rectilinear"` keeps the existing behaviour. */
+  projectionModel?: LensProjectionModel;
 }
 ```
 
@@ -77,6 +79,12 @@ export interface CalculateFieldOfViewInput {
    * infinity-focus/pinhole approximation.
    */
   focusDistanceM?: number;
+  /**
+   * Ideal projection model. Omit it or pass `"rectilinear"` to keep the rectilinear behaviour and
+   * model ids. Other models use the focal length as the mapping scale and do not accept
+   * focusDistanceM.
+   */
+  projectionModel?: LensProjectionModel;
 }
 ```
 

package/docs/api/camera-lens-projection.md

@@ -0,0 +1,246 @@
+# camera/lens-projection.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/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.
+
+## calculateLensProjectionDirection
+
+Inverse-maps one image-plane point to its unit camera-frame scene direction under the declared
+projection model. It rejects points outside the model's image circle. For equirectangular, it
+rejects points outside +/-pi longitude and +/-pi/2 latitude.
+
+```ts
+export function calculateLensProjectionDirection(
+  input: CalculateLensProjectionDirectionInput
+): CalculationResult<LensProjectionDirection>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateLensProjectionDirectionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateLensProjectionDirectionInput {
+  projectionModel: LensProjectionModel;
+  focalLengthMm: number;
+  /** Image-plane point relative to the optical axis, in millimetres. */
+  imagePointMm: { x: number; y: number };
+}
+```
+
+## calculateLensProjectionFieldOfView
+
+Angular field of view across a centred sensor dimension along one axis through the optical
+axis: 2 * theta(d / 2) for radial models and d / f for equirectangular.
+
+For equirectangular, the result is the longitude span for a horizontal dimension and the latitude
+span for a vertical one. A sensor dimension larger than a fisheye's image circle is rejected, not
+clipped.
+
+```ts
+export function calculateLensProjectionFieldOfView(
+  input: CalculateLensProjectionFieldOfViewInput
+): CalculationResult<LensProjectionFieldOfView>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateLensProjectionFieldOfViewBounds
+
+Asymmetric angular span between two signed sensor coordinates on one axis through the optical
+axis, for off-centre crops.
+
+```ts
+export function calculateLensProjectionFieldOfViewBounds(
+  input: CalculateLensProjectionFieldOfViewBoundsInput
+): CalculationResult<LensProjectionFieldOfViewBounds>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateLensProjectionFieldOfViewBoundsInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateLensProjectionFieldOfViewBoundsInput {
+  projectionModel: LensProjectionModel;
+  focalLengthMm: number;
+  /** Signed minimum sensor coordinate along one axis through the optical axis, in mm. */
+  minimumSensorCoordinateMm: number;
+  /** Signed maximum sensor coordinate along the same axis, in mm. */
+  maximumSensorCoordinateMm: number;
+}
+```
+
+## CalculateLensProjectionFieldOfViewInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateLensProjectionFieldOfViewInput {
+  projectionModel: LensProjectionModel;
+  focalLengthMm: number;
+  /** Centred sensor/capture dimension along one axis through the optical axis, in mm. */
+  sensorDimensionMm: number;
+}
+```
+
+## calculateLensProjectionImagePoint
+
+Maps one camera-frame scene direction to its ideal image-plane point under the declared
+projection model.
+
+```ts
+export function calculateLensProjectionImagePoint(
+  input: CalculateLensProjectionImagePointInput
+): CalculationResult<LensProjectionImagePoint>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateLensProjectionImagePointInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateLensProjectionImagePointInput {
+  projectionModel: LensProjectionModel;
+  /**
+   * Projection scale in millimetres: the focal length f of the mapping function, or for
+   * equirectangular the image distance per radian.
+   */
+  focalLengthMm: number;
+  /** Scene direction in the camera frame. Need not be normalized; must be non-zero. */
+  direction: LensDirection;
+}
+```
+
+## LENS_PROJECTION_MODELS
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+LENS_PROJECTION_MODELS: readonly LensProjectionModel[] =
+  Object.freeze([
+    "rectilinear",
+    "fisheye-equidistant",
+    "fisheye-equisolid-angle",
+    "fisheye-stereographic",
+    "fisheye-orthographic",
+    "equirectangular"
+  ])
+```
+
+## LensDirection
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensDirection {
+  /** Camera-frame direction component, +X right. Any positive length. */
+  x: number;
+  /** Camera-frame direction component, +Y up. */
+  y: number;
+  /** Camera-frame direction component along the optical axis toward the scene. */
+  z: number;
+}
+```
+
+## LensProjectionDirection
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensProjectionDirection {
+  projectionModel: LensProjectionModel;
+  /** Unit direction in the camera frame. */
+  direction: LensDirection;
+  fieldAngleRadians: number;
+  imageRadiusMm: number;
+}
+```
+
+## LensProjectionFieldOfView
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensProjectionFieldOfView {
+  projectionModel: LensProjectionModel;
+  degrees: number;
+  radians: number;
+  /** Projection scale used by the mapping, in millimetres. */
+  projectionDistanceMm: number;
+}
+```
+
+## LensProjectionFieldOfViewBounds
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensProjectionFieldOfViewBounds {
+  projectionModel: LensProjectionModel;
+  minimumRadians: number;
+  maximumRadians: number;
+  radians: number;
+  minimumDegrees: number;
+  maximumDegrees: number;
+  degrees: number;
+  projectionDistanceMm: number;
+}
+```
+
+## LensProjectionImagePoint
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensProjectionImagePoint {
+  projectionModel: LensProjectionModel;
+  imagePointMm: { x: number; y: number };
+  /** Angle between the direction and the optical axis, in radians. */
+  fieldAngleRadians: number;
+  /** Distance of the image point from the optical axis, in millimetres. */
+  imageRadiusMm: number;
+}
+```
+
+## LensProjectionModel
+
+Ideal projection model discriminator. `rectilinear` is the engine default.
+
+```ts
+export type LensProjectionModel =
+  | "rectilinear"
+  | "fisheye-equidistant"
+  | "fisheye-equisolid-angle"
+  | "fisheye-stereographic"
+  | "fisheye-orthographic"
+  | "equirectangular";
+```
+
+## parseLensProjectionModel
+
+Runtime parser for the projection discriminator. Rejects (fails closed on) unknown values.
+
+```ts
+export function parseLensProjectionModel(
+  value: unknown
+): LensProjectionModel;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## RadialLensProjectionModel
+
+Radial (rotationally symmetric) projection models.
+
+```ts
+export type RadialLensProjectionModel = Exclude<
+  LensProjectionModel,
+  "equirectangular"
+>;
+```

package/docs/api/camera-projected-object-size.md

@@ -1,14 +1,15 @@
 # camera/projected-object-size.ts public contracts
 
-Package **1.5.0**, root API **1.5.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.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/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.
 
 ## calculateProjectedObjectSize
 
-Calculates the projected size of a fronto-parallel object plane.
+Calculates the projected size of a flat object that faces the camera
+(fronto-parallel).
 
-Without focusDistanceM, the function preserves ideal pinhole projection
-using nominal focal length. With focusDistanceM, it projects to the ideal
-thin-lens sensor plane selected by that focus distance.
+Without focusDistanceM, it uses ideal pinhole projection with the nominal
+focal length. With focusDistanceM, it projects onto the ideal thin-lens
+sensor plane for that focus distance.
 
 ```ts
 export function calculateProjectedObjectSize(

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

@@ -1,6 +1,6 @@
 # capture/capture-export-metadata.ts public contracts
 
-Package **1.5.0**, root API **1.5.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.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/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_EXPORT_METADATA_SCHEMA_VERSION
 
@@ -12,7 +12,7 @@ CAPTURE_EXPORT_METADATA_SCHEMA_VERSION = "0.1.0" as const
 
 ## CaptureExportArtifactIdentity
 
-Caller-owned resource and saved-incarnation UUIDs; no random IDs or wall clock in the engine.
+Resource and saved-file UUIDs supplied by the caller. The engine never makes random IDs or reads the clock.
 
 ```ts
 export interface CaptureExportArtifactIdentity { documentId: string; instanceId: string }
@@ -20,13 +20,13 @@ export interface CaptureExportArtifactIdentity { documentId: string; instanceId:
 
 ## CaptureExportMetadataInput
 
-Metadata-only pairing input. CaptureID must already be a non-nil UUID on the committed capture.
+Input for pairing metadata only. The committed capture must already have a non-nil UUID as its CaptureID.
 
 ```ts
 export interface CaptureExportMetadataInput {
   capture: SimulatedCapture;
   workflow: CaptureExportWorkflow;
-  /** Explicit capture-event UTC timestamp, exactly YYYY-MM-DDTHH:mm:ss.sssZ; never scene time. */
+  /** UTC time of the capture event, exactly YYYY-MM-DDTHH:mm:ss.sssZ. It is never scene time. */
   capturedAtUtc: string;
   raw: CaptureExportArtifactIdentity;
   jpeg: CaptureExportArtifactIdentity;
@@ -35,7 +35,7 @@ export interface CaptureExportMetadataInput {
 
 ## CaptureExportMetadataPair
 
-Equal shared metadata and distinct resource IDs do not prove RAW/JPEG pixel derivation.
+Matching metadata and distinct resource IDs do not prove that the JPEG pixels came from the RAW.
 
 ```ts
 export interface CaptureExportMetadataPair {
@@ -49,7 +49,7 @@ export interface CaptureExportMetadataPair {
 
 ## CaptureExportSharedMetadata
 
-Shared semantic values, not packed EXIF/DNG tags or an XMP packet.
+The shared values, before they are packed into EXIF or DNG tags or an XMP packet.
 
 ```ts
 export interface CaptureExportSharedMetadata {
@@ -60,7 +60,7 @@ export interface CaptureExportSharedMetadata {
   simulatedCapture: true;
   make: "Photivra";
   model: "Photivra Virtual Camera";
-  /** Explicitly the captured engine API version, not a claim of an npm distribution version. */
+  /** The engine API version that made the capture. It does not claim to be an npm package version. */
   software: string;
   creatorTool: string;
   engineApiVersion: string;
@@ -80,7 +80,7 @@ export interface CaptureExportSharedMetadata {
 
 ## CaptureExportWorkflow
 
-Non-generative workflows only; sampled/AI/composite media need a separate reviewed policy.
+Only non-generative workflows. Sampled, AI-generated or composite media would need a separate, reviewed policy.
 
 ```ts
 export type CaptureExportWorkflow = "human-directed-non-generative" | "fully-procedural-non-generative";
@@ -88,7 +88,7 @@ export type CaptureExportWorkflow = "human-directed-non-generative" | "fully-pro
 
 ## createCaptureExportMetadataPair
 
-Projects known capture metadata once for both future writers; never encodes or verifies image data.
+Builds the known capture metadata once, for both the RAW and JPEG writers. It never encodes or checks image data.
 
 ```ts
 export function createCaptureExportMetadataPair(input: CaptureExportMetadataInput): CaptureExportMetadataPair;
@@ -98,7 +98,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseCaptureExportMetadataInput
 
-Fail-closed parser; no default workflow, time, creator, physical-device or file lineage claims.
+Strict parser. It rejects missing values and never fills in a default workflow, time, creator, physical device or file history.
 
 ```ts
 export function parseCaptureExportMetadataInput(value: unknown): CaptureExportMetadataInput;

package/docs/api/capture-dng-import.md

@@ -0,0 +1,134 @@
+# capture/dng-import.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/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.
+
+## DNG_IMPORT_LIMITS
+
+Upper bound for `maximumPixels`. 200 MP (megapixels) of 16-bit codes is 400 MB.
+
+```ts
+DNG_IMPORT_LIMITS = Object.freeze({ defaultMaximumPixels: 64_000_000, maximumPixels: 200_000_000, defaultMaximumIfds: 64, maximumIfds: 1024 })
+```
+
+## DNG_IMPORT_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+DNG_IMPORT_SCHEMA_VERSION = "1.0.0" as const
+```
+
+## DngImportInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DngImportInput {
+  bytes: Uint8Array;
+  /** Pixel-count limit (width x height), checked before any decode allocation. Default 64 000 000, at most 200 000 000. */
+  maximumPixels?: number;
+  /** Total IFDs (main chain plus SubIFDs) visited. Default 64, at most 1024. */
+  maximumIfds?: number;
+}
+```
+
+## ImportedDngBlackLevel
+
+Black level (the code for zero light) pattern, from BlackLevel, BlackLevelRepeatDim and BlackLevelDeltaH/V. Origin is the active-area top-left.
+
+```ts
+export interface ImportedDngBlackLevel {
+  repeatRows: number;
+  repeatColumns: number;
+  /** Row-column-sample order, length repeatRows x repeatColumns x samplesPerPixel. */
+  values: number[];
+  /** Per active-area column offset, or null when absent (all zeros). */
+  deltaH: number[] | null;
+  /** Per active-area row offset, or null when absent (all zeros). */
+  deltaV: number[] | null;
+}
+```
+
+## ImportedDngCfa
+
+Repeating CFA pattern. Its origin is the top-left corner of `activeArea` (DNG 1.7.1.0, PhotometricInterpretation).
+
+```ts
+export interface ImportedDngCfa {
+  repeatRows: number;
+  repeatColumns: number;
+  /** Row-major plane indices into `planeColors`, length repeatRows x repeatColumns. */
+  pattern: number[];
+  /** CFAPlaneColor: 0 red, 1 green, 2 blue, 3 cyan, 4 magenta, 5 yellow, 6 white. Default [0, 1, 2]. */
+  planeColors: number[];
+}
+```
+
+## ImportedDngRaw
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ImportedDngRaw {
+  schemaVersion: typeof DNG_IMPORT_SCHEMA_VERSION;
+  byteOrder: "little-endian" | "big-endian";
+  /** DNGVersion bytes, or null for a TIFF-EP file without DNG tags. */
+  dngVersion: [number, number, number, number] | null;
+  make: string | null;
+  model: string | null;
+  uniqueCameraModel: string | null;
+  /** TIFF/Exif Orientation 1..8 (default 1). Codes are returned in stored, not oriented, order. */
+  orientation: number;
+  width: number;
+  height: number;
+  samplesPerPixel: number;
+  bitsPerSample: number;
+  compression: "uncompressed" | "lossless-jpeg";
+  photometricInterpretation: "cfa" | "linear-raw";
+  /** Stored raw codes, row-major then sample, length width x height x samplesPerPixel. */
+  codes: Uint16Array;
+  cfa: ImportedDngCfa | null;
+  /** LinearizationTable when present; not applied to `codes`. */
+  linearizationTable: Uint16Array | null;
+  blackLevel: ImportedDngBlackLevel;
+  /** WhiteLevel per sample (default 2^bitsPerSample − 1). */
+  whiteLevel: number[];
+  /** ActiveArea as a rectangle (default the whole image). */
+  activeArea: ImportedDngRect;
+  /** DefaultCropOrigin/Size relative to the active-area origin; may be fractional (RATIONAL). */
+  defaultCrop: ImportedDngRect;
+  /** XYZ → camera (reference) matrices, row-major colorPlanes x 3, or null. */
+  colorMatrix1: number[] | null;
+  colorMatrix2: number[] | null;
+  /** CalibrationIlluminant1/2 (Exif LightSource code), or null when absent. */
+  calibrationIlluminant1: number | null;
+  calibrationIlluminant2: number | null;
+  /** AsShotNeutral in camera (reference) coordinates, or null. */
+  asShotNeutral: number[] | null;
+  /** RawDataUniqueID as 32 lowercase hex digits, or null. */
+  rawDataUniqueId: string | null;
+}
+```
+
+## ImportedDngRect
+
+Half-open raster rectangle in stored-image pixel coordinates (+X right, +Y down).
+
+```ts
+export interface ImportedDngRect { x: number; y: number; width: number; height: number }
+```
+
+## parseDngRawImage
+
+Parse one DNG or TIFF-EP file and decode its primary CFA or LinearRaw image (the first IFD with
+NewSubFileType 0 and PhotometricInterpretation 32803 or 34892, in IFD-chain then SubIFD order).
+
+Supported raw data: Compression 1 at 8..16 bits/sample (8 bits as bytes, 16 bits in the file byte
+order, other depths packed MSB-first with byte-aligned rows, per DNG BitsPerSample) and Compression 7
+lossless Huffman JPEG (T.81 Annex H) in strips or tiles, chunky planar configuration only.
+
+```ts
+export function parseDngRawImage(input: DngImportInput): ImportedDngRaw;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

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

@@ -1,14 +1,17 @@
 # capture/environment-raw-producer.ts public contracts
 
-Package **1.5.0**, root API **1.5.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.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/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.
 
 ## EnvironmentSensorRawFrame
 
-Approximate executed provider-to-RAW lineage. sites retain per-site optical/EQE
-results; raw retains charge, capacity, seeded-noise/readout diagnostics and exact
-native frame. providerEvaluationCount is actual bounded work, not a quality score.
-Conservative verification/activation flags belong to this standalone adapter;
-a parent production plan records its own graph execution without upgrading them.
+Result: the approximate record of what ran, from provider to RAW.
+
+- `sites` keeps the per-site optics and EQE results.
+- `raw` keeps charge, capacity, seeded-noise and readout diagnostics, and the exact native frame.
+- `providerEvaluationCount` is the actual (bounded) work done, not a quality score.
+
+The cautious verification and activation flags belong to this standalone function. A parent
+production plan records its own execution and does not upgrade them.
 
 ```ts
 export interface EnvironmentSensorRawFrame {
@@ -24,9 +27,12 @@ export interface EnvironmentSensorRawFrame {
 
 ## simulateEnvironmentSensorRawFrame
 
-Preflight complete native coverage and aggregate support before invoking supplied
-provider code, then reuse dark/completeness/capacity/noise/ADC ownership. The
-returned RAW frame feeds the existing reconstruction and paired export APIs.
+Simulates a RAW frame from a scene-radiance provider.
+
+Before calling any provider code, it checks that the sites cover the full native
+frame and that all inputs are supported. Dark current, charge completeness,
+capacity, noise and ADC use the existing sensor modules. The returned RAW frame
+works with the existing reconstruction and paired-export APIs.
 
 ```ts
 export function simulateEnvironmentSensorRawFrame(input: SimulateEnvironmentSensorRawFrameInput): CalculationResult<EnvironmentSensorRawFrame>;
@@ -36,13 +42,13 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## SimulateEnvironmentSensorRawFrameInput
 
-Full native site order; generated photo/dark charge cannot be supplied as a shortcut.
+All native sites, in native order. Generated photo or dark charge cannot be passed in as a shortcut.
 
 ```ts
 export interface SimulateEnvironmentSensorRawFrameInput {
   frame: SensorRawProducerInput["frame"];
   sceneBinding: { sceneStateId: string; providerSceneId: string; evidence: readonly EvidenceProvenance[] };
-  /** Shared shutter schedule is bound to the committed frame duration. */
+  /** The shared shutter schedule, tied to the committed frame duration. */
   exposureWindow: NonNullable<SensorRawProducerInput["exposureWindow"]>;
   sites: readonly {
     environment: Omit<CalculateEnvironmentSensorPhotoSignalInput, "evaluateRadiance" | "evaluateApertureRadiance">;

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

@@ -0,0 +1,16 @@
+# capture/export-jpeg.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/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.
+
+## EXPORT_JPEG_ENCODER_ID
+
+Identifies the exact byte output of the baseline encoder.
+
+Version 2 (engine 2.0.0) uses the fixed cosine table below instead of runtime `Math.cos`, and rounds
+quantized coefficients half away from zero. Compared with version 1, bytes can differ only where a
+coefficient before rounding was within about one ULP (unit in the last place) of a half-integer, or
+was exactly a negative half-integer. The repository's test images are unchanged.
+
+```ts
+EXPORT_JPEG_ENCODER_ID = "photivra-baseline-jpeg-444-v2" as const
+```