@photivra/engine 0.5.0 → 0.6.0

package/docs/USAGE.md

@@ -233,7 +233,7 @@ p_distorted = p_ideal × scale
 
 The coefficients are dimensionless **only together with the declared physical normalization radius**. Reusing coefficients with a different normalization changes the model.
 
-`maximumNormalizedRadius` is the caller-declared valid operating envelope. Photivra analytically checks that radial distance remains strictly monotonic over that interval; profiles that fold over are rejected so inverse mapping is unique.
+`maximumNormalizedRadius` is the caller-declared valid operating envelope. Photivra analytically checks that radial distance remains strictly monotonic over that interval, including near-linear higher-order coefficient cases; profiles that fold over are rejected so inverse mapping is unique. Derived normalized radii must remain finite, and malformed runtime point/batch inputs fail closed rather than entering the inverse solver.
 
 This first field-mapping slice is radial-only and centered on the optical axis. It does not model tangential/decentered distortion, anamorphic mapping, wavelength dependence, or a calibrated named lens.
 
@@ -657,10 +657,984 @@ Source origin and reuse rights are also independent. Manufacturer or third-party
 
 Scalar facts may cite multiple evidence records. Multi-valued capabilities such as rolling/global readout carry evidence independently for each value so one source does not silently support another capability.
 
-`readoutCapabilities` describes hardware capabilities, not the mode selected for one exposure. Capture-specific readout selection and timing belong to later readout/capture-mode models.
+`readoutCapabilities` describes hardware capabilities, not the mode selected for one exposure. The capture-mode profile can declare that a selected mode needs mode-specific readout timing, while the actual timing values remain owned by the separate readout-timing contract.
 
 Unknown facts should be omitted instead of inferred. Architecture metadata remains descriptive only: BSI, stacking, readout family, and CFA family do not directly change FOV, crop factor, pixel pitch, exposure, noise, or dynamic range. A separate documented downstream physical/calibration model is required before any such effect can be claimed.
 
