@photivra/engine 1.5.0 → 2.0.0

package/docs/api/sensor-fixed-pattern-noise.md

@@ -0,0 +1,104 @@
+# sensor/fixed-pattern-noise.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculateSensorFixedPatternSite
+
+Computes the fixed-pattern values of one absolute colour-sampling site.
+
+- PRNU gain g = max(0, 1 + σ_PRNU·z₁);
+- hot pixel when u < f_hot, then dark factor d = m_hot; otherwise d = max(0, 1 + σ_DSNU·z₂);
+- row offset σ_row·z(row y), column offset σ_col·z(column x), in input-referred electrons.
+
+Each z is a standard normal value and u a uniform value, each from its own stream hashed with
+MurmurHash3 from (sensorInstanceSeed, x, y, stream). Row values use x = 0 and column values y = 0,
+so a whole row or column shares one value. Cutting negative factors off at zero shifts the mean
+factor by less than 1e-6 for σ ≤ 0.2.
+
+```ts
+export function calculateSensorFixedPatternSite(input: {
+  profile: SensorFixedPatternNoiseProfile; site: { x: number; y: number };
+}): SensorFixedPatternSiteValues;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSensorFixedPatternNoiseProfile
+
+Validates an untrusted fixed-pattern noise profile. Unknown keys, out-of-range parameters and
+missing evidence are rejected. The PRNU and DSNU relative standard deviations are limited to 0.5
+and 5, and the hot-pixel multiplier to 1–1e6.
+
+```ts
+export function parseSensorFixedPatternNoiseProfile(value: unknown): SensorFixedPatternNoiseProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SENSOR_FIXED_PATTERN_NOISE_MODEL
+
+Versioned identity of the pattern-generation equations and seed schedule.
+
+```ts
+SENSOR_FIXED_PATTERN_NOISE_MODEL = Object.freeze({ id: "photivra-sensor-fixed-pattern", version: "1.0.0" } as const)
+```
+
+## SENSOR_FIXED_PATTERN_NOISE_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SENSOR_FIXED_PATTERN_NOISE_PROFILE_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## SensorFixedPatternNoiseProfile
+
+Explicit fixed-pattern parameters for one sensor instance. Every component is required; a zero
+standard deviation, fraction or RMS disables that component.
+
+```ts
+export interface SensorFixedPatternNoiseProfile {
+  schemaVersion: typeof SENSOR_FIXED_PATTERN_NOISE_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  /** The colour-sampling grid whose absolute site coordinates index the pattern. */
+  colorSamplingProfileId: string;
+  scientificStatus: "approximation";
+  /** Identifies the physical sensor. Independent of every per-capture noise seed. */
+  sensorInstanceSeedUint32: number;
+  /** EMVA 1288 PRNU: spatial standard deviation of the photo response divided by its mean. */
+  photoResponseNonUniformity: { relativeStandardDeviation: EvidenceBackedFact<number> };
+  /** Spatial standard deviation of the dark-current rate divided by the population-mean rate. */
+  darkSignalNonUniformity: { relativeStandardDeviation: EvidenceBackedFact<number> };
+  /** Fraction of sites whose dark-current rate is the population mean times the multiplier. */
+  hotPixels: { siteFraction: EvidenceBackedFact<number>; darkCurrentMultiplier: EvidenceBackedFact<number> };
+  /** Fixed readout offset per row, in input-referred electrons, normally distributed with zero mean. */
+  rowOffset: { rmsElectrons: EvidenceBackedFact<number> };
+  /** Fixed readout offset per column, in input-referred electrons, normally distributed with zero mean. */
+  columnOffset: { rmsElectrons: EvidenceBackedFact<number> };
+  patternDistribution: "normal-factors-truncated-at-zero";
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## SensorFixedPatternSiteValues
+
+The deterministic pattern values of one colour-sampling site.
+
+```ts
+export interface SensorFixedPatternSiteValues {
+  profileId: string;
+  modelId: typeof SENSOR_FIXED_PATTERN_NOISE_MODEL.id;
+  modelVersion: typeof SENSOR_FIXED_PATTERN_NOISE_MODEL.version;
+  site: { x: number; y: number };
+  /** Multiplies the expected photo charge (1 = no PRNU); never negative. */
+  photoResponseGainFactor: number;
+  /** Multiplies the population-mean dark expectation (1 = no DSNU); never negative. */
+  darkCurrentFactor: number;
+  hotPixel: boolean;
+  rowOffsetElectrons: number;
+  columnOffsetElectrons: number;
+  /** rowOffsetElectrons + columnOffsetElectrons, added at readout. */
+  readoutOffsetElectrons: number;
+}
+```

package/docs/api/sensor-iso-gain.md

@@ -0,0 +1,63 @@
+# sensor/iso-gain.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## createIsoGainReadoutRegimes
+
+Builds a readout regime and signal-chain band for each exposure index (see the module comment
+for the equations). The result is checked with the same rules as parseSensorReadoutConversionProfile.
+Each regime carries an `exposureIndexGain` record of how it was derived.
+
+```ts
+export function createIsoGainReadoutRegimes(input: CreateIsoGainReadoutRegimesInput): IsoGainReadoutRegimes;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateIsoGainReadoutRegimesInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateIsoGainReadoutRegimesInput {
+  regimeIdPrefix: string;
+  scientificStatus: SensorSpectralResponseScientificStatus;
+  baseExposureIndex: number;
+  /** Strictly increasing settings, each at least the base exposure index. */
+  exposureIndices: readonly number[];
+  /** Q0: electron-equivalent signal that reaches digital saturation at the base exposure index. */
+  baseSaturationElectronEquivalent: EvidenceBackedFact<number>;
+  /** A_max: largest analog gain relative to the base regime (>= 1). */
+  maximumAnalogGain: EvidenceBackedFact<number>;
+  adc: { bitDepth: number; blackLevelCode: number; digitalSaturationCode: number };
+  conversionGainModes: readonly IsoGainConversionGainMode[];
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## IsoGainConversionGainMode
+
+One conversion-gain mode, active from its minimum exposure index up to the next mode's.
+
+```ts
+export interface IsoGainConversionGainMode {
+  mode: SensorReadoutExposureIndexGain["conversionGainMode"];
+  minimumExposureIndex: number;
+  readNoiseRmsElectrons: EvidenceBackedFact<number>;
+  /** Optional charge storage limit of this mode. Every regime's pre-ADC threshold must be at or below it. */
+  maximumChargeElectrons?: EvidenceBackedFact<number>;
+}
+```
+
+## IsoGainReadoutRegimes
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IsoGainReadoutRegimes {
+  regimes: readonly SensorReadoutConversionRegime[];
+  /** One single-value band per setting, ready for a GenericIsoSignalChainProfile. */
+  standardRegimeBands: readonly GenericIsoStandardRegimeBand[];
+}
+```

package/docs/api/sensor-iso-signal-chain.md

@@ -1,6 +1,6 @@
 # sensor/iso-signal-chain.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.
 
 ## GENERIC_ISO_SIGNAL_CHAIN_PRESET_CATALOG_SCHEMA_VERSION
 
@@ -128,12 +128,10 @@ export interface GenericIsoStandardRegimeBand {
 
 ## parseGenericIsoSignalChainPresetCatalog
 
-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.
 
-The selected ISO/capture-mode state binds an explicit generic readout regime. Photons and photo/dark
-shot-noise expectations remain upstream; regime gain, read noise and clipping are separately
-declared. Generic tier labels do not calibrate or rank commercial equipment.
+Generic tier labels in the catalogue do not calibrate or rank real cameras.
 
 ```ts
 export function parseGenericIsoSignalChainPresetCatalog(
@@ -145,12 +143,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseGenericIsoSignalChainProfile
 
-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.
 
-The selected ISO/capture-mode state binds an explicit generic readout regime. Photons and photo/dark
-shot-noise expectations remain upstream; regime gain, read noise and clipping are separately
-declared. Generic tier labels do not calibrate or rank commercial equipment.
+The profile binds each ISO and capture-mode state to an explicit readout regime, whose gain,
+read noise and clipping are declared separately.
 
 ```ts
 export function parseGenericIsoSignalChainProfile(
@@ -198,12 +195,8 @@ export interface ResolvedGenericIsoSignalChain {
 
 ## resolveGenericIsoSignalChain
 
-Select the explicit readout regime bound to the resolved ISO and capture-mode state; do not derive
-gain/noise from an ISO number.
-
-The selected ISO/capture-mode state binds an explicit generic readout regime. Photons and photo/dark
-shot-noise expectations remain upstream; regime gain, read noise and clipping are separately
-declared. Generic tier labels do not calibrate or rank commercial equipment.
+Picks the explicit readout regime bound to the resolved ISO and capture-mode state. Gain and noise
+are never derived from the ISO number.
 
 ```ts
 export function resolveGenericIsoSignalChain(
@@ -234,12 +227,10 @@ export interface ResolveGenericIsoSignalChainInput {
 
 ## resolveGenericIsoSignalChainPreset
 
-Select a generic catalog preset and return its explicit profile binding without claiming
-manufacturer calibration.
+Picks a generic preset from the catalogue and returns the signal-chain profile it uses. It makes
+no claim of manufacturer calibration.
 
-The selected ISO/capture-mode state binds an explicit generic readout regime. Photons and photo/dark
-shot-noise expectations remain upstream; regime gain, read noise and clipping are separately
-declared. Generic tier labels do not calibrate or rank commercial equipment.
+Generic tier labels do not calibrate or rank real cameras.
 
 ```ts
 export function resolveGenericIsoSignalChainPreset(

package/docs/api/sensor-local-exposure-binding.md

@@ -1,21 +1,20 @@
 # sensor/local-exposure-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.
 
 ## bindSensorRateToLocalExposure
 
-Binds one engine-produced sensor response-rate result to the local exposure
-window at the same color-sampling site.
+Links one engine-made sensor response-rate result to the local exposure
+window of the same colour-sampling site.
 
-This first temporal binding supports only the explicit one-to-one
-native-effective-sample ↔ color-site relationship. A multi-site block
-binding proves contributor membership but does not prove each color site's
-sub-sample timing coordinate, so spatially varying shutter timing fails
-closed rather than inventing fractional positions.
+Only a one-to-one link between native image samples and colour sites is
+supported. A block binding shows which sites contribute, but not each site's
+timing position within the sample. So shutter timing that varies across the
+sensor is rejected rather than guessing fractional positions.
 
-The result establishes timing only. It deliberately does not establish that
-the optical/electrical rate is stationary through the local exposure window,
-so rate×duration integration remains unauthorized.
+The result fixes timing only. It does not establish that the optical or
+electrical rate is constant through the window, so it does not by itself
+allow rate × duration integration.
 
 ```ts
 export function bindSensorRateToLocalExposure(
@@ -39,8 +38,8 @@ export interface BindSensorRateToLocalExposureInput {
   bindingProfile:
     NativeEffectiveRasterColorSamplingBindingProfile;
   /**
-   * One capture/exposure event. samplePointsNative is owned by this binding
-   * function and therefore intentionally excluded.
+   * One capture (exposure) event. samplePointsNative is left out on purpose,
+   * because this function sets it.
    */
   exposureWindowInput:
     Omit<

package/docs/api/sensor-optical-stack.md

@@ -1,6 +1,6 @@
 # sensor/optical-stack.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.
 
 ## AntiAliasingPointSplitComponent
 
@@ -9,16 +9,16 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface AntiAliasingPointSplitComponent {
   /**
-   * Native sensor physical offset from the nominal landing point.
-   * +X right, +Y down. Units: micrometres.
+   * Physical offset on the native sensor from where the light would otherwise
+   * land. +X right, +Y down. Units: micrometres.
    */
   offsetMicrometers: {
     x: number;
     y: number;
   };
   /**
-   * Dimensionless normalized spatial weight. Point-splitting kernels describe
-   * spatial redistribution only; total stack throughput is outside this field.
+   * Normalized weight (dimensionless). A point-splitting kernel only describes
+   * where the light goes; the stack's total throughput is not part of it.
    */
   normalizedWeight: number;
 }
@@ -26,18 +26,17 @@ export interface AntiAliasingPointSplitComponent {
 
 ## parseSensorOpticalStackProfile
 
-Parses descriptive sensor optical-stack metadata plus an optional explicitly
-declared effective anti-aliasing spatial response.
+Parses descriptive sensor optical-stack metadata, plus an optional explicitly
+declared anti-aliasing (AA) spatial response.
 
-Unknown facts are omitted instead of inferred. Physical component presence
-is intentionally separate from effective anti-aliasing response so the
-schema can represent cancellation/neutralization designs without claiming
-the physical assembly is absent.
+Leave out unknown facts rather than guessing them. Physical presence of a
+component is separate from the net AA response, so the schema can describe
+designs that cancel the AA effect without claiming the hardware is missing.
 
-Cover/filter-stack and microlens presence do not create optical effects in
-schema 0.1.0. Thickness, refractive index, spectral transmission, angular
-acceptance, focus shift and microlens collection behavior require later
-explicit models/calibration.
+In schema 0.1.0, cover glass, filters and microlenses create no optical
+effect. Thickness, refractive index, spectral transmission, angle of
+acceptance, focus shift and microlens collection need later explicit models
+or calibration.
 
 ```ts
 export function parseSensorOpticalStackProfile(
@@ -49,15 +48,15 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## resolveAntiAliasingSpatialKernel
 
-Resolves only the effective anti-aliasing spatial kernel.
+Resolves only the anti-aliasing (AA) spatial kernel.
 
-This is not a whole optical-stack PSF. Cover/filter transmission, refraction,
-microlens behavior, field/wavelength/polarization dependence, and total
-throughput remain excluded.
+This is not the PSF (point-spread function) of the whole optical stack. Cover
+glass and filter transmission, refraction, microlens behaviour, dependence on
+field position, wavelength or polarization, and total throughput are excluded.
 
-A documented absent effective anti-aliasing response resolves to an identity
-component at zero offset. An unknown response (field omitted) or a
-present-but-unresolved response fails closed.
+A documented absent AA response gives a single component with weight 1 at zero
+offset (no blur). An unknown response (field omitted) or one that is present
+but unspecified is rejected.
 
 ```ts
 export function resolveAntiAliasingSpatialKernel(
@@ -103,25 +102,24 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export type SensorEffectiveAntiAliasingSpatialResponse =
   | {
       /**
-       * Documented absence/cancellation of intentional anti-aliasing spatial
-       * splitting. This does not mean the whole sensor stack is optically
-       * identity.
+       * Documented absence (or cancellation) of deliberate AA splitting. It does
+       * not mean the rest of the sensor stack has no optical effect.
        */
       kind: "absent";
       evidence: readonly EvidenceProvenance[];
     }
   | {
       /**
-       * An effective anti-aliasing response is known to exist, but its spatial
-       * response is not defensibly specified.
+       * An AA effect is known to exist, but its spatial response is not
+       * specified well enough to use.
        */
       kind: "present-unresolved";
       evidence: readonly EvidenceProvenance[];
     }
   | {
       /**
-       * Generic normalized point-splitting approximation in native sensor
-       * physical coordinates.
+       * Generic approximation: each point is split into weighted copies at
+       * offsets in native sensor physical coordinates.
        */
       kind: "normalized-point-splitting-kernel";
       evidence: readonly EvidenceProvenance[];
@@ -141,8 +139,8 @@ export interface SensorMicrolensDeclaration {
   presence: "present" | "absent";
   evidence: readonly EvidenceProvenance[];
   /**
-   * Presence alone does not establish an angular, spectral, fill-factor, or
-   * collection-efficiency model.
+   * Being present does not establish any model of angle, spectrum, fill factor
+   * or collection efficiency.
    */
   opticalEffectModel: "unresolved";
 }
@@ -156,8 +154,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface SensorOpticalStackComponent {
   componentId: string;
   /**
-   * Roles may be combined because one physical element can provide multiple
-   * optical/filter functions.
+   * A component can have several roles, because one physical element can do
+   * more than one optical or filtering job.
    */
   roles: readonly SensorOpticalStackComponentRole[];
   evidence: readonly EvidenceProvenance[];
@@ -189,22 +187,21 @@ export interface SensorOpticalStackProfile {
   profileId: string;
   evidence: readonly EvidenceProvenance[];
   /**
-   * Ordered from incident-light side toward the sensor.
+   * In order from the side light enters towards the sensor.
    *
    * These components are descriptive metadata only. Their presence does not
-   * create transmission, focus-shift, aberration, or spectral effects.
+   * create transmission, focus-shift, aberration or spectral effects.
    */
   orderedComponents?: readonly SensorOpticalStackComponent[];
   /**
-   * Omitted means unknown/unasserted.
+   * Omitted means "unknown, not stated".
    *
-   * This is intentionally separate from physical component presence so a
-   * stack can contain low-pass-related hardware while its net effective
-   * anti-aliasing response is absent/cancelled.
+   * This is separate from which components are present, so a stack can
+   * contain low-pass hardware while its net AA effect is absent or cancelled.
    */
   effectiveAntiAliasingSpatialResponse?: SensorEffectiveAntiAliasingSpatialResponse;
   /**
-   * Omitted means unknown/unasserted.
+   * Omitted means "unknown, not stated".
    */
   microlens?: SensorMicrolensDeclaration;
 }

package/docs/api/sensor-photon-energy.md

@@ -1,6 +1,6 @@
 # sensor/photon-energy.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.
 
 ## AirRefractiveIndexConditionPolicy
 
@@ -33,12 +33,12 @@ export interface AirRefractiveIndexReferenceConditions {
 
 ## calculatePhotonEnergyFromWavelength
 
-Convert a valid vacuum wavelength, or explicitly atmosphere-bound air wavelength, into optical
-frequency and photon energy using exact SI constants.
+Converts a vacuum wavelength, or an air wavelength with its stated atmosphere, into optical
+frequency and photon energy using the exact SI constants h and c.
 
-Photon energy uses exact SI h and c with vacuum wavelength. Air wavelength requires an
-exact-wavelength sourced phase index and atmosphere compatibility; lambdaVacuum = n*lambdaAir.
-Retained refractive-index uncertainty is not an automatically propagated photon-energy uncertainty.
+An air wavelength needs a sourced phase refractive index for that exact wavelength and matching
+atmosphere; λ_vacuum = n·λ_air. The index's uncertainty is kept but not automatically carried
+through to the photon energy.
 
 ```ts
 export function calculatePhotonEnergyFromWavelength(
@@ -69,12 +69,11 @@ export interface CalculatePhotonEnergyFromWavelengthInput {
 
 ## parseSourcedAirPhaseRefractiveIndex
 
-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.
 
-Photon energy uses exact SI h and c with vacuum wavelength. Air wavelength requires an
-exact-wavelength sourced phase index and atmosphere compatibility; lambdaVacuum = n*lambdaAir.
-Retained refractive-index uncertainty is not an automatically propagated photon-energy uncertainty.
+The index is the phase refractive index n of air at one exact wavelength, from a cited source, for
+stated atmospheric conditions. It converts air to vacuum wavelength: λ_vacuum = n·λ_air.
 
 ```ts
 export function parseSourcedAirPhaseRefractiveIndex(

package/docs/api/sensor-physical-charge-capacity.md

@@ -1,16 +1,13 @@
 # sensor/physical-charge-capacity.ts public contracts
 
-Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## assessSensorPhysicalChargeCapacity
 
-Compare complete expected stored electrons to the explicitly applicable physical capacity and report
-expectation-domain headroom without nonlinear storage simulation.
+Compares the complete expected stored electrons with the physical capacity that applies, and
+reports the remaining headroom in expected electrons. Non-linear storage is not simulated.
 
-Physical storage capacity is a source-specific total stored-electron limit tied to site, operating
-state and temperature. The assessment compares complete expected charge; it does not clamp
-realizations or infer overflow/blooming. Camera saturation and ADC/readout thresholds remain
-distinct.
+It does not clip random realizations and does not model overflow or blooming.
 
 ```ts
 export function assessSensorPhysicalChargeCapacity(
@@ -38,13 +35,11 @@ export interface AssessSensorPhysicalChargeCapacityInput {
 
 ## parseSensorPhysicalChargeCapacityProfile
 
-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.
 
-Physical storage capacity is a source-specific total stored-electron limit tied to site, operating
-state and temperature. The assessment compares complete expected charge; it does not clamp
-realizations or infer overflow/blooming. Camera saturation and ADC/readout thresholds remain
-distinct.
+The capacity is a total stored-electron limit from a specific source, tied to a site, operating
+state and temperature. Camera saturation capacity and ADC or readout thresholds are separate.
 
 ```ts
 export function parseSensorPhysicalChargeCapacityProfile(

package/docs/api/sensor-pixel-pitch.md

@@ -1,6 +1,6 @@
 # sensor/pixel-pitch.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.
 
 ## calculatePixelPitch
 

package/docs/api/sensor-radiometry-readiness.md

@@ -1,13 +1,13 @@
 # sensor/radiometry-readiness.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.
 
 ## assessRadiometryReadiness
 
-Assesses whether the declared prerequisites are sufficient for a nominal
-photon estimate and, separately, for a calibrated photon claim.
+Checks whether the declared prerequisites are enough for a nominal photon
+estimate and, separately, for a calibrated photon claim.
 
-This assessment does not enable composed photon/noise output.
+It does not switch on composed photon or noise output.
 
 ```ts
 export function assessRadiometryReadiness(
@@ -65,10 +65,10 @@ export type OpticalTransmissionRequirement =
 
 ## parseRadiometryReadinessProfile
 
-Parses untrusted radiometry-prerequisite metadata.
+Parses untrusted metadata about radiometry prerequisites.
 
-This validates structure and provenance; it cannot prove that a cited
-calibration/evidence claim is scientifically true.
+It checks structure and provenance. It cannot prove that a cited calibration
+or evidence claim is scientifically true.
 
 ```ts
 export function parseRadiometryReadinessProfile(
@@ -127,8 +127,8 @@ export interface RadiometryReadinessAssessment {
   approximateRequirements: readonly RadiometryRequirementId[];
   unquantifiedUncertaintyRequirements: readonly RadiometryRequirementId[];
   /**
-   * This assessment never enables composed photon/noise output by itself.
-   * Integration remains an explicit later product/engine decision.
+   * Always false: this assessment never switches on composed photon or noise
+   * output by itself. Doing so is a separate, explicit later decision.
    */
   composedPhotonOutputEnabled: false;
 }