@photivra/engine 1.5.0 → 2.1.0

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

@@ -1,10 +1,10 @@
 # capture/raw-frame-reconstruction.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.
 
 ## parseRawFrameReconstructionInput
 
-Revalidates committed RAW codes/geometry and complete phase dispatch; no external plane may supply output values.
+Revalidates the committed RAW codes and geometry and checks that every CFA phase has a kernel. No external image plane can supply output values.
 
 ```ts
 export function parseRawFrameReconstructionInput(value: unknown): RawFrameReconstructionInput;
@@ -22,7 +22,7 @@ RAW_FRAME_RECONSTRUCTION_SCHEMA_VERSION = "0.1.0" as const
 
 ## RawFrameReconstruction
 
-Traceable virtual sensor-channel values, not colorimetric RGB or a rendered photograph.
+Traceable sensor-channel values. Not colorimetric RGB and not a rendered photograph.
 
 ```ts
 export interface RawFrameReconstruction {
@@ -36,10 +36,10 @@ export interface RawFrameReconstruction {
     pixelWidth: number;
     pixelHeight: number;
     channelIds: readonly string[];
-    /** Interleaved native-region row-major values; black-subtracted normalization, signed. */
+    /** Interleaved values over the native region, row-major. Black-subtracted and normalized; can be negative. */
     samples: readonly number[];
   };
-  /** Child envelopes and exact weighted RAW contributions, in matching native-region row-major order. */
+  /** Per-pixel result envelopes and the exact weighted RAW contributions, in the same row-major order. */
   pixels: readonly CalculationResult<SensorRawReconstructedPixel>[];
   lineage: "engine-reconstructed-from-attached-raw";
   producerOriginVerified: false;
@@ -54,7 +54,7 @@ export interface RawFrameReconstruction {
 
 ## RawFrameReconstructionInput
 
-Bounded reference handoff; region coordinates stay in the full native sensor frame.
+Input to the bounded reference reconstruction. Region coordinates are in the full native sensor frame.
 
 ```ts
 export interface RawFrameReconstructionInput {
@@ -66,7 +66,7 @@ export interface RawFrameReconstructionInput {
 
 ## RawFrameReconstructionPhaseProfile
 
-Kernel selection is explicit per absolute native CFA repeat phase, not guessed from channel names.
+A kernel is chosen explicitly for each absolute native CFA repeat phase, not guessed from channel names.
 
 ```ts
 export interface RawFrameReconstructionPhaseProfile {
@@ -78,7 +78,7 @@ export interface RawFrameReconstructionPhaseProfile {
 
 ## resolveRawFrameReconstruction
 
-Delegates each pixel to #14's explicit linear reconstruction using only the attached native RAW samples.
+Computes each pixel with the sensor module's explicit linear reconstruction, using only the attached native RAW samples.
 
 ```ts
 export function resolveRawFrameReconstruction(input: RawFrameReconstructionInput): CalculationResult<RawFrameReconstruction>;

package/docs/api/capture-raw-white-level.md

@@ -0,0 +1,37 @@
+# capture/raw-white-level.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.
+
+## calculateEffectiveSaturationCode
+
+W as documented above; throws unless B < W ≤ D. Ties round up, matching the ADC.
+
+Accepts an `EffectiveSaturationReadout` or a whole `SensorRawCodeSample`, optionally with the
+regime's `integralNonLinearity`. From 2.0.0 any other field is rejected with
+`InvalidConfigurationError`, and the `integralNonLinearity` record and its knots are checked too.
+
+```ts
+export function calculateEffectiveSaturationCode(readout: EffectiveSaturationReadout): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## EffectiveSaturationReadout
+
+Readout fields the white level depends on; a `SensorRawCodeSample` satisfies this shape.
+
+```ts
+export interface EffectiveSaturationReadout {
+  physicalChargeCapacityElectrons: number;
+  preAdcSaturationElectronEquivalent: number;
+  systemConversionGainElectronsPerCode: number;
+  blackLevelCode: number;
+  digitalSaturationCode: number;
+  /** ADC code-range maximum (2^bits − 1), when known. */
+  adcMaximumCode?: number;
+  /** Post-ADC digital gain d ≥ 1; omitted means 1. */
+  digitalGain?: number;
+  /** Declared ADC integral non-linearity, the readout regime's `adc.integralNonLinearity`. */
+  integralNonLinearity?: { kind: "piecewise-linear-code-offset"; knots: readonly { code: number; offsetCodes: number }[] };
+}
+```

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

@@ -1,6 +1,6 @@
 # capture/release-sequence.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.
 
 ## CancelledReleaseSequence
 
@@ -37,8 +37,8 @@ export interface CancelReleaseSequenceInput {
 
 ## createCancelledReleaseSequence
 
-Produces an explicit cancelled sequence state without mutating the scheduled
-source sequence or leaving the completed/omitted frame boundary ambiguous.
+Returns a cancelled copy of a sequence. The original scheduled sequence is not
+changed, and it is always clear which frames were completed and which were dropped.
 
 ```ts
 export function createCancelledReleaseSequence(
@@ -215,11 +215,10 @@ export interface ResolvedReleaseSequence {
 
 ## resolveReleaseSequence
 
-Resolves one deterministic logical still-release sequence.
+Resolves one deterministic 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.
+It schedules logical exposures only; how the sensor captures each one is
+handled elsewhere. Render speed or frame rate is never used as capture timing.
 
 ```ts
 export function resolveReleaseSequence(

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

@@ -1,10 +1,10 @@
 # capture/sensor-raw-frame.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.
 
 ## createSensorRawFrame
 
-Commits native RAW samples and capture metadata; no demosaic, WB, tone or format packing.
+Commits native RAW samples and capture metadata. No demosaicing, WB, tone mapping or file packing.
 
 ```ts
 export function createSensorRawFrame(input: SensorRawFrameInput): SensorRawFrame;
@@ -14,7 +14,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSensorRawFrameInput
 
-Validates dense bounded native coverage and exact CFA/mode/site/code identity, without IO.
+Checks that every native site has one sample, within limits, and that CFA, mode, site and code identities match exactly. No I/O.
 
 ```ts
 export function parseSensorRawFrameInput(value: unknown): SensorRawFrameInput;
@@ -32,7 +32,7 @@ SENSOR_RAW_FRAME_SCHEMA_VERSION = "0.1.0" as const
 
 ## SensorRawFrame
 
-Immutable RAW attachment. Structural validation does not prove producer truth or DNG compatibility.
+Immutable attached RAW frame. Passing the structural checks does not prove the producer was correct or that the data is DNG-compatible.
 
 ```ts
 export interface SensorRawFrame extends SensorRawFrameInput {
@@ -49,7 +49,7 @@ export interface SensorRawFrame extends SensorRawFrameInput {
 
 ## SensorRawFrameInput
 
-Declared attachment of #14 native CFA samples to a committed photographic capture.
+Declares that native CFA samples from the sensor model belong to a committed photographic capture.
 
 ```ts
 export interface SensorRawFrameInput {
@@ -60,7 +60,7 @@ export interface SensorRawFrameInput {
   colorSamplingProfile: SensorColorSamplingProfile;
   bindingProfile: NativeEffectiveRasterColorSamplingBindingProfile;
   containerBitDepth: 16;
-  /** Exactly one sample per full native site, row-major; no processed RGB masking. */
+  /** Exactly one sample per native site, row-major. Not processed RGB with a mask applied. */
   samples: readonly SensorRawCaptureSample[];
 }
 ```

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

@@ -1,10 +1,10 @@
 # capture/sensor-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.
 
 ## parseSensorRawProducerInput
 
-Validates complete native exposure inputs; no charge/noise/RAW code is accepted as a shortcut.
+Validates the complete per-site exposure inputs. Charge, noise or RAW codes are never accepted as a shortcut.
 
 ```ts
 export function parseSensorRawProducerInput(value: unknown): SensorRawProducerInput;
@@ -14,10 +14,14 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## SENSOR_RAW_PRODUCER_NOISE_MODEL
 
-Capture noise model identity binds the seed schedule and signed electronic readout behavior.
+Version of the capture noise model. It fixes the hashed per-site seed schedule and the signed electronic
+readout behaviour.
+
+0.4.0: exact ADC rounding with ties up, normal-approximation Poisson draws for means of 1e9 and above,
+optional post-ADC digital gain and INL (integral non-linearity), and optional per-sensor fixed-pattern noise.
 
 ```ts
-SENSOR_RAW_PRODUCER_NOISE_MODEL = Object.freeze({ id: "photivra-native-raw-noise", version: "0.2.0" } as const)
+SENSOR_RAW_PRODUCER_NOISE_MODEL = Object.freeze({ id: "photivra-native-raw-noise", version: "0.4.0" } as const)
 ```
 
 ## SENSOR_RAW_PRODUCER_SCHEMA_VERSION
@@ -30,7 +34,7 @@ SENSOR_RAW_PRODUCER_SCHEMA_VERSION = "0.3.0" as const
 
 ## SensorRawProducerExposureWindowInput
 
-Full-native exposure schedule; sampling coordinates belong to the producer.
+Exposure schedule for the full sensor. The producer owns the sampling coordinates.
 
 ```ts
 export type SensorRawProducerExposureWindowInput = Omit<CalculateCaptureExposureWindowsInput,
@@ -39,20 +43,20 @@ export type SensorRawProducerExposureWindowInput = Omit<CalculateCaptureExposure
 
 ## SensorRawProducerInput
 
-Bounded single-frame handoff, never a conversion from independent RGB pixels.
+Input for one bounded frame. It is never a conversion from separate RGB pixels.
 
 ```ts
 export interface SensorRawProducerInput {
   frame: Omit<SensorRawFrameInput, "samples">;
   sites: readonly SensorRawProducerSiteInput[];
-  /** Omission preserves the existing global 0..shutterSeconds event contract. */
+  /** If omitted, every event uses the existing global window 0..shutterSeconds. */
   exposureWindow?: SensorRawProducerExposureWindowInput;
 }
 ```
 
 ## SensorRawProducerResult
 
-Engine-produced codes and child diagnostics; upstream radiance/response truth remains declared.
+Codes produced by the engine, with per-step diagnostics. The upstream radiance and response are as declared, not verified.
 
 ```ts
 export interface SensorRawProducerResult {
@@ -60,7 +64,7 @@ export interface SensorRawProducerResult {
   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";
+  seedSchedule: "murmur3-capture-seed-native-index-stream-v2";
   frame: SensorRawFrame;
   localExposureWindows?: CalculationResult<CaptureExposureWindows>;
   sites: readonly {
@@ -74,7 +78,7 @@ export interface SensorRawProducerResult {
 
 ## SensorRawProducerSiteInput
 
-One declared EQE/dark/completeness event and explicit readout state per native site.
+For each native site: one declared exposure event (EQE photo signal, dark signal, charge completeness) and its readout state.
 
 ```ts
 export interface SensorRawProducerSiteInput {
@@ -84,12 +88,14 @@ export interface SensorRawProducerSiteInput {
   operatingStateId: string;
   readoutProfile: SensorReadoutConversionProfile;
   regimeId: string;
+  /** Optional fixed-pattern noise (FPN) for this sensor; one profile for the whole frame. Omit it to disable FPN. */
+  fixedPatternNoise?: SensorFixedPatternNoiseProfile;
 }
 ```
 
 ## simulateSensorRawFrame
 
-Composes existing accumulated-charge → capacity → Poisson → read noise/ADC → native sample → immutable frame contracts.
+Runs accumulated charge → capacity → Poisson noise → read noise and ADC → native sample → immutable frame.
 
 ```ts
 export function simulateSensorRawFrame(input: SensorRawProducerInput): CalculationResult<SensorRawProducerResult>;

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

@@ -1,10 +1,10 @@
 # capture/simulated-capture.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.
 
 ## CaptureExposureSource
 
-A procedural/physical source identity without a manufactured linear-master plane.
+Identifies a procedural or physical source, without making up a linear master plane.
 
 ```ts
 export type CaptureExposureSource = SimulatedCaptureInput["source"] | (Omit<SimulatedCaptureInput["source"], "kind"> & {kind:"scene-radiance-source"});
@@ -12,7 +12,7 @@ export type CaptureExposureSource = SimulatedCaptureInput["source"] | (Omit<Simu
 
 ## CaptureFloatStorage
 
-External bytes are caller-owned; the engine never reads a path or URL.
+External bytes belong to the caller. The engine never reads a path or URL.
 
 ```ts
 export type CaptureFloatStorage =
@@ -22,7 +22,7 @@ export type CaptureFloatStorage =
 
 ## CaptureLinearImageState
 
-Distinct linear domains, not one interchangeable 'linear' flag.
+Which kind of linear data a plane holds. These are different domains, not one interchangeable "linear" flag.
 
 ```ts
 export type CaptureLinearImageState = "scene-referred-xyz" | "virtual-sensor-channels" | "color-transformed-linear-rgb";
@@ -30,7 +30,7 @@ export type CaptureLinearImageState = "scene-referred-xyz" | "virtual-sensor-cha
 
 ## CaptureLinearPlane
 
-Linear float plane; all channels are co-sited and interleaved in row-major order.
+Linear float plane. All channels are sampled at the same positions and interleaved in row-major order.
 
 ```ts
 export interface CaptureLinearPlane {
@@ -42,9 +42,9 @@ export interface CaptureLinearPlane {
   pixelHeight: number;
   channelIds: readonly string[];
   colorProfile: CapturePublicProfileReference | null;
-  /** Defined for colorimetric/RGB encodings; null for unresolved sensor channels. */
+  /** Set for colorimetric (RGB) encodings; null for raw sensor channels with no colour meaning yet. */
   encodingReferenceWhiteXyz: CaptureWhiteXyz | null;
-  /** Value normalization, independent of capture saturation or eventual integer white. */
+  /** How values are normalized. Independent of capture saturation and of any later integer white level. */
   referenceWhiteValue: number;
   whiteBalanceApplication: "intent-only" | "applied-rgb-gains" | "applied-chromatic-adaptation" | "not-applicable";
   captureSaturation:
@@ -65,7 +65,7 @@ export interface CapturePublicProfileReference { id: string; version: string }
 
 ## CaptureWhiteBalanceIntent
 
-A resolved #108 choice, sanitized for public metadata. No estimator is rerun.
+A resolved white-balance state (ResolvedWhiteBalanceState), cleaned for public metadata. No WB estimator is rerun.
 
 ```ts
 export interface CaptureWhiteBalanceIntent {
@@ -87,7 +87,7 @@ export interface CaptureWhiteXyz { x: number; y: 1; z: number }
 
 ## createCaptureWhiteBalanceIntent
 
-Converts validated shooting WB into a public metadata allowlist, discarding private extras.
+Converts the validated shooting WB to the allowed public metadata fields, dropping private extras.
 
 ```ts
 export function createCaptureWhiteBalanceIntent(input: { state: ResolvedWhiteBalanceState }): CaptureWhiteBalanceIntent;
@@ -97,7 +97,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## createSimulatedCapture
 
-Commits a format-neutral float master manifest; no radiance generation, clamp, WB or export encoding.
+Commits a capture with a manifest of float master planes. No radiance generation, clipping, WB or file encoding.
 
 ```ts
 export function createSimulatedCapture(input: SimulatedCaptureInput): CalculationResult<SimulatedCapture>;
@@ -117,7 +117,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## resolveSimulatedCapturePlane
 
-Requires an exact plane image state; callers may not substitute another kind of 'linear'.
+Requires the exact image state of the plane. Callers cannot substitute another kind of "linear".
 
 ```ts
 export function resolveSimulatedCapturePlane(input: {
@@ -129,7 +129,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## serializeSimulatedCapture
 
-Canonical allowlisted JSON, including semantic samples/IDs, not private caches or file layout.
+Canonical JSON of the allowed fields, including sample values and IDs. Excludes private caches and file layout.
 
 ```ts
 export function serializeSimulatedCapture(input: { capture: SimulatedCapture }): string;
@@ -147,7 +147,7 @@ SIMULATED_CAPTURE_SCHEMA_VERSION = "0.2.0" as const
 
 ## SimulatedCapture
 
-Immutable committed value. Geometry/focal equivalence are derived, never caller overrides.
+The immutable committed capture. Geometry and equivalent focal length are computed, never taken from the caller.
 
 ```ts
 export interface SimulatedCapture extends SimulatedCaptureInput {
@@ -160,7 +160,7 @@ export interface SimulatedCapture extends SimulatedCaptureInput {
 
 ## SimulatedCaptureInput
 
-Format-neutral input from an upstream master/capture provider, not a preview image.
+Input from an upstream master or capture provider, independent of file format. Not a preview image.
 
 ```ts
 export interface SimulatedCaptureInput {
@@ -179,7 +179,7 @@ export interface SimulatedCaptureInput {
     dynamicRangeHistory: "unknown" | "no-loss-declared" | "upstream-clipped";
   };
   whiteBalanceIntent: CaptureWhiteBalanceIntent | null;
-  /** Adopted/WB white is a camera choice, not automatically the encoding white. */
+  /** The adopted (WB) white is a camera choice. It is not automatically the encoding white. */
   adoptedWhiteXyz: CaptureWhiteXyz | null;
   models: readonly { profile: CapturePublicProfileReference; scientificStatus: ProvenanceKind; publicEvidenceIds: readonly string[] }[];
   planes: readonly CaptureLinearPlane[];

package/docs/api/color-camera-color-matrix.md

@@ -0,0 +1,103 @@
+# color/camera-color-matrix.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.
+
+## CameraColorMatrixFit
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CameraColorMatrixFit {
+  constraint: CameraMatrixFitConstraint;
+  /** Row-major camera RGB → XYZ (XYZ white Y = 1; camera white green = 1). */
+  cameraRgbToXyz: ColorMatrix3x3;
+  xyzToCameraRgb: ColorMatrix3x3;
+  illuminantWhiteXyz: CieXyzTristimulus;
+  /** Camera response to the perfect diffuser (green = 1); its reciprocal gives neutral WB gains. */
+  cameraWhiteRgb: ColorVector3;
+  patches: readonly CameraMatrixPatchReport[];
+  meanDeltaE2000: number;
+  maximumDeltaE2000: number;
+  /** Root-mean-square XYZ residual over all patches and components. */
+  rmsXyzResidual: number;
+}
+```
+
+## CameraMatrixFitConstraint
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type CameraMatrixFitConstraint = "least-squares" | "white-point-preserving-least-squares";
+```
+
+## CameraMatrixPatchReport
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CameraMatrixPatchReport {
+  patchId: string;
+  cameraRgb: ColorVector3;
+  targetXyz: CieXyzTristimulus;
+  predictedXyz: CieXyzTristimulus;
+  deltaE2000: number;
+}
+```
+
+## CameraMatrixTrainingPatch
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CameraMatrixTrainingPatch {
+  patchId: string;
+  reflectance: ColorimetricSpectrum;
+}
+```
+
+## CameraSpectralSensitivities
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CameraSpectralSensitivities {
+  red: ColorimetricSpectrum;
+  green: ColorimetricSpectrum;
+  blue: ColorimetricSpectrum;
+}
+```
+
+## estimateCameraColorMatrix
+
+Fits a camera-RGB → XYZ matrix from spectral sensitivities, training reflectances,
+an illuminant and CMFs, and reports the per-patch CIEDE2000 residual.
+
+```ts
+export function estimateCameraColorMatrix(input: EstimateCameraColorMatrixInput): CalculationResult<CameraColorMatrixFit>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## EstimateCameraColorMatrixInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface EstimateCameraColorMatrixInput {
+  quadratureNodes: readonly ColorimetricQuadratureNode[];
+  illuminant: ColorimetricSpectrum;
+  cameraSpectralSensitivities: CameraSpectralSensitivities;
+  patches: readonly CameraMatrixTrainingPatch[];
+  colorMatchingFunctions: ColorMatchingFunctionsSource;
+  constraint: CameraMatrixFitConstraint;
+}
+```
+
+## MAX_CAMERA_MATRIX_TRAINING_PATCHES
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+MAX_CAMERA_MATRIX_TRAINING_PATCHES = 10_000
+```

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

@@ -1,12 +1,14 @@
 # color/capture-color.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.
 
 ## calculateCaptureColorTransform
 
-Converts a bounded inline XYZ/ideal-camera plane to unclamped linear sRGB.
-Reuses resolved WB intent; never estimates illumination or changes exposure/noise.
-XYZ diagonal adaptation is explicitly an approximation, distinct from RGB gains.
+Converts a bounded inline XYZ (ideal-camera) plane to unclamped linear sRGB.
+It reuses the resolved white-balance intent. It never estimates the lighting and never changes
+exposure or noise. Adapting to the adopted white (XYZ diagonal by default, or an explicit
+Bradford or CAT16 cone-space transform) is labelled an approximation, and
+is separate from RGB gains.
 
 ```ts
 export function calculateCaptureColorTransform(input: CaptureColorTransformInput): CalculationResult<CaptureColorTransformResult>;
@@ -22,9 +24,18 @@ The exact contract is declared below; use the domain guide for assumptions and s
 CAPTURE_COLOR_MODEL_VERSION = "0.1.0" as const
 ```
 
+## CaptureChromaticAdaptationTransform
+
+Cone-space transform for adapting to the adopted white. If omitted, the original
+XYZ-diagonal scaling (model id `photivra-xyz-diagonal-adaptation`) is used unchanged.
+
+```ts
+export type CaptureChromaticAdaptationTransform = "bradford" | "cat16";
+```
+
 ## CaptureColorModel
 
-Profile data exposes complete row-major matrices and domain conditions to consumers.
+Profile data gives callers the complete row-major matrices and the conditions where they apply.
 
 ```ts
 export interface CaptureColorModel {
@@ -44,7 +55,7 @@ export interface CaptureColorModel {
 
 ## CaptureColorTransformInput
 
-IDs identify a new derived plane; source capture stays immutable.
+IDs name a new derived plane. The source capture is never changed.
 
 ```ts
 export interface CaptureColorTransformInput {
@@ -69,25 +80,25 @@ export interface CaptureColorTransformResult {
   whiteBalance: CaptureColorWhiteBalance;
   /** Matrix on CIE XYZ, identity when no adaptation; row-major, dimensionless. */
   chromaticAdaptationMatrix: Matrix;
-  /** False: even adopted-white scaling is a camera choice under mixed illumination. */
+  /** False: under mixed lighting, even scaling to the adopted white is a choice the camera makes. */
   claimsUniqueSceneWhite: false;
 }
 ```
 
 ## CaptureColorWhiteBalance
 
-One explicit color interpretation; gains and adaptation cannot silently double-apply WB.
+One explicit colour interpretation. Gains and adaptation cannot both apply white balance by accident.
 
 ```ts
 export type CaptureColorWhiteBalance =
   | { kind: "preserve-intent" }
   | { kind: "apply-resolved-rgb-gains"; channelBasis: CapturePublicProfileReference }
-  | { kind: "adopted-white-xyz-scaling" };
+  | { kind: "adopted-white-xyz-scaling"; transform?: CaptureChromaticAdaptationTransform };
 ```
 
 ## LINEAR_CAPTURE_RGB_PROFILE
 
-Linear light, sRGB primaries/D65; no sRGB transfer curve is applied.
+Linear light with sRGB primaries and a D65 white. No sRGB transfer curve is applied.
 
 ```ts
 LINEAR_CAPTURE_RGB_PROFILE = Object.freeze({ id: "linear-srgb-d65", version: CAPTURE_COLOR_MODEL_VERSION })
@@ -95,7 +106,7 @@ LINEAR_CAPTURE_RGB_PROFILE = Object.freeze({ id: "linear-srgb-d65", version: CAP
 
 ## parseCaptureColorTransformInput
 
-Validates the entire capture and explicit transform policy across untrusted JSON boundaries.
+Validates the whole capture and its explicit transform policy, read from untrusted JSON.
 
 ```ts
 export function parseCaptureColorTransformInput(value: unknown): CaptureColorTransformInput;