@photivra/engine 1.5.0 → 2.1.0

package/docs/api/composition-image-formation-plan.md

@@ -1,17 +1,19 @@
 # composition/image-formation-plan.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.
 
 ## createProductionCaptureSnapshot
 
-Commit resolved capture settings, scene time/identity, stochastic seed and optional
-temporal/focus/WB state by value. Later application mutations cannot alter this scientific event.
+Records, by value, the resolved capture settings, the scene time and identity, the random seed,
+and optional timing, focus and white-balance state. Later changes in the application cannot alter
+this captured event.
 
-The planner owns scientific stage ordering, immutable capture identity and reproducibility.
-Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
-bounded environment route executes supplied radiance through native RAW and optional output, while
-sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
-reproducibility keys, not cryptographic integrity proofs.
+The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+change, and makes results reproducible. A well-formed but unsupported combination returns
+structured blockers. A malformed declaration throws. The bounded environment route runs the
+supplied radiance through native RAW and, optionally, output processing. The sample-only and
+attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+reproducibility, not cryptographic proof of integrity.
 
 ```ts
 export function createProductionCaptureSnapshot(
@@ -24,10 +26,10 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## createProductionCaptureSnapshotFromReleaseFrame
 
-Creates one immutable production snapshot directly from a committed #105
-release frame. The release frame owns exposure/focus/automation/seed
-identity; callers provide only the scene/output-local state that is not
-owned by the release sequence.
+Creates one immutable production snapshot directly from a committed release
+frame (ResolvedReleaseFrame). The release frame supplies the exposure, focus,
+automation and seed. The caller supplies only the scene and output state that
+the release sequence does not.
 
 ```ts
 export function createProductionCaptureSnapshotFromReleaseFrame(
@@ -91,16 +93,17 @@ export interface CreateProductionCaptureSnapshotInput {
 
 ## createProductionImageFormationPlan
 
-Expand requested stages through the authoritative graph, validate shared commitments and capability
-limits, then execute only supported declared input routes. Return explicit
-active/zero/omitted/blocked dispositions and child evidence rather than silently skipping a
-requested effect.
+Builds the production plan. Adds dependencies to the requested stages using the stage graph,
+checks the shared state and capability limits, then runs only supported, declared input routes.
+Each requested effect is reported as active, zero, omitted or blocked, with child evidence. A
+requested effect is never skipped silently.
 
-The planner owns scientific stage ordering, immutable capture identity and reproducibility.
-Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
-bounded environment route executes supplied radiance through native RAW and optional output, while
-sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
-reproducibility keys, not cryptographic integrity proofs.
+The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+change, and makes results reproducible. A well-formed but unsupported combination returns
+structured blockers. A malformed declaration throws. The bounded environment route runs the
+supplied radiance through native RAW and, optionally, output processing. The sample-only and
+attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+reproducibility, not cryptographic proof of integrity.
 
 ```ts
 export function createProductionImageFormationPlan(
@@ -113,17 +116,18 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## CreateProductionImageFormationPlanInput
 
-Join one validated prepared context and immutable capture snapshot with exactly
-one supported physical input route: supplied sample, attached RAW processing or
-executed environment capture. The environment route owns its synchronous
-provider callback and may supply a processing policy with RAW omitted; execution
-provides the exact realized frame. Incompatible route combinations fail closed.
-A complete record does not authorize effects outside the supported envelope.
+Combines one validated prepared context and one immutable capture snapshot
+with exactly one supported physical input route: a supplied sample, processing
+of an attached RAW, or an executed environment capture. The environment route
+brings its own synchronous provider callback. It may supply a processing
+policy without a RAW; execution then provides the exact realized frame.
+Incompatible route combinations are rejected. A complete record does not make
+effects outside the supported range valid.
 
 ```ts
 export interface CreateProductionImageFormationPlanInput {
   environmentCapture?: ProductionEnvironmentCaptureInput;
-  /** Explicit authoritative post-ADC RAW input; output processing cannot synthesize upstream scene truth. */
+  /** Explicit RAW input after the ADC. Output processing cannot invent the upstream scene. */
   processedOutput?: ProductionProcessedOutputInput;
   preparedContext:
     PreparedImageFormationContext;
@@ -169,14 +173,15 @@ export interface ImageFormationFidelityProfile {
 
 ## parseImageFormationFidelityProfile
 
-Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
-missing required fields and incompatible scientific data fail at this boundary.
+Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data are rejected here.
 
-The planner owns scientific stage ordering, immutable capture identity and reproducibility.
-Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
-bounded environment route executes supplied radiance through native RAW and optional output, while
-sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
-reproducibility keys, not cryptographic integrity proofs.
+The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+change, and makes results reproducible. A well-formed but unsupported combination returns
+structured blockers. A malformed declaration throws. The bounded environment route runs the
+supplied radiance through native RAW and, optionally, output processing. The sample-only and
+attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+reproducibility, not cryptographic proof of integrity.
 
 ```ts
 export function parseImageFormationFidelityProfile(
@@ -188,14 +193,15 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parsePreparedImageFormationContext
 
-Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
-missing required fields and incompatible scientific data fail at this boundary.
+Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data are rejected here.
 
-The planner owns scientific stage ordering, immutable capture identity and reproducibility.
-Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
-bounded environment route executes supplied radiance through native RAW and optional output, while
-sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
-reproducibility keys, not cryptographic integrity proofs.
+The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+change, and makes results reproducible. A well-formed but unsupported combination returns
+structured blockers. A malformed declaration throws. The bounded environment route runs the
+supplied radiance through native RAW and, optionally, output processing. The sample-only and
+attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+reproducibility, not cryptographic proof of integrity.
 
 ```ts
 export function parsePreparedImageFormationContext(
@@ -207,14 +213,15 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseProductionCaptureSnapshot
 
-Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
-missing required fields and incompatible scientific data fail at this boundary.
+Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data are rejected here.
 
-The planner owns scientific stage ordering, immutable capture identity and reproducibility.
-Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
-bounded environment route executes supplied radiance through native RAW and optional output, while
-sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
-reproducibility keys, not cryptographic integrity proofs.
+The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+change, and makes results reproducible. A well-formed but unsupported combination returns
+structured blockers. A malformed declaration throws. The bounded environment route runs the
+supplied radiance through native RAW and, optionally, output processing. The sample-only and
+attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+reproducibility, not cryptographic proof of integrity.
 
 ```ts
 export function parseProductionCaptureSnapshot(
@@ -226,14 +233,15 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseRendererCapabilityDeclaration
 
-Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
-missing required fields and incompatible scientific data fail at this boundary.
+Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data are rejected here.
 
-The planner owns scientific stage ordering, immutable capture identity and reproducibility.
-Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
-bounded environment route executes supplied radiance through native RAW and optional output, while
-sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
-reproducibility keys, not cryptographic integrity proofs.
+The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+change, and makes results reproducible. A well-formed but unsupported combination returns
+structured blockers. A malformed declaration throws. The bounded environment route runs the
+supplied radiance through native RAW and, optionally, output processing. The sample-only and
+attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+reproducibility, not cryptographic proof of integrity.
 
 ```ts
 export function parseRendererCapabilityDeclaration(
@@ -370,14 +378,16 @@ export interface PreparedImageFormationContext {
 
 ## prepareImageFormationContext
 
-Parse, own and freeze relatively static equipment, scene, renderer and fidelity declarations for
-reuse by later immutable captures. This prepares semantic state and does not render a frame.
+Parses, copies and freezes the declarations that change rarely (equipment, scene, renderer and
+fidelity), so later immutable captures can reuse them. This prepares state; it does not render a
+frame.
 
-The planner owns scientific stage ordering, immutable capture identity and reproducibility.
-Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
-bounded environment route executes supplied radiance through native RAW and optional output, while
-sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
-reproducibility keys, not cryptographic integrity proofs.
+The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+change, and makes results reproducible. A well-formed but unsupported combination returns
+structured blockers. A malformed declaration throws. The bounded environment route runs the
+supplied radiance through native RAW and, optionally, output processing. The sample-only and
+attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+reproducibility, not cryptographic proof of integrity.
 
 ```ts
 export function prepareImageFormationContext(
@@ -430,11 +440,12 @@ PRODUCTION_IMAGE_FORMATION_PLAN_VERSION =
 
 ## ProductionCaptureSnapshot
 
-Owned frozen per-event state linking capture/release/scene/output IDs, physical
-aperture/shutter/ISO, seconds-valued scene time and an explicit uint32 seed.
-Optional focus/WB/temporal bindings commit their exact resolved state. This is a
-semantic snapshot, not the generated image; changing a later UI value requires a
-new snapshot rather than mutating a previously planned capture.
+Frozen state for one capture event. It links the capture, release, scene and
+output IDs, the physical aperture, shutter and ISO, the scene time in seconds
+and an explicit uint32 seed. Optional focus, white-balance and timing
+bindings record their exact resolved state. This is a description of the
+capture, not the generated image. If a UI value changes later, make a new
+snapshot; never change a capture that is already planned.
 
 ```ts
 export interface ProductionCaptureSnapshot {
@@ -470,14 +481,14 @@ export interface ProductionCaptureSnapshot {
 
 ## ProductionEnvironmentCaptureInput
 
-Executes the existing bounded environment capture inside the authoritative plan.
-The callback is synchronous local provider code; it is never serialized. Returned
-provider samples and realized RAW, rather than function identity, bind replay.
+Runs the existing bounded environment capture inside the plan. The callback is
+synchronous local provider code and is never serialized. Replay is tied to the
+returned provider samples and the realized RAW, not to the function's identity.
 
 ```ts
 export interface ProductionEnvironmentCaptureInput {
   capture: SimulateEnvironmentSensorRawFrameInput;
-  /** Optional post-capture policy. The RAW source is supplied only by execution. */
+  /** Optional post-capture policy. Only execution supplies the RAW source. */
   processing?: Omit<ProcessedSensorRawInput, "reconstruction"> & {
     reconstruction: Omit<ProcessedSensorRawInput["reconstruction"], "rawFrame">;
   };
@@ -523,19 +534,21 @@ export type ProductionImageFormationBlockerCode =
   | "missing-temporal-capture-input"
   | "temporal-evaluation-blocked"
   | "missing-camera-rotation-model"
+  | "missing-lens-field-mapping"
   | "missing-sensor-readout-timing"
   | "renderer-temporal-sampling-insufficient";
 ```
 
 ## ProductionImageFormationPlan
 
-Immutable engine-owned scientific execution record. Inspect status and blockers
-before treating requested stages as usable; each stage distinguishes execution,
-modeled-zero, fidelity omission and unsupported inputs. Optional environment and
-processed results carry exact child lineage, while sample-only routes retain
-upstream blockers. Versions identify independent contracts. The fingerprint is
-canonical FNV reproducibility identity, not adversarial integrity. Replay also
-requires identical provider responses; no renderer callback is serialized.
+Immutable record, owned by the engine, of what the scientific pipeline did.
+Check the status and blockers before using any requested stage. Each stage
+says whether it ran, was modelled as zero, was left out for fidelity, or had
+unsupported inputs. Optional environment and processed results carry their
+exact child lineage; sample-only routes keep their upstream blockers.
+Versions identify independent contracts. The fingerprint is a canonical FNV
+key for reproducibility; it does not protect against tampering. A replay also
+needs identical provider responses. No renderer callback is serialized.
 
 ```ts
 export interface ProductionImageFormationPlan {
@@ -590,9 +603,9 @@ export interface ProductionImageFormationPlan {
     readonly PlannedImageFormationEffect[];
   blockers:
     readonly ProductionImageFormationBlocker[];
-  /** Noncryptographic commitment of execution data, excluding executable callback identity. */
+  /** Non-cryptographic fingerprint of the execution data. Does not include the callback's identity. */
   environmentCaptureRequestFingerprint?: string;
-  /** Executed bounded source-to-ADC lineage; provider transport remains unverified. */
+  /** Lineage of the executed, bounded path from light source to ADC. The provider's transport is not verified. */
   environmentCaptureResult?: ReturnType<typeof simulateEnvironmentSensorRawFrame>;
   processedOutputResult?: ReturnType<typeof calculateProcessedSensorRaw>;
   physicalSceneToSensorResult?:
@@ -698,6 +711,16 @@ export interface ProductionTemporalCaptureInput {
   orientation: CaptureOrientation;
   readout?:
     SensorReadoutTimingDeclaration;
+  /**
+   * Optional explicit link from sensor readout to exposure timing. With the electronic
+   * rolling-shutter model, the exposure-window schedule must equal
+   * resolveElectronicRollingShutterExposureSchedule(readout). Then every per-site exposure window
+   * (and the rotation time sampling) includes the per-line offset.
+   */
+  readoutExposureLinkage?: {
+    kind: "electronic-rolling-shutter-line-reset-read";
+    evidence: readonly EvidenceProvenance[];
+  };
   rotation?: {
     angularVelocityRadPerSec:
       CameraAngularVelocityRadPerSec;
@@ -722,7 +745,8 @@ export interface ProductionTemporalCaptureResult {
   exposureTimeReference:
     "first-opening-boundary-phase";
   readoutExposureSynchronization:
-    "not-assumed";
+    | "not-assumed"
+    | "electronic-rolling-shutter-line-linked";
   sensorReadoutTimingRemainsSeparate:
     true;
   temporalRadianceIntegrated:
@@ -741,11 +765,13 @@ RENDERER_CAPABILITY_SCHEMA_VERSION =
 
 ## RendererCapabilityDeclaration
 
-Plain-data declaration of one consumer backend's supported scientific domains,
-stages/effects and temporal budget. It is validated metadata, not executable
-renderer code or proof of physical correctness. Unknown/insufficient capability
-must block requested fidelity before trusted provider execution. Interactive and
-reference roles keep the same committed science even when backend fidelity differs.
+Plain-data declaration of what one rendering backend supports: scientific
+domains, stages and effects, and its time-sample budget. It is validated
+metadata. It is not executable renderer code and not proof of physical
+correctness. If a capability is unknown or not enough, the requested
+fidelity is blocked before any trusted provider code runs. Interactive and
+reference backends keep the same committed science even when their fidelity
+differs.
 
 ```ts
 export interface RendererCapabilityDeclaration {
@@ -806,14 +832,17 @@ export interface RequiredImageFormationEffect {
 
 ## serializeProductionImageFormationPlan
 
-Return deterministic canonical JSON of a validated production plan. Sorted object keys preserve
-array order; the representation contains data and excludes executable provider callbacks.
-
-The planner owns scientific stage ordering, immutable capture identity and reproducibility.
-Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
-bounded environment route executes supplied radiance through native RAW and optional output, while
-sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
-reproducibility keys, not cryptographic integrity proofs.
+Returns deterministic canonical JSON for a validated production plan. Object keys are sorted;
+array order is kept. The JSON holds data only and leaves out provider callbacks. The plan version
+and its fingerprint (recomputed over the content) must match, so an empty or edited object is
+rejected instead of serialized.
+
+The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+change, and makes results reproducible. A well-formed but unsupported combination returns
+structured blockers. A malformed declaration throws. The bounded environment route runs the
+supplied radiance through native RAW and, optionally, output processing. The sample-only and
+attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+reproducibility, not cryptographic proof of integrity.
 
 ```ts
 export function serializeProductionImageFormationPlan(

package/docs/api/composition-plan-consumer.md

@@ -1,15 +1,15 @@
 # composition/plan-consumer.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.
 
 ## createProductionPlanConsumerManifest
 
-Creates a deterministic renderer/reference consumption view over one
-finalized semantic production plan.
+Creates a deterministic view of one finished production plan, for a renderer
+or a reference consumer.
 
-The consumer role changes execution responsibility only. It does not alter
-scientific stage/effect identity, temporal sample count, seeds, or physical
-results.
+The consumer role only changes who is responsible for executing. It does not
+change the scientific stages or effects, the number of time samples, the
+seeds or any physical result.
 
 ```ts
 export function createProductionPlanConsumerManifest(
@@ -71,7 +71,7 @@ export interface ProductionPlanConsumerManifest {
     }[];
   blockers:
     readonly ProductionImageFormationBlocker[];
-  /** Same immutable executed RAW and output results; consumers cannot re-render a different source. */
+  /** The same immutable RAW and output results that ran. A consumer cannot re-render from a different source. */
   environmentCaptureResult?: ProductionImageFormationPlan["environmentCaptureResult"];
   processedOutputResult?: ProductionImageFormationPlan["processedOutputResult"];
   physicalSceneToSensorResult:

package/docs/api/core-calculation-result.md

@@ -1,6 +1,6 @@
 # core/calculation-result.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.
 
 ## AbsoluteUncertaintyEstimate
 
@@ -69,10 +69,10 @@ export interface CalculationProvenance {
 
 Optional quality metadata for a calculation result.
 
-Components remain separate by default. Callers must not add, combine in
-quadrature, or otherwise collapse uncertainty components unless a
-scientifically justified composition method explicitly documents
-independence/correlation assumptions.
+Uncertainty components stay separate. Do not add them, combine them in
+quadrature (root-sum-of-squares) or merge them in any other way, unless you use
+a scientifically justified method that documents its independence and
+correlation assumptions.
 
 ```ts
 export interface CalculationQuality {
@@ -86,21 +86,25 @@ export interface CalculationQuality {
 
 Standard result envelope for public scientific calculations.
 
-Deterministic analytical results remain lightweight: quality is omitted when
-there is no defensible uncertainty/accuracy metadata to report.
+Deterministic analytical results stay lightweight. They omit `quality` when
+there is no defensible uncertainty or accuracy metadata to report.
+
+Read-only from 2.0.0: the envelope, `provenance` and `quality` are frozen deeply and `value`
+at its top level. Copy a value before changing it. Typed arrays inside a value stay mutable.
+See docs/API_STYLE.md "Read-only results".
 
 ```ts
 export interface CalculationResult<T> {
-  value: T;
-  provenance: CalculationProvenance;
-  quality?: CalculationQuality;
+  readonly value: T;
+  readonly provenance: CalculationProvenance;
+  readonly quality?: CalculationQuality;
 }
 ```
 
 ## CalculationValidRange
 
-Documented parameter range over which a model/calibration is considered
-valid. This is model applicability metadata, not a statistical interval.
+The documented parameter range in which a model or calibration is valid.
+It says where the model applies. It is not a statistical interval.
 
 ```ts
 export interface CalculationValidRange {
@@ -174,8 +178,8 @@ export interface RelativeUncertaintyEstimate extends UncertaintyEstimateBase {
 
 Optional confidence metadata for a quantified uncertainty estimate.
 
-A confidence level is only meaningful when the basis can be stated. It must
-not be used as a generic subjective confidence score.
+Give a confidence level only when you can state its basis. Do not use it as a
+general, subjective confidence score.
 
 ```ts
 export interface UncertaintyConfidence {

package/docs/api/core-configuration-error.md

@@ -1,6 +1,6 @@
 # core/configuration-error.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.
 
 ## InvalidConfigurationError
 

package/docs/api/core-image-formation.md

@@ -1,13 +1,13 @@
 # core/image-formation.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.
 
 ## getImageFormationContract
 
-Returns the public image-formation ownership/order contract.
+Returns the image-formation contract: the order of stages and who owns each one.
 
-The result is descriptive metadata, not a renderer implementation or an
-assertion that every reserved stage is currently available.
+The result is descriptive metadata. It is not a renderer, and a listed stage is not
+necessarily available yet.
 
 ```ts
 export function getImageFormationContract(): ImageFormationContract;
@@ -19,9 +19,9 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 Version of the public image-formation ordering contract.
 
-This version is independent from package, root-engine, and composed-POC
-versions. It describes semantic ownership/order only; it does not imply that
-every reserved stage is implemented.
+It is separate from the package, root-engine and composed proof-of-concept (POC)
+versions. It covers only stage order and ownership. It does not mean every listed
+stage is implemented.
 
 ```ts
 IMAGE_FORMATION_CONTRACT_VERSION = "0.4.0" as const

package/docs/api/core-scientific-assurance.md

@@ -1,14 +1,16 @@
 # core/scientific-assurance.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.
 
 ## ComposedScientificAssurance
 
-Cross-stage status and retained evidence for one declared scientific result.
-Required incomplete/approximate children constrain the aggregate; deterministic
-processing cannot upgrade approximation to calibration. Uncertainty components
-remain independently identified unless an explicit mathematical propagation model
-justifies a combination. A count of successful stages is not an accuracy bound.
+Combined status and kept evidence for one declared scientific result across stages.
+
+- A required input that is incomplete or approximate limits the combined status.
+- Deterministic processing cannot turn an approximation into a calibration.
+- Uncertainty components stay separate unless an explicit mathematical propagation
+  model justifies combining them.
+- A count of successful stages is not an accuracy bound.
 
 ```ts
 export interface ComposedScientificAssurance {
@@ -70,11 +72,11 @@ export type ComposedScientificUncertaintyStatus =
 
 ## composeScientificAssurance
 
-Composes scientific-status, evidence and uncertainty semantics without
-inventing a numeric aggregate uncertainty.
+Combines the scientific status, evidence and uncertainty of several inputs into one
+record, without inventing a single numeric uncertainty.
 
-Required downstream status is bounded by the weakest required input.
-Component evidence/uncertainty is preserved verbatim after validation.
+The combined status can be no better than the weakest required input. Each component's
+evidence and uncertainty is kept exactly as given, after validation.
 
 ```ts
 export function composeScientificAssurance(

package/docs/api/core-spectral-composition.md

@@ -1,15 +1,15 @@
 # core/spectral-composition.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.
 
 ## composeSpectralCoverage
 
-Intersects continuous spectral support and unions all interpolation
-breakpoints inside the common range.
+Finds the wavelength range that all continuous inputs share, and collects every
+interpolation breakpoint inside it.
 
-Air/vacuum conversion is never implicit. Discrete lines are deliberately
-excluded because delta-like line measures require a different integration
-path from continuous per-nanometre densities.
+Air and vacuum wavelengths are never converted implicitly. Discrete lines are not
+accepted here: a delta-like line is integrated differently from a continuous
+per-nanometre density.
 
 ```ts
 export function composeSpectralCoverage(
@@ -121,8 +121,8 @@ export interface IntegratedDiscreteSpectralLineMeasure {
 
 ## integrateDiscreteSpectralLineMeasure
 
-Integrates a discrete line measure by summing already wavelength-integrated
-line contributions. No d-lambda factor is applied.
+Integrates over discrete lines by summing their contributions, which are already
+integrated over wavelength. No dλ (wavelength step) factor is applied.
 
 ```ts
 export function integrateDiscreteSpectralLineMeasure(
@@ -163,10 +163,10 @@ export interface NormalizedDiscreteSpectralLineDistribution {
 
 ## parseNormalizedDiscreteSpectralLineDistribution
 
-Parses a normalized set of delta-like discrete spectral lines.
+Parses a normalized set of discrete spectral lines (each treated as a delta function).
 
-Each weight is an integrated line fraction, not a per-nanometre spectral
-density sample. The weights must sum to one.
+Each weight is the fraction of the total carried by that line. It is not a
+per-nanometre density sample. The weights must sum to one.
 
 ```ts
 export function parseNormalizedDiscreteSpectralLineDistribution(
@@ -180,10 +180,10 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSpectralCoverageParticipant
 
-Parses one continuous spectral-coverage participant.
+Parses the wavelength coverage of one continuous spectral input.
 
-This contract describes support and interpolation breakpoints only. It does
-not carry spectral values, transmission, response, radiance, or uncertainty.
+It describes only the wavelength range (support) and interpolation breakpoints. It
+carries no spectral values, transmission, response, radiance or uncertainty.
 
 ```ts
 export function parseSpectralCoverageParticipant(