@photivra/engine 1.4.0 → 2.0.0

package/docs/api/sensor-accumulated-charge.md

@@ -1,16 +1,14 @@
 # sensor/accumulated-charge.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## composeSensorAccumulatedCharge
 
-Compose photo, independently evaluated dark and explicitly incremental charge by exact local
-exposure identity, retaining completeness assessment before capacity/noise.
+Adds photo charge, separately computed dark charge and any explicitly declared extra charge for
+one exact local exposure, and keeps the completeness assessment. Capacity and noise come later.
 
-Photo, dark and explicitly incremental stored-electron components must share the exact
-site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
-consequence of an empty component array. Expected stored charge remains distinct from a stochastic
-realization or nonlinear full-well clamp.
+All parts must belong to the exact same site, colour channel and local shutter event. The
+result is the expected charge, separate from a random realization or the full-well clamp.
 
 ```ts
 export function composeSensorAccumulatedCharge(
@@ -72,13 +70,11 @@ export type ComposeSensorPhotoAccumulatedChargeInput = ComposeSensorAccumulatedC
 
 ## parseSensorAccumulatedChargeCompletenessProfile
 
-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 an untrusted completeness profile and returns it normalized. Unknown enum values,
+missing required fields and inconsistent scientific data are rejected.
 
-Photo, dark and explicitly incremental stored-electron components must share the exact
-site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
-consequence of an empty component array. Expected stored charge remains distinct from a stochastic
-realization or nonlinear full-well clamp.
+Completeness is a declaration backed by evidence. An empty list of components does not
+mean the charge accounting is complete.
 
 ```ts
 export function parseSensorAccumulatedChargeCompletenessProfile(
@@ -90,13 +86,9 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSensorAdditionalStoredChargeComponent
 
-Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
-missing required fields and incompatible scientific data fail at this boundary.
-
-Photo, dark and explicitly incremental stored-electron components must share the exact
-site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
-consequence of an empty component array. Expected stored charge remains distinct from a stochastic
-realization or nonlinear full-well clamp.
+Validates an untrusted additional stored-charge component (charge other than photo and dark
+charge, declared explicitly as an addition) and returns it normalized. Unknown enum values,
+missing required fields and inconsistent scientific data are rejected.
 
 ```ts
 export function parseSensorAdditionalStoredChargeComponent(

package/docs/api/sensor-architecture.md

@@ -1,19 +1,18 @@
 # sensor/architecture.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## parseSensorArchitectureProfile
 
 Parses untrusted descriptive sensor-architecture metadata.
 
-Schema 0.2.0 remains accepted and returns a 0.2.0 profile unchanged in
-semantic identity. Schema 0.3.0 adds optional evidence-backed CMOS/CCD
-technology-family metadata. Unknown facts should be omitted instead of
-inferred.
+Schema 0.2.0 is still accepted and returns a 0.2.0 profile with the same
+meaning. Schema 0.3.0 adds an optional, evidence-backed technology family
+(CMOS or CCD). Leave out facts you do not know rather than guessing them.
 
-The parser validates structure, supported vocabulary, and field-level
-evidence only; it does not verify that a cited real-world claim is
-factually true and technology family does not activate hidden physics.
+The parser checks structure, allowed values and per-field evidence only. It
+does not check that a cited real-world claim is true, and the technology
+family does not switch on any hidden physics.
 
 ```ts
 export function parseSensorArchitectureProfile(
@@ -53,8 +52,8 @@ export type SensorArchitectureProfile =
 
 Legacy sensor-architecture schema.
 
-Schema 0.2.0 remains accepted and is preserved exactly when parsed. It does
-not support technologyFamily; omission remains unknown/unasserted.
+Schema 0.2.0 is still accepted and kept exactly as parsed. It has no
+technologyFamily field; leaving it out means "unknown, not stated".
 
 ```ts
 export interface SensorArchitectureProfileV0_2
@@ -66,18 +65,18 @@ export interface SensorArchitectureProfileV0_2
 
 ## SensorArchitectureProfileV0_3
 
-Current descriptive sensor hardware/capability metadata.
+Current descriptive metadata about the sensor hardware and its capabilities.
 
-Omitted properties mean unknown/unasserted. These fields are not scientific
-effect switches: no architecture value changes noise, dynamic range, FOV,
-crop factor, exposure, readout timing, or sampling without a separate
-downstream model that explicitly consumes that fact.
+An omitted property means "unknown, not stated". These fields do not switch
+on scientific effects. No architecture value changes noise, dynamic range,
+field of view, crop factor, exposure, readout timing or sampling unless a
+separate downstream model explicitly uses that fact.
 
 ```ts
 export interface SensorArchitectureProfileV0_3
   extends SensorArchitectureProfileBase {
   schemaVersion: typeof SENSOR_ARCHITECTURE_PROFILE_SCHEMA_VERSION;
-  /** Coarse detector technology identity only; never a performance switch. */
+  /** Broad detector technology (for example CMOS or CCD) only. It never changes performance. */
   technologyFamily?: SourcedSensorArchitectureFact<SensorTechnologyFamily>;
 }
 ```

package/docs/api/sensor-camera-saturation-capacity.md

@@ -1,15 +1,13 @@
 # sensor/camera-saturation-capacity.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## assessSensorCameraSaturationCapacity
 
-Compare dark-corrected expected photo signal with the declared camera response-chain capacity
-without adding dark charge or identifying a hardware clamp.
+Compares the expected photo signal (dark-corrected) with the camera's declared saturation
+capacity. Dark charge is not added, and no hardware clamp is identified.
 
-Camera saturation capacity is a dark-corrected photo-signal electron-equivalent limit. It is not
-physical total-charge storage capacity, ADC maximum or evidence of the limiting hardware stage. This
-assessment compares expectations and does not synthesize post-saturation codes.
+This compares expected values only. It does not make up codes beyond saturation.
 
 ```ts
 export function assessSensorCameraSaturationCapacity(
@@ -37,12 +35,12 @@ export interface AssessSensorCameraSaturationCapacityInput {
 
 ## parseSensorCameraSaturationCapacityProfile
 
-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.
 
-Camera saturation capacity is a dark-corrected photo-signal electron-equivalent limit. It is not
-physical total-charge storage capacity, ADC maximum or evidence of the limiting hardware stage. This
-assessment compares expectations and does not synthesize post-saturation codes.
+Camera saturation capacity is a limit on the dark-corrected photo signal, in electron
+equivalents. It is not the physical charge storage capacity or the ADC maximum, and does not
+identify which hardware stage limits it.
 
 ```ts
 export function parseSensorCameraSaturationCapacityProfile(

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

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

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

@@ -1,6 +1,6 @@
 # sensor/capture-mode-timing.ts public contracts
 
-Package **1.4.0**, root API **1.4.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## CAPTURE_MODE_TIMING_PROFILE_SCHEMA_VERSION
 
@@ -41,11 +41,11 @@ export interface CaptureModeTimingProfile {
 
 ## parseCaptureModeTimingProfile
 
-Parses timing facts that are explicitly bound to one exact capture mode.
+Parses timing facts tied to one exact capture mode.
 
-Schema 0.1.0 intentionally admits only the timing schedule families already
-owned by #12: simultaneous/global or uniform-linear native scans. Unsupported
-non-uniform/segmented schedules fail closed instead of being approximated.
+Schema 0.1.0 accepts only the schedules the readout-timing and exposure-window
+models already support: global (simultaneous) or uniform linear native scans.
+Non-uniform or segmented schedules are rejected rather than approximated.
 
 ```ts
 export function parseCaptureModeTimingProfile(
@@ -57,11 +57,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## resolveCaptureModeTiming
 
-Resolves the authoritative exposure/readout timing for one exact capture
-mode and timing-profile identity.
+Resolves the exposure and readout timing for one exact capture mode and
+timing profile.
 
-Readout timing remains distinct from exposure-boundary timing. No absolute
-readout/exposure synchronization is inferred.
+Readout timing stays separate from the exposure opening and closing times.
+No absolute sync between readout and exposure is assumed.
 
 ```ts
 export function resolveCaptureModeTiming(

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

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