+## Color-sampling topology
+
+Use `parseSensorColorSamplingProfile()` when an exact color-sampling topology is known independently from descriptive sensor-family metadata:
+
+```ts
+import {
+  parseSensorColorSamplingProfile,
+  resolveColorSamplingSite
+} from "@photivra/engine";
+
+const topology = parseSensorColorSamplingProfile({
+  schemaVersion: "0.1.0",
+  profileId: "example-periodic-layout",
+  evidence: [
+    {
+      sourceOrigin: "photivra",
+      sourceReference: "example:periodic-layout",
+      reuseStatus: "photivra-owned"
+    }
+  ],
+  coordinateSystem:
+    "native-sensor-color-sampling-site-index",
+  layout: {
+    kind: "periodic-mosaic",
+    repeatWidthSites: 2,
+    repeatHeightSites: 2,
+    siteChannelIds: [
+      "red-like",
+      "green-a",
+      "green-b",
+      "blue-like"
+    ],
+    anchor: "native-sensor-top-left-site"
+  }
+});
+
+const site = resolveColorSamplingSite({
+  profile: topology,
+  site: { x: 5, y: 8 }
+});
+
+console.log(site.mapping);
+```
+
+The topology coordinate system is a distinct **native sensor color-sampling-site lattice**:
+
+- zero-based integer site indices;
+- origin at the native sensor's top-left sampling site;
+- +X right and +Y down;
+- periodic phase anchored to absolute sensor-site indices.
+
+It is intentionally **not** `NativeImageRaster`. The existing native image raster is an effective image-sampling grid and does not guarantee one sample per physical photodiode or one sample per color-filter site. A later explicit binding must establish how a selected capture mode's effective raster maps to this topology before RAW/CFA sampling can be simulated.
+
+That distinction also protects crop phase. If an active crop begins part-way through a repeating tile, callers must preserve the original absolute native site indices. Crop-local `(0,0)` must not silently become a new CFA origin.
+
+`siteChannelIds` are semantic measurement-channel identifiers only. Names such as `red-like`, `green-a`, or `clear` do not establish:
+
+- wavelength response;
+- quantum efficiency;
+- spectral sensitivity;
+- colorimetric primaries;
+- white balance behavior;
+- calibrated sensor response.
+
+Those belong to later spectral/radiometric contracts.
+
+The periodic layout is generic. It can represent a 2×2 Bayer-like phase, larger repeating mosaics, grouped-color tiles, RGBW-like layouts, or other periodic channel arrangements without adding a manufacturer-specific layout enum. Distinct green positions can use the same channel ID or separate IDs when later calibration requires them to remain distinct.
+
+The exact topology is also separate from `SensorArchitectureProfile.colorSamplingFamily`. A family such as `bayer`, `quad-bayer`, `custom-rgb-mosaic`, or `layered-color` is descriptive metadata; Photivra never invents an exact repeating tile from that family label.
+
+Monochrome is represented separately with one semantic measurement-channel ID and no spatial mosaic.
+
+Layered color is deliberately **structural-only** in schema 0.1.0 and uses a separate unresolved spatial-reference marker rather than pretending it shares the periodic site lattice:
+
+```ts
+const layered = parseSensorColorSamplingProfile({
+  schemaVersion: "0.1.0",
+  profileId: "example-layered",
+  evidence: [
+    {
+      sourceOrigin: "photivra",
+      sourceReference: "example:layered",
+      reuseStatus: "photivra-owned"
+    }
+  ],
+  coordinateSystem:
+    "native-sensor-layered-spatial-relationship-not-resolved",
+  layout: {
+    kind: "layered",
+    layerChannelIds: [
+      "layer-a",
+      "layer-b",
+      "layer-c"
+    ],
+    spatialSamplingRelationship: "not-resolved"
+  }
+});
+```
+
+The engine does not expose per-site layered resolution yet. Real layered designs can use unequal per-layer spatial density or registration, so assuming one coincident equal-resolution RGB triplet at every site would be scientifically unsafe.
+
+Schema 0.1.0 also does not model sparse exceptions to an otherwise periodic layout, such as phase-detect sites, masked sites, sensor defects, or other non-periodic overrides.
+
+Physical orientation remains downstream. The native topology is not rotated or re-phased merely because the camera is held vertically. Likewise, changing CFA topology does not change physical imaging area, crop factor, FOV, or output geometry.
+
+## Capture-mode/color-sampling binding
+
+Use `parseNativeEffectiveRasterColorSamplingBindingProfile()` when evidence establishes how one exact canonical `NativeImageRaster` relates to the separate native color-sampling-site lattice.
+
+The first binding is deliberately regular and sensor-anchored:
+
+```ts
+import {
+  parseNativeEffectiveRasterColorSamplingBindingProfile,
+  resolveNativeEffectiveRasterColorSamplingBinding
+} from "@photivra/engine";
+
+const binding = parseNativeEffectiveRasterColorSamplingBindingProfile({
+  schemaVersion: "0.1.0",
+  bindingId: "example-native-to-cfa",
+  colorSamplingProfileId: "example-periodic-layout",
+  nativeRaster: {
+    pixelWidth: 6000,
+    pixelHeight: 4000
+  },
+  evidence: [
+    {
+      sourceOrigin: "photivra",
+      sourceReference: "example:native-to-cfa-binding",
+      reuseStatus: "photivra-owned"
+    }
+  ],
+  relationship: {
+    kind: "regular-native-effective-sample-blocks",
+    sitesPerNativeSampleX: 1,
+    sitesPerNativeSampleY: 1,
+    anchor: "shared-native-top-left"
+  }
+});
+
+const resolvedBinding =
+  resolveNativeEffectiveRasterColorSamplingBinding({
+    nativeRaster: {
+      pixelWidth: 6000,
+      pixelHeight: 4000
+    },
+    colorSamplingProfile: topology,
+    bindingProfile: binding
+  });
+```
+
+A `1 × 1` relationship is still an **asserted/evidenced binding**. Matching dimensions, matching aspect ratio, output megapixels, or a family label such as Bayer never prove that one `NativeImageRaster` sample corresponds to one color-sampling site.
+
+The binding applies only to the exact native raster dimensions recorded in the profile. The first schema supports one native effective sample mapping to a regular rectangular block of color-sampling sites with a shared native top-left anchor. Irregular site relationships require a later explicit mapping.
+
+To compose that sensor-level relationship with a capture mode, use `resolveCaptureModeColorSamplingContributors()`:
+
+```ts
+import {
+  resolveCaptureModeColorSamplingContributors
+} from "@photivra/engine";
+
+const sources =
+  resolveCaptureModeColorSamplingContributors({
+    nativeRaster: {
+      pixelWidth: 6000,
+      pixelHeight: 4000
+    },
+    captureModeProfile: modes,
+    modeId: "grouped",
+    colorSamplingProfile: topology,
+    bindingProfile: binding,
+    modeSampleIndexFullFrame: {
+      x: 10,
+      y: 20
+    },
+    groupedSamplingAnchor: {
+      anchor: "native-effective-raster-top-left",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "example:group-phase",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    }
+  });
+
+console.log(sources.colorSamplingSiteRect);
+console.log(sources.channelSiteCounts);
+console.log(sources.channelComposition);
+```
+
+`modeSampleIndexFullFrame` is always expressed in the selected mode's **full-frame per-frame effective sampling raster**. The API intentionally does not accept crop-local coordinates. If an active crop starts away from the native origin, a caller must preserve or recover the absolute full-frame mode index before resolving CFA structure. This prevents active crops from silently re-phasing the mosaic.
+
+For `grouped-native-samples` modes, group width/height alone do not prove group phase. The caller must separately provide evidence that the groups are anchored at the native effective raster top-left. A future contract can add other explicitly evidenced group phases if required.
+
+The result is a compact **pre-reconstruction structural source region**:
+
+- `nativeEffectiveSampleRect` identifies the absolute native effective samples structurally associated with the mode sample;
+- `colorSamplingSiteRect` identifies the corresponding absolute color-site rectangle;
+- `channelSiteCounts` gives exact counts per semantic channel for monochrome/periodic topology;
+- `channelComposition` reports whether the structural region contains one channel or multiple channels.
+
+The bridge does **not** enumerate every contributing site. It also does not establish sum/average weights, spectral response, photon/electron values, or a complete downstream reconstructed-pixel dependency graph.
+
+A mixed-channel region therefore remains mixed. Photivra does not collapse a red/green/blue structural region into one synthetic CFA channel merely because a capture mode groups those native effective samples. `combinationDomain` from the capture mode remains separate from any unimplemented weighting/combination equation.
+
+`declared-effective-raster` modes fail closed even when their dimensions happen to match the native raster. Their relationship was intentionally declared non-simple in #13 and therefore needs a mode-specific color-site mapping rather than dimension inference.
+
+Layered-color topology also remains unbound because schema 0.1.0 does not yet define per-layer spatial density/registration.
+
+Pixel-shift/sensor-shift metadata is preserved but does not change CFA assignment. The sensor and its filters move together relative to the optical image; the optical-registration effect of that shift belongs to a later image-formation contract.
+
+## Sensor optical stack
+
+Use `parseSensorOpticalStackProfile()` for evidence-backed physical stack metadata and a separately declared **effective anti-aliasing spatial response**:
+
+```ts
+import {
+  parseSensorOpticalStackProfile,
+  resolveAntiAliasingSpatialKernel
+} from "@photivra/engine";
+
+const stack = parseSensorOpticalStackProfile({
+  schemaVersion: "0.1.0",
+  profileId: "example-stack",
+  evidence: [
+    {
+      sourceOrigin: "photivra",
+      sourceReference: "example:stack",
+      reuseStatus: "photivra-owned"
+    }
+  ],
+  orderedComponents: [
+    {
+      componentId: "front-pack",
+      roles: [
+        "cover-glass",
+        "infrared-cut",
+        "anti-reflection"
+      ],
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "example:front-pack",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    }
+  ],
+  effectiveAntiAliasingSpatialResponse: {
+    kind: "normalized-point-splitting-kernel",
+    evidence: [
+      {
+        sourceOrigin: "photivra",
+        sourceReference: "example:aa-kernel",
+        reuseStatus: "photivra-owned"
+      }
+    ],
+    coordinateSystem: "native-sensor-physical",
+    scope:
+      "field-wavelength-polarization-invariant-approximation",
+    components: [
+      {
+        offsetMicrometers: { x: -1, y: 0 },
+        normalizedWeight: 0.5
+      },
+      {
+        offsetMicrometers: { x: 1, y: 0 },
+        normalizedWeight: 0.5
+      }
+    ]
+  },
+  microlens: {
+    presence: "present",
+    evidence: [
+      {
+        sourceOrigin: "photivra",
+        sourceReference: "example:microlens-presence",
+        reuseStatus: "photivra-owned"
+      }
+    ],
+    opticalEffectModel: "unresolved"
+  }
+});
+
+const aaKernel =
+  resolveAntiAliasingSpatialKernel(stack);
+
+console.log(aaKernel.components);
+```
+
+The physical component list and effective AA response are intentionally separate. A stack may contain birefringent/retarder elements while the net intentional low-pass response is cancelled or otherwise effectively absent.
+
+`effectiveAntiAliasingSpatialResponse` has three first-stage states:
+
+- omitted — **unknown/unasserted**;
+- `kind: "absent"` — evidence says this model should add no intentional AA spatial-splitting term;
+- `kind: "present-unresolved"` — an AA effect exists but its spatial response is not defensibly known;
+- `kind: "normalized-point-splitting-kernel"` — the caller explicitly supplies a normalized spatial point-splitting approximation.
+
+Unknown and absent are not interchangeable. Likewise, `absent` does **not** mean the complete sensor stack has an identity PSF, and it does not mean aliasing or moiré are impossible. Lens PSF, cover/filter behavior, microlenses, sampling topology, and scene detail still matter.
+
+The point-splitting kernel is deliberately generic:
+
+- component count is arbitrary rather than fixed to four rays;
+- offsets are in micrometres in `native-sensor-physical` coordinates (+X right, +Y down);
+- physical camera orientation does not rotate/redefine the stored kernel;
+- normalized weights must sum to one;
+- the weights describe **spatial redistribution only**.
+
+They do not represent total optical throughput, spectral transmission, photon efficiency, QE, or fill factor. Those belong to separate radiometric/sensor-response contracts.
+
+The first point-splitting scope is explicitly `field-wavelength-polarization-invariant-approximation`. Real OLPF behavior may depend on wavelength, incidence angle/field position, polarization, materials, and stack geometry. Do not upgrade this generic kernel into a calibrated whole-stack PSF.
+
+`orderedComponents` is incident-light → sensor descriptive metadata. Component roles can include cover glass, IR/UV filtering, AR treatment, birefringent low-pass elements, wave plates, and other optical filters. Schema 0.1.0 does not derive transmission, refractive focus shift, aberration, thickness effects, or a spectral response from those roles.
+
+Microlens presence or absence is also descriptive only. A `present` microlens does not by itself specify angular acceptance, spatial concentration, fill factor, crosstalk, QE improvement, or field behavior.
+
+The resolver therefore returns only the **effective AA spatial kernel** and explicitly reports that cover/filter effects, microlens response, throughput, spectral transmission, field dependence, wavelength dependence, and polarization dependence are not included.
+
+## Sensor sampling aperture
+
+Use `parseSensorSamplingApertureProfile()` and `resolveSensorSamplingAperture()` when the physical color-site lattice registration and a geometric photosensitive-region approximation are known:
+
+```ts
+import {
+  parseSensorSamplingApertureProfile,
+  resolveSensorSamplingAperture
+} from "@photivra/engine";
+
+const sampling = parseSensorSamplingApertureProfile({
+  schemaVersion: "0.1.0",
+  profileId: "example-sampling-aperture",
+  colorSamplingProfileId: "example-periodic-layout",
+  colorSamplingBindingId: "example-native-to-cfa",
+  evidence: [
+    {
+      sourceOrigin: "photivra",
+      sourceReference: "example:sampling-aperture",
+      reuseStatus: "photivra-owned"
+    }
+  ],
+  siteCenterLattice: {
+    kind: "regular-rectangular-site-center-lattice",
+    coordinateSystem: "native-sensor-physical",
+    pitchXMicrometers: 6,
+    pitchYMicrometers: 6,
+    firstSiteCenterFromImagingAreaTopLeftMicrometers: {
+      x: 3,
+      y: 3
+    },
+    evidence: [
+      {
+        sourceOrigin: "photivra",
+        sourceReference: "example:site-registration",
+        reuseStatus: "photivra-owned"
+      }
+    ]
+  },
+  geometricSensitiveAperture: {
+    kind: "uniform-axis-aligned-rectangle",
+    widthMicrometers: 5,
+    heightMicrometers: 5,
+    centerOffsetFromSiteCenterMicrometers: {
+      x: 0,
+      y: 0
+    },
+    evidence: [
+      {
+        sourceOrigin: "photivra",
+        sourceReference: "example:sensitive-region",
+        reuseStatus: "photivra-owned"
+      }
+    ]
+  }
+});
+
+const siteAperture = resolveSensorSamplingAperture({
+  imagingArea: {
+    widthMm: 36,
+    heightMm: 24
+  },
+  nativeRaster: {
+    pixelWidth: 6000,
+    pixelHeight: 4000
+  },
+  colorSamplingProfile: topology,
+  colorSamplingBindingProfile: binding,
+  samplingApertureProfile: sampling,
+  site: { x: 100, y: 200 }
+});
+
+console.log(
+  siteAperture.geometricSensitiveAperture
+    .boundsFromOpticalAxisMm
+);
+```
+
+The site-center lattice is a distinct physical registration contract:
+
+- coordinates are `native-sensor-physical`: optical-axis origin, +X right, +Y down;
+- `pitchXMicrometers` and `pitchYMicrometers` are explicit evidence-backed site-center spacings;
+- the first site's center is explicitly registered relative to the physical imaging area's top-left edge;
+- the full declared lattice must fit inside the supplied physical imaging area.
+
+Photivra does **not** derive this site pitch or origin from `NativeImageRaster`. The native effective raster and the color-site lattice already have a structural binding, but physical placement remains a separate fact.
+
+The geometric sensitive aperture is separate from site pitch. A scalar fill fraction is not sufficient to reconstruct shape or centering, so schema 0.1.0 stores explicit rectangle dimensions and center offset.
+
+The first resolved footprint is deliberately narrow:
+
+- uniform axis-aligned rectangle;
+- contained within one regular lattice cell;
+- no neighboring geometric-aperture overlap in this model;
+- normalized spatial weighting is a unit-area average;
+- physical aperture area is reported separately.
+
+The engine also derives `geometricSensitiveAreaFractionOfLatticeCell`:
+
+```text
+geometric sensitive rectangle area
+----------------------------------
+nominal site lattice cell area
+```
+
+This is a **geometry diagnostic**, not a calibrated sensitivity result. It does not establish QE, effective radiometric collection area, photon conversion, optical throughput, or physical photodiode truth.
+
+Use `kind: "unresolved"` when the geometric footprint is known to be required but its shape/dimensions are not defensibly available. Resolution then fails closed instead of fabricating a rectangle from site pitch, megapixels, or a fill-factor percentage.
+
+The first sampling-aperture model explicitly excludes:
+
+- effective AA point splitting;
+- microlens spatial redirection;
+- charge diffusion;
+- electrical/optical crosstalk;
+- wavelength/spectral response;
+- quantum efficiency;
+- optical transmission/throughput;
+- calibrated radiometric collection area.
+
+Those effects may change the **effective** spatial response or sensitivity even when the geometric sensitive region is unchanged. For example, microlenses can redirect incident light toward the photosensitive portion of a front-illuminated pixel, and their effectiveness can vary with incidence angle. The geometric aperture must therefore not absorb microlens behavior silently.
+
+Physical camera orientation remains downstream. The site lattice and aperture stay in invariant native sensor physical coordinates.
+
+## Sensor spatial-sampling quadrature
+
+Use `calculateSensorSpatialSamplingQuadrature()` to build deterministic renderer-neutral spatial integration nodes for one resolved color-sampling site after combining:
+
+1. the geometric sensitive aperture from `SensorSamplingApertureProfile`; and
+2. the effective anti-aliasing point-splitting response from `SensorOpticalStackProfile`.
+
+```ts
+import {
+  calculateSensorSpatialSamplingQuadrature
+} from "@photivra/engine";
+
+const quadrature =
+  calculateSensorSpatialSamplingQuadrature({
+    imagingArea: { widthMm: 36, heightMm: 24 },
+    nativeRaster: {
+      pixelWidth: 6000,
+      pixelHeight: 4000
+    },
+    colorSamplingProfile: topology,
+    colorSamplingBindingProfile: binding,
+    samplingApertureProfile: sampling,
+    opticalStackProfile: stack,
+    site: { x: 100, y: 200 },
+    spatialSampleCountX: 4,
+    spatialSampleCountY: 4
+  });
+
+console.log(quadrature.value.nodes);
+```
+
+The first scheme is a tensor-product uniform midpoint rule over the geometric aperture. Each AA split component multiplies that aperture quadrature.
+
+AA composition uses **inverse source sampling**. If the optical stack declares that a component displaces optical energy by `+delta` on the sensor plane, a destination aperture point reads the pre-AA optical field at:
+
+```text
+pre-AA source = destination aperture point - AA displacement
+```
+
+The destination sensor site's CFA/color channel applies to every node. A shifted pre-AA source coordinate is an optical-field location, not another CFA site, so it never reassigns the destination CFA channel.
+
+Two measures are returned separately:
+
+- `combinedNormalizedSpatialWeight` — dimensionless weight for approximating a spatial average;
+- `combinedAreaMeasureSquareMicrometers` — geometric area measure for approximating a spatial area integral.
+
+The area measure is **not** effective radiometric collection area, throughput, QE, or photon count.
+
+Near sensor edges, AA inverse-source coordinates may lie outside the active physical imaging area. Those nodes remain valid and are retained. Photivra does not clamp them, drop them, or renormalize the remaining weights. A renderer/optical-field provider owns source-coverage policy.
+
+The API intentionally returns geometry and measures only. It does not evaluate optical-field values, radiance, spectral response, photons/electrons, temporal exposure, RAW values, or reconstruction. Spatial and temporal quadrature remain separate until a later explicit composition evaluates a common downstream field.
+
+Because spatial integration error depends on the downstream optical field's spatial-frequency/content, Photivra does not report a geometry-only convergence/error estimate. Reference rendering can compare increasing spatial sample counts in the quantity actually being integrated.
+
+A per-site node allocation safety limit prevents malformed/untrusted counts from creating an oversized array in one call.
+
+## Sensor spatial-sample reduction
+
+Use `reduceSensorSpatialSamplingQuadrature()` after a renderer or optical model has evaluated one scalar value at every spatial quadrature node's `preAntiAliasingSourcePointMm`.
+
+Node values are identified by the quadrature identity tuple—AA component index plus aperture X/Y sample indices—rather than by array position.
+
+Two input domains are supported:
+
+- `relative-linear`: a nonnegative dimensionless irradiance-like proxy for deterministic regression/testing;
+- `radiometric-irradiance`: physical sensor-plane irradiance in W/m².
+
+The physical domain follows standard radiometric meaning: irradiance is incident radiant flux per unit area, so integrating W/m² over the geometric aperture area yields incident radiant flux in watts. This still remains upstream of CFA spectral response, microlens response, QE, exposure-time integration, and sensor conversion.
+
+The reducer returns both a normalized spatial average and an area-weighted integral. For relative values the area integral is relative-value × µm²; for physical irradiance it is converted to watts.
+
+The CFA `channelId` is descriptive metadata only. No wavelength-dependent filter/sensor response is applied, so the output is **not** a physically color-filtered mosaic value and must not be called RAW.
+
+Every quadrature node requires an explicit nonnegative finite input, including nodes whose pre-AA source coordinate lies outside the active imaging area. The reducer never clamps, zero-fills, extrapolates, drops, or renormalizes missing edge support.
+
+Signed color-transform intermediates, RGB display values, gamma-encoded values, radiance, spectral irradiance, temporal exposure, photons/electrons, noise, saturation, black level, ADC quantization, RAW codes, and demosaic/reconstruction are outside this contract.
+
+## Capture-mode profiles
+
+Use `parseCaptureModeProfile()` and `resolveCaptureMode()` to describe how one physical sensor can expose different acquisition/sampling/reconstruction modes without changing sensor identity:
+
+```ts
+import {
+  parseCaptureModeProfile,
+  resolveCaptureMode
+} from "@photivra/engine";
+
+const modes = parseCaptureModeProfile({
+  schemaVersion: "0.1.0",
+  modes: [
+    {
+      modeId: "pixel-shift-4",
+      evidence: [
+        {
+          sourceOrigin: "manufacturer",
+          sourceReference: "example:pixel-shift-mode",
+          reuseStatus: "factual-reference-only"
+        }
+      ],
+      acquisition: {
+        kind: "fixed-multi-frame",
+        frameCount: {
+          value: 4,
+          evidence: [
+            {
+              sourceOrigin: "manufacturer",
+              sourceReference: "example:pixel-shift-frame-count",
+              reuseStatus: "factual-reference-only"
+            }
+          ]
+        }
+      },
+      perFrameSampling: {
+        kind: "native-effective-raster"
+      },
+      interFrameSensorOffsetsNativeSamples: {
+        value: [
+          { x: 0, y: 0 },
+          { x: 0.5, y: 0 },
+          { x: 0, y: 0.5 },
+          { x: 0.5, y: 0.5 }
+        ],
+        evidence: [
+          {
+            sourceOrigin: "manufacturer",
+            sourceReference: "example:pixel-shift-offset-sequence",
+            reuseStatus: "factual-reference-only"
+          }
+        ]
+      },
+      reconstructionStages: [
+        {
+          value: "pixel-shift-combination",
+          evidence: [
+            {
+              sourceOrigin: "manufacturer",
+              sourceReference: "example:pixel-shift-combination",
+              reuseStatus: "factual-reference-only"
+            }
+          ]
+        }
+      ],
+      processedImageRaster: {
+        value: {
+          pixelWidth: 12000,
+          pixelHeight: 8000
+        },
+        evidence: [
+          {
+            sourceOrigin: "manufacturer",
+            sourceReference: "example:processed-raster",
+            reuseStatus: "factual-reference-only"
+          }
+        ]
+      },
+      dependencies: [
+        "color-sampling-model",
+        "inter-frame-registration"
+      ]
+    }
+  ]
+});
+
+const selected = resolveCaptureMode({
+  nativeRaster: {
+    pixelWidth: 6000,
+    pixelHeight: 4000
+  },
+  profile: modes,
+  modeId: "pixel-shift-4"
+});
+
+console.log(selected.processedImageMegapixels);
+```
+
+The model is deliberately **orthogonal**, not one mutually exclusive marketing-style mode enum. A mode independently describes:
+
+- acquisition as single-frame, fixed multi-frame, or variable multi-frame;
+- per-frame sampling as the native effective raster, exact integer grouping of native effective samples, or another explicitly evidenced effective raster;
+- an optional ordered inter-frame sensor-offset sequence for fixed multi-frame modes;
+- zero or more reconstruction stages such as remosaic, pixel-shift combination, and generic multi-frame computational combination;
+- the processed-image raster before final output crop/resampling;
+- explicit downstream model dependencies.
+
+This lets a computational multi-frame mode also use grouped per-frame sampling instead of forcing it into one exclusive category.
+
+`NativeImageRaster` keeps its canonical meaning: an **effective native image-sampling grid**, not a physical photosite raster. Neither native megapixels nor processed/final-output megapixels may be used to infer physical photodiode count.
+
+For grouped sampling, Photivra derives the per-frame sampling raster only when the native dimensions divide exactly by the evidenced grouping factors. The optional `combinationDomain` distinguishes `charge-domain`, `pre-conversion-analog`, and `post-conversion-digital`. When that fact is not known it must be omitted; the word “binning” or a 2×2 resolution ratio does not establish where combination occurred.
+
+Inter-frame sensor offsets are expressed in units of the **native effective sampling pitch**. They are not evidence of physical photodiode pitch. The offset sequence length must match a fixed multi-frame count when supplied.
+
+`processedImageRaster` belongs to the capture-mode/reconstruction pipeline. It does not change physical imaging area, crop factor, field of view, or the native effective raster. It may be larger than the native raster for a multi-frame reconstruction without implying a higher-resolution physical sensor.
+
+Final output crop/resampling remains owned by the existing staged capture/output geometry contract. A processed raster therefore does not itself define final display/export dimensions or viewing FOV.
+
+The capture-mode schema records dependencies such as `color-sampling-model`, `mode-specific-readout-timing`, `radiometric-calibration`, and `inter-frame-registration` without pretending those downstream models are already implemented.
+
+## Sensor readout timing
+
+Use `calculateSensorReadoutTiming()` for a capture-specific native sensor scan schedule without conflating sensor readout with shutter-curtain timing:
+
+```ts
+import {
+  calculateSensorReadoutTiming,
+  transformNativeRasterVectorToOriented
+} from "@photivra/engine";
+
+const timing = calculateSensorReadoutTiming({
+  nativeRaster: { pixelWidth: 6000, pixelHeight: 4000 },
+  activeCaptureRect: { x: 0, y: 0, width: 6000, height: 4000 },
+  shutterMechanism: "electronic",
+  readout: {
+    readoutMode: "rolling",
+    captureReadoutDurationSeconds: {
+      value: 0.024,
+      unit: "s",
+      evidence: [
+        {
+          sourceOrigin: "manufacturer",
+          sourceReference: "manufacturer-spec:example",
+          reuseStatus: "factual-reference-only"
+        }
+      ]
+    },
+    scanDirectionNative: {
+      value: "top-to-bottom",
+      evidence: [
+        {
+          sourceOrigin: "manufacturer",
+          sourceReference: "manufacturer-spec:direction-example",
+          reuseStatus: "factual-reference-only"
+        }
+      ]
+    },
+    spatialSamplingSkewSeconds: {
+      value: 0.020,
+      unit: "s",
+      evidence: [
+        {
+          sourceOrigin: "third-party",
+          sourceReference: "measurement:spatial-skew-example",
+          reuseStatus: "factual-reference-only"
+        }
+      ]
+    }
+  },
+  samplePointsNative: [
+    { x: 3000, y: 0 },
+    { x: 3000, y: 2000 },
+    { x: 3000, y: 4000 }
+  ]
+});
+
+console.log(timing.value.samples);
+console.log(timing.value.scan?.unitVectorNative);
+
+const orientedDirection = transformNativeRasterVectorToOriented({
+  vector: timing.value.scan?.unitVectorNative ?? { x: 0, y: 0 },
+  orientation: "portrait-clockwise"
+});
+```
+
+The two timing facts are intentionally separate. `captureReadoutDurationSeconds` records the selected capture's declared data-readout duration; `spatialSamplingSkewSeconds` drives only the spatial phase span of the current rolling approximation. Photivra does not assume those values are equal.
+
+Global readout declares only the capture data-readout duration. Its spatial phase offset is zero everywhere even when that duration is non-zero.
+
+The rolling schedule is a `uniform-linear-single-axis` approximation in invariant native sensor coordinates. `NativeImageRaster` remains an effective image-sampling grid, so this API does not claim that each raster row/column corresponds to one physical photodiode row or hardware readout line. Non-uniform, segmented, center-out, interleaved and multi-tap readout patterns are not represented by this first model.
+
+Physical camera orientation is deliberately excluded from the timing input. Use the existing native↔oriented vector transform when a downstream renderer needs the scan direction in oriented capture coordinates. Output crop/resolution is also excluded and therefore cannot silently change native readout timing.
+
+Active-crop/capture-mode timing must be supplied explicitly; the engine never scales full-frame timing from crop dimensions. Shutter mechanism is recorded independently and does not modify the schedule. Mechanical-curtain travel, EFCS timing, local exposure windows, rolling-shutter geometric distortion, flash/flicker interaction and motion integration remain future work.
+
+## Readout/exposure spatial linkage
+
+Use `assessReadoutExposureTimingLinkage()` when a specific capture-mode source supports a relationship between rolling sensor readout spatial order and an **electronic** exposure boundary:
+
+```ts
+import { assessReadoutExposureTimingLinkage } from "@photivra/engine";
+
+const relationship = assessReadoutExposureTimingLinkage({
+  nativeRaster: { pixelWidth: 6000, pixelHeight: 4000 },
+  shutterMechanism: "electronic",
+  readout: {
+    readoutMode: "rolling",
+    captureReadoutDurationSeconds: {
+      value: 0.031,
+      unit: "s",
+      evidence: [
+        {
+          sourceOrigin: "manufacturer",
+          sourceReference: "example:data-readout-duration",
+          reuseStatus: "factual-reference-only"
+        }
+      ]
+    },
+    scanDirectionNative: {
+      value: "top-to-bottom",
+      evidence: [
+        {
+          sourceOrigin: "manufacturer",
+          sourceReference: "example:readout-direction",
+          reuseStatus: "factual-reference-only"
+        }
+      ]
+    },
+    spatialSamplingSkewSeconds: {
+      value: 0.02,
+      unit: "s",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "example:measured-spatial-skew",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    }
+  },
+  nominalExposureDurationSeconds: {
+    value: 1 / 1000,
+    unit: "s",
+    evidence: [
+      {
+        sourceOrigin: "photivra",
+        sourceReference: "example:capture-config",
+        reuseStatus: "photivra-owned"
+      }
+    ]
+  },
+  opening: {
+    kind: "uniform-linear-native-scan",
+    directionNative: {
+      value: "top-to-bottom",
+      evidence: [
+        {
+          sourceOrigin: "manufacturer",
+          sourceReference: "example:electronic-opening-direction",
+          reuseStatus: "factual-reference-only"
+        }
+      ]
+    },
+    traversalDurationSeconds: {
+      value: 0.01,
+      unit: "s",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "example:opening-traversal",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    }
+  },
+  closing: {
+    kind: "uniform-linear-native-scan",
+    directionNative: {
+      value: "top-to-bottom",
+      evidence: [
+        {
+          sourceOrigin: "manufacturer",
+          sourceReference: "example:electronic-closing-direction",
+          reuseStatus: "factual-reference-only"
+        }
+      ]
+    },
+    traversalDurationSeconds: {
+      value: 0.01,
+      unit: "s",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "example:closing-traversal",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    }
+  },
+  linkage: {
+    kind: "spatial-phase-linked",
+    links: [
+      {
+        boundary: "opening",
+        phaseOrientation: "same",
+        evidence: [
+          {
+            sourceOrigin: "manufacturer",
+            sourceReference: "example:documented-spatial-relationship",
+            reuseStatus: "factual-reference-only"
+          }
+        ]
+      }
+    ]
+  }
+});
+
+console.log(relationship.value.links[0]);
+```
+
+The positive link means only that the selected electronic exposure boundary shares the rolling readout's **normalized native spatial phase/order**:
+
+- `same` means boundary phase equals readout phase;
+- `reversed` means boundary phase equals `1 - readout phase`.
+
+It does **not** mean the two events occur at the same absolute time.
+
+The function therefore reports `absoluteTemporalAlignment: "not-established"` even when directions and first-to-last timing spans happen to match.
+
+The readout spatial skew and exposure-boundary traversal duration may differ. Their ratio is reported as `boundaryTraversalToReadoutSpatialSkewRatio`, which is descriptive only.
+
+The total `captureReadoutDurationSeconds` remains a separate evidence-backed fact and does not participate in linkage validation.
+
+Only electronic boundaries can be spatial-phase-linked to sensor readout. A mechanical opening/closing boundary is rejected. Global readout has no rolling spatial phase and therefore cannot participate in this first linkage type.
+
+Use `linkage: { kind: "unlinked" }` when Photivra should assert no relationship. This means **no relationship is asserted**; it does not establish that the underlying hardware processes are physically independent.
+
+## Capture exposure-window timing
+
+Use `calculateCaptureExposureWindows()` to describe when different native-sensor locations begin and end their local exposure without conflating shutter actuation with sensor readout:
+
+```ts
+import { calculateCaptureExposureWindows } from "@photivra/engine";
+
+const windows = calculateCaptureExposureWindows({
+  nativeRaster: { pixelWidth: 6000, pixelHeight: 4000 },
+  shutterMechanism: "electronic-first-curtain",
+  nominalExposureDurationSeconds: {
+    value: 1 / 1000,
+    unit: "s",
+    evidence: [
+      {
+        sourceOrigin: "photivra",
+        sourceReference: "capture-config:example",
+        reuseStatus: "photivra-owned"
+      }
+    ]
+  },
+  opening: {
+    kind: "uniform-linear-native-scan",
+    directionNative: {
+      value: "top-to-bottom",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "timing-profile:opening-direction",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    },
+    traversalDurationSeconds: {
+      value: 0.004,
+      unit: "s",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "timing-profile:opening-traversal",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    }
+  },
+  closing: {
+    kind: "uniform-linear-native-scan",
+    directionNative: {
+      value: "top-to-bottom",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "timing-profile:closing-direction",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    },
+    traversalDurationSeconds: {
+      value: 0.004,
+      unit: "s",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "timing-profile:closing-traversal",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    }
+  },
+  samplePointsNative: [
+    { x: 3000, y: 0 },
+    { x: 3000, y: 2000 },
+    { x: 3000, y: 4000 }
+  ]
+});
+
+console.log(windows.value.samples);
+console.log(windows.value.localExposureDurationRangeSeconds);
+```
+
+The time basis is `first-opening-boundary-phase`: zero means the first spatial phase of the declared opening boundary. This deliberately avoids pretending that a spatially scanned capture has one universal local exposure-start event.
+
+Opening and closing schedules are independent. Each may currently be either:
+
+- `simultaneous`; or
+- `uniform-linear-native-scan` with its own evidence-backed native direction and traversal duration.
+
+The nominal exposure duration is a separate evidence-backed quantity. For a native point:
+
+```text
+local start = opening phase
+local end   = nominal exposure duration + closing phase
+local duration = local end - local start
+```
+
+Matched opening/closing scans with equal traversal produce constant local exposure duration. Different directions or traversal durations can intentionally produce spatially varying local duration.
+
+Photivra validates the **entire active rectangle**, not only supplied diagnostic points. Because the first schedules are affine over the native rectangle, corner extrema are sufficient to reject any declaration that would produce zero or negative local exposure duration somewhere in the capture.
+
+`shutterMechanism` determines only the conceptual boundary actuators:
+
+- `mechanical` → mechanical opening + mechanical closing;
+- `electronic-first-curtain` → electronic opening + mechanical closing;
+- `electronic` → electronic opening + electronic closing.
+
+The mechanism does not supply traversal direction or timing.
+
+This exposure-window model remains separate from `calculateSensorReadoutTiming()`. A later integration layer must explicitly bind exposure boundaries, sensor readout, and time-parameterized motion; Photivra does not assume a sensor readout phase is an exposure-start or exposure-end boundary.
+
+Physical orientation and digital output geometry remain downstream. The schedule stays in invariant native sensor coordinates and can use the existing native↔oriented vector transforms when a consumer needs presentation-oriented direction.
+
+The first model does not cover curtain acceleration, curved/nonlinear curtain travel, segmented/center-out/interleaved electronic schedules, flash/flicker interaction, shutter shock, EFCS-specific pupil/bokeh effects, or rolling-shutter image distortion.
+
 ## Capture orientation, active area, and output geometry
 
 Use `resolveCaptureGeometry()` to keep physical sensor identity, active capture, physical camera orientation, and final digital output geometry separate:
