@photivra/engine 1.4.0 → 2.0.0

package/docs/api/processing-panorama.md

@@ -0,0 +1,82 @@
+# processing/panorama.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.
+
+## createPanoramaTask
+
+Stitches frames with known rotations onto a cylindrical or equirectangular canvas.
+
+```ts
+export function createPanoramaTask(input: PanoramaInput, provider: ProcessingProvider): ProcessingTask<PanoramaOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PanoramaCanvas
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PanoramaCanvas {
+  projection: "equirectangular" | "cylindrical";
+  width: number;
+  height: number;
+  /** [min, max] longitude θ in radians across the canvas columns (left → right). */
+  longitudeRangeRad: readonly [number, number];
+  /** [min, max] latitude φ in radians (bottom → top); cylindrical rows are linear in tan φ. */
+  latitudeRangeRad: readonly [number, number];
+}
+```
+
+## PanoramaFrame
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PanoramaFrame {
+  image: ProcessingRgbImage;
+  /** Rectilinear focal length in pixels (same pixel pitch on both axes). */
+  focalLengthPixels: number;
+  /** Principal point in pixel coordinates (pixel centres at i + 0.5); default the image centre. */
+  principalPointPixels?: { x: number; y: number };
+  /** Camera rotation relative to the reference camera: pitch/yaw/roll radians, engine sign convention. */
+  rotationRad: { pitch: number; yaw: number; roll: number };
+}
+```
+
+## PanoramaInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PanoramaInput {
+  frames: readonly PanoramaFrame[];
+  canvas: PanoramaCanvas;
+  /** Default `feather`. */
+  blending?: "feather" | "multi-band";
+  /** Default `gain` (Brown & Lowe 2007); `none` keeps frame intensities. */
+  exposureCompensation?: "none" | "gain";
+  /** Normalized intensity noise σ_N; default 0.04 (≈ 10/255, the published 8-bit value). */
+  gainNoiseSigma?: number;
+  /** Gain prior σ_g; default 0.1. */
+  gainPriorSigma?: number;
+  /** Multi-band pyramid levels; default min(4, auto). Coarse bands wider than the frame overlap mix
+   * low frequencies that were normalized differently, so keep 2^(levels−1) well below the overlap width. */
+  pyramidLevels?: number;
+  maximumWorkingBytes?: number;
+}
+```
+
+## PanoramaOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PanoramaOutput extends ProcessingRgbImage {
+  /** Number of frames covering each canvas pixel; 0 = uncovered (value 0). */
+  coverage: Uint8Array;
+  /** Gain applied to each frame (1 when compensation is off). */
+  gains: readonly number[];
+  provenance: ProcessingProvenance;
+}
+```

package/docs/api/processing-processing-task.md

@@ -0,0 +1,107 @@
+# processing/processing-task.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.
+
+## PROCESSING_DEFAULT_MAXIMUM_WORKING_BYTES
+
+Default working-memory bound when `maximumWorkingBytes` is omitted (1 GiB).
+
+```ts
+PROCESSING_DEFAULT_MAXIMUM_WORKING_BYTES = 1 << 30
+```
+
+## PROCESSING_MAX_FRAMES
+
+Largest number of input frames (brackets, focus slices, panorama frames).
+
+```ts
+PROCESSING_MAX_FRAMES = 32
+```
+
+## PROCESSING_MAX_PIXELS
+
+Largest image (pixels per frame) any processing operator accepts.
+
+```ts
+PROCESSING_MAX_PIXELS = 1 << 26
+```
+
+## PROCESSING_MODEL_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+PROCESSING_MODEL_VERSION = "1.0.0" as const
+```
+
+## ProcessingLinearColorSpace
+
+Linear RGB encodings the colour-aware operators accept (all D65).
+
+```ts
+export type ProcessingLinearColorSpace = "linear-srgb-d65" | "linear-display-p3-d65" | "linear-rec2020-d65";
+```
+
+## ProcessingProvenance
+
+Result provenance of a processing operator; processing outputs are never calibrated.
+
+```ts
+export interface ProcessingProvenance extends CalculationProvenance {
+  kind: "approximation";
+  assumptions: readonly string[];
+}
+```
+
+## ProcessingProvider
+
+Host hooks, the same shape as the native task providers.
+
+```ts
+export interface ProcessingProvider {
+  /** Must yield to the host event loop, allowing cancellation/input events between rows. */
+  yieldControl(signal: AbortSignal): Promise<void>;
+  /** Optional observer called after each processed row of each pass; cannot change output. */
+  onProgress?(progress: NativeTaskProgress): void;
+}
+```
+
+## ProcessingRgbImage
+
+Interleaved RGB image: `data[(y·width + x)·3 + c]`, row-major, +Y down.
+
+```ts
+export interface ProcessingRgbImage {
+  width: number;
+  height: number;
+  data: Float32Array;
+}
+```
+
+## ProcessingTask
+
+Single-use cancellable processing task.
+
+```ts
+export interface ProcessingTask<T> {
+  readonly state: ProcessingTaskState;
+  /** Rows processed so far across every pass. */
+  readonly completedTileCount: number;
+  /** Total rows of every pass; known before `run()`. */
+  readonly totalTileCount: number;
+  /** Upper estimate of typed-array bytes allocated by the task, including its output. */
+  readonly estimatedWorkingBytes: number;
+  run(): Promise<void>;
+  cancel(): void;
+  dispose(): void;
+  takeOutput(): T;
+}
+```
+
+## ProcessingTaskState
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ProcessingTaskState = "ready" | "running" | "completed" | "cancelled" | "failed" | "disposed" | "transferred";
+```

package/docs/api/processing-tone-mapping.md

@@ -0,0 +1,142 @@
+# processing/tone-mapping.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.
+
+## createDurandDorseyToneMappingTask
+
+Durand & Dorsey (2002) bilateral base/detail tone mapping. The fast bilateral filter is the paper's
+piecewise-linear scheme:
+1. Place intensity nodes i_j no more than σ_r apart.
+2. For each node, compute J_j = (f ⊗ (g_r(I − i_j)·I)) / (f ⊗ g_r(I − i_j)) on a box-downsampled grid.
+3. Upsample bilinearly, then interpolate linearly between the two nodes on either side of each
+   full-resolution intensity.
+
+```ts
+export function createDurandDorseyToneMappingTask(input: DurandDorseyToneMappingInput, provider: ProcessingProvider): ProcessingTask<DurandDorseyToneMappingOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createExposureFusionTask
+
+Mertens, Kautz & Van Reeth (2007) exposure fusion with Laplacian-pyramid blending.
+
+```ts
+export function createExposureFusionTask(input: ExposureFusionInput, provider: ProcessingProvider): ProcessingTask<ExposureFusionOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createReinhardGlobalToneMappingTask
+
+Reinhard, Stark, Shirley & Ferwerda (2002) global photographic tone reproduction.
+
+```ts
+export function createReinhardGlobalToneMappingTask(input: ReinhardGlobalToneMappingInput, provider: ProcessingProvider): ProcessingTask<ReinhardGlobalToneMappingOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## DurandDorseyToneMappingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DurandDorseyToneMappingInput {
+  image: ProcessingRgbImage;
+  inputColorSpace: ProcessingLinearColorSpace;
+  /** Spatial σ in pixels; default 2% of the larger image side. */
+  spatialSigmaPixels?: number;
+  /** Range σ in log₁₀ luminance; default 0.4. */
+  rangeSigmaLog10?: number;
+  /** Target base-layer contrast ratio; default 5. */
+  targetContrast?: number;
+  /** Spatial downsampling factor of the fast bilateral filter; default max(1, round(σ_s/4)). */
+  downsampleFactor?: number;
+  maximumWorkingBytes?: number;
+}
+```
+
+## DurandDorseyToneMappingOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DurandDorseyToneMappingOutput extends ToneMappedImage {
+  /** Bilateral base layer (log₁₀ luminance) per pixel; −Infinity for pixels with luminance ≤ 0, which are excluded from the filter. */
+  baseLog10: Float32Array;
+  compressionFactor: number;
+}
+```
+
+## ExposureFusionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExposureFusionInput {
+  /** Display-referred (e.g. sRGB-encoded) frames with values nominally in [0, 1]. */
+  frames: readonly ProcessingRgbImage[];
+  contrastExponent?: number;
+  saturationExponent?: number;
+  wellExposednessExponent?: number;
+  /** Well-exposedness Gaussian σ; default 0.2. */
+  wellExposednessSigma?: number;
+  /** Pyramid levels; default down to a 1-pixel side (at most 12). */
+  pyramidLevels?: number;
+  maximumWorkingBytes?: number;
+}
+```
+
+## ExposureFusionOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExposureFusionOutput extends ProcessingRgbImage {
+  /** Components clipped to [0, 1] after collapsing the blended pyramid. */
+  clippedSampleCount: number;
+  provenance: ProcessingProvenance;
+}
+```
+
+## ReinhardGlobalToneMappingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ReinhardGlobalToneMappingInput {
+  image: ProcessingRgbImage;
+  inputColorSpace: ProcessingLinearColorSpace;
+  /** Key value a; default 0.18. */
+  key?: number;
+  /** Smallest scaled luminance mapped to white; default the largest scaled luminance. */
+  whiteLuminance?: number;
+  /** δ in the log-average exp(mean(log(δ + L_w))); default 1e-6. */
+  logAverageDelta?: number;
+  maximumWorkingBytes?: number;
+}
+```
+
+## ReinhardGlobalToneMappingOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ReinhardGlobalToneMappingOutput extends ToneMappedImage {
+  logAverageLuminance: number;
+  whiteLuminance: number;
+}
+```
+
+## ToneMappedImage
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ToneMappedImage extends ProcessingRgbImage {
+  /** Output components above 1 (left unclipped for the downstream gamut/encoding stage). */
+  aboveOneSampleCount: number;
+  provenance: ProcessingProvenance;
+}
+```

package/docs/api/schema-camera.md

@@ -1,6 +1,6 @@
 # schema/camera.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.
+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.
 
 ## CameraConfiguration
 
@@ -58,9 +58,11 @@ export interface LensConfiguration {
 
 ## SensorConfiguration
 
-The legacy CameraConfiguration is a finite unit-bearing POC setting record, not a complete
-equipment capability profile. Its parser lives in schema/validation; newer ISO/exposure
-capabilities remain separate so adding a control policy does not reinterpret saved POC data.
+The legacy CameraConfiguration: one set of camera settings, with units, for the
+proof-of-concept (POC) simulation. It is not a full description of what a camera can do.
+
+Its parser is in schema/validation. Newer ISO and exposure capabilities are separate types,
+so adding a control policy never changes the meaning of saved POC data.
 
 ```ts
 export interface SensorConfiguration {

package/docs/api/schema-illumination-spectral.md

@@ -1,14 +1,14 @@
 # schema/illumination-spectral.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.
+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.
 
 ## createSceneIlluminationSpectralCoverageParticipant
 
-Adapts a continuous scene-illumination spectrum into the shared spectral
-coverage contract.
+Converts a continuous light-source spectrum into the shared spectral coverage
+type (wavelength range plus breakpoints).
 
-Discrete-line spectra intentionally use their own measure path and are never
-broadened into continuous breakpoints.
+Discrete-line spectra are handled separately and are never widened into
+continuous breakpoints.
 
 ```ts
 export function createSceneIlluminationSpectralCoverageParticipant(
@@ -32,13 +32,12 @@ export interface CreateSceneIlluminationSpectralCoverageParticipantInput {
 
 ## resolveSceneIlluminationDiscreteLineMeasure
 
-Resolves a discrete illumination spectrum into integrated per-line source
-quantities.
+Splits a discrete-line light source into the amount carried by each line.
 
-Relative line weights are fractions of the declared wavelength-integrated
-source magnitude. A disabled source resolves to zero contribution. This
-helper does not evaluate visibility, material response, transport, outgoing
-scene radiance, optics, or sensor response.
+Each relative line weight is a fraction of the source's declared total (integrated
+over wavelength). A disabled source contributes zero. This helper does not handle
+visibility, material response, light transport, outgoing scene radiance, optics or
+sensor response.
 
 ```ts
 export function resolveSceneIlluminationDiscreteLineMeasure(

package/docs/api/schema-illumination-temporal.md

@@ -1,14 +1,13 @@
 # schema/illumination-temporal.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.
+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.
 
 ## evaluateSceneIlluminationTemporalMultiplier
 
-Evaluates one explicitly registered time-varying source multiplier at one
-physical capture time.
+Returns one registered source's time-varying multiplier at one capture time.
 
-Capture time is seconds from the first opening-boundary phase. Sensor data
-readout timing is not used as a time surrogate.
+Capture time is in seconds from the first opening boundary of the exposure. Sensor
+readout timing is never used in place of capture time.
 
 ```ts
 export function evaluateSceneIlluminationTemporalMultiplier(
@@ -53,11 +52,11 @@ export interface IntegrateSceneIlluminationTemporalMultiplierInput {
 
 ## integrateSceneIlluminationTemporalMultiplierOverExposureWindow
 
-Integrates one time-varying source multiplier over one authoritative local
-exposure window from #12 using deterministic midpoint quadrature.
+Integrates one source's time-varying multiplier over one local exposure window
+(from sensor/exposure-window), using the deterministic midpoint rule.
 
-This integrates relative temporal modulation only. It does not apply source
-magnitude, scene transport, optics, sensor response, or metering policy.
+It integrates only the relative modulation over time. It does not apply source
+magnitude, scene light transport, optics, sensor response or metering policy.
 
 ```ts
 export function integrateSceneIlluminationTemporalMultiplierOverExposureWindow(
@@ -70,12 +69,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSceneIlluminationTemporalProfile
 
-Parses time-varying illumination metadata as an additive overlay on one
-existing illumination profile.
+Parses a time-varying illumination profile that sits on top of one existing
+illumination profile.
 
-The base source magnitude/spectrum remain authoritative. Each binding applies
-one relative temporal multiplier waveform to one source. Unbound sources
-remain time-invariant.
+The base source magnitude and spectrum still apply. Each binding multiplies one
+source by one relative waveform over time. Sources with no binding stay constant.
 
 ```ts
 export function parseSceneIlluminationTemporalProfile(
@@ -244,7 +242,7 @@ export interface SceneIlluminationTemporalSourceBinding {
   captureTimeReference:
     "first-opening-boundary-phase";
   /**
-   * Capture-reference time at which waveform-local t=0 occurs.
+   * The capture time at which the waveform's own t=0 falls.
    *
    * waveformTime = captureTime - waveformTimeZeroSecondsFromCaptureReference
    */

package/docs/api/schema-illumination.md

@@ -1,14 +1,14 @@
 # schema/illumination.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.
+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.
 
 ## parseSceneIlluminationProfile
 
 Parses a renderer-independent scene illumination profile.
 
-The result describes illumination sources only. It does not calculate
-outgoing scene radiance, apply material response, evaluate visibility or
-indirect transport, or authorize downstream photon/electron claims.
+The result describes light sources only. It does not compute outgoing scene
+radiance, material response, visibility or indirect light, and on its own it
+does not justify photon or electron counts downstream.
 
 ```ts
 export function parseSceneIlluminationProfile(

package/docs/api/schema-scene-radiance-temporal.md

@@ -1,15 +1,15 @@
 # schema/scene-radiance-temporal.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.
+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.
 
 ## createSceneRadianceTemporalSamplingPlan
 
-Creates renderer/provider-neutral scene-radiance evaluation nodes over one
-authoritative local exposure window.
+Plans the times (nodes) at which a scene-radiance provider must report radiance
+during one local exposure window. Works with any renderer or provider.
 
-The plan deliberately carries capture time separately from the legacy #85
-request field name. Providers/renderers must evaluate scene/source radiance
-at node.captureTimeSecondsFromReference on the first-opening-boundary clock.
+Capture time is a separate field, not the older request field
+timeSecondsFromExposureStart. Providers must evaluate radiance at
+node.captureTimeSecondsFromReference, measured from the first opening boundary.
 
 ```ts
 export function createSceneRadianceTemporalSamplingPlan(
@@ -88,12 +88,11 @@ export interface ReducedSceneRadianceTemporalExposure {
 
 ## reduceSceneRadianceTemporalSamples
 
-Reduces provider-returned wavelength-resolved scene radiance over the
-authoritative local exposure window.
+Combines the provider's per-wavelength scene radiance over the local exposure window.
 
-Every sample must bind to the exact plan node/time/result identity. Numeric
-uncertainty is retained per node and explicitly not combined because no
-correlation/independence assumption is introduced.
+Each sample must match its planned node, time and result identity exactly.
+Uncertainty stays per node and is not combined, because no correlation or
+independence is assumed.
 
 ```ts
 export function reduceSceneRadianceTemporalSamples(

package/docs/api/schema-scene-radiance.md

@@ -1,10 +1,10 @@
 # schema/scene-radiance.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.
+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.
 
 ## assessSceneMaterialResponseFidelity
 
-Returns the conservative material fidelity represented by a profile.
+Returns the material fidelity a profile supports, choosing the lower level when in doubt.
 
 ```ts
 export function assessSceneMaterialResponseFidelity(
@@ -16,11 +16,12 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSceneMaterialResponseProfile
 
-Parses material-response metadata consumed by a scene-radiance provider.
+Parses material-response metadata used by a scene-radiance provider.
 
-RGB/PBR data is approximation-only. Spectral data describes a
-wavelength-preserving provider input and does not itself calculate a BSDF,
-scene radiance, fluorescence, emission, volumetrics, or polarization.
+RGB or PBR (physically based rendering) material data is always an approximation.
+Spectral data is a per-wavelength provider input. It does not itself compute a BSDF
+(how a surface scatters light), scene radiance, fluorescence, emission, volumetric
+effects or polarization.
 
 ```ts
 export function parseSceneMaterialResponseProfile(
@@ -45,11 +46,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSceneRadianceEvaluationResult
 
-Parses one provider-produced outgoing spectral-radiance result.
+Parses one outgoing spectral-radiance result from a provider.
 
-The numeric value is accepted as provider output; parsing validates units,
-finite/nonnegative value, provenance, and identity fields but does not prove
-that the provider's transport calculation is physically correct.
+The number is accepted as the provider reported it. Parsing checks units, that the
+value is finite and nonnegative, provenance and identity fields. It does not prove
+the provider's light-transport calculation is physically correct.
 
 ```ts
 export function parseSceneRadianceEvaluationResult(
@@ -61,11 +62,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSceneRadianceProviderProfile
 
-Parses a renderer-neutral provider capability/profile declaration.
+Parses a provider's declaration of what it can do (its profile). Works with any renderer.
 
-Schema 0.1.0 is deliberately approximation-only. A provider may consume
-calibrated inputs, but this contract does not authorize a calibrated
-outgoing-radiance claim until later spectral/transport completeness work.
+Schema 0.1.0 is approximation-only by design. A provider may use calibrated inputs,
+but this contract cannot support a claim of calibrated outgoing radiance. That needs
+later work on complete spectral and light-transport models.
 
 ```ts
 export function parseSceneRadianceProviderProfile(
@@ -383,10 +384,10 @@ export type SceneRadianceUncertainty =
 
 ## validateSceneRadianceEvaluationBindings
 
-Validates exact identity/binding relationships around provider output.
+Checks that a provider result matches its request and profile identities exactly.
 
-This function never recomputes the radiance value and never promotes the
-provider's approximation to calibrated radiometry.
+It never recomputes the radiance value, and never upgrades the provider's
+approximation to calibrated radiometry.
 
 ```ts
 export function validateSceneRadianceEvaluationBindings(

package/docs/api/schema-scene.md

@@ -1,6 +1,6 @@
 # schema/scene.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.
+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.
 
 ## SceneCapability
 
@@ -22,8 +22,8 @@ export type SceneCapability =
 
 Versioned, renderer-independent description of a curated synthetic scene.
 
-Asset locations are intentionally not part of this scientific schema;
-callers may bind the metadata to their own asset systems separately.
+Asset locations are deliberately left out of this scientific schema. Callers
+can link the metadata to their own asset systems.
 
 ```ts
 export interface SceneDefinition {
@@ -73,18 +73,18 @@ Describes how scene-linear image values relate to physical light.
 export type SceneRadiometry =
   | {
       /**
-       * Relative linear values preserve light ratios but are not absolutely
-       * calibrated for photon-count calculations.
+       * Relative linear values keep light ratios correct but have no absolute
+       * calibration, so they cannot be used to compute photon counts.
        */
       kind: "relative-linear";
       referenceValue: number;
     }
   | {
       /**
-       * Scene package includes an absolute luminance anchor that can support
-       * calibrated photometric exposure work. Luminance alone is not
-       * sufficient to derive photon counts; photon simulation additionally
-       * requires defensible spectral and optical calibration.
+       * The scene package includes an absolute luminance reference, which can
+       * support calibrated photometric exposure work. Luminance alone cannot give
+       * photon counts. Simulating photons also needs defensible spectral and
+       * optical calibration.
        */
       kind: "absolute-luminance";
       referenceValue: number;

package/docs/api/schema-validation.md

@@ -1,6 +1,6 @@
 # schema/validation.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.
+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.
 
 ## parseCameraConfiguration