@photivra/engine 2.15.0 → 2.17.0

package/docs/USAGE.md

@@ -1455,7 +1455,7 @@ console.log(blur.value.diameterMm);
 
 You supply the circle-of-confusion criterion used for depth of field (DOF). These are ideal geometric thin-lens models. They do not include diffraction or real-lens aberrations in the DOF criterion.
 
-`simulateCapture` and the display view render the defocus blur disc with `lens.defocus: { model: "geometric-disc" }`, up to a kernel radius of `DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES` (64 sites, a disc 129 sites across) and refuse a larger one. Use `calculateDefocusDiscKernelRadius()` to check a request before rendering it. It runs the capture's own resolution and limit test, so it agrees with the capture's refusal. Pass the f-number the capture uses (in an automatic exposure mode, the resolved one) and the sensor's pixel pitch:
+`simulateCapture` and the display view render the defocus blur disc with `lens.defocus: { model: "geometric-disc" }`, up to a kernel radius of `DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES` (512 sites, a disc 1025 sites across, 6.15 mm at 6 µm; 64 sites before 2.17.0) and refuse a larger one. Up to 64 sites the disc is convolved directly, as before; above it, by runs of equal kernel weights (#564), the same sums at a cost that grows with the radius instead of its square ([Quick start, Large defocus discs](QUICK_START.md#large-defocus-discs-564)). Use `calculateDefocusDiscKernelRadius()` to check a request before rendering it. It runs the capture's own resolution and limit test, so it agrees with the capture's refusal, and `convolution` says which method renders it. Pass the f-number the capture uses (in an automatic exposure mode, the resolved one) and the sensor's pixel pitch:
 
 ```ts
 import { calculateDefocusDiscKernelRadius } from "@photivra/engine";
@@ -1463,13 +1463,14 @@ import { calculateDefocusDiscKernelRadius } from "@photivra/engine";
 const check = calculateDefocusDiscKernelRadius({
   focalLengthMm: 50,
   aperture: 1.4,
-  focusDistanceM: 1,
+  focusDistanceM: 0.25,
   subjectDistanceM: 2,
   pixelPitchMicrometers: 6
 });
 
-console.log(check.value.withinLimit); // false: lens.defocus refuses this request
-console.log(check.value.kernelRadiusSites, check.value.excessKernelRadiusSites); // 78, 14
+console.log(check.value.withinLimit); // false: lens.defocus refuses this request (a 7.81 mm blur, 1,303 sites across)
+console.log(check.value.kernelRadiusSites, check.value.excessKernelRadiusSites); // 651, 139
+// Focused at 1 m instead: 157 sites across, radius 78, withinLimit true, convolution "runs".
 ```
 
 See [Physics Foundation](https://github.com/Photivra/photivra/blob/main/docs/PHYSICS_FOUNDATION.md#thin-lens-focus-and-depth-of-field).
@@ -3293,6 +3294,9 @@ void develop;
 
 - `highlightMode: "reconstruct"` blends pixels above 0.8 of white towards neutral, instead of clipping
   each WB-scaled channel. It is an approximation, not a recovery of the clipped signal.
+- `exposureCompensationStops` (#556, −2 to +5, default 0) multiplies each site's black-subtracted, white-normalized
+  value by 2^stops before demosaic and white balance. A site pushed to white clips and counts as saturated; the RAW
+  codes are not changed. 0 develops byte for byte as before. The WebGPU accelerator rejects a non-zero push.
 - `extended-reinhard-luminance` takes `{ whiteLuminance }`, the luminance mapped to output white.
 - `createPhotographicExportPair(input, { signal })` accepts an optional `AbortSignal`.
 
@@ -7467,6 +7471,28 @@ console.log(calculateGeometricFocusBreathing({
 }).value.deltaDegrees);
 ```
 
+## Generic lens catalogue (#549)
+
+`GENERIC_LENS_CATALOGUE` lists the engine's 30 generic primes (17 professional, 13 consumer, "PV 50 1.2 Pro", "PV 50 1.8"; Photivra's
+own designs, not real products). `resolveGenericLens` resolves one for a sensor, an f-number and a focus distance: its focal length
+(scaled by the crop factor), aperture range, close focus, projection and its character, Seidel aberrations, axial and lateral
+colour, distortion and vignetting profiles, flare, breathing and focus scatter, each a labelled approximation.
+`simulateGenericLensFocusError` draws a seeded autofocus error; `createGenericLensCorrectionProfile` builds the lens's generic
+correction profile for `resolveLensCorrectionPlan`. `simulateCapture` renders a catalogue lens with `lens.catalogue`
+([quick start](QUICK_START.md#generic-lens-catalogue-549)). Equations, tables and the chart measurements:
+[LENS_CATALOGUE.md](https://github.com/Photivra/photivra/blob/main/docs/LENS_CATALOGUE.md).
+
+```ts
+import { GENERIC_LENS_CATALOGUE, resolveGenericLens, simulateGenericLensFocusError } from "@photivra/engine";
+
+const frame = { widthMm: 36, heightMm: 24 };
+const pro = resolveGenericLens({ lensId: "pv-50-1.2-pro", activeImagingArea: frame, fNumber: 2 });
+const consumer = resolveGenericLens({ lensId: "pv-50-1.8", activeImagingArea: frame, fNumber: 2 });
+console.log(GENERIC_LENS_CATALOGUE.length, pro.character.aberrations.comaWaves < consumer.character.aberrations.comaWaves); // 30 true
+const shot = simulateGenericLensFocusError({ lensId: "pv-50-1.8", activeImagingArea: frame, fNumber: 1.8, focusDistanceM: 2, seed: 1, shotIndex: 0 });
+console.log(shot.focusDistanceM, shot.imageSideErrorMicrometers);
+```
+
 ## Parallel native environment RAW (row-band partitions, 2.0)
 
 `createNativeEnvironmentRawTask` runs on one thread. For several cores, split the capture into row bands with
@@ -7802,6 +7828,27 @@ import { simulateDisplayView } from "@photivra/engine";
 const view = await simulateDisplayView({ scene: { preset: "slanted-edge" }, sensor: { pixelPitchMicrometers: 3 }, output: { width: 600, height: 400 } },
   { width: 60, height: 40 });
 console.log(view.kind, view.view.scaleX, view.assumptions.find((a) => a.id === "view.definition")?.value);
+// #533: the real capture's clipped-highlight pixels in the rendered region, as the expected value of simulateCapture's count.
+console.log(view.diagnostics.highlight.saturatedPixelCount, view.diagnostics.highlight.statistic); // a real number, "expected-value"
+```
+
+`diagnostics.highlight.saturatedPixelCount` is the expected number of the real capture's output pixels in the rendered
+region that have a clipped contributing site. `simulateCapture` counts the same pixels on its one noise sample, so the two
+are equal where every site is far from white. Counts of regions that tile a view add up to the whole view's count. See
+[Highlight count](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#highlight-count-533).
+
+From #563 the view renders `lens.projection`, `lens.distortion`, `lens.vignetting` and camera rotation (global
+shutter), in focus and with `lens.defocus` out of focus, with each real site's expected electrons as the capture's. These
+requests run on the CPU (`gpu: "auto"` falls back labelled `unsupported-on-backend`); rotation with a rolling shutter is
+refused. See [Lens projection, distortion, vignetting and rotation](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#lens-projection-distortion-vignetting-and-rotation).
+
+```ts
+import { simulateDisplayView } from "@photivra/engine";
+
+const fisheye = await simulateDisplayView({ scene: { preset: "siemens-star" }, sensor: { pixelPitchMicrometers: 3 }, output: { width: 120, height: 80 },
+  lens: { projection: "fisheye-equisolid-angle", vignetting: { normalizationRadiusMm: 0.25, maximumNormalizedRadius: 1, coefficients: { r2: -0.4, r4: 0, r6: 0 } } } },
+  { width: 30, height: 20 });
+console.log(fisheye.kind, fisheye.assumptions.find((a) => a.id === "lens.vignetting")?.kind); // "display-view" "model"
 ```
 
 #### Rendering a prepared view on the GPU (2.11, #481)
@@ -7809,9 +7856,10 @@ console.log(view.kind, view.view.scaleX, view.assumptions.find((a) => a.id === "
 `prepareDisplayView(request, { gpu })` chooses the renderer: `"off"` (the default) is the CPU reference, `"auto"` the GPU
 when a conforming device is available and the request is supported (else the CPU, labelled), `"require"` fails instead of
 falling back. `gpuDevice` hands the view a worker's `navigator.gpu` or an `ImageKernelAccelerator` whose device it shares.
-Every render says which path ran in `diagnostics.fast.execution`, in the accelerator's words. No GPU display-view renderer
-exists yet (#478), so today `"auto"` runs the CPU reference labelled `unsupported-on-backend` without requesting a device;
-see [Rendering on the GPU](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#rendering-on-the-gpu).
+Every render says which path ran in `diagnostics.fast.execution`, in the accelerator's words. The engine's renderer runs the
+Speed (#478) and Quality (#479) kernels on a conforming device for the requests it covers. Elsewhere `"auto"` runs the CPU
+reference and gives the reason (in Node without a WebGPU entry point, for example); see
+[Rendering on the GPU](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#rendering-on-the-gpu).
 
 ```ts
 import { prepareDisplayView, type SimulateCaptureOptions } from "@photivra/engine";
@@ -7912,7 +7960,7 @@ console.log(barrel.request.siteInput(0).environment.lensFieldMapping?.distortion
 lattice, and the capture convolves the scene radiance with it, which is a geometric approximation. With
 `lens.diffraction`, each spectral node's diffraction kernel is convolved with the disc, which is a further
 approximation. The `lens.defocus` assumption records the diameter in µm and in sites, the kernel radius and the
-execution. `simulateDisplayView` does not render it yet. See [Optics](QUICK_START.md#optics).
+execution. `simulateDisplayView` renders it too, also with projection, distortion, vignetting and rotation (#563). See [Optics](QUICK_START.md#optics).
 
 ```ts
 import { simulateCapture } from "@photivra/engine";
@@ -7926,6 +7974,21 @@ const blurred = await simulateCapture({
 console.log(blurred.assumptions.find((a) => a.id === "lens.defocus")?.value); // diameterSites ≈ 5.95, kernelRadiusSites 3
 ```
 
+Bokeh character (#553): `lens.defocus` also takes `blades` (a polygonal or rounded-blade opening), `sphericalAberration`
+(primary W040: a soft-edged blur on one side of the focus plane and a bright-rimmed one on the other) and `catsEye`
+(mechanical vignetting by field position; `simulateCapture` only). Each is off by default. `calculateDefocusBokehKernel`
+returns the kernel without rendering. See [Bokeh character](QUICK_START.md#bokeh-character-553).
+
+```ts
+import { calculateDefocusBokehKernel } from "@photivra/engine";
+
+const kernel = calculateDefocusBokehKernel({
+  focalLengthMm: 50, aperture: 4, focusDistanceM: 1.4, subjectDistanceM: 2, pixelPitchMicrometers: 6,
+  bokeh: { blades: { count: 5 }, sphericalAberration: { w040Micrometers: 0.5, atFNumber: 4 } }
+});
+console.log(kernel.value.side, kernel.value.kernelRadiusSites, kernel.value.method); // "behind-focus", 17, "pupil-ray-binning"
+```
+
 `motion.angularVelocityRadPerSec` rotates the camera during the exposure (8 time midpoints by
 default). `motion.shutter: "rolling"` derives each site's exposure window from the body's rolling
 readout, with `resolveElectronicRollingShutterExposureSchedule`. See [Motion](QUICK_START.md#motion).

package/docs/api/capture-native-raw-development.md

@@ -31,6 +31,14 @@ export function createNativeRawDevelopmentTask(input: NativeRawDevelopmentInput,
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## NATIVE_RAW_DEVELOPMENT_EXPOSURE_RANGE_STOPS
+
+Accepted range of `NativeRawDevelopmentInput.exposureCompensationStops` and `simulateCapture`'s `output.exposureCompensationStops` (#556).
+
+```ts
+NATIVE_RAW_DEVELOPMENT_EXPOSURE_RANGE_STOPS = Object.freeze({ minimum: -2, maximum: 5 } as const)
+```
+
 ## NativeRawDevelopmentInput
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -56,6 +64,14 @@ export interface NativeRawDevelopmentInput {
    * always true for a 2×2 Bayer pattern. Interior pixels are unchanged.
    */
   borderHandling?: RawReconstructionBorderHandling;
+  /**
+   * Development exposure push in stops (#556), from {@link NATIVE_RAW_DEVELOPMENT_EXPOSURE_RANGE_STOPS} −2 to +5; default 0.
+   * Each site's black-subtracted, white-normalized value is multiplied by 2^stops before demosaic, white balance, the
+   * highlight mode, colour and the tone curve, like a raw editor's exposure slider. A site whose pushed value reaches the
+   * white level is clipped there and counted as saturated (so `highlightMode: "reconstruct"` rolls it off); values below
+   * black stay signed. The RAW codes are not changed. 0 (or omitted) develops exactly as before, byte for byte.
+   */
+  exposureCompensationStops?: number;
   /** Counts the kept packed RAW plus the integer output. It does not count caller buffers, process heap or GPU memory. */
   maximumRetainedPayloadBytes: number;
 }

package/docs/api/core-version.md

@@ -11,5 +11,5 @@ version they were made with. Proof-of-concept (POC), schema and model contracts
 own versions. Release checks confirm it matches package.json and the packed package.
 
 ```ts
-ENGINE_API_VERSION = "2.15.0" as const
+ENGINE_API_VERSION = "2.17.0" as const
 ```

package/docs/api/equipment-generic-lens-catalogue.md

@@ -0,0 +1,281 @@
+# equipment/generic-lens-catalogue.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## GENERIC_LENS_CATALOGUE
+
+The 30 lenses: 17 professional, then 13 consumer, each set by focal length.
+
+```ts
+GENERIC_LENS_CATALOGUE: readonly GenericLensCatalogueEntry[] = Object.freeze([...PRO.map((row) => entry("professional", row)),
+  ...CONSUMER.map((row) => entry("consumer", row))])
+```
+
+## GENERIC_LENS_IDS
+
+The catalogue ids, in catalogue order.
+
+```ts
+GENERIC_LENS_IDS: readonly string[] = Object.freeze(GENERIC_LENS_CATALOGUE.map((lens) => lens.lensId))
+```
+
+## GENERIC_LENS_SET_BASELINES
+
+The set baselines (owner's table, #549), each lens's starting point before its adjustments.
+
+```ts
+GENERIC_LENS_SET_BASELINES: Readonly<Record<GenericLensSet, Readonly<GenericLensCharacterValues>>> = Object.freeze({
+  professional: Object.freeze({ sphericalWaves: 0.25, comaWaves: 0.35, astigmatismWaves: 0.3, fieldCurvatureWaves: 0.15, axialColorWaves: 0.15,
+    lateralColorFraction: 0.00008, distortionMagnitude: 0.01, naturalVignettingStops: 0.4, opticalVignettingStops: 0.6, veilingGlareFraction: 0.005, ghostFraction: 0.002,
+    breathingFraction: -0.03, focusScatterDepthOfFocusFraction: 0.1, closeFocusFactor: 0.15 }),
+  consumer: Object.freeze({ sphericalWaves: 0.5, comaWaves: 1.0, astigmatismWaves: 0.8, fieldCurvatureWaves: 0.45, axialColorWaves: 0.4,
+    lateralColorFraction: 0.0003, distortionMagnitude: 0.03, naturalVignettingStops: 0.7, opticalVignettingStops: 1.1, veilingGlareFraction: 0.02, ghostFraction: 0.008,
+    breathingFraction: -0.08, focusScatterDepthOfFocusFraction: 0.3, closeFocusFactor: 0.5 })
+})
+```
+
+## GenericLensAdjustments
+
+Per-lens multipliers of the set baseline (missing: 1). `distortion` is signed and required: −1 barrel, +1 pincushion at the baseline.
+
+```ts
+export type GenericLensAdjustments = { distortion: number } & Partial<Record<"spherical" | "coma" | "astigmatism" | "fieldCurvature" | "axialColor" | "lateralColor" |
+  "vignetting" | "strayLight" | "breathing" | "focusScatter" | "closeFocus", number>>;
+```
+
+## GenericLensCatalogueEntry
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericLensCatalogueEntry {
+  /** Catalogue id, for example "pv-50-1.2-pro". */
+  lensId: string;
+  /** Display name, for example "PV 50 1.2 Pro". */
+  name: string;
+  set: GenericLensSet;
+  kind: GenericLensKind;
+  /** Full-frame-equivalent focal length (36 × 24 mm reference). */
+  equivalentFocalLengthMm: number;
+  widestFNumber: number;
+  narrowestFNumber: number;
+  /** Largest magnification: 0.15 (the generic rule) or 1 for the professional macro. */
+  maximumMagnification: number;
+  projection: LensProjectionModel;
+  /** Fisheyes only: a circular image inside the frame, or one that fills it. */
+  fisheyeImage?: "circular" | "full-frame";
+  adjustments: Readonly<GenericLensAdjustments>;
+  /** Why this lens departs from its set's baseline. */
+  note: string;
+  /**
+   * A short plain-English summary of the lens's character (at most 40 characters, US spelling), written from its adjustments and
+   * `note`, for lists and pickers. It describes only what the catalogue models (bokeh shape is not modeled: the defocus is a disc).
+   */
+  summary: string;
+}
+```
+
+## GenericLensCharacter
+
+A catalogue lens's character resolved for a sensor, an f-number and a focus distance. Aberrations in waves at 550 nm.
+
+```ts
+export interface GenericLensCharacter {
+  fNumber: number;
+  focusDistanceM: number | null;
+  /** Thin-lens magnification at the focus distance (0 at infinity). */
+  magnification: number;
+  /** 1 + c·m/m_max. */
+  closeFocusGain: number;
+  /** Pupil-radius ratio N0/N. */
+  pupilScale: number;
+  /** Resolved Seidel coefficients at the frame corner (H = 1), waves at 550 nm; `balancingDefocusWaves` = −spherical. */
+  aberrations: { sphericalWaves: number; balancingDefocusWaves: number; comaWaves: number; astigmatismWaves: number; fieldCurvatureWaves: number; axialColorWaves: number };
+  /** Lateral colour: F-to-C image-radius difference at the corner, fraction of the half-diagonal and micrometres on this sensor. */
+  lateralColor: { fraction: number; cornerMicrometers: number };
+  /** Radial distortion profile (normalised to the half-diagonal, valid to 1.25 of it, beyond the corner) and its corner value (fraction; negative = barrel). */
+  distortion: { profile: RadialDistortionProfile; corner: number };
+  /** Relative illumination profile (normalised to the half-diagonal, valid to 1.25 of it) and the corner fall-off in stops. */
+  vignetting: { profile: IlluminationVignettingProfile; cornerStops: number };
+  strayLight: { veilingGlareFraction: number; ghostFraction: number };
+  /** Field-of-view change at this focus and at minimum focus, beyond thin-lens unit focusing (fraction, negative = narrower). */
+  breathing: { fieldOfViewChange: number; atMinimumFocus: number };
+  /** Standard deviation of the autofocus error as a fraction of the depth of focus 2·N·c. */
+  focusScatterDepthOfFocusFraction: number;
+}
+```
+
+## GenericLensCharacterValues
+
+The character of a set, at each lens's widest aperture. Aberrations are in waves at 550 nm at the frame corner.
+
+```ts
+export interface GenericLensCharacterValues {
+  /** Spherical aberration W040 (balanced by W020 = −W040): centre sharpness. */
+  sphericalWaves: number;
+  /** Coma W131 at H = 1: the comet-shaped point images of night photography. */
+  comaWaves: number;
+  /** Astigmatism W222 at H = 1: edge and corner sharpness. */
+  astigmatismWaves: number;
+  /** Field curvature W220 at H = 1: edge and corner sharpness. */
+  fieldCurvatureWaves: number;
+  /** Axial colour: the F-to-C difference of the defocus W020, waves at 550 nm. */
+  axialColorWaves: number;
+  /** Lateral colour: the F-to-C difference of the image radius at the corner, as a fraction of the half-diagonal. */
+  lateralColorFraction: number;
+  /** Corner distortion magnitude |k1| (fraction); each lens gives the sign (barrel −, pincushion +). */
+  distortionMagnitude: number;
+  /** Corner fall-off in stops that stays when stopped down (natural vignetting). */
+  naturalVignettingStops: number;
+  /** Extra corner fall-off in stops at the widest aperture (optical vignetting); gone two stops down. */
+  opticalVignettingStops: number;
+  /** Veiling glare: the fraction of the image's mean irradiance spread as a uniform veil. */
+  veilingGlareFraction: number;
+  /** Peak ghost power as a fraction of a bright source's power on the axis. */
+  ghostFraction: number;
+  /** Field-of-view change between infinity and minimum focus as a fraction (negative: narrower), beyond thin-lens unit focusing. */
+  breathingFraction: number;
+  /** Standard deviation of the autofocus error as a fraction of the depth of focus 2·N·c. */
+  focusScatterDepthOfFocusFraction: number;
+  /** c in the close-focus factor 1 + c·m/m_max. */
+  closeFocusFactor: number;
+}
+```
+
+## GenericLensFocusError
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericLensFocusError {
+  lensId: string;
+  /** The intended and the sampled focus distance, m (the sampled one held within minimum focus and a far limit). */
+  intendedFocusDistanceM: number;
+  focusDistanceM: number;
+  /** The standard normal draw z and the image-side focus error z·σ·2Nc, µm (positive: a longer image distance, so focused nearer). */
+  standardNormal: number;
+  imageSideErrorMicrometers: number;
+  /** σ (fraction of the depth of focus) and the depth of focus 2·N·c, µm. */
+  depthOfFocusFraction: number;
+  depthOfFocusMicrometers: number;
+  /** True when the sampled image distance was held at the minimum-focus or the far (1000 m) limit. */
+  held: "minimum-focus" | "far-limit" | null;
+  scientificStatus: "approximation";
+}
+```
+
+## GenericLensKind
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type GenericLensKind = "standard" | "macro" | "fisheye";
+```
+
+## GenericLensSet
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type GenericLensSet = "professional" | "consumer";
+```
+
+## ResolvedGenericLens
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedGenericLens {
+  lensId: string;
+  name: string;
+  set: GenericLensSet;
+  kind: GenericLensKind;
+  equivalentFocalLengthMm: number;
+  /** Physical focal length on this sensor: equivalent ÷ crop factor. */
+  focalLengthMm: number;
+  cropFactor35Mm: number;
+  /** Half-diagonal of the sensor, mm: field height H = 1 and ρ = 1 of the profiles. */
+  halfDiagonalMm: number;
+  widestFNumber: number;
+  narrowestFNumber: number;
+  /** Marked third-stop f-numbers within the range. */
+  fNumbers: readonly number[];
+  /** max(0.10 m, f·(1 + 1/m_max)), metres from the lens (thin lens). */
+  minimumFocusDistanceM: number;
+  maximumMagnification: number;
+  projection: LensProjectionModel;
+  fisheyeImage: "circular" | "full-frame" | null;
+  /** Fisheyes: the radius of the 180° image circle on this sensor, 2·f·sin 45° (equisolid), mm. Null otherwise. */
+  imageCircleRadiusMm: number | null;
+  character: GenericLensCharacter;
+  note: string;
+  /** The catalogue entry's `summary`: a short plain-English description of the lens's character (at most 40 characters). */
+  summary: string;
+  evidence: readonly EvidenceProvenance[];
+  scientificStatus: "approximation";
+  limitations: readonly string[];
+}
+```
+
+## resolveGenericLens
+
+Resolves a catalogue lens for a sensor: its focal length (equivalent ÷ the diagonal crop factor), f-number range, close focus
+and projection, and its character (aberrations, colour, distortion, vignetting, flare, breathing and focus scatter) at the
+given f-number and focus distance. Every value is a labelled approximation of a generic lens, not a measured product.
+
+```ts
+export function resolveGenericLens(input: ResolveGenericLensInput): ResolvedGenericLens;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveGenericLensInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveGenericLensInput {
+  /** A catalogue id (`GENERIC_LENS_IDS`). */
+  lensId: string;
+  /** The sensor's active capture area, mm. */
+  activeImagingArea: { widthMm: number; heightMm: number };
+  /** Default: the widest aperture. Must lie in the lens's range. */
+  fNumber?: number;
+  /** Default: infinity. At least the minimum focus distance. */
+  focusDistanceM?: number;
+}
+```
+
+## simulateGenericLensFocusError
+
+Focus consistency (#549): a seeded, reproducible autofocus error for one shot. The image-side error is z·σ·2Nc, with z a
+standard normal draw from (seed, shotIndex) (MurmurHash3 stream seed, xorshift32 and Box–Muller, the generators of the
+capture's sensor noise), σ the lens's focus scatter as a fraction of the depth of focus 2·N·c, and
+c the circle of confusion. The thin-lens image distance of the intended focus moves by that error and the focus distance is
+read back from it. An approximation of autofocus variation; off unless called (or `simulateCapture`'s `lens.focusScatter`).
+
+```ts
+export function simulateGenericLensFocusError(input: SimulateGenericLensFocusErrorInput): GenericLensFocusError;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SimulateGenericLensFocusErrorInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SimulateGenericLensFocusErrorInput {
+  lensId: string;
+  activeImagingArea: { widthMm: number; heightMm: number };
+  fNumber: number;
+  /** The intended focus distance, m. */
+  focusDistanceM: number;
+  /** uint32 seed of the shooting session. */
+  seed: number;
+  /** uint32 index of the shot in the session. Default 0. */
+  shotIndex?: number;
+  /** Circle of confusion for the depth of focus, mm. Default: the sensor diagonal / 1500. */
+  circleOfConfusionMm?: number;
+}
+```