@photivra/engine 1.5.0 → 2.1.0

package/docs/api/exposure-flash.md

@@ -1,16 +1,29 @@
 # exposure/flash.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.
+
+## createHighSpeedSyncIlluminationOverlay
+
+Registers a resolved high-speed-sync burst as a temporal illumination overlay: a rectangular
+waveform over [0, D]. Each line then collects the burst over its own local exposure window.
+
+```ts
+export function createHighSpeedSyncIlluminationOverlay(
+  input: Omit<CreateManualFlashIlluminationOverlayInput, "resolvedSync"> & { resolvedSync: ResolvedHighSpeedFlashSync }
+): ManualFlashIlluminationOverlay;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
 ## createManualFlashIlluminationOverlay
 
-Construct an owned registered temporal illumination overlay from the resolved manual pulse while
-preserving base ambient source identity.
+Builds a temporal illumination overlay from the resolved manual pulse. The identity of the base
+ambient light source is kept.
 
-Manual flash is a registered relative pulse/source overlay on the capture opening-reference clock.
-Ordinary front/rear sync requires a real whole-frame opening interval. HSS/TTL and flash metering
-are unsupported here; source magnitude, optical transport and sensor integration retain their own
-contracts.
+Manual flash is a relative light pulse added on top of the scene light, timed on the capture's
+opening-reference clock. Ordinary front- or rear-curtain sync needs a real interval when the whole
+frame is open at once. High-speed sync (HSS), TTL and flash metering are not handled here. Source
+brightness, optical transport and sensor integration have their own contracts.
 
 ```ts
 export function createManualFlashIlluminationOverlay(
@@ -34,12 +47,21 @@ export interface CreateManualFlashIlluminationOverlayInput {
   flashProfile:
     ManualFlashProfile;
   resolvedSync:
-    ResolvedManualFlashSync;
+    FlashOverlaySyncRegistration;
   illuminationProfileId: string;
   temporalProfileId: string;
 }
 ```
 
+## FLASH_SYNC_CAPABILITY_HSS_SCHEMA_VERSION
+
+Sync-capability schema that may declare high-speed sync (a fast pulse train that acts as continuous light).
+
+```ts
+FLASH_SYNC_CAPABILITY_HSS_SCHEMA_VERSION =
+  "0.2.0" as const
+```
+
 ## FLASH_SYNC_CAPABILITY_SCHEMA_VERSION
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -49,6 +71,22 @@ FLASH_SYNC_CAPABILITY_SCHEMA_VERSION =
   "0.1.0" as const
 ```
 
+## FlashOverlaySyncRegistration
+
+Fields of a resolved sync (ordinary or HSS) needed to register a flash overlay.
+
+```ts
+export type FlashOverlaySyncRegistration = Pick<
+  ResolvedManualFlashSync,
+  | "flashEnabled"
+  | "flashProfileId"
+  | "flashProfileVersion"
+  | "sourceId"
+  | "waveformTimeZeroSecondsFromCaptureReference"
+  | "evidence"
+>;
+```
+
 ## FlashSyncCapabilityProfile
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -56,14 +94,26 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface FlashSyncCapabilityProfile {
   schemaVersion:
-    typeof FLASH_SYNC_CAPABILITY_SCHEMA_VERSION;
+    | typeof FLASH_SYNC_CAPABILITY_SCHEMA_VERSION
+    | typeof FLASH_SYNC_CAPABILITY_HSS_SCHEMA_VERSION;
   profileId: string;
   profileVersion: string;
   captureModeId: string;
   timingProfileId: string;
   supportedOrdinarySyncModes:
     readonly ManualFlashSyncMode[];
-  highSpeedSyncSupported: false;
+  /** Schema 0.1.0 is always false; schema 0.2.0 may declare HSS with {@link highSpeedSync}. */
+  highSpeedSyncSupported: boolean;
+  /** Present exactly when highSpeedSyncSupported is true (schema 0.2.0). */
+  highSpeedSync?: {
+    /**
+     * η: energy of one full-power high-speed-sync burst, as a fraction of one full-power ordinary
+     * pulse, in (0, 1]. The caller declares it from evidence (capacitor and thermal limits). It is
+     * never inferred.
+     */
+    burstEnergyFractionOfFullPulse: number;
+    evidence: readonly EvidenceProvenance[];
+  };
   ordinarySyncRequiresWholeActiveFrameSimultaneouslyExposed:
     true;
   evidence: readonly EvidenceProvenance[];
@@ -71,6 +121,17 @@ export interface FlashSyncCapabilityProfile {
 }
 ```
 
+## HIGH_SPEED_SYNC_MODEL
+
+Model identity of the pulsed quasi-continuous high-speed-sync burst.
+
+```ts
+HIGH_SPEED_SYNC_MODEL = Object.freeze({
+  id: "flash-hss-quasi-continuous-burst",
+  version: "1.0.0"
+} as const)
+```
+
 ## MANUAL_FLASH_PROFILE_SCHEMA_VERSION
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -181,13 +242,13 @@ export type ManualFlashSyncMode =
 
 ## parseFlashSyncCapabilityProfile
 
-Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
-missing required fields and incompatible scientific data fail at this boundary.
+Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data are rejected here.
 
-Manual flash is a registered relative pulse/source overlay on the capture opening-reference clock.
-Ordinary front/rear sync requires a real whole-frame opening interval. HSS/TTL and flash metering
-are unsupported here; source magnitude, optical transport and sensor integration retain their own
-contracts.
+Manual flash is a relative light pulse added on top of the scene light, timed on the capture's
+opening-reference clock. Ordinary front- or rear-curtain sync needs a real interval when the whole
+frame is open at once. High-speed sync (HSS), TTL and flash metering are not handled here. Source
+brightness, optical transport and sensor integration have their own contracts.
 
 ```ts
 export function parseFlashSyncCapabilityProfile(
@@ -199,13 +260,13 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseManualFlashProfile
 
-Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
-missing required fields and incompatible scientific data fail at this boundary.
+Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data are rejected here.
 
-Manual flash is a registered relative pulse/source overlay on the capture opening-reference clock.
-Ordinary front/rear sync requires a real whole-frame opening interval. HSS/TTL and flash metering
-are unsupported here; source magnitude, optical transport and sensor integration retain their own
-contracts.
+Manual flash is a relative light pulse added on top of the scene light, timed on the capture's
+opening-reference clock. Ordinary front- or rear-curtain sync needs a real interval when the whole
+frame is open at once. High-speed sync (HSS), TTL and flash metering are not handled here. Source
+brightness, optical transport and sensor integration have their own contracts.
 
 ```ts
 export function parseManualFlashProfile(
@@ -225,6 +286,54 @@ export type RequestedFlashSyncMode =
   | "high-speed-sync";
 ```
 
+## ResolvedHighSpeedFlashSync
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedHighSpeedFlashSync extends FlashOverlaySyncRegistration {
+  modelId: typeof HIGH_SPEED_SYNC_MODEL.id;
+  modelVersion: typeof HIGH_SPEED_SYNC_MODEL.version;
+  syncMode: "high-speed-sync";
+  syncStatus: "disabled" | "high-speed-sync-resolved";
+  captureModeId: string;
+  timingProfileId: string;
+  syncCapabilityProfileId: string;
+  timeReference: "first-opening-boundary-phase";
+  powerFraction: number;
+  /** η from the sync capability profile. */
+  burstEnergyFractionOfFullPulse: number;
+  /** ∫ pulse(t) dt of the declared ordinary pulse, whose relative peak is 1 (relative multiplier · s). */
+  singlePulseIntegratedRelativeSeconds: number;
+  /** D: burst support covering the first line opening to the last line closing. */
+  burstStartSecondsFromCaptureReference: number;
+  burstEndSecondsFromCaptureReference: number;
+  burstDurationSeconds: number;
+  /** Local (slit) exposure durations t_e over the active frame. */
+  localExposureDurationRangeSeconds: { minimum: number; maximum: number };
+  /** Flash energy each line receives relative to one ordinary pulse at the same power: η·t_e/D. */
+  energyFractionOfSinglePulseRange: { minimum: number; maximum: number };
+  /** Effective guide-number factor relative to the same-power ordinary pulse: √(η·t_e/D). */
+  guideNumberFactorRange: { minimum: number; maximum: number };
+  uniformAcrossActiveFrame: boolean;
+  /** The rectangular high-speed-sync burst, written as a manual pulse profile for the illumination overlay. */
+  burstFlashProfile: ManualFlashProfile | null;
+  releaseFrameBinding:
+    | {
+        sequenceId: string;
+        releaseFrameId: string;
+        frameIndex: number;
+        sceneTimeSecondsFromSequenceStartAtBurstStart: number;
+        sceneTimeSecondsFromSequenceStartAtBurstEnd: number;
+      }
+    | null;
+  hssModeled: true;
+  ttlModeled: false;
+  sensorReadoutTimingUsedAsExposureTiming: false;
+  limitations: readonly string[];
+}
+```
+
 ## ResolvedManualFlashSync
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -287,15 +396,61 @@ export interface ResolvedManualFlashSync {
 }
 ```
 
+## resolveHighSpeedFlashSync
+
+Resolves high-speed (focal-plane) sync (HSS): a fast pulse train that acts as continuous light and
+covers the whole travelling-slit exposure.
+
+At shutter speeds faster than the ordinary sync limit, the shutter's opening and closing edges
+cross the frame as a slit, and the whole frame is never open at once. A single short pulse would
+light only a band.
+
+HSS instead fires a rapid pulse train. It behaves like constant output P over the burst D, from
+the first line opening to the last line closing. Each line collects P·t_e over its slit time t_e.
+- The burst energy is E_burst = η·p·E_pulse. η comes from the sync profile, p is the power
+  fraction and E_pulse is the energy of an ordinary full-power pulse.
+- So P = E_burst/D, and each line receives η·p·E_pulse·t_e/D.
+- Exposure ∝ GN² (inverse-square law, GN = d·N). So, relative to an ordinary pulse at the same
+  power, the effective guide number is GN_HSS/GN = √(η·t_e/D).
+Shortening t_e by one stop therefore costs half a stop of guide number.
+
+Approximations: the pulse train is treated as continuous (pulse period ≪ t_e). Recycle and thermal
+limits are folded into η. Front/rear-curtain placement does not apply, because the burst covers
+the whole exposure.
+
+```ts
+export function resolveHighSpeedFlashSync(input: ResolveHighSpeedFlashSyncInput): ResolvedHighSpeedFlashSync;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveHighSpeedFlashSyncInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveHighSpeedFlashSyncInput {
+  flashEnabled: boolean;
+  /** Ordinary full-power pulse definition; its integral defines the full-power pulse energy. */
+  flashProfile: ManualFlashProfile;
+  /** Schema 0.2.0 profile with highSpeedSyncSupported true. */
+  syncCapabilities: FlashSyncCapabilityProfile;
+  timing: ResolvedCaptureModeTiming;
+  /** Commanded output as a fraction of full power, (0, 1]. */
+  powerFraction: number;
+  releaseFrame?: ResolvedReleaseFrame;
+}
+```
+
 ## resolveManualFlashSync
 
-Place a declared ordinary flash pulse into the actual whole-frame exposure opening interval for
-front or rear sync, or return structured incompatibility.
+Places a declared ordinary flash pulse inside the actual interval when the whole frame is open, for
+front- or rear-curtain sync. Otherwise returns a structured incompatibility.
 
-Manual flash is a registered relative pulse/source overlay on the capture opening-reference clock.
-Ordinary front/rear sync requires a real whole-frame opening interval. HSS/TTL and flash metering
-are unsupported here; source magnitude, optical transport and sensor integration retain their own
-contracts.
+Manual flash is a relative light pulse added on top of the scene light, timed on the capture's
+opening-reference clock. Ordinary front- or rear-curtain sync needs a real interval when the whole
+frame is open at once. High-speed sync (HSS), TTL and flash metering are not handled here. Source
+brightness, optical transport and sensor integration have their own contracts.
 
 ```ts
 export function resolveManualFlashSync(

package/docs/api/exposure-metering-scene-radiance.md

@@ -1,15 +1,16 @@
 # exposure/metering-scene-radiance.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.
 
 ## createSceneRadianceDerivedExposureMeteringSampleSet
 
-Creates a relative pre-exposure meter sample set bound to one validated #85
-provider context.
+Builds a set of relative pre-exposure meter samples tied to one validated
+scene-radiance provider context.
 
-The caller/renderer still supplies the scalar relative samples. This bridge
-validates identity and timing semantics only; it does not convert spectral
-radiance into luminance or define a calibrated meter spectral response.
+The caller or renderer still supplies the relative sample values. This
+bridge only checks identity and timing. It does not convert spectral
+radiance into luminance, and it does not define a calibrated meter spectral
+response.
 
 ```ts
 export function createSceneRadianceDerivedExposureMeteringSampleSet(
@@ -48,11 +49,11 @@ export interface CreateSceneRadianceDerivedExposureMeteringSampleSetInput {
 
 ## parseSceneRadianceMeteringDerivationProfile
 
-Parses the declared approximation used to reduce renderer/provider scene
-information into the scalar relative-linear domain consumed by metering.
+Parses the declared approximation that turns renderer or provider scene data
+into the single relative linear values the meter uses.
 
-This profile explicitly does not authorize a calibrated luminance or
-spectral-to-photometric conversion claim.
+The profile does not support any claim of calibrated luminance or of a
+spectral-to-photometric conversion.
 
 ```ts
 export function parseSceneRadianceMeteringDerivationProfile(

package/docs/api/exposure-metering-target.md

@@ -1,14 +1,15 @@
 # exposure/metering-target.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.
 
 ## createExposureMeterTargetFromMeteringResult
 
-Freezes one metering result into the stable relative exposure target
-consumed by downstream camera-control policy.
+Freezes one metering result into a stable relative exposure target, for
+camera-control logic to use.
 
-The target copies the meter snapshot by value. Future scene/light changes do
-not mutate this object, which is the engine seam needed for AE-lock behavior.
+The target copies the meter snapshot by value. Later changes to the scene or
+light do not change it. This is what the engine provides for AE lock
+(auto-exposure lock).
 
 ```ts
 export function createExposureMeterTargetFromMeteringResult(
@@ -108,9 +109,9 @@ export type ExposureMeterTargetSourceResult =
 
 Sets an absolute exposure-compensation value on a frozen meter target.
 
-Compensation is always re-derived from the uncompensated base target, so
-repeated UI updates cannot accidentally accumulate floating-point/control
-drift. Positive compensation requests more exposure.
+Compensation is always worked out again from the base target without
+compensation, so repeated UI updates cannot build up floating-point or
+control drift. Positive compensation asks for more exposure.
 
 ```ts
 export function setExposureCompensationOnMeterTarget(

package/docs/api/exposure-metering-temporal.md

@@ -1,17 +1,17 @@
 # exposure/metering-temporal.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.
 
 ## meterSceneRadianceTemporalExposure
 
-Meters a declared weighted time-average of scene-radiance-derived relative
-pre-exposure samples.
+Meters a declared weighted time average of relative pre-exposure samples
+derived from scene radiance.
 
-Every temporal sample must already be explicitly bound to one #85 temporal
-illumination profile and one capture time in the
-first-opening-boundary-phase reference. Spatial metering is performed first
-in the same declared profile, then those scalar pre-exposure measurements are
-combined linearly by caller-declared normalized time weights.
+Each time sample must already be bound to one temporal illumination profile
+and one capture time, measured from the first opening-boundary phase. Each
+time sample is metered spatially first, with the same declared profile. The
+resulting single values are then combined linearly using normalized time
+weights that the caller declares.
 
 ```ts
 export function meterSceneRadianceTemporalExposure(

package/docs/api/exposure-metering.md

@@ -1,6 +1,20 @@
 # exposure/metering.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.
+
+## calculateHighlightPriorityPlacementSignal
+
+Relative signal at which a highlight-priority profile places its highlight
+percentile: `saturationRelativeSignal * 2^-headroomStops`.
+
+```ts
+export function calculateHighlightPriorityPlacementSignal(
+  saturationRelativeSignal: number,
+  headroomStops: number
+): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
 ## EXPOSURE_METERING_PROFILE_SCHEMA_VERSION
 
@@ -33,9 +47,37 @@ export type ExposureMeteringPolicy =
         number;
     }
   | {
+      /**
+       * Weighted average that emphasises highlights (unchanged since 1.x).
+       * Brighter samples get the weight `minimumWeightFraction + (1 -
+       * minimumWeightFraction) * (signal / maximum)^exponent`. The weighted mean
+       * is then placed at the profile target.
+       *
+       * This is NOT highlight protection. No sample is placed relative to
+       * saturation. In a mostly mid-grey scene with a small bright area, it
+       * underexposes the mid-tones compared with uniform metering, yet does not
+       * guarantee headroom. Use `highlight-priority` to keep highlights below
+       * saturation.
+       */
       kind: "highlight-weighted";
       minimumWeightFraction: number;
       exponent: number;
+    }
+  | {
+      /**
+       * Highlight-priority placement. The area-weighted `highlightPercentile`
+       * quantile of the relative pre-exposure signal is placed `headroomStops`
+       * below `saturationRelativeSignal`. The profile target must state that
+       * placement exactly: `targetRelativeSignal = saturationRelativeSignal *
+       * 2^-headroomStops` (see {@link calculateHighlightPriorityPlacementSignal}).
+       */
+      kind: "highlight-priority";
+      /** Area-weighted quantile in (0, 1]; 1 places the brightest sample. */
+      highlightPercentile: number;
+      /** Relative pre-exposure signal at which the declared output saturates. */
+      saturationRelativeSignal: number;
+      /** Non-negative headroom in stops between the placed highlight and saturation. */
+      headroomStops: number;
     };
 ```
 
@@ -126,14 +168,31 @@ export interface ExposureMeteringZoneSample {
 }
 ```
 
+## HighlightPriorityMeteringDiagnostics
+
+Diagnostics reported only for the highlight-priority policy.
+
+```ts
+export interface HighlightPriorityMeteringDiagnostics {
+  highlightPercentile: number;
+  /** Lower area-weighted quantile (inverse empirical CDF) of the samples. */
+  percentileRelativeSignal: number;
+  saturationRelativeSignal: number;
+  headroomStops: number;
+  placementRelativeSignal: number;
+  quantileDefinition:
+    "area-weighted-lower-quantile-inverse-empirical-cdf";
+}
+```
+
 ## meterRelativeExposure
 
-Meters relative pre-exposure linear signal over the actual oriented active
-capture frame.
+Meters relative pre-exposure linear signal over the actual active capture
+frame, in its capture orientation.
 
-The first contract is an educational/relative approximation. It is
-intentionally independent of final output crop, display/tone mapping,
-exposure compensation, and automatic exposure setting resolution.
+This first contract is an educational, relative approximation. It
+deliberately ignores the final output crop, display and tone mapping,
+exposure compensation and the choice of automatic exposure settings.
 
 ```ts
 export function meterRelativeExposure(
@@ -159,9 +218,10 @@ export interface MeterRelativeExposureInput {
 
 Parses one generic relative exposure-metering profile.
 
-Schema 0.1.0 is approximation-only and consumes relative pre-exposure
-linear signal. It deliberately does not claim luminance, spectral radiance,
-sensor-plane irradiance, or a specific manufacturer's meter calibration.
+Schema 0.1.0 is an approximation only. It works on relative linear signal
+measured before the exposure. It deliberately does not claim luminance,
+spectral radiance, sensor-plane irradiance or any manufacturer's meter
+calibration.
 
 ```ts
 export function parseExposureMeteringProfile(

package/docs/api/exposure-program-line.md

@@ -1,6 +1,6 @@
 # exposure/program-line.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.
 
 ## EXPOSURE_PROGRAM_LINE_SCHEMA_VERSION
 
@@ -50,10 +50,11 @@ export interface ExposureProgramLineProfile {
 
 Parses a generic educational/product exposure program line.
 
-A program line is control policy, not physics. Nodes declare desired
-aperture/shutter pairs at explicit optical-exposure stops relative to the
-resolver's reference exposure. Resolution later verifies that every node is
-physically consistent with that reference and current equipment capability.
+A program line is control policy, not physics. Each node declares a wanted
+aperture/shutter pair at an explicit number of stops of optical exposure,
+relative to the resolver's reference exposure. The resolver later checks
+that every node is physically consistent with that reference and with what
+the equipment can do.
 
 ```ts
 export function parseExposureProgramLineProfile(

package/docs/api/facade-chart-radiance-batch.md

@@ -0,0 +1,96 @@
+# facade/chart-radiance-batch.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.
+
+## calculateChartRadianceBatch
+
+Float64 CPU reference: every query's value(s), row-major (query, column).
+
+```ts
+export function calculateChartRadianceBatch(input: ChartRadianceBatchInput): { plan: ChartRadianceBatchPlan; values: Float64Array };
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateChartRadianceBatchPlan
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export function calculateChartRadianceBatchPlan(input: ChartRadianceBatchInput): ChartRadianceBatchPlan;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CHART_RADIANCE_BATCH_LIMITS
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+CHART_RADIANCE_BATCH_LIMITS = Object.freeze({ maximumQueries: 24_000_000, maximumWavelengths: 256, maximumChannels: 4 })
+```
+
+## CHART_RADIANCE_BATCH_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+CHART_RADIANCE_BATCH_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## ChartRadianceBatchInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ChartRadianceBatchInput {
+  schemaVersion: typeof CHART_RADIANCE_BATCH_SCHEMA_VERSION;
+  /** An engine chart preset (caller scene functions are not supported here). */
+  scene: ChartScene;
+  illuminant: CaptureIlluminant;
+  illuminanceLux: number;
+  /** Frame height / width. */
+  aspect: number;
+  /** Frame points, interleaved [u0, v0, u1, v1, …]. Finite. */
+  points: Float32Array | Float64Array;
+  /** The wavelengths the queries use, in nanometres (1–256). */
+  wavelengthsNanometers: readonly number[];
+  /** Radiance queries: one wavelength index per point. Exactly one of this and `channelWeights`. */
+  wavelengthIndices?: Uint8Array | Uint16Array;
+  /** Spectral integration: per channel (1–4), one finite weight per wavelength. */
+  channelWeights?: readonly (readonly number[])[];
+}
+```
+
+## ChartRadianceBatchPlan
+
+Validated plan with the resolved chart, illuminant and irradiance scale. Arrays are borrowed.
+
+```ts
+export interface ChartRadianceBatchPlan {
+  chart: ResolvedChartScene;
+  illuminant: ResolvedCaptureIlluminant;
+  irradianceScale: number;
+  queryCount: number;
+  /** Output values per query: 1 for radiance queries, the channel count for spectral integration. */
+  columns: number;
+  mode: "radiance" | "spectral-integral";
+  wavelengthsNanometers: readonly number[];
+  channelWeights: readonly (readonly number[])[] | null;
+  /** Spectral radiance of one material at a wavelength: the provider's own radianceAt for that material. */
+  materialRadiance(material: number, wavelengthNanometers: number): number;
+  /** The reference value of one query and output column (radianceAt, and its wavelength-ordered sum). */
+  queryValue(points: Float32Array | Float64Array, wavelengthIndices: Uint8Array | Uint16Array | undefined, query: number, column: number): number;
+}
+```
+
+## mapEnvironmentDirectionsToChartPoints
+
+Frame points of environment-direction queries on the chart plane, exactly as the planar provider's
+`evaluateRadiance` computes them: look direction l = −o, plane point l·distance/l.z, in frame units.
+
+```ts
+export function mapEnvironmentDirectionsToChartPoints(input: { directions: Float32Array | Float64Array; distanceM: number; metresPerFrameUnit: number }): Float64Array;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.