@@ -862,6 +1836,302 @@ These relations do not model scene radiance, lens T-stop/transmission, vignettin
 
 See [Motion and Signal Foundation](MOTION_AND_SIGNAL.md#exposure-relations).
 
+## Capture rotation exposure trajectories
+
+Use `calculateCaptureRotationTrajectories()` when you need to evaluate **pure camera rotation over each native point's local exposure interval** while preserving the separation between shutter/exposure timing and sensor readout:
+
+```ts
+import { calculateCaptureRotationTrajectories } from "@photivra/engine";
+
+const trajectories = calculateCaptureRotationTrajectories({
+  imagingArea: { widthMm: 36, heightMm: 24 },
+  nativeRaster: { pixelWidth: 6000, pixelHeight: 4000 },
+  shutterMechanism: "electronic",
+  nominalExposureDurationSeconds: {
+    value: 1 / 1000,
+    unit: "s",
+    evidence: [
+      {
+        sourceOrigin: "photivra",
+        sourceReference: "capture-config:example",
+        reuseStatus: "photivra-owned"
+      }
+    ]
+  },
+  opening: {
+    kind: "uniform-linear-native-scan",
+    directionNative: {
+      value: "top-to-bottom",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "timing-profile:opening-direction",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    },
+    traversalDurationSeconds: {
+      value: 0.015,
+      unit: "s",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "timing-profile:opening-traversal",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    }
+  },
+  closing: {
+    kind: "uniform-linear-native-scan",
+    directionNative: {
+      value: "top-to-bottom",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "timing-profile:closing-direction",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    },
+    traversalDurationSeconds: {
+      value: 0.015,
+      unit: "s",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "timing-profile:closing-traversal",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    }
+  },
+  focalLengthMm: 50,
+  angularVelocityRadPerSec: {
+    pitch: 0,
+    yaw: 0.1,
+    roll: 0
+  },
+  samplePointsNative: [
+    { x: 3000, y: 0 },
+    { x: 3000, y: 2000 },
+    { x: 3000, y: 4000 }
+  ]
+});
+
+console.log(trajectories.value.samples);
+```
+
+The function maps each native point to the pre-orientation image plane at the capture reference time, then evaluates the existing `calculateCameraRotationImageMapping()` primitive at that point's local exposure start and end.
+
+The explicit time reference is the **first opening-boundary phase**. For this composition only, that reference is bound to `t = 0` of the low-level rotation model. This does not redefine the standalone rotation API for other callers.
+
+The returned trajectory is **forward temporal geometry for a stationary world ray**:
+
+- `referenceImagePointMm` is the ray's image-plane position at the capture reference;
+- `atLocalExposureStart` and `atLocalExposureEnd` are its mapped positions at the local window endpoints;
+- `localExposureTrajectoryEndpointDeltaMm` is the chord between those endpoints.
+
+The chord is not an integrated blur kernel. It also is not a renderer-ready rolling-shutter warp.
+
+A capture-scan image mapping is location-dependent because capture time varies across the image. For the current pure-rotation model, destination-to-reference inversion is analytic once the destination location selects its local capture time. More general motion models may require additional solving and global-validity analysis. Finite-exposure rendering still requires integration over the full local interval rather than one endpoint or midpoint displacement.
+
+`calculateSensorReadoutTiming()` is intentionally not an input. If a specific capture mode has a defensible relationship between electronic exposure timing and sensor readout timing, that relationship should be represented by a future explicit mode/link contract rather than assumed by this API.
+
+The current trajectory model remains pure rotation only. It excludes camera translation/parallax, subject motion, rotating/deforming subjects, occlusion changes, panning intent, exposure integration, flash/flicker, shutter shock, and final rolling-shutter inverse warping.
+
+## Capture rotation temporal quadrature
+
+Use `calculateCaptureRotationTemporalQuadrature()` when a downstream renderer or reference evaluator needs deterministic pure-rotation geometry samples across each destination point's complete local exposure interval:
+
+```ts
+import { calculateCaptureRotationTemporalQuadrature } from "@photivra/engine";
+
+const quadrature = calculateCaptureRotationTemporalQuadrature({
+  imagingArea: { widthMm: 36, heightMm: 24 },
+  nativeRaster: { pixelWidth: 6000, pixelHeight: 4000 },
+  shutterMechanism: "electronic",
+  nominalExposureDurationSeconds: {
+    value: 1 / 1000,
+    unit: "s",
+    evidence: [
+      {
+        sourceOrigin: "photivra",
+        sourceReference: "capture-config:example",
+        reuseStatus: "photivra-owned"
+      }
+    ]
+  },
+  opening: {
+    kind: "simultaneous"
+  },
+  closing: {
+    kind: "simultaneous"
+  },
+  focalLengthMm: 50,
+  angularVelocityRadPerSec: {
+    pitch: 0,
+    yaw: 0.1,
+    roll: 0
+  },
+  orientation: "landscape",
+  temporalSampleCount: 8,
+  samplePointsNative: [{ x: 3000, y: 2000 }]
+});
+
+console.log(quadrature.value.points[0]?.nodes);
+```
+
+The first model uses deterministic uniform midpoint quadrature. With `N` samples, node phases are:
+
+```text
+phase_i = (i + 0.5) / N
+```
+
+Each phase is passed through `calculateCaptureRotationInverseMappings()`, so instantaneous destination-to-reference geometry remains defined by one existing public model.
+
+Every node exposes two different temporal weights:
+
+- `normalizedTimeWeight = 1 / N` for a downstream time-average under the declared uniform temporal-response approximation;
+- `timeMeasureSeconds = localExposureDuration / N` for a downstream time integral.
+
+Do not interchange them. The first is dimensionless; the second carries seconds. Neither includes shutter transmission, scene radiance, sensor response, photon conversion, vignetting, or other radiometric throughput.
+
+Different sensor locations may have different local exposure start/end times. If opening and closing scans produce different local durations, `timeMeasureSeconds` therefore differs by destination point while the normalized average weights still sum to approximately one for each point.
+
+This API returns **temporal geometry nodes and measures only**. It does not:
+
+- fetch or sample scene radiance;
+- average the reference coordinates;
+- calculate a blur radius/kernel or PSF;
+- resolve visibility/occlusion changes;
+- apply sensor readout timing;
+- apply flash/flicker or shutter-shock behavior;
+- write or resample output pixels.
+
+Averaging geometric coordinates is not equivalent to integrating radiance along moving rays.
+
+Photivra also does not report a geometry-only integration-error estimate. Temporal image error depends on downstream radiance, visibility, texture/edge frequency, reconstruction, and the motion path. A reference renderer can compare increasing `temporalSampleCount` values in the radiance/output domain when convergence evidence is needed.
+
+## Instantaneous capture rotation inverse mapping
+
+Use `calculateCaptureRotationInverseMappings()` to map captured destination locations back to the **first-opening-boundary reference image** under pure camera rotation:
+
+```ts
+import {
+  calculateCaptureRotationInverseMappings
+} from "@photivra/engine";
+
+const mapping = calculateCaptureRotationInverseMappings({
+  imagingArea: { widthMm: 36, heightMm: 24 },
+  nativeRaster: { pixelWidth: 6000, pixelHeight: 4000 },
+  shutterMechanism: "electronic",
+  nominalExposureDurationSeconds: {
+    value: 1 / 1000,
+    unit: "s",
+    evidence: [
+      {
+        sourceOrigin: "photivra",
+        sourceReference: "capture-config:example",
+        reuseStatus: "photivra-owned"
+      }
+    ]
+  },
+  opening: {
+    kind: "uniform-linear-native-scan",
+    directionNative: {
+      value: "top-to-bottom",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "timing-profile:opening-direction",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    },
+    traversalDurationSeconds: {
+      value: 0.015,
+      unit: "s",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "timing-profile:opening-traversal",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    }
+  },
+  closing: {
+    kind: "uniform-linear-native-scan",
+    directionNative: {
+      value: "top-to-bottom",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "timing-profile:closing-direction",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    },
+    traversalDurationSeconds: {
+      value: 0.015,
+      unit: "s",
+      evidence: [
+        {
+          sourceOrigin: "photivra",
+          sourceReference: "timing-profile:closing-traversal",
+          reuseStatus: "photivra-owned"
+        }
+      ]
+    }
+  },
+  focalLengthMm: 50,
+  angularVelocityRadPerSec: {
+    pitch: 0,
+    yaw: 0.1,
+    roll: 0
+  },
+  localExposurePhase: 0.5,
+  orientation: "landscape",
+  samplePointsNative: [
+    { x: 3000, y: 0 },
+    { x: 3000, y: 2000 },
+    { x: 3000, y: 4000 }
+  ]
+});
+
+console.log(mapping.value.samples);
+```
+
+`localExposurePhase` is mandatory:
+
+- `0` evaluates local exposure start;
+- `0.5` evaluates the local temporal midpoint;
+- `1` evaluates local exposure end.
+
+Photivra does not choose a default phase because a finite exposure does not have one uniquely correct sharp geometry.
+
+Each destination native point first selects its local exposure time. Under the current constant-axis pure-rotation model, the captured ray can then be rotated **analytically** back to the exposure-start reference frame with `calculateInverseCameraRotationImageMapping()`. No iterative/fixed-point solver or convergence tolerance is needed.
+
+The result reports:
+
+- destination native and ideal image-plane coordinates;
+- the local exposure window and selected capture time;
+- the corresponding reference image-plane ray;
+- reference-minus-destination displacement in image-plane millimetres;
+- equivalent continuous native effective-sample displacement;
+- that displacement rotated into the requested physical capture orientation.
+
+The mapping deliberately remains in the ideal pre-lens geometry stage. It does not apply radial distortion, lateral CA, PSF, output crop, or output resampling.
+
+Reference rays are **not clamped** to the active source region. Camera motion can cause a valid captured destination to require reference-image data outside that region. A renderer must decide how to handle unavailable source coverage rather than silently clamping/stretching an edge.
+
+This is an **instantaneous** mapping only. It is not a complete finite-exposure rolling/capture-scan image. Motion blur requires multiple temporal samples or another defensible integration method over each local exposure window, including an explicit exposure-weighting model if the weighting is not uniform.
+
+Sensor data-readout timing is intentionally not part of this calculation. Capture exposure boundaries remain the authoritative timing input until a separate capture-mode/link contract establishes otherwise.
+
+The current model is pure rotation only. Translation/parallax, subject motion, deformation, occlusion changes, global injectivity/fold analysis, flash/flicker, shutter shock, and finite-exposure integration remain outside this slice.
+
 ## Spatial camera-rotation mapping
 
 Use `calculateCameraRotationImageMapping()` when you need the image-plane location of a stationary world ray after **pure camera rotation** at an arbitrary physical time from exposure start.
@@ -1138,7 +2408,7 @@ The current composed POC reports X/Y geometric sample pitch but still uses one b
 
 POC API 0.20 composes the capture-geometry foundation through final output/viewing semantics. Existing requests remain valid. New callers may supply an optional `capture` object with physical orientation, an optional native active-capture rectangle, an optional oriented output crop, and an optional final output raster.
 
-Capture mode deliberately keeps legacy `crop.factor` separate: it must remain `1` when `capture` is present. Staged capture can use the existing `subjectCrop` request, but the result appears under `capture.subjectFraming` because it is a post-output framing stage rather than a legacy total-crop factor.
+The POC staged `capture` geometry request deliberately keeps legacy `crop.factor` separate: it must remain `1` when `capture` is present. This geometry request is distinct from the sensor/capture-mode profile contract. Staged capture can use the existing `subjectCrop` request, but the result appears under `capture.subjectFraming` because it is a post-output framing stage rather than a legacy total-crop factor.
 
 Equivalent-viewing CoC in capture mode uses the final retained physical image region, including subject framing when present; changing only output pixel resolution does not change the criterion. Explicit `circleOfConfusionMm` remains unchanged.