@photivra/engine 1.5.0 → 2.1.0

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.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.
 
 ## 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.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.
 
 ## 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.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.
 
 ## 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.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.
 
 ## 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.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.
 
 ## 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.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.
 
 ## 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.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.
 
 ## 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.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.
 
 ## parseCameraConfiguration
 

package/docs/api/sensor-accumulated-charge.md

@@ -1,16 +1,14 @@
 # sensor/accumulated-charge.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.
 
 ## composeSensorAccumulatedCharge
 
-Compose photo, independently evaluated dark and explicitly incremental charge by exact local
-exposure identity, retaining completeness assessment before capacity/noise.
+Adds photo charge, separately computed dark charge and any explicitly declared extra charge for
+one exact local exposure, and keeps the completeness assessment. Capacity and noise come later.
 
-Photo, dark and explicitly incremental stored-electron components must share the exact
-site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
-consequence of an empty component array. Expected stored charge remains distinct from a stochastic
-realization or nonlinear full-well clamp.
+All parts must belong to the exact same site, colour channel and local shutter event. The
+result is the expected charge, separate from a random realization or the full-well clamp.
 
 ```ts
 export function composeSensorAccumulatedCharge(
@@ -72,13 +70,11 @@ export type ComposeSensorPhotoAccumulatedChargeInput = ComposeSensorAccumulatedC
 
 ## parseSensorAccumulatedChargeCompletenessProfile
 
-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 completeness profile and returns it normalized. Unknown enum values,
+missing required fields and inconsistent scientific data are rejected.
 
-Photo, dark and explicitly incremental stored-electron components must share the exact
-site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
-consequence of an empty component array. Expected stored charge remains distinct from a stochastic
-realization or nonlinear full-well clamp.
+Completeness is a declaration backed by evidence. An empty list of components does not
+mean the charge accounting is complete.
 
 ```ts
 export function parseSensorAccumulatedChargeCompletenessProfile(
@@ -90,13 +86,9 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSensorAdditionalStoredChargeComponent
 
-Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
-missing required fields and incompatible scientific data fail at this boundary.
-
-Photo, dark and explicitly incremental stored-electron components must share the exact
-site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
-consequence of an empty component array. Expected stored charge remains distinct from a stochastic
-realization or nonlinear full-well clamp.
+Validates an untrusted additional stored-charge component (charge other than photo and dark
+charge, declared explicitly as an addition) and returns it normalized. Unknown enum values,
+missing required fields and inconsistent scientific data are rejected.
 
 ```ts
 export function parseSensorAdditionalStoredChargeComponent(

package/docs/api/sensor-architecture.md

@@ -1,19 +1,18 @@
 # sensor/architecture.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.
 
 ## parseSensorArchitectureProfile
 
 Parses untrusted descriptive sensor-architecture metadata.
 
-Schema 0.2.0 remains accepted and returns a 0.2.0 profile unchanged in
-semantic identity. Schema 0.3.0 adds optional evidence-backed CMOS/CCD
-technology-family metadata. Unknown facts should be omitted instead of
-inferred.
+Schema 0.2.0 is still accepted and returns a 0.2.0 profile with the same
+meaning. Schema 0.3.0 adds an optional, evidence-backed technology family
+(CMOS or CCD). Leave out facts you do not know rather than guessing them.
 
-The parser validates structure, supported vocabulary, and field-level
-evidence only; it does not verify that a cited real-world claim is
-factually true and technology family does not activate hidden physics.
+The parser checks structure, allowed values and per-field evidence only. It
+does not check that a cited real-world claim is true, and the technology
+family does not switch on any hidden physics.
 
 ```ts
 export function parseSensorArchitectureProfile(
@@ -53,8 +52,8 @@ export type SensorArchitectureProfile =
 
 Legacy sensor-architecture schema.
 
-Schema 0.2.0 remains accepted and is preserved exactly when parsed. It does
-not support technologyFamily; omission remains unknown/unasserted.
+Schema 0.2.0 is still accepted and kept exactly as parsed. It has no
+technologyFamily field; leaving it out means "unknown, not stated".
 
 ```ts
 export interface SensorArchitectureProfileV0_2
@@ -66,18 +65,18 @@ export interface SensorArchitectureProfileV0_2
 
 ## SensorArchitectureProfileV0_3
 
-Current descriptive sensor hardware/capability metadata.
+Current descriptive metadata about the sensor hardware and its capabilities.
 
-Omitted properties mean unknown/unasserted. These fields are not scientific
-effect switches: no architecture value changes noise, dynamic range, FOV,
-crop factor, exposure, readout timing, or sampling without a separate
-downstream model that explicitly consumes that fact.
+An omitted property means "unknown, not stated". These fields do not switch
+on scientific effects. No architecture value changes noise, dynamic range,
+field of view, crop factor, exposure, readout timing or sampling unless a
+separate downstream model explicitly uses that fact.
 
 ```ts
 export interface SensorArchitectureProfileV0_3
   extends SensorArchitectureProfileBase {
   schemaVersion: typeof SENSOR_ARCHITECTURE_PROFILE_SCHEMA_VERSION;
-  /** Coarse detector technology identity only; never a performance switch. */
+  /** Broad detector technology (for example CMOS or CCD) only. It never changes performance. */
   technologyFamily?: SourcedSensorArchitectureFact<SensorTechnologyFamily>;
 }
 ```

package/docs/api/sensor-camera-saturation-capacity.md

@@ -1,15 +1,13 @@
 # sensor/camera-saturation-capacity.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.
 
 ## assessSensorCameraSaturationCapacity
 
-Compare dark-corrected expected photo signal with the declared camera response-chain capacity
-without adding dark charge or identifying a hardware clamp.
+Compares the expected photo signal (dark-corrected) with the camera's declared saturation
+capacity. Dark charge is not added, and no hardware clamp is identified.
 
-Camera saturation capacity is a dark-corrected photo-signal electron-equivalent limit. It is not
-physical total-charge storage capacity, ADC maximum or evidence of the limiting hardware stage. This
-assessment compares expectations and does not synthesize post-saturation codes.
+This compares expected values only. It does not make up codes beyond saturation.
 
 ```ts
 export function assessSensorCameraSaturationCapacity(
@@ -37,12 +35,12 @@ export interface AssessSensorCameraSaturationCapacityInput {
 
 ## parseSensorCameraSaturationCapacityProfile
 
-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 untrusted input and returns it as a normalized, typed value. Unknown enum values,
+missing required fields and inconsistent scientific data are rejected.
 
-Camera saturation capacity is a dark-corrected photo-signal electron-equivalent limit. It is not
-physical total-charge storage capacity, ADC maximum or evidence of the limiting hardware stage. This
-assessment compares expectations and does not synthesize post-saturation codes.
+Camera saturation capacity is a limit on the dark-corrected photo signal, in electron
+equivalents. It is not the physical charge storage capacity or the ADC maximum, and does not
+identify which hardware stage limits it.
 
 ```ts
 export function parseSensorCameraSaturationCapacityProfile(