@photivra/engine 1.5.0 → 2.1.0

package/docs/api/sensor-capture-color-sampling-binding.md

@@ -1,6 +1,6 @@
 # sensor/capture-color-sampling-binding.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.
 
 ## CaptureModeFullFrameSampleIndex
 
@@ -9,9 +9,9 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface CaptureModeFullFrameSampleIndex {
   /**
-   * Zero-based index in the selected mode's full-frame per-frame effective
-   * sampling raster. Crop-local coordinates must be translated to absolute
-   * full-frame mode indices before calling this API.
+   * Zero-based index in the selected mode's full-frame sample grid (per frame).
+   * Convert crop-relative coordinates to absolute full-frame indices before
+   * calling this API.
    */
   x: number;
   y: number;
@@ -90,34 +90,35 @@ export interface NativeEffectiveRasterColorSamplingBindingProfile {
   bindingId: string;
   colorSamplingProfileId: string;
   /**
-   * Exact canonical native effective raster this binding was evidenced for.
-   * The binding must not be reused against a different raster merely because
-   * another sensor/mode has similar dimensions or a matching aspect ratio.
+   * The exact native image grid this binding has evidence for. Do not reuse
+   * the binding with another grid just because another sensor or mode has
+   * similar dimensions or the same aspect ratio.
    */
   nativeRaster: NativeImageRaster;
   /**
-   * Evidence supporting the native-effective-grid ↔ color-site-grid
-   * relationship itself.
+   * Evidence for the link between the native image grid and the colour-site
+   * grid itself.
    *
-   * Capture-mode and color-topology facts retain separate provenance.
+   * Capture-mode and colour-layout facts keep their own separate evidence.
    */
   evidence: readonly EvidenceProvenance[];
   relationship: {
     kind: "regular-native-effective-sample-blocks";
     /**
-     * Number of abstract color-sampling sites spanned horizontally by one
-     * native effective image sample.
+     * Number of colour-sampling sites one native image sample spans
+     * horizontally.
      */
     sitesPerNativeSampleX: number;
     /**
-     * Number of abstract color-sampling sites spanned vertically by one
-     * native effective image sample.
+     * Number of colour-sampling sites one native image sample spans
+     * vertically.
      */
     sitesPerNativeSampleY: number;
     /**
-     * Both grids are anchored to the same native sensor top-left.
+     * Both grids start at the same native sensor top-left corner.
      *
-     * This keeps phase absolute across later active crops/orientation.
+     * This keeps the CFA phase absolute through later active-area crops and
+     * orientation changes.
      */
     anchor: "shared-native-top-left";
   };
@@ -139,12 +140,12 @@ export interface NativeEffectiveSampleRect {
 
 ## parseNativeEffectiveRasterColorSamplingBindingProfile
 
-Parses the explicit relationship between the canonical native effective image
-raster and the separate native sensor color-sampling-site lattice.
+Parses the explicit link between the native image pixel grid and the separate
+grid of colour-sampling sites.
 
-This first binding supports only regular rectangular site blocks with a
-shared native top-left anchor. Irregular mappings, sparse exceptions and
-mode-specific declared-effective rasters require later explicit contracts.
+This first version supports only regular rectangular blocks of sites that
+share the native top-left corner. Irregular mappings, sparse exceptions and
+mode-specific declared grids would need new, explicit contracts.
 
 ```ts
 export function parseNativeEffectiveRasterColorSamplingBindingProfile(
@@ -156,28 +157,24 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## resolveCaptureModeColorSamplingContributors
 
-Resolves which color-sampling sites form the pre-reconstruction structural source region for one selected
-capture-mode effective sample.
+Finds which colour-sampling sites lie under one capture-mode sample, before any
+reconstruction (demosaicing).
 
-The mode sample index is always absolute in the selected mode's full-frame
-per-frame raster. The API intentionally does not accept crop-local indices,
-preventing active-crop origins from silently resetting CFA phase.
+The sample index is always absolute in the selected mode's full-frame grid. Crop-relative
+indices are not accepted, so an active-area crop can never silently reset the CFA phase.
 
-For grouped-native-sample modes, the returned site rectangle covers all
-native effective samples in the declared regular group. This is a structural
-pre-reconstruction association only: the engine reports channel-site counts
-but never claims complete downstream digital-pixel dependency or invents
-signal-combination weights, sum/average semantics, spectral response, or
-photon/electron values.
+For modes that group native samples, the returned rectangle covers every native sample in
+the declared regular group. This only describes which sites lie under the sample. The engine
+reports how many sites of each channel there are, but does not claim this is every dependency
+of the final digital pixel. It never makes up combination weights, sum or average rules,
+spectral response, or photon or electron values.
 
-Declared-effective-raster modes fail closed because #68 explicitly says
-their relationship to the native effective grid is not safely expressible as
-simple integer grouping.
+Modes with a declared sample grid are rejected, because the capture-mode profile says their
+relationship to the native grid cannot safely be written as simple integer grouping.
 
-Inter-frame sensor shifts are preserved as capture-mode metadata only. The
-sensor and CFA move together, so those offsets do not change site channel
-assignment; their optical-registration effect belongs to a later spatial
-sampling/image-formation contract.
+Sensor shifts between frames are kept as capture-mode metadata only. The sensor and CFA move
+together, so the shifts do not change which channel a site belongs to. Their effect on optical
+registration belongs to a later spatial-sampling or image-formation model.
 
 ```ts
 export function resolveCaptureModeColorSamplingContributors(
@@ -200,8 +197,8 @@ export interface ResolveCaptureModeColorSamplingContributorsInput {
   bindingProfile: NativeEffectiveRasterColorSamplingBindingProfile;
   modeSampleIndexFullFrame: CaptureModeFullFrameSampleIndex;
   /**
-   * Required for grouped-native-samples modes because #68 declares grouping
-   * factors but does not itself prove the grouping phase/origin.
+   * Required for modes that group native samples, because the capture-mode
+   * profile declares grouping factors but does not prove where the groups start.
    */
   groupedSamplingAnchor?: GroupedCaptureModeSamplingAnchorDeclaration;
 }
@@ -232,8 +229,8 @@ export interface ResolvedCaptureModeColorSamplingContributors {
   channelSiteCounts: readonly ColorSamplingChannelSiteCount[];
   channelComposition: ColorSamplingChannelComposition;
   /**
-   * Present only when the selected capture mode groups native effective
-   * samples before producing one per-frame effective sample.
+   * Present only when the selected capture mode groups several native samples
+   * into one sample per frame.
    */
   grouping:
     | {
@@ -245,10 +242,10 @@ export interface ResolvedCaptureModeColorSamplingContributors {
       }
     | null;
   /**
-   * Sensor-shift sequence remains attached to the sensor/capture mode.
+   * The sensor-shift sequence stays attached to the sensor and capture mode.
    *
-   * The sensor and its CFA move together, so these offsets must not be applied
-   * as changes to color-site channel assignment.
+   * The sensor and its CFA move together, so these offsets must not change
+   * which colour channel a site belongs to.
    */
   interFrameSensorOffsetsNativeSamples?: SourcedCaptureModeFact<
     readonly CaptureModeSensorOffsetNativeSamples[]
@@ -303,12 +300,11 @@ export interface ResolvedNativeEffectiveRasterColorSamplingBinding {
 
 ## resolveNativeEffectiveRasterColorSamplingBinding
 
-Validates and resolves the sensor-level binding between NativeImageRaster and
-an exact monochrome/periodic color-sampling topology.
+Validates and resolves the link between NativeImageRaster and an exact colour
+sampling layout (monochrome or a repeating pattern such as a CFA).
 
-Matching dimensions are never treated as proof of a 1:1 relationship. The
-relationship exists only because the caller supplied this evidence-backed
-binding profile.
+Matching dimensions are never taken as proof of a one-to-one link. The link
+exists only because the caller supplied this evidence-backed binding profile.
 
 ```ts
 export function resolveNativeEffectiveRasterColorSamplingBinding(

package/docs/api/sensor-capture-mode-timing.md

@@ -1,6 +1,6 @@
 # sensor/capture-mode-timing.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.
 
 ## CAPTURE_MODE_TIMING_PROFILE_SCHEMA_VERSION
 
@@ -41,11 +41,11 @@ export interface CaptureModeTimingProfile {
 
 ## parseCaptureModeTimingProfile
 
-Parses timing facts that are explicitly bound to one exact capture mode.
+Parses timing facts tied to one exact capture mode.
 
-Schema 0.1.0 intentionally admits only the timing schedule families already
-owned by #12: simultaneous/global or uniform-linear native scans. Unsupported
-non-uniform/segmented schedules fail closed instead of being approximated.
+Schema 0.1.0 accepts only the schedules the readout-timing and exposure-window
+models already support: global (simultaneous) or uniform linear native scans.
+Non-uniform or segmented schedules are rejected rather than approximated.
 
 ```ts
 export function parseCaptureModeTimingProfile(
@@ -57,11 +57,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## resolveCaptureModeTiming
 
-Resolves the authoritative exposure/readout timing for one exact capture
-mode and timing-profile identity.
+Resolves the exposure and readout timing for one exact capture mode and
+timing profile.
 
-Readout timing remains distinct from exposure-boundary timing. No absolute
-readout/exposure synchronization is inferred.
+Readout timing stays separate from the exposure opening and closing times.
+No absolute sync between readout and exposure is assumed.
 
 ```ts
 export function resolveCaptureModeTiming(

package/docs/api/sensor-capture-mode.md

@@ -1,6 +1,6 @@
 # sensor/capture-mode.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.
 
 ## CaptureModeAcquisition
 
@@ -21,30 +21,30 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface CaptureModeDefinition {
   modeId: string;
   /**
-   * Evidence supporting the existence/overall acquisition behavior of this
-   * mode. Field-level facts below retain their own evidence when needed.
+   * Evidence that this mode exists and for how it captures overall. Facts in
+   * the fields below keep their own evidence where needed.
    */
   evidence: readonly EvidenceProvenance[];
   acquisition: CaptureModeAcquisition;
   perFrameSampling: CaptureModePerFrameSampling;
   /**
-   * Optional ordered sensor-displacement sequence for fixed multi-frame modes.
-   * The whole sequence is one evidence-backed fact because published mode
-   * documentation commonly describes the sequence as a unit.
+   * Optional ordered sequence of sensor shifts, for modes with a fixed number
+   * of frames. The whole sequence is one evidence-backed fact, because
+   * published documentation usually describes it as a unit.
    */
   interFrameSensorOffsetsNativeSamples?: SourcedCaptureModeFact<
     readonly CaptureModeSensorOffsetNativeSamples[]
   >;
   /**
-   * Ordered reconstruction/combination stages owned by later reconstruction
-   * work. These labels reserve semantics; they do not implement algorithms.
+   * Ordered reconstruction or combination stages. These labels only name the
+   * stages for later reconstruction models; they implement no algorithm.
    */
   reconstructionStages?: readonly SourcedCaptureModeFact<CaptureModeReconstructionStage>[];
   /**
-   * Image raster produced by the capture-mode/reconstruction pipeline before
-   * final output crop/resampling.
+   * Image size produced by the capture mode and reconstruction, before the
+   * final output crop or resampling.
    *
-   * This raster does not redefine physical sensor geometry or field of view.
+   * It does not change the physical sensor geometry or field of view.
    */
   processedImageRaster: SourcedCaptureModeFact<RasterDimensions>;
   /**
@@ -117,13 +117,13 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface CaptureModeSensorOffsetNativeSamples {
   /**
-   * Horizontal sensor displacement in units of the native effective sampling
-   * pitch. This is not a claim about physical photodiode pitch.
+   * Horizontal sensor shift, in units of the native sample pitch. This says
+   * nothing about the physical photodiode pitch.
    */
   x: number;
   /**
-   * Vertical sensor displacement in units of the native effective sampling
-   * pitch. This is not a claim about physical photodiode pitch.
+   * Vertical sensor shift, in units of the native sample pitch. This says
+   * nothing about the physical photodiode pitch.
    */
   y: number;
 }
@@ -137,8 +137,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface DeclaredEffectiveCaptureSampling {
   kind: "declared-effective-raster";
   /**
-   * Per-frame effective sampling raster for a mode whose sampling relationship
-   * to the native grid is not safely expressible as simple integer grouping.
+   * Sample grid per frame, for a mode whose relationship to the native grid
+   * cannot safely be written as simple integer grouping.
    */
   raster: SourcedCaptureModeFact<RasterDimensions>;
 }
@@ -165,8 +165,8 @@ export interface GroupedNativeCaptureSampling {
   groupWidthSamples: SourcedCaptureModeFact<number>;
   groupHeightSamples: SourcedCaptureModeFact<number>;
   /**
-   * Omitted means unknown/unasserted. Do not infer where combination occurs
-   * from the word "binning" or from the raster ratio.
+   * Omitted means "unknown, not stated". Do not guess where samples are
+   * combined from the word "binning" or from the ratio of image sizes.
    */
   combinationDomain?: SourcedCaptureModeFact<CaptureModeSampleCombinationDomain>;
 }
@@ -184,12 +184,12 @@ export interface NativeEffectiveCaptureSampling {
 
 ## parseCaptureModeProfile
 
-Parses a capture-mode profile without inferring sensor physics from output
+Parses a capture-mode profile. Sensor physics is never guessed from output
 resolution or marketing mode names.
 
-The profile is intentionally orthogonal: acquisition frame sequence,
-per-frame sampling, optional inter-frame sensor shift, reconstruction stages,
-processed raster and downstream dependencies are independent axes.
+The profile's parts are independent of each other: the frame sequence,
+sampling within each frame, optional sensor shift between frames,
+reconstruction stages, the processed image size and downstream dependencies.
 
 ```ts
 export function parseCaptureModeProfile(
@@ -201,12 +201,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## resolveCaptureMode
 
-Resolves one capture mode against the selected sensor's native effective
-image-sampling raster.
+Resolves one capture mode against the selected sensor's native pixel grid.
 
-Resolution changes do not mutate physical sensor geometry. The returned
-processed raster is pre-output geometry and must not be used to infer crop
-factor, field of view or physical photosite count.
+Resolution changes do not change the physical sensor geometry. The returned
+processed image size is before output, and must not be used to work out crop
+factor, field of view or the physical photosite count.
 
 ```ts
 export function resolveCaptureMode(
@@ -311,8 +310,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface VariableMultiFrameCaptureAcquisition {
   kind: "variable-multi-frame";
   /**
-   * Evidence that the mode is variable/multi-frame, even when exact count
-   * bounds are not published.
+   * Evidence that the mode uses a variable number of frames, even when the
+   * exact frame-count limits are not published.
    */
   evidence: readonly EvidenceProvenance[];
   minimumFrameCount?: SourcedCaptureModeFact<number>;

package/docs/api/sensor-color-sampling.md

@@ -1,6 +1,6 @@
 # sensor/color-sampling.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.
 
 ## LayeredColorSamplingLayout
 
@@ -10,13 +10,13 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface LayeredColorSamplingLayout {
   kind: "layered";
   /**
-   * Semantic layer/channel identifiers only. They do not define spectral
-   * response, depth ordering, spatial sampling density, or registration.
+   * Names for the layers or channels only. They do not define spectral
+   * response, depth order, sampling density or alignment between layers.
    */
   layerChannelIds: readonly string[];
   /**
-   * The first layered representation is deliberately structural only because
-   * real layered sensors may use unequal per-layer spatial sampling.
+   * Layered layouts are described structurally only for now, because real
+   * layered sensors may sample each layer differently.
    */
   spatialSamplingRelationship: "not-resolved";
 }
@@ -30,8 +30,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface MonochromeColorSamplingLayout {
   kind: "monochrome";
   /**
-   * Semantic measurement-channel identifier only. It is not a spectral
-   * response curve, wavelength, colorimetric primary, or calibration.
+   * A name for the measured channel only. It is not a spectral response
+   * curve, wavelength, colour primary or calibration.
    */
   channelId: string;
 }
@@ -55,8 +55,8 @@ export interface NativeColorSamplingSiteIndex {
   /**
    * Zero-based integer site index from the native sensor's left edge.
    *
-   * This is an abstract color-sampling-site lattice index. It is not a
-   * NativeImageRaster coordinate and does not assert one site = one physical
+   * It indexes the abstract grid of colour-sampling sites. It is not a
+   * NativeImageRaster coordinate and does not claim one site is one physical
    * photodiode.
    */
   x: number;
@@ -71,19 +71,17 @@ export interface NativeColorSamplingSiteIndex {
 
 ## parseSensorColorSamplingProfile
 
-Parses an exact color-sampling topology declaration without binding it to
-NativeImageRaster, physical photodiodes, spectral response, or a
-manufacturer-specific family enum.
+Parses an exact colour-sampling layout. It is not tied to NativeImageRaster,
+physical photodiodes, spectral response or a manufacturer's layout name.
 
-Periodic mosaics use an abstract native sensor color-sampling-site lattice
-with zero-based integer indices, top-left origin, +X right and +Y down.
-The repeat phase is anchored to the sensor lattice, so later active crops or
-orientation transforms must preserve the original native site indices.
+Repeating mosaics use an abstract grid of native sensor sites with zero-based
+integer indices, origin at the top left, +X right and +Y down. The repeat
+pattern is fixed to this grid, so later crops or orientation changes must keep
+the original native site indices.
 
-Layered layouts are structural-only in this first contract because real
-layered sensors may use unequal spatial sampling density/registration across
-layers. No per-site layered resolver is exposed until that relationship is
-modeled explicitly.
+Layered layouts are described structurally only, because real layered sensors
+may sample each layer at different densities or offsets. There is no per-site
+lookup for layered layouts until that is modelled explicitly.
 
 ```ts
 export function parseSensorColorSamplingProfile(
@@ -109,15 +107,15 @@ export interface PeriodicMosaicColorSamplingLayout {
    */
   repeatHeightSites: number;
   /**
-   * Row-major semantic channel IDs for one repeating tile.
+   * Channel IDs for one repeating tile, in row-major order.
    *
    * Length must equal repeatWidthSites × repeatHeightSites.
    */
   siteChannelIds: readonly string[];
   /**
-   * The repeat tile is anchored at native sensor sampling-site index (0, 0).
+   * The repeat tile starts at native sensor site (0, 0).
    *
-   * Active crops and physical orientation must not silently reset this phase.
+   * Active-area crops and camera orientation must not silently reset this phase.
    */
   anchor: "native-sensor-top-left-site";
 }
@@ -125,15 +123,15 @@ export interface PeriodicMosaicColorSamplingLayout {
 
 ## resolveColorSamplingSite
 
-Resolves the semantic measurement-channel assignment at one abstract native
-sensor color-sampling-site index for monochrome or periodic-mosaic layouts.
+Returns which channel one native site measures, for monochrome or repeating
+mosaic layouts.
 
-This API intentionally has no NativeImageRaster input. A later explicit
-binding must establish how a selected capture mode's effective raster maps
-to this color-sampling-site lattice before RAW/CFA sampling can be simulated.
+It deliberately takes no NativeImageRaster. A separate binding
+(capture-color-sampling-binding) must say how a capture mode's sample grid
+maps onto this site grid before RAW or CFA sampling can be simulated.
 
-Layered layouts fail closed because their per-layer spatial relationship is
-not resolved by the first structural contract.
+Layered layouts are rejected, because how their layers line up spatially is
+not defined yet.
 
 ```ts
 export function resolveColorSamplingSite(
@@ -179,7 +177,7 @@ export interface ResolvedColorSamplingSite {
         repeatHeightSites: number;
       };
   /**
-   * Explicit scientific boundaries for downstream consumers.
+   * States what this profile does not establish, for downstream code.
    */
   spectralResponseEstablished: false;
   nativeImageRasterBindingEstablished: false;
@@ -207,9 +205,9 @@ export interface SensorColorSamplingProfile {
   schemaVersion: "0.1.0";
   profileId: string;
   /**
-   * Evidence supporting this exact topology declaration.
+   * Evidence for this exact layout.
    *
-   * Descriptive architecture-family metadata remains a separate contract.
+   * Descriptive sensor-architecture metadata is a separate type.
    */
   evidence: readonly EvidenceProvenance[];
   coordinateSystem: SensorColorSamplingProfileCoordinateSystem;

package/docs/api/sensor-constant-rate-temporal-integration.md

@@ -1,6 +1,6 @@
 # sensor/constant-rate-temporal-integration.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.
 
 ## IntegrateStationarySensorRateInput
 
@@ -19,11 +19,12 @@ export interface IntegrateStationarySensorRateInput {
 
 ## integrateStationarySensorRateOverLocalExposure
 
-Integrates one explicitly stationary response-rate result over its exact
-bound local exposure window.
+Integrates one response rate, declared constant, over its exact local
+exposure window.
 
-This function is intentionally limited to the constant-rate approximation.
-It does not sample or integrate a time-varying signal.
+This is the constant-rate approximation only. It does not sample or
+integrate a time-varying signal. EQE rates give expected photons and
+electrons; A/W rates give coulombs. Counts stay fractional.
 
 ```ts
 export function integrateStationarySensorRateOverLocalExposure(
@@ -36,13 +37,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSensorRateTemporalStationarityProfile
 
-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.
 
-Rate times duration is allowed only by explicit stationarity bound to the exact site and local
-shutter interval. EQE integrates to expected photons/electrons; A/W integrates current magnitude to
-coulombs without an implicit carrier mapping. Counts remain fractional expectations before
-stochastic sampling.
+The profile declares that a rate is constant (stationary) for an exact site and local shutter
+interval, which is what allows rate × duration.
 
 ```ts
 export function parseSensorRateTemporalStationarityProfile(

package/docs/api/sensor-dark-current.md

@@ -1,16 +1,14 @@
 # sensor/dark-current.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.
 
 ## calculateSensorDarkCurrentCharge
 
-Evaluate the declared temperature-dependent dark electron rate and integrate over the exact
-photo-signal local exposure event.
+Evaluates the declared dark-current rate at the sensor temperature and integrates it over the exact
+local exposure of the photo signal.
 
-Dark current is an independently declared pre-compensation thermal electron rate. Exact-temperature
-or sampled linear interpolation is supported only within declared applicability; no universal
-doubling-temperature law is inferred. Population means remain approximations and do not model
-hot-pixel/DCNU structure.
+The rate is a population mean, an approximation. Hot pixels and DCNU (dark-current non-uniformity)
+are not modelled. No universal doubling-temperature law is assumed.
 
 ```ts
 export function calculateSensorDarkCurrentCharge(
@@ -55,13 +53,12 @@ export interface CalculateSensorDarkCurrentChargeInput<Exposure extends SensorEq
 
 ## parseSensorDarkCurrentProfile
 
-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.
 
-Dark current is an independently declared pre-compensation thermal electron rate. Exact-temperature
-or sampled linear interpolation is supported only within declared applicability; no universal
-doubling-temperature law is inferred. Population means remain approximations and do not model
-hot-pixel/DCNU structure.
+The profile declares the dark-current rate (before compensation) against temperature, at an exact
+temperature or as samples. Interpolation (log-linear, or the legacy linear rule) is allowed only
+within the declared range. No universal doubling-temperature law is assumed.
 
 ```ts
 export function parseSensorDarkCurrentProfile(
@@ -193,6 +190,7 @@ export type SensorDarkCurrentTemperatureModel =
         number;
     }
   | {
+      /** Legacy interpolation, linear in rate. Between samples of an exponential curve it gives values that are too high. */
       kind:
         "piecewise-linear-temperature-table";
       interpolation: "piecewise-linear";
@@ -203,6 +201,24 @@ export type SensorDarkCurrentTemperatureModel =
         darkCurrentElectronsPerSecond:
           number;
       }[];
+    }
+  | {
+      /**
+       * Linear interpolation of ln(rate) between neighbouring samples. That makes the rate exponential
+       * in temperature within each interval, matching the roughly exponential (Arrhenius, or
+       * "doubling temperature") behaviour of thermally generated dark current. Rates must be strictly
+       * positive. No single doubling temperature is imposed; each interval follows its own two samples.
+       */
+      kind:
+        "log-linear-temperature-table";
+      interpolation: "log-linear";
+      outsideRangeBehavior:
+        "fail-closed";
+      samples: readonly {
+        temperatureC: number;
+        darkCurrentElectronsPerSecond:
+          number;
+      }[];
     };
 ```
 
@@ -216,7 +232,7 @@ export type SensorPhotoDarkCurrentCharge = SensorDarkCurrentCharge | SensorTempo
 
 ## SensorTemporalDarkCurrentCharge
 
-Dark charge shares the exact temporal photo event, without a stationarity ID.
+Dark charge for the exact same time-resolved photo event. It has no stationarity ID.
 
 ```ts
 export type SensorTemporalDarkCurrentCharge = Omit<SensorDarkCurrentCharge, "stationarityProfileId" | "temporalIntegrationId" | "componentEvidence"> & {