@photivra/engine 1.5.0 → 2.1.0

package/docs/api/sensor-raw-reconstruction.md

@@ -1,16 +1,77 @@
 # sensor/raw-reconstruction.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.
 
-## createSensorRawCaptureSample
+## BUILT_IN_BAYER_DEMOSAIC_MODEL_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+BUILT_IN_BAYER_DEMOSAIC_MODEL_VERSION = "1.0.0" as const
+```
+
+## BuiltInBayerDemosaicKernel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type BuiltInBayerDemosaicKernel = "bilinear";
+```
+
+## BuiltInBayerDemosaicProfiles
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BuiltInBayerDemosaicProfiles {
+  kernel: BuiltInBayerDemosaicKernel;
+  /** One profile per absolute CFA phase, row-major (`phaseY`, then `phaseX`). */
+  phaseProfiles: { phaseX: number; phaseY: number; profile: SensorRawReconstructionProfile }[];
+  outputChannelIds: [string, string, string];
+  /** Largest |offset| of any contribution: 1 for bilinear. */
+  kernelReachSites: number;
+}
+```
+
+## createBuiltInBayerDemosaicProfiles
+
+Builds the per-phase linear reconstruction profiles of the built-in bilinear Bayer demosaic kernel.
 
-Commit one validated native RAW sample with exact site/channel/event identity for declared
-reconstruction.
+The result is the ordinary `explicit-linear-native-neighborhood` profile used by RAW frame
+reconstruction, native RAW development and `createCfaPlaneReconstructionTask`; there is no special
+code path. Edge pixels need either a region whose neighbourhood stays inside the frame, or mirror
+border handling.
 
-Reconstruction consumes explicitly bound native post-ADC samples and declared normalized channel
-kernels. Native CFA phase is absolute and orientation/crop remain downstream. This structural linear
-reconstruction does not infer spectral sensor primaries, calibrated color or a complete arbitrary
-demosaic algorithm.
+Approximation: fixed linear interpolation, not a calibrated or adaptive demosaic. Bilinear blurs
+and shows "zipper" artefacts at edges. Aliasing and moiré are not modelled. The adaptive AHD method
+is `createAhdDemosaicTask`.
+
+```ts
+export function createBuiltInBayerDemosaicProfiles(input: CreateBuiltInBayerDemosaicProfilesInput): CalculationResult<BuiltInBayerDemosaicProfiles>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateBuiltInBayerDemosaicProfilesInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateBuiltInBayerDemosaicProfilesInput {
+  kernel: BuiltInBayerDemosaicKernel;
+  /** Capture mode the RAW frame belongs to; copied into every phase profile. */
+  captureModeId: string;
+  /** Must be a 2×2 periodic Bayer mosaic: one red, one blue and two diagonal green sites. */
+  colorSamplingProfile: SensorColorSamplingProfile;
+  /** CFA channel IDs for the red, green and blue roles. This is also the output channel order. */
+  channelRoles: { red: string; green: string; blue: string };
+}
+```
+
+## createSensorRawCaptureSample
+
+Commits one validated native RAW sample, with its exact site, channel and exposure event, for use
+in reconstruction.
 
 ```ts
 export function createSensorRawCaptureSample(
@@ -31,18 +92,22 @@ export interface CreateSensorRawCaptureSampleInput {
     SensorRawCodeSample;
   contributors:
     ResolvedCaptureModeColorSamplingContributors;
+  /**
+   * The selected readout regime's declared ADC integral non-linearity (INL), if any. The code sample
+   * records INL only at its own code, but the effective white level needs it at saturation.
+   */
+  adcIntegralNonLinearity?:
+    SensorAdcIntegralNonLinearity;
 }
 ```
 
 ## parseSensorRawReconstructionProfile
 
-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.
 
-Reconstruction consumes explicitly bound native post-ADC samples and declared normalized channel
-kernels. Native CFA phase is absolute and orientation/crop remain downstream. This structural linear
-reconstruction does not infer spectral sensor primaries, calibrated color or a complete arbitrary
-demosaic algorithm.
+The profile declares a normalized linear kernel for each output channel. It does not infer the
+sensor's spectral primaries or calibrated colour.
 
 ```ts
 export function parseSensorRawReconstructionProfile(
@@ -52,15 +117,21 @@ export function parseSensorRawReconstructionProfile(
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## RawReconstructionBorderHandling
+
+How a reconstruction neighbourhood that leaves the native frame is handled.
+
+```ts
+export type RawReconstructionBorderHandling = "reject" | "mirror";
+```
+
 ## resolveSensorRawReconstruction
 
-Gather exactly supplied native channel contributions through explicit normalized kernels while
-preserving CFA identity and signed black-subtracted values.
+Combines the supplied native samples through explicit normalized kernels, keeping CFA identity
+and signed black-subtracted values.
 
-Reconstruction consumes explicitly bound native post-ADC samples and declared normalized channel
-kernels. Native CFA phase is absolute and orientation/crop remain downstream. This structural linear
-reconstruction does not infer spectral sensor primaries, calibrated color or a complete arbitrary
-demosaic algorithm.
+The CFA phase is absolute; orientation and crop come later. This fixed linear reconstruction does
+not infer spectral primaries or calibrated colour, and is not a general demosaic algorithm.
 
 ```ts
 export function resolveSensorRawReconstruction(
@@ -134,6 +205,12 @@ export interface SensorRawCaptureSample {
   digitalSaturationCode: number;
   blackSubtractedNormalizedCode:
     number;
+  /** Full-saturation code from `calculateEffectiveSaturationCode`; constant per CFA phase. */
+  effectiveSaturationCode: number;
+  /** Regime system conversion gain, e⁻ per code (DNG NoiseProfile input). */
+  systemConversionGainElectronsPerCode: number;
+  /** Total read noise in e⁻: the square root of the sum of the squared RMS components (DNG NoiseProfile input). */
+  readNoiseRmsElectrons: number;
   readoutProfileId: string;
   readoutRegimeId: string;
   sourceChargeSeedUint32: number;

package/docs/api/sensor-readout-exposure-linkage.md

@@ -1,21 +1,19 @@
 # sensor/readout-exposure-linkage.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.
 
 ## assessReadoutExposureTimingLinkage
 
-Assesses an explicitly declared relationship between rolling sensor readout
-spatial phase and one or more electronic exposure-boundary scans.
+Checks an explicitly declared link between the rolling readout scan and one
+or more electronic exposure-boundary scans.
 
-This contract is deliberately weaker than temporal synchronization. It can
-establish that two schedules traverse the same native spatial phase ordering
-(or its reverse), but it does not establish when sensor data readout occurs
-relative to exposure start/end.
+This is deliberately weaker than time synchronization. It can show that two
+schedules sweep the native sensor in the same order (or in reverse), but not
+when readout happens relative to the start or end of exposure.
 
-The total capture data-readout duration is preserved diagnostically and is
-never used to validate the relationship. Different rolling-readout spatial
-skew and exposure-boundary traversal durations are allowed; their ratio is
-reported without implying a shared clock origin.
+The total data-readout time is kept for diagnostics and never used to check
+the link. The readout skew and the boundary sweep time may differ; their
+ratio is reported without implying a shared clock.
 
 ```ts
 export function assessReadoutExposureTimingLinkage(
@@ -43,6 +41,56 @@ export interface AssessReadoutExposureTimingLinkageInput {
 }
 ```
 
+## createRollingShutterCaptureExposureSchedule
+
+The exposure-schedule fields of a derived rolling-shutter schedule, without model metadata.
+
+```ts
+export function createRollingShutterCaptureExposureSchedule(
+  schedule: ElectronicRollingShutterExposureSchedule
+): Pick<CalculateCaptureExposureWindowsInput, "shutterMechanism" | "nominalExposureDurationSeconds" | "opening" | "closing">;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ELECTRONIC_ROLLING_SHUTTER_MODEL
+
+Model identity of the electronic rolling-shutter (line reset → line read) exposure schedule.
+
+```ts
+ELECTRONIC_ROLLING_SHUTTER_MODEL = Object.freeze({
+  id: "electronic-rolling-shutter-line-reset-read",
+  version: "1.0.0"
+} as const)
+```
+
+## ElectronicRollingShutterExposureSchedule
+
+Exposure-window schedule of an electronic rolling shutter. Its `shutterMechanism`,
+`nominalExposureDurationSeconds`, `opening` and `closing` fields form a complete exposure schedule, so
+they can be passed as a native RAW / environment `exposureWindow` or spread into a production
+`temporalCapture.exposureWindowInput` (see {@link createRollingShutterCaptureExposureSchedule}).
+
+```ts
+export interface ElectronicRollingShutterExposureSchedule {
+  modelId: typeof ELECTRONIC_ROLLING_SHUTTER_MODEL.id;
+  modelVersion: typeof ELECTRONIC_ROLLING_SHUTTER_MODEL.version;
+  shutterMechanism: "electronic";
+  nominalExposureDurationSeconds: SourcedCaptureTimingSeconds;
+  /** Line-reset scan: a native point at normalized scan position s starts integrating at s·τ. */
+  opening: UniformLinearExposureBoundarySchedule;
+  /** Line-read scan: the same point stops integrating at T + s·τ. */
+  closing: UniformLinearExposureBoundarySchedule;
+  /** Explicit linkage declaration accepted by {@link assessReadoutExposureTimingLinkage}. */
+  linkage: Extract<ReadoutExposureTimingLinkageDeclaration, { kind: "spatial-phase-linked" }>;
+  /** τ: offset between the first and last exposure starts (equal to the readout skew). */
+  lineScanSkewSeconds: number;
+  /** Every point integrates for exactly the nominal exposure duration T. */
+  localExposureDurationSeconds: number;
+  limitations: readonly string[];
+}
+```
+
 ## ReadoutExposureBoundaryId
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -59,8 +107,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface ReadoutExposureBoundarySpatialLink {
   boundary: ReadoutExposureBoundaryId;
   /**
-   * Relationship between normalized rolling-readout scan phase and the
-   * selected electronic exposure-boundary scan phase.
+   * How the normalized position of the rolling readout scan relates to that
+   * of the selected electronic exposure-boundary scan.
    *
    * "same": boundary normalized phase = readout normalized phase.
    * "reversed": boundary normalized phase = 1 - readout normalized phase.
@@ -69,10 +117,10 @@ export interface ReadoutExposureBoundarySpatialLink {
    */
   phaseOrientation: ReadoutExposureSpatialPhaseOrientation;
   /**
-   * Evidence supporting the relationship itself.
+   * Evidence for the link itself.
    *
-   * The readout direction/timing and exposure-boundary direction/timing retain
-   * their own separate evidence.
+   * The readout direction and timing, and the exposure-boundary direction and
+   * timing, keep their own separate evidence.
    */
   evidence: readonly EvidenceProvenance[];
 }
@@ -94,15 +142,15 @@ export interface ReadoutExposureBoundarySpatialLinkAssessment {
   readoutDirectionNative: NativeSensorReadoutScanDirection;
   boundaryDirectionNative: NativeSensorReadoutScanDirection;
   /**
-   * First-to-last rolling sensor spatial sampling skew.
+   * Rolling readout skew: time from the first to the last scan position.
    */
   readoutSpatialSamplingSkewSeconds: SourcedSensorTimingSeconds;
   /**
-   * First-to-last exposure-boundary traversal duration.
+   * Time for the exposure boundary to sweep from first to last position.
    */
   boundaryTraversalDurationSeconds: SourcedCaptureTimingSeconds;
   /**
-   * Derived descriptive ratio only. A value of 1 does not prove temporal
+   * A descriptive ratio only. A value of 1 does not prove time
    * synchronization or a common clock origin.
    */
   boundaryTraversalToReadoutSpatialSkewRatio: number;
@@ -135,8 +183,8 @@ export interface ReadoutExposureTimingLinkageAssessment {
   activeCaptureRect: RasterRect;
   absoluteTemporalAlignment: "not-established";
   /**
-   * Capture data-readout duration is preserved for diagnostics but is not used
-   * to validate any exposure-boundary linkage.
+   * Data-readout time for the capture. Kept for diagnostics, but never used to
+   * check an exposure-boundary link.
    */
   captureReadoutDurationSeconds: SourcedSensorTimingSeconds;
   links: readonly ReadoutExposureBoundarySpatialLinkAssessment[];
@@ -155,7 +203,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export type ReadoutExposureTimingLinkageDeclaration =
   | {
       /**
-       * Photivra asserts no readout↔exposure relationship for this capture.
+       * No link between readout and exposure is stated for this capture.
        * This is not evidence that the physical processes are independent.
        */
       kind: "unlinked";
@@ -163,10 +211,58 @@ export type ReadoutExposureTimingLinkageDeclaration =
     }
   | {
       /**
-       * One or more exposure boundaries are explicitly related to rolling
-       * readout by normalized native-sensor spatial phase.
+       * One or more exposure boundaries are explicitly linked to the rolling
+       * readout by their normalized position across the native sensor.
        */
       kind: "spatial-phase-linked";
       links: readonly ReadoutExposureBoundarySpatialLink[];
     };
 ```
+
+## resolveElectronicRollingShutterExposureSchedule
+
+Derives the exposure-window schedule of a fully electronic rolling shutter from its rolling readout
+declaration.
+
+In a CMOS rolling shutter, each line is reset, collects light for the exposure time T and is then
+read. The reset pointer runs T ahead of the read pointer, and both move at the line rate (El Gamal &
+Eltoukhy 2005; Liang, Chang & Chen 2008). With the uniform linear scan used throughout this engine, a
+native point at normalized scan position s ∈ [0, 1] (along the declared scan direction, over the
+active capture) collects light over [s·τ, s·τ + T], where τ is the declared first-to-last readout
+skew. So both boundaries become uniform linear scans in the readout direction that take τ to sweep.
+
+When this schedule feeds the per-site exposure windows, everything that samples motion, moving
+sources or time-varying light at local exposure times (environment RAW, rotation quadrature,
+temporal illumination integration) produces rolling-shutter skew, wobble, partial exposure and
+flicker banding.
+
+Approximation: constant line rate, no line-reset jitter, no hybrid of global reset with a mechanical
+closing shutter, and the active-capture skew is declared by the caller (never scaled from a
+full-frame value).
+
+```ts
+export function resolveElectronicRollingShutterExposureSchedule(
+  input: ResolveElectronicRollingShutterExposureScheduleInput
+): ElectronicRollingShutterExposureSchedule;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveElectronicRollingShutterExposureScheduleInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveElectronicRollingShutterExposureScheduleInput {
+  /** Rolling readout declaration whose scan direction and spatial skew drive both exposure boundaries. */
+  readout: RollingSensorReadoutTimingDeclaration;
+  /** Per-line integration time between line reset and line read. */
+  nominalExposureDurationSeconds: SourcedCaptureTimingSeconds;
+  /**
+   * Evidence that this capture uses a fully electronic, line-by-line (rolling) shutter whose reset
+   * scan runs at the readout line rate. This explicit link is required before sensor readout timing
+   * may set the exposure-window timing.
+   */
+  linkageEvidence: readonly EvidenceProvenance[];
+}
+```

package/docs/api/sensor-readout-timing.md

@@ -1,23 +1,23 @@
 # sensor/readout-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.
 
 ## calculateSensorReadoutTiming
 
-Resolves a capture-specific native sensor readout scan schedule.
+Resolves the sensor readout scan schedule for one capture.
 
-Rolling readout uses a uniform-linear single-axis approximation across the
-declared active capture. The caller supplies the spatial timing span
-explicitly; it is never inferred from total data-readout duration, active
-crop dimensions, native raster density, output resolution, sensor
-architecture metadata, or shutter mechanism.
+Rolling readout is modelled as a uniform linear scan along one axis of the
+declared active capture. The caller supplies the scan's time span (skew)
+explicitly. It is never worked out from the total data-readout time, crop
+size, pixel density, output resolution, sensor-architecture metadata or the
+shutter mechanism.
 
-Global readout has no spatial phase skew in this model even when a non-zero
-data-readout duration is declared.
+Global readout has no skew in this model, even when a non-zero data-readout
+time is declared.
 
-This foundation does not define local exposure start/end times, mechanical
-curtain travel, EFCS curtain behavior, rolling-shutter image distortion,
-flash/flicker interactions, or motion integration.
+Not covered: local exposure start and end times, mechanical curtain travel,
+EFCS (electronic first-curtain shutter) behaviour, rolling-shutter image
+distortion, flash or flicker, and motion integration.
 
 ```ts
 export function calculateSensorReadoutTiming(
@@ -35,23 +35,23 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface CalculateSensorReadoutTimingInput {
   nativeRaster: NativeImageRaster;
   /**
-   * Active capture rectangle in invariant native raster coordinates.
+   * Active capture rectangle, in fixed native pixel coordinates.
    *
-   * Defaults to the complete native raster. Timing is never inferred by
-   * scaling a full-frame value to this rectangle.
+   * Defaults to the whole native image. Timing is never worked out by scaling
+   * a full-frame value to this rectangle.
    */
   activeCaptureRect?: RasterRect;
   /**
-   * Selected shutter mechanism for the capture.
+   * The shutter mechanism chosen for the capture.
    *
-   * It is reported independently and does not modify the sensor timing
-   * schedule in this foundation.
+   * It is reported separately and does not change the sensor readout timing
+   * in this model.
    */
   shutterMechanism: CaptureShutterMechanism;
   readout: SensorReadoutTimingDeclaration;
   /**
-   * Optional continuous native raster edge-coordinate points for timing
-   * diagnostics. Pixel centers may be represented with +0.5 offsets.
+   * Optional points, in continuous native pixel coordinates measured from pixel
+   * edges, to report timing for. A pixel centre is at +0.5.
    */
   samplePointsNative?: readonly RasterPoint[];
 }
@@ -76,9 +76,9 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface GlobalSensorReadoutTimingDeclaration {
   readoutMode: "global";
   /**
-   * Capture-specific sensor data-readout duration.
+   * Sensor data-readout time for this capture.
    *
-   * This is deliberately not interpreted as spatial exposure/readout skew.
+   * It is deliberately not treated as the spatial exposure or readout skew.
    */
   captureReadoutDurationSeconds: SourcedSensorTimingSeconds;
   scanDirectionNative?: never;
@@ -106,11 +106,10 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface RollingSensorReadoutTimingDeclaration {
   readoutMode: "rolling";
   /**
-   * Capture-specific sensor data-readout duration.
+   * Sensor data-readout time for this capture.
    *
-   * This fact is retained independently from spatial sampling skew because
-   * published/declared readout duration and the spatial timing span need not be
-   * treated as the same quantity.
+   * It is kept separate from the spatial skew, because a published readout time
+   * and the scan's time span are not necessarily the same quantity.
    */
   captureReadoutDurationSeconds: SourcedSensorTimingSeconds;
   /**
@@ -118,8 +117,8 @@ export interface RollingSensorReadoutTimingDeclaration {
    */
   scanDirectionNative: SourcedSensorReadoutFact<NativeSensorReadoutScanDirection>;
   /**
-   * Time difference between the first and last spatial scan positions in the
-   * uniform-linear timing approximation.
+   * Time between the first and last scan positions, in the uniform linear
+   * timing approximation (the readout skew).
    */
   spatialSamplingSkewSeconds: SourcedSensorTimingSeconds;
 }
@@ -127,11 +126,11 @@ export interface RollingSensorReadoutTimingDeclaration {
 
 ## SensorReadoutMode
 
-Readout architecture selected for one capture.
+The readout mode chosen for one capture.
 
-This reuses the architecture vocabulary but is not a hardware-capability
-assertion. SensorArchitectureProfile.readoutCapabilities remains descriptive
-metadata and is not consulted automatically.
+It uses the same names as the architecture metadata, but does not claim the
+hardware supports it. SensorArchitectureProfile.readoutCapabilities is
+descriptive only and is not checked automatically.
 
 ```ts
 export type SensorReadoutMode = SensorReadoutArchitecture;
@@ -180,10 +179,9 @@ export interface SensorReadoutTimingSample {
   pointNative: RasterPoint;
   normalizedScanPosition: number | null;
   /**
-   * Relative native-sensor readout phase in seconds.
+   * Readout time of this point, in seconds, relative to the first scan position (0).
    *
-   * Zero is the first spatial scan position. This is not automatically an
-   * exposure-start time or shutter-curtain time.
+   * It is not automatically an exposure-start time or a shutter-curtain time.
    */
   readoutPhaseOffsetSeconds: number;
 }

package/docs/api/sensor-response-application-compatibility.md

@@ -1,15 +1,14 @@
 # sensor/response-application-compatibility.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.
 
 ## assessSensorResponseApplicationCompatibility
 
-Assess whether exact source-plane, area, profile/channel and reference-condition bindings permit the
-selected response application path.
+Checks whether the source plane, area, profile, channel and reference conditions allow the
+selected way of applying the response.
 
-Response application checks exact profile/channel, source plane, incident-area basis, spatial
-uniformity and reference conditions. Structural compatibility alone does not authorize signal
-conversion; per-bin operating-range validity and the typed EQE/A-W path are separate gates.
+Passing this alone does not allow converting light to signal. The per-bin operating-range check
+and the EQE or A/W conversion are separate steps.
 
 ```ts
 export function assessSensorResponseApplicationCompatibility(
@@ -39,12 +38,11 @@ export interface AssessSensorResponseApplicationCompatibilityInput {
 
 ## parseSensorResponseApplicationProfile
 
-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.
 
-Response application checks exact profile/channel, source plane, incident-area basis, spatial
-uniformity and reference conditions. Structural compatibility alone does not authorize signal
-conversion; per-bin operating-range validity and the typed EQE/A-W path are separate gates.
+The profile states the source plane, incident-area basis, spatial uniformity and reference
+conditions under which a response applies.
 
 ```ts
 export function parseSensorResponseApplicationProfile(

package/docs/api/sensor-response-operating-range.md

@@ -1,16 +1,14 @@
 # sensor/response-operating-range.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.
 
 ## assessSensorResponseOperatingRange
 
-Assess every declared spectral-bin input against operating applicability and superposition before
-authorizing instantaneous response conversion.
+Checks every declared spectral-bin input against the operating range and the superposition
+requirement, before any instantaneous response conversion is allowed.
 
-Operating-range assessment preserves incident power versus irradiance, wavelength support, reference
-conditions and declared nonlinearity criterion. Per-bin conversion requires spectral-bin
-applicability and spatial linear superposition. Valid mean input must not conceal an invalid bright
-local sub-aperture.
+Each bin must be in range, and spatial linear superposition must hold. A valid average must not
+hide a part of the aperture that is too bright.
 
 ```ts
 export function assessSensorResponseOperatingRange(
@@ -38,13 +36,11 @@ export interface AssessSensorResponseOperatingRangeInput {
 
 ## parseSensorResponseOperatingRangeProfile
 
-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.
 
-Operating-range assessment preserves incident power versus irradiance, wavelength support, reference
-conditions and declared nonlinearity criterion. Per-bin conversion requires spectral-bin
-applicability and spatial linear superposition. Valid mean input must not conceal an invalid bright
-local sub-aperture.
+The profile states the input quantity (incident power or irradiance), wavelength coverage,
+reference conditions and non-linearity criterion of the calibrated operating range.
 
 ```ts
 export function parseSensorResponseOperatingRangeProfile(
@@ -219,15 +215,15 @@ export interface SensorResponseOperatingRangeProfile {
   linearityCriterion:
     SensorResponseLinearityCriterion;
   /**
-   * Optional for backward compatibility. Omission parses as not-established
-   * and blocks new response-rate authorization.
+   * Optional for backward compatibility. If omitted, it parses as "not
+   * established", which blocks new response-rate conversions.
    */
   spatialLinearityModel?:
     SensorResponseOperatingSpatialLinearityModel;
   /**
-   * Optional for backward compatibility. Omission means the calibration only
-   * establishes a broadband-integrated operating range and cannot authorize
-   * wavelength-by-wavelength response conversion.
+   * Optional for backward compatibility. If omitted, the calibration only
+   * establishes an operating range for broadband (wavelength-integrated) input,
+   * and cannot allow wavelength-by-wavelength response conversion.
    */
   spectralInputModel?:
     SensorResponseOperatingSpectralInputModel;