@photivra/engine 1.5.0 → 2.0.0

package/docs/api/sensor-spatial-sample-reduction.md

@@ -1,26 +1,25 @@
 # sensor/spatial-sample-reduction.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.
 
 ## reduceSensorSpatialSamplingQuadrature
 
-Reduces explicitly identified nonnegative linear scalar values over a
+Combines nonnegative linear values, each tagged with its node, over a
 validated sensor spatial quadrature.
 
-This function does not sample a renderer or optical model itself. Callers
-evaluate one value at every quadrature node's preAntiAliasingSourcePointMm
-and provide those values with exact node identity. Ordering is deliberately
-irrelevant.
+It does not sample a renderer or optical model itself. Callers evaluate one
+value at every node's preAntiAliasingSourcePointMm and pass the values with
+their exact node identity. Order does not matter.
 
-Two domains are supported:
+Two value domains are supported:
 
-- relative-linear: dimensionless nonnegative irradiance-like proxy for
-  deterministic renderer/science regression;
-- radiometric-irradiance: physical sensor-plane irradiance in W/m^2.
+- relative-linear: a dimensionless, nonnegative stand-in for irradiance, for
+  deterministic renderer and science regression tests;
+- radiometric-irradiance: physical irradiance on the sensor plane in W/m^2.
 
