@photivra/engine 1.5.0 → 2.0.0

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

@@ -1,17 +1,11 @@
 # sensor/raw-readout.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.
 
 ## calculateExpectedSensorReadout
 
-Map expected charge through declared gain/offset/readout limits without stochastic sampling and
-retain separate clipping domains.
-
-Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
-noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
-limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
-pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
-regime.
+Maps the expected charge through the declared gain, offset and readout limits, with no random
+sampling. Each kind of clipping (physical storage, pre-ADC, digital) is reported separately.
 
 ```ts
 export function calculateExpectedSensorReadout(
@@ -40,14 +34,10 @@ export interface CalculateExpectedSensorReadoutInput {
 
 ## parseSensorChargeSamplingProfile
 
-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.
 
-Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
-noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
-limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
-pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
-regime.
+The profile sets how expected charge is sampled into random photo and dark counts.
 
 ```ts
 export function parseSensorChargeSamplingProfile(
@@ -59,14 +49,10 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSensorReadoutConversionProfile
 
-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.
 
-Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
-noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
-limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
-pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
-regime.
+The profile lists the declared conversion regimes. ISO never invents a regime.
 
 ```ts
 export function parseSensorReadoutConversionProfile(
@@ -97,14 +83,8 @@ export interface ResolvedSensorReadoutRegime {
 
 ## resolveSensorReadoutRegime
 
-Select and validate a declared readout regime against exact channel/profile identity rather than
-inferring it from ISO.
-
-Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
-noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
-limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
-pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
-regime.
+Selects a declared readout regime and checks it against the exact channel and profile identity.
+The regime is never inferred from ISO.
 
 ```ts
 export function resolveSensorReadoutRegime(
@@ -145,6 +125,20 @@ SENSOR_READOUT_CONVERSION_PROFILE_SCHEMA_VERSION =
   "0.1.0" as const
 ```
 
+## SensorAdcIntegralNonLinearity
+
+Optional ADC integral non-linearity (INL): an offset in code units (LSB, least significant bit),
+piecewise linear in the ideal continuous ADC input code, added before quantization. The points must
+start at code 0 and end at the ADC maximum code. If omitted, the ADC is ideal and uniform.
+
+```ts
+export interface SensorAdcIntegralNonLinearity {
+  kind: "piecewise-linear-code-offset";
+  knots: readonly { code: number; offsetCodes: number }[];
+  evidence: readonly EvidenceProvenance[];
+}
+```
+
 ## SensorAdditionalChargeSamplingModel
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -187,6 +181,17 @@ export interface SensorChargeRealization {
   photoRealizedElectronCount: number;
   darkExpectedElectronCount: number;
   darkRealizedElectronCount: number;
+  /** Fixed-pattern profile applied to this realization, or null for the uniform population model. */
+  fixedPatternNoiseProfileId:
+    string | null;
+  /** PRNU gain applied to the photo expectation (exactly 1 without a fixed pattern). */
+  photoResponseGainFactor: number;
+  /** DSNU/hot-pixel factor applied to the dark expectation (exactly 1 without a fixed pattern). */
+  darkCurrentFactor: number;
+  hotPixel: boolean;
+  /** Poisson means actually sampled: expectation × the site's fixed-pattern factor. */
+  photoSampledMeanElectronCount: number;
+  darkSampledMeanElectronCount: number;
   additionalComponents:
     readonly {
       componentId: string;
@@ -280,8 +285,15 @@ export interface SensorExpectedReadoutSignal {
   expectedCodeBeforeBlackOffset:
     number;
   blackLevelCode: number;
+  /** Continuous ADC input code including any declared INL offset. */
   expectedCodeBeforeQuantization:
     number;
+  adcIntegralNonLinearityOffsetCodes:
+    number;
+  digitalGain: number;
+  /** Continuous code after post-ADC digital gain about black (equals the ADC input without one). */
+  expectedCodeAfterDigitalGain:
+    number;
   adcBitDepth: number;
   adcMaximumCode: number;
   digitalSaturationCode: number;
@@ -337,11 +349,17 @@ export interface SensorRawCodeSample {
     }[];
   totalElectronicReadNoiseElectrons:
     number;
+  /** Fixed-pattern profile applied at readout, or null. */
+  fixedPatternNoiseProfileId:
+    string | null;
+  /** Static fixed-pattern row + column offset in input-referred electrons (0 without a pattern). */
+  fixedPatternReadoutOffsetElectrons:
+    number;
   electronEquivalentAfterReadNoise:
     number;
   preAdcSaturationElectronEquivalent:
     number;
-  /** Signed electronic signal after upper saturation, before conversion/pedestal. */
+  /** Signed electronic signal after the upper (pre-ADC) clip, before conversion and the black pedestal. */
   electronEquivalentAfterPreAdcSaturation:
     number;
   preAdcSaturationApplied:
@@ -349,8 +367,17 @@ export interface SensorRawCodeSample {
   systemConversionGainElectronsPerCode:
     number;
   blackLevelCode: number;
+  /** Continuous ADC input code including any declared integral non-linearity offset. */
   codeBeforeQuantization:
     number;
+  /** INL offset added before quantization (0 for an ideal ADC). */
+  adcIntegralNonLinearityOffsetCodes:
+    number;
+  /** ADC output after quantization and the ADC code-range limit, before digital gain. */
+  adcCodeBeforeDigitalGain:
+    number;
+  /** Post-ADC digital gain (1 when the regime declares none). */
+  digitalGain: number;
   quantizedCodeBeforeDigitalClamp:
     number;
   adcBitDepth: number;
@@ -397,11 +424,12 @@ export interface SensorReadoutConversionProfile {
 
 ## SensorReadoutConversionRegime
 
-One explicitly selected electronic conversion regime, with sourced electrons
-per code, upper pre-ADC electron-equivalent threshold, independent RMS-electron
-read-noise components and unsigned ADC coding policy. Black pedestal and digital
-saturation are code-domain quantities. The regime does not infer its hardware
-mechanism or selection from ISO and does not replace physical storage capacity.
+One explicitly selected electronic conversion regime. It has a sourced number of
+electrons per code, an upper pre-ADC threshold in electron equivalents, separate
+read-noise components (RMS electrons) and an unsigned ADC coding policy. The black
+pedestal and digital saturation are in code units. The regime does not guess its
+hardware mechanism, is not chosen from ISO automatically, and does not replace
+physical storage capacity.
 
 ```ts
 export interface SensorReadoutConversionRegime {
@@ -420,23 +448,52 @@ export interface SensorReadoutConversionRegime {
     digitalSaturationCode: number;
     transfer:
       "uniform-round-half-up";
+    /**
+     * Optional post-ADC digital gain (>= 1) applied about the black level:
+     * code = roundHalfUp((adcCode - black) * digitalGain + black). Omission means 1.
+     */
+    digitalGain?: number;
+    integralNonLinearity?:
+      SensorAdcIntegralNonLinearity;
   };
+  exposureIndexGain?:
+    SensorReadoutExposureIndexGain;
   evidence:
     readonly EvidenceProvenance[];
   limitations: readonly string[];
 }
 ```
 
+## SensorReadoutExposureIndexGain
+
+Optional record of how one regime's ISO gain was derived (the exposure index of CIPA DC-004,
+relative to the base exposure index). The readout equations still use
+systemConversionGainElectronsPerCode (analog, before the ADC) and adc.digitalGain (after the ADC).
+This record must agree with them and never replaces them.
+
+```ts
+export interface SensorReadoutExposureIndexGain {
+  exposureIndex: number;
+  baseExposureIndex: number;
+  /** Analog (pre-ADC) gain relative to the base-exposure-index regime. */
+  analogGain: number;
+  /** Post-ADC digital gain; equals adc.digitalGain (1 when omitted). */
+  digitalGain: number;
+  conversionGainMode:
+    | "single-conversion-gain"
+    | "low-conversion-gain"
+    | "high-conversion-gain";
+  evidence: readonly EvidenceProvenance[];
+}
+```
+
 ## simulateSensorChargeRealization
 
-Draw deterministic independently seeded photo/dark Poisson counts and explicit additional-component
-policies from expected accumulated charge.
+Draws deterministic, separately seeded Poisson counts for photo and dark charge, and applies the
+declared policies for additional components, starting from the expected accumulated charge.
 
-Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
-noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
-limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
-pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
-regime.
+This is steps 1–2 of the readout order (see the module notes). Physical storage saturation is
+reported separately from later clipping.
 
 ```ts
 export function simulateSensorChargeRealization(
@@ -458,19 +515,22 @@ export interface SimulateSensorChargeRealizationInput {
   samplingProfile:
     SensorChargeSamplingProfile;
   seedUint32: number;
+  /**
+   * Optional fixed-pattern noise for this sensor. PRNU (photo-response non-uniformity) scales the
+   * photo Poisson mean; DSNU (dark-signal non-uniformity) and hot pixels scale the dark Poisson mean.
+   * If omitted, the result is exactly the uniform population model.
+   */
+  fixedPatternNoise?:
+    SensorFixedPatternNoiseProfile;
 }
 ```
 
 ## simulateSensorRawCode
 
-Use the declared seed/regime to preserve signed electronic noise through pedestal and quantization,
-then return the bounded native ADC code and stage diagnostics.
-
-Signal ordering is expected charge → independent seeded photo/dark draws → signed electronic read
-noise → upper pre-ADC threshold → black pedestal → nearest-half-up ADC quantization → unsigned code
-limits. Signed below-black values survive until the final code clamp. Physical storage saturation,
-pre-ADC clipping and digital clipping have distinct diagnostics; ISO never invents a conversion
-regime.
+Simulates one RAW code from a charge realization with the declared seed and regime: steps 3–7 of
+the readout order (see the module notes). Signed read noise is kept through the black pedestal and
+quantization, and only the final code is clamped. Returns the bounded native ADC code and per-step
+diagnostics.
 
 ```ts
 export function simulateSensorRawCode(
@@ -495,5 +555,11 @@ export interface SimulateSensorRawCodeInput {
     SensorReadoutConversionProfile;
   regimeId: string;
   readNoiseSeedUint32: number;
+  /**
+   * Optional fixed pattern; must be the same profile used for the charge realization. Its static
+   * row/column offsets are added with read noise before the pre-ADC threshold.
+   */
+  fixedPatternNoise?:
+    SensorFixedPatternNoiseProfile;
 }
 ```

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[];
+}
+```