-The destination site's channelId is metadata only. No CFA spectral
-transmittance/sensitivity is applied, so the output must not be called a
-physically color-filtered mosaic sample or RAW value.
+The destination site's channelId is a label only. No CFA spectral
+transmittance or sensitivity is applied, so do not call the output a
+colour-filtered mosaic sample or a RAW value.
 
 ```ts
 export function reduceSensorSpatialSamplingQuadrature(
@@ -39,9 +38,9 @@ export interface ReduceSensorSpatialSamplingQuadratureInput {
   quadrature: SensorSpatialSamplingQuadrature;
   valueDomain: SensorSpatialSampleValueDomain;
   /**
-   * Exactly one explicitly identified value per quadrature node.
+   * Exactly one value per quadrature node, each with its node identity.
    *
-   * Ordering is not significant; node identity is.
+   * Order does not matter; the node identity does.
    */
   nodeValues: readonly SensorSpatialQuadratureNodeValue[];
 }
@@ -67,10 +66,9 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface SensorSpatialQuadratureNodeValue {
   node: SensorSpatialQuadratureNodeIdentity;
   /**
-   * Nonnegative finite scalar in the declared value domain.
+   * A nonnegative, finite number in the declared value domain.
    *
-   * Values are evaluated at the corresponding quadrature node's
-   * preAntiAliasingSourcePointMm.
+   * It is evaluated at the matching node's preAntiAliasingSourcePointMm.
    */
   value: number;
 }
@@ -87,9 +85,9 @@ export interface SensorSpatialSampleReduction {
     y: number;
   };
   /**
-   * Semantic destination CFA/color-site label only.
+   * Label of the destination CFA (colour filter array) site only.
    *
-   * No spectral filter response is applied by this reducer.
+   * This reducer applies no spectral filter response.
    */
   channelId: string;
   outputMeaning:
@@ -134,13 +132,13 @@ export type SensorSpatialSampleReductionValue =
       semantic:
         "nonnegative-sensor-plane-irradiance-proxy";
       /**
-       * Dimensionless weighted spatial average in the same relative domain.
+       * Weighted spatial average (dimensionless), in the same relative domain.
        */
       normalizedSpatialAverageRelative: number;
       /**
        * Relative value × square micrometres.
        *
-       * This is a geometric area-weighted diagnostic, not radiometric power.
+       * A geometric, area-weighted diagnostic, not a radiometric power.
        */
       geometricAreaIntegralRelativeSquareMicrometers: number;
     }
@@ -149,18 +147,17 @@ export type SensorSpatialSampleReductionValue =
       unit: "W/m^2";
       semantic: "sensor-plane-irradiance";
       /**
-       * Weighted mean irradiance over the geometric aperture after applying
-       * the declared normalized AA spatial redistribution.
+       * Weighted mean irradiance over the geometric aperture, after the
+       * declared normalized AA spreading.
        */
       normalizedSpatialAverageIrradianceWattsPerSquareMeter: number;
       /**
-       * Incident radiant flux represented by integrating the supplied
-       * irradiance over the geometric aperture under the declared normalized
-       * AA redistribution. Units: watts.
+       * Incident radiant flux: the supplied irradiance integrated over the
+       * geometric aperture, with the declared normalized AA spreading.
+       * Units: watts.
        *
-       * This remains pre-CFA-response, pre-QE, pre-microlens-response and
-       * excludes any optical-stack throughput not already present in the
-       * caller-supplied irradiance values.
+       * It is before any CFA response, QE or microlens response, and excludes
+       * any optical-stack throughput not already in the caller's irradiance values.
        */
       geometricApertureIncidentFluxWatts: number;
     };

package/docs/api/sensor-spatial-sampling-quadrature.md

@@ -1,36 +1,34 @@
 # sensor/spatial-sampling-quadrature.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.
 
 ## calculateSensorSpatialSamplingQuadrature
 
-Builds deterministic spatial quadrature nodes for one CFA/color-sampling site.
+Builds the deterministic spatial sample points (quadrature nodes) for one CFA
+(colour filter array) site.
 
-The quadrature composes:
+It combines:
 
-1. the resolved geometric sensitive aperture from the sampling-aperture
-   foundation; and
-2. the resolved effective AA point-splitting kernel from the optical-stack
-   foundation.
+1. the site's geometric light-sensitive aperture (from sampling-aperture); and
+2. the anti-aliasing (AA) point-splitting kernel (from optical-stack).
 
-The first aperture integration uses a tensor-product uniform midpoint rule.
-For an AA component that moves optical energy by +delta on the sensor plane,
-a destination aperture point samples the pre-AA optical field at
-destination - delta. This inverse-source convention prevents applying the AA
-shift twice.
+The aperture is integrated with a grid of evenly spaced midpoints (a
+tensor-product midpoint rule). If an AA component moves light by +delta on
+the sensor, a destination point samples the light field before AA at
+destination − delta. Working backwards like this means the shift is never
+applied twice.
 
-The destination sensor site's CFA channel applies to every node. The
-pre-AA source coordinate is an optical-field location, not another CFA site;
-therefore shifted source coordinates never reassign the destination channel.
+The destination site's CFA channel applies to every node. The pre-AA source
+point is a position in the light field, not another CFA site, so a shifted
+source point never changes the destination channel.
 
-Nodes whose pre-AA source coordinates fall outside the active imaging area
-are retained. They are neither clamped nor dropped/renormalized. A renderer
-or optical-field provider owns source-coverage policy.
+Nodes whose pre-AA source point falls outside the active imaging area are
+kept. They are neither clamped nor dropped (and weights are not
+renormalized). The renderer or light-field provider decides how to cover them.
 
-normalized weights approximate a spatial average. Square-micrometre measures
-approximate a geometric area integral. Neither includes radiometric
-throughput, QE, photon conversion, microlenses, diffusion/crosstalk, or
-temporal integration.
+Normalized weights approximate a spatial average. Square-micrometre measures
+approximate a geometric area integral. Neither includes throughput, QE,
+photon conversion, microlenses, diffusion, crosstalk or integration over time.
 
 ```ts
 export function calculateSensorSpatialSamplingQuadrature(
@@ -93,7 +91,7 @@ export interface SensorSpatialSamplingQuadrature {
   sourceCoveragePolicy: "not-applied";
   nodes: readonly SensorSpatialSamplingQuadratureNode[];
   /**
-   * Hard scientific boundaries.
+   * Fixed statements of what this result does not include.
    */
   opticalFieldValuesIncluded: false;
   radianceIncluded: false;
@@ -129,17 +127,17 @@ export interface SensorSpatialSamplingQuadratureNode {
   apertureSampleXIndex: number;
   apertureSampleYIndex: number;
   /**
-   * Destination point inside the geometric sensitive aperture after the
-   * declared AA point-splitting response.
+   * Destination point inside the geometric sensitive aperture, after the
+   * declared AA point splitting.
    *
-   * Native sensor physical coordinates, millimetres from the optical axis.
+   * Native sensor physical coordinates, in millimetres from the optical axis.
    */
   destinationAperturePointMm: {
     x: number;
     y: number;
   };
   /**
-   * Declared AA displacement of optical energy on the sensor plane.
+   * How far the declared AA component moves light on the sensor plane.
    *
    * +X right, +Y down; micrometres.
    */
@@ -148,8 +146,8 @@ export interface SensorSpatialSamplingQuadratureNode {
     y: number;
   };
   /**
-   * Pre-AA source point that maps to destinationAperturePointMm under the
-   * declared split component:
+   * The point in the light field before AA that lands on
+   * destinationAperturePointMm through this split component:
    *
    * source = destination - AA offset
    */
@@ -158,9 +156,9 @@ export interface SensorSpatialSamplingQuadratureNode {
     y: number;
   };
   /**
-   * Whether the pre-AA source point lies inside the active physical imaging
-   * area. False is not an error; downstream source-coverage policy decides how
-   * to handle valid optical support outside the active sampling area.
+   * Whether the pre-AA source point is inside the active physical imaging
+   * area. False is not an error; downstream code decides how to handle valid
+   * light from outside the active sampling area.
    */
   preAntiAliasingSourceInsideImagingArea: boolean;
   /** Dimensionless midpoint weight for the aperture-area average. */
@@ -168,20 +166,20 @@ export interface SensorSpatialSamplingQuadratureNode {
   /** Dimensionless normalized weight from the AA split component. */
   normalizedAntiAliasingWeight: number;
   /**
-   * Dimensionless product used for a spatial average of a downstream optical
-   * field under this quadrature approximation.
+   * Product of the two weights (dimensionless), used to average a light field
+   * over the site with this quadrature.
    */
   combinedNormalizedSpatialWeight: number;
   /**
-   * Geometric area measure represented by this aperture midpoint before the
-   * AA component weight is applied. Units: square micrometres.
+   * Geometric area this aperture midpoint stands for, before the AA component
+   * weight is applied. Units: square micrometres.
    */
   apertureAreaMeasureSquareMicrometers: number;
   /**
-   * Geometric area measure multiplied by the dimensionless AA component
-   * weight. Units remain square micrometres.
+   * Geometric area multiplied by the (dimensionless) AA component weight.
+   * Units are still square micrometres.
    *
-   * This is not an effective radiometric collection area.
+   * This is not an effective light-collection area.
    */
   combinedAreaMeasureSquareMicrometers: number;
 }

package/docs/api/sensor-spatio-spectral-reduction.md

@@ -1,28 +1,27 @@
 # sensor/spatio-spectral-reduction.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.
 
 ## reduceSensorSpatioSpectralIrradiance
 
-Reduces explicitly supplied sensor-plane spectral irradiance E_lambda(x,y)
-over the Cartesian product of an existing spatial quadrature and spectral
+Integrates supplied spectral irradiance on the sensor plane, E_lambda(x,y),
+over every combination of an existing spatial quadrature and spectral
 quadrature.
 
-The supplied density unit is W/m^2/nm and wavelengthMeasureNanometers is
-d-lambda in nm, so their direct product has units W/m^2. Do not convert
-d-lambda to metres unless the spectral-density denominator is converted
-consistently.
+Units: the density is in W/m^2/nm and wavelengthMeasureNanometers is dλ in
+nm, so their product is in W/m^2. Do not convert dλ to metres unless the
+density's per-nanometre unit is converted to match.
 
-Spatial area integration uses the spatial quadrature's geometric area
-measures converted from square micrometres to square metres. The result is
-geometric-aperture incident radiant flux only; geometric area is not upgraded
-to an effective radiometric collection area.
+Area integration uses the spatial quadrature's geometric area measures,
+converted from square micrometres to square metres. The result is the
+incident radiant flux on the geometric aperture only; geometric area is not
+treated as an effective light-collection area.
 
-This reducer deliberately stops before sensor response. The spectral plan was
-derived from a specific response channel so its support/knots are useful, but
-QE, A/W responsivity and channel-filter transmission are not applied here.
-Response-scope/source-plane matching therefore remains an explicit later
-composition step.
+It deliberately stops before the sensor response. The spectral plan comes
+from a specific response channel, so its wavelength range and breakpoints
+fit that channel, but QE, A/W responsivity and colour-filter transmission are
+not applied here. Matching the response's scope and source plane is a
+separate later step.
 
 ```ts
 export function reduceSensorSpatioSpectralIrradiance(
@@ -42,10 +41,10 @@ export interface ReduceSensorSpatioSpectralIrradianceInput {
   spatialQuadrature: SensorSpatialSamplingQuadrature;
   spectralQuadrature: SensorSpectralQuadrature;
   /**
-   * Exactly one explicitly identified E_lambda(x,y) value for every Cartesian
-   * product of spatial and spectral quadrature nodes.
+   * Exactly one E_lambda(x,y) value, with its node identity, for every
+   * combination of spatial node and spectral node.
    *
-   * Ordering is not significant; node identity is.
+   * Order does not matter; the node identity does.
    */
   sampleValues: readonly SensorSpatioSpectralIrradianceSample[];
 }
@@ -112,11 +111,11 @@ export interface SensorSpatioSpectralIrradianceReduction {
   wavelengthIntegratedSpatialAverageIrradianceWattsPerSquareMeter:
     number;
   /**
-   * Integral over the requested wavelength interval and geometric aperture
-   * area. Units: W.
+   * Integral over the requested wavelength interval and the geometric
+   * aperture area. Units: W.
    *
-   * This is pre-sensor-response incident radiant flux over the declared
-   * wavelength interval, not collected optical power or generated charge.
+   * This is the incident radiant flux before the sensor response, over the
+   * declared wavelength interval. It is not collected power or generated charge.
    */
   wavelengthIntegratedGeometricApertureIncidentFluxWatts:
     number;
@@ -158,8 +157,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface SensorSpatioSpectralIrradianceSample {
   node: SensorSpatioSpectralNodeIdentity;
   /**
-   * Spectral irradiance evaluated at the spatial quadrature node's
-   * preAntiAliasingSourcePointMm and this spectral node's wavelength.
+   * Spectral irradiance at the spatial node's preAntiAliasingSourcePointMm
+   * and this spectral node's wavelength.
    *
    * Units: W/m^2/nm.
    */
@@ -196,11 +195,10 @@ export interface SensorSpatioSpectralWavelengthReduction {
   normalizedSpatialAverageSpectralIrradianceWattsPerSquareMeterPerNanometer:
     number;
   /**
-   * Spectral radiant flux density incident over the geometric sensitive
-   * aperture after the declared normalized AA redistribution.
-   * Units: W/nm.
+   * Spectral radiant flux reaching the geometric sensitive aperture, after the
+   * declared normalized AA spreading. Units: W/nm.
    *
-   * This uses geometric area, not an established radiometric collection area.
+   * This uses geometric area, not an established light-collection area.
    */
   geometricApertureIncidentSpectralFluxWattsPerNanometer: number;
   /**

package/docs/api/sensor-spectral-coverage.md

@@ -1,14 +1,14 @@
 # sensor/spectral-coverage.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.
 
 ## createSensorSpectralCoverageParticipant
 
-Adapts one parsed sensor response channel into the shared continuous
-spectral-coverage contract.
+Converts one parsed sensor response channel into the shared continuous
+spectral-coverage format.
 
-This exposes support and interpolation knots only. It does not apply QE or
-A/W responsivity and does not establish scene/optics coverage.
+It gives only the wavelength range and interpolation breakpoints. It does not
+apply QE or A/W responsivity, and says nothing about scene or optics coverage.
 
 ```ts
 export function createSensorSpectralCoverageParticipant(

package/docs/api/sensor-spectral-quadrature.md

@@ -1,29 +1,27 @@
 # sensor/spectral-quadrature.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.
 
 ## calculateSensorSpectralQuadrature
 
-Builds deterministic wavelength quadrature nodes for one exact sensor
-response channel without applying the response to a source spectrum.
+Builds deterministic wavelength sample points for one exact sensor response
+channel. It does not apply the response to any spectrum.
 
-The requested wavelength range must lie fully inside the response channel's
-declared usable range. Response-curve knots and optional caller-provided
-continuous-spectrum/optics breakpoints partition that range. Each segment is
-then subdivided so no midpoint subinterval exceeds
+The requested range must lie fully inside the channel's declared usable
+range. The response curve's breakpoints, plus any caller-supplied breakpoints
+from the source spectrum or optics, split that range into segments. Each
+segment is then subdivided so no midpoint subinterval is wider than
 maximumSubintervalWidthNanometers.
 
-wavelengthMeasureNanometers is d-lambda in nanometres. It is not a
-dimensionless response weight. Future integration must use a source spectral
-density expressed per nanometre or explicitly convert units before
-multiplying by this measure.
+wavelengthMeasureNanometers is dλ in nanometres, not a dimensionless response
+weight. Multiply it only by a spectral density per nanometre, or convert
+units explicitly first.
 
-This function deliberately does not apply QE or A/W responsivity. Those
-representations have different compatible downstream signal domains: QE is
-photon-to-electron efficiency, while A/W responsivity relates incident
-radiant power to electrical current. A later versioned composition must also
-match responseScope to the source plane and collection-area semantics before
-integrating any signal.
+QE and A/W responsivity are deliberately not applied. They lead to different
+signals: QE is photon-to-electron efficiency, while A/W responsivity relates
+incident radiant power to electrical current. A later step must also match
+responseScope to the source plane and collection area before integrating any
+signal.
 
 ```ts
 export function calculateSensorSpectralQuadrature(
@@ -45,27 +43,27 @@ export interface CalculateSensorSpectralQuadratureInput {
   channelId: string;
   wavelengthBasis: SpectralWavelengthBasis;
   /**
-   * Explicit wavelength interval to sample. This API validates the interval
-   * against sensor-response support only; it does not establish scene-spectrum
-   * or optical-transmission coverage.
+   * Wavelength interval to sample. It is checked only against the range the
+   * sensor response supports, not against scene-spectrum or optical-transmission
+   * coverage.
    */
   wavelengthRangeNanometers:
     SensorSpectralWavelengthRangeNanometers;
   /**
-   * Hard upper bound on each midpoint subinterval width.
+   * Strict upper limit on the width of each midpoint subinterval.
    *
-   * Response knots and optional additional breakpoints split the requested
-   * range first; each resulting segment is then subdivided until every
-   * subinterval is no wider than this value.
+   * Response breakpoints and any additional breakpoints split the requested
+   * range first. Each segment is then subdivided until every subinterval is
+   * no wider than this value.
    */
   maximumSubintervalWidthNanometers: number;
   /**
    * Optional strictly increasing wavelength breakpoints from other continuous
-   * spectral factors, such as scene spectral-density or optical-transmission
-   * interpolation knots. Values must lie strictly inside the requested range.
+   * spectral inputs, such as the interpolation points of a scene spectrum or of
+   * optical transmission. Values must be strictly inside the requested range.
    *
-   * These coordinates do not assert that those external factors are actually
-   * available or valid over the requested range.
+   * Passing them does not claim those other inputs are available or valid over
+   * the requested range.
    */
   additionalBreakpointsNanometers?:
     readonly number[];
@@ -103,7 +101,7 @@ export interface SensorSpectralQuadrature {
   segmentBoundarySource:
     "requested-range-plus-response-knots-plus-optional-additional-breakpoints";
   /**
-   * Ordered unique segment boundaries, including requested range endpoints.
+   * Sorted, unique segment boundaries, including the ends of the requested range.
    */
   segmentBoundariesNanometers:
     readonly number[];
@@ -122,7 +120,7 @@ export interface SensorSpectralQuadrature {
       readonly (readonly EvidenceProvenance[])[];
   };
   /**
-   * Hard scientific boundaries.
+   * Fixed statements of what this result does not include.
    */
   responseValuesIncluded: false;
   responseApplicationPerformed: false;
@@ -158,16 +156,16 @@ export interface SensorSpectralQuadratureNode {
    */
   wavelengthNanometers: number;
   /**
-   * d-lambda represented by this node. Units: nm.
+   * dλ (wavelength width) this node stands for. Units: nm.
    *
-   * This is wavelength measure only. It is not response-weighted throughput,
-   * photon count, radiant energy, current, or a dimensionless probability.
+   * It is only a wavelength width. It is not response-weighted throughput,
+   * a photon count, radiant energy, current or a dimensionless probability.
    */
   wavelengthMeasureNanometers: number;
   /**
-   * Dimensionless wavelength measure normalized by the requested range width.
+   * The wavelength width divided by the requested range width (dimensionless).
    *
-   * This may be useful for averages, but it is not a sensor-response weight.
+   * Useful for averages, but it is not a sensor-response weight.
    */
   normalizedWavelengthWeight: number;
 }

package/docs/api/sensor-spectral-response.md

@@ -1,6 +1,6 @@
 # sensor/spectral-response.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.
 
 ## EffectiveSensorResponseScope
 
@@ -14,12 +14,12 @@ export type EffectiveSensorResponseScope =
 
 ## parseSensorSpectralResponseProfile
 
-Parses reusable wavelength-dependent response data for semantic sensor
-channels without inferring response from channel names or CFA family.
+Parses wavelength-dependent response data for sensor channels. Responses are
+never guessed from channel names or the CFA type.
 
-Embedded multi-point curves require reusable-data or Photivra-owned evidence.
-Public/factual references without reuse permission may support metadata but
-cannot by themselves authorize copying numeric curve data into the engine.
+An embedded multi-point curve needs evidence that the data is reusable or
+owned by Photivra. A public reference without reuse permission can support
+metadata, but does not by itself allow copying numeric curve data into the engine.
 
 ```ts
 export function parseSensorSpectralResponseProfile(
@@ -108,11 +108,11 @@ export type ResolvedSensorSpectralResponseValue =
 
 ## resolveSensorSpectralResponseAtWavelength
 
-Public spectral-response resolver for untrusted/raw profile inputs.
+Public spectral-response lookup for untrusted, unparsed profiles.
 
-Profiles are parsed once here. Internal composition code that has already
-parsed both profiles may use resolveParsedSensorSpectralResponseAtWavelength
-to avoid repeating full profile parsing for every wavelength node.
+The profiles are parsed here, once. Internal code that has already parsed
+both profiles can call resolveParsedSensorSpectralResponseAtWavelength, to
+avoid parsing them again for every wavelength node.
 
 ```ts
 export function resolveSensorSpectralResponseAtWavelength(
@@ -139,6 +139,17 @@ export interface ResolveSensorSpectralResponseAtWavelengthInput {
 }
 ```
 
+## SENSOR_SPECTRAL_RESPONSE_CHANNEL_BINDING_FORMAT
+
+Current channel-binding format. v2 (package 2.0.0) serializes the parsed channel with sorted keys.
+v1 (package 1.5.0 and earlier) used the unparsed channel's JSON in insertion order; it is rejected
+with an explicit version error instead of being compared.
+
+```ts
+SENSOR_SPECTRAL_RESPONSE_CHANNEL_BINDING_FORMAT =
+  "photivra-spectral-channel-response-canonical-json-v2" as const
+```
+
 ## SensorSpectralChannelResponse
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -195,18 +206,19 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface SensorSpectralResponseChannelBinding {
   format:
-    "photivra-spectral-channel-response-canonical-json-v1";
+    typeof SENSOR_SPECTRAL_RESPONSE_CHANNEL_BINDING_FORMAT;
   canonicalJson: string;
 }
 ```
 
 ## SensorSpectralResponseProfile
 
-Versioned channel-response data linked to one exact color-sampling profile.
-Each channel declares effective EQE, effective A/W response or separable filter
-and detector EQE, sampled support/interpolation and an explicit wavelength basis.
-Reference conditions, evidence and uncertainty retain their own validity. Names
-such as red/green/blue never supply missing curves or justify extrapolation.
+Versioned response data for the channels of one exact colour-sampling profile.
+Each channel declares an effective EQE, an effective A/W response, or separate
+filter and detector EQE curves, with its sampled range, interpolation and an
+explicit wavelength basis (air or vacuum). Reference conditions, evidence and
+uncertainty each keep their own validity. Names such as red, green or blue
+never fill in a missing curve or justify extrapolation.
 
 ```ts
 export interface SensorSpectralResponseProfile {

package/docs/api/sensor-temporal-photo-signal.md

@@ -1,12 +1,12 @@
 # sensor/temporal-photo-signal.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.
 
 ## createSensorEqeTemporalPhotoSignal
 
-Re-evaluate physical input at every time before committing an owned compact
-photo signal. Detailed child evidence/uncertainty stays in the returned
-exposure diagnostics. This does not establish renderer/source execution.
+Re-evaluates the physical input at every time, then commits a compact photo
+signal. Detailed per-step evidence and uncertainty stay in the returned
+exposure diagnostics. This does not show that a renderer or source actually ran.
 
 ```ts
 export function createSensorEqeTemporalPhotoSignal(input: {
@@ -19,7 +19,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSensorEqeTemporalPhotoSignal
 
-Recompute exact midpoint count sums; declarations do not prove source truth.
+Parses a time-resolved photo signal and recomputes its midpoint sums exactly. Declarations do not prove the source is correct.
 
 ```ts
 export function parseSensorEqeTemporalPhotoSignal(value: unknown): SensorEqeTemporalPhotoSignal;
@@ -37,7 +37,7 @@ export type SensorEqePhotoExposure = SensorEqeExposureIntegration | SensorEqeTem
 
 ## SensorEqeTemporalPhotoSignal
 
-Compact untreated photo expectation; temporal identity is not stationarity evidence.
+Compact expected photo signal, before any processing. Being tied to a time window is not evidence that the light was constant.
 
 ```ts
 export interface SensorEqeTemporalPhotoSignal extends Omit<SensorEqeExposureIntegration,