@photivra/engine 2.11.1 → 2.12.0

package/CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
-## 2.11.1 — unreleased (prepared October 31, 2026)
+## 2.12.0 — unreleased (prepared October 31, 2026)
+
+A minor release for the app's Beta camera: Auto ISO through the one-call API, and the deviation from the standard exposure for an exposure meter. With `iso` absent or a number, samples, RAW codes and files are the same as 2.11.1; the exposure result gains `isoControl` and `standardExposureDeviationStops`.
+- **New:** `exposure.iso: "auto"` in every exposure mode, with `exposure.autoIso` in aperture priority and an Auto ISO report in the result (#516, #518); `exposure.standardExposureDeviationStops` (#515, #517).
+- **Compatibility:** two new root type exports (1,767), none removed; `exposure.iso` widens to `number | "auto"`; new result fields only.
+
+### Added
+
+- **`simulateCapture` and the display view: Auto ISO in every exposure mode (#516).** `exposure.iso: "auto"` hands the ISO to the existing exposure-mode resolvers' Auto ISO branches, within the body's Auto ISO range, in `manual`, `aperture-priority`, `shutter-priority` and `program`; the default stays ISO 100. With `iso` absent or a number nothing changes: every hash lock holds, and the only result change is the new `exposure.isoControl: "manual"`.
+  - **Per mode:** manual keeps the aperture and shutter (`resolveManualExposureMode`, automatic ISO); aperture priority uses `resolveAperturePriorityAutoIsoExposureMode` with the new `exposure.autoIso: { slowestPreferredShutterSeconds, afterMaximumIso? }` (the slowest preferred shutter is required, within the body's shutter range; `afterMaximumIso` is `"allow-slower-shutter"`, the default, or `"hold-preferred-shutter"`); shutter priority uses the `minimum-iso-aperture-first` policy; program uses the program line at the lowest ISO and raises the ISO beyond the line's end. Every policy starts at the lowest selectable Auto ISO and snaps to the nearest selectable ISO in stops (the lower on a tie). The automatic slowest shutter (#504) and photographer-set limits (#505) are not part of this change.
+  - **Result:** `exposure.settings.iso` is the ISO used; `exposure.isoControl` is `"automatic"`; `exposure.autoIso` (`SimulateCaptureAutoIsoReport`) gives `idealIsoBeforeConstraints`, `autoIsoMinimum`, `autoIsoMaximum`, `clamped`, the resolver's `limitingConstraint` (for example `"iso-maximum"`) and `residualStops`, and in aperture priority the policy, the slowest preferred shutter and `afterMaximumIsoFallbackUsed`. The display view (`simulateDisplayView`, `prepareDisplayView`) and the ideal reference report the same fields; a new `exposure.autoIso` assumption records the policy.
+  - **Validation:** a string other than `"auto"`, `exposure.autoIso` outside aperture priority with Auto ISO, a missing, non-finite or out-of-range slowest preferred shutter, an unknown `afterMaximumIso` or key, and a body without Auto ISO fail with `InvalidConfigurationError`.
+  - **Tests** (`test/simulate-capture-auto-iso.test.ts`): each mode with `"auto"` (the default scene at f/8, 1/125 s gives ISO 100; three stops darker gives ISO 800, byte-identical to a manual ISO 800 capture in manual and aperture priority; compensation; the minimum and maximum with their limiting constraints; both `afterMaximumIso` policies; shutter priority past the widest aperture; program past the line's end); a capture, its display view (direct and prepared), its ideal reference and its region parts give the same exposure and report, and the parts stitch to the capture's bytes; fourteen invalid options fail with a domain error in the capture and the prepared view.
+  - New root exports: the types `SimulateCaptureAutoIsoAfterMaximum` and `SimulateCaptureAutoIsoReport` (1,767). `SimulateCaptureOptions.exposure.iso` widens to `number | "auto"` and gains `autoIso`; the capture, display-view and ideal-reference `exposure` gain `isoControl` and the optional `autoIso`. Docs: `docs/QUICK_START.md` ("Inputs and defaults", "Auto ISO") and `docs/USAGE.md`.
+- **The deviation from the standard exposure, in stops (#515, for Photivra/apps#124).** `simulateCapture`'s and the display view's `exposure` gain `standardExposureDeviationStops`: Δ = log₂(N²/t) − log₂(0.65·L·S/10), from the CIPA DC-004-2020 relations the facade already meters with (S = 10/H, §3.2; H = 0.65·L·t/N², §5.5 (4)), with the settings used and `meteredSceneLuminanceCdPerSquareMeter`; no new metering. Positive is darker than the standard exposure (under), negative brighter (over); in an automatic mode it is minus the compensation plus any step or limit the resolver hit. It is `null` when the metered luminance is 0 (a black scene, which manual mode captures), never infinite. No other result, sample or RAW code changes; every hash lock holds.
+  - Tests: `test/exposure-deviation.test.ts`: 0 with the defaults (|Δ| ≈ 1.2 × 10⁻⁵ from the metering quadrature), +0.919 at f/11, +1.000 at f/8√2, −1.059 at 1/60 s, −1.000 at ISO 200, −⅔ in aperture priority with +⅔ stop, the 30 s limit at 0.01 lux (+9.16), the display view's value equal to the capture's, and `null` for a black scene.
+
+## 2.11.1 — published October 31, 2026
 
 A patch release that publishes 2.11.0's engine to npm. The owner tagged `v2.11.0` on `6bef763` and published its GitHub release on October 28, 2026, but its npm publish run (40636849817) was cancelled at the verify job's 25-minute limit while the single-job coverage gate was still running, so `@photivra/engine@2.11.0` was never published; npm `latest` is 2.10.0. A published tag runs the publish workflow of its own commit, so 2.11.0 cannot be published again; 2.11.1 carries the fixed workflow.
 - **No API, behaviour or value change from 2.11.0:** `src/` differs only in `ENGINE_API_VERSION`; the packed files differ only in the version fields and the release documentation (docs/RELEASE_2_11_1.md, "Same package").

package/CITATION.cff

@@ -9,7 +9,7 @@ abstract: "An open TypeScript engine for the science and mathematics of photogra
 repository-code: "https://github.com/photivra/photivra"
 url: "https://photivra.com"
 license: "Apache-2.0"
-version: "2.11.1"
+version: "2.12.0"
 keywords:
   - photography
   - camera optics

package/NODE_SUPPORT.md

@@ -90,11 +90,9 @@ For **7 days** from a line's LTS start, the guard therefore accepts a build of t
 - Other majors, prereleases and end-of-life dates are checked as before.
 - A build that carries the LTS marker passes as before.
 
-### Early warning
+### Checking ahead
 
-`.github/workflows/node-lts-lookahead.yml` runs daily and on manual dispatch. It does not run on pull requests and is not a required check. It fetches `https://nodejs.org/dist/index.json`, takes the newest stable release of each supported major, and runs the policy guard against it at 00:00 UTC on today and each of the next 14 days (`.github/node-lts-lookahead.mjs`). If any date fails, the job fails and names the major, the first failing date, the build and the reason. That leaves two weeks to act before the required checks fail.
-
-The warning is expected once a year: from 7 days before a line's LTS start until Node publishes its first LTS build, it reports the end of the grace period. It clears by itself when the LTS build appears. If it stays red near the end of the grace period, review the snapshot against the official schedule. Do not widen a window just to clear it. An end of life inside the next 14 days fails it the same way.
+No scheduled job checks the policy ahead of time; the guard in every CI job is the check, so a date boundary first shows as a failing required check on the first run after it. To see a boundary coming, for example before a release, run `node .github/node-lts-lookahead.mjs`. It fetches `https://nodejs.org/dist/index.json`, takes the newest stable release of each supported major, and runs the policy guard against it at 00:00 UTC on today and each of the next 14 days. A failing date names the major, the first failing date, the build and the reason. Do not widen a window just to clear it.
 
 Routine minor and patch updates within an approved major may follow normal green-PR rules. Do not auto-merge a major upgrade of the Node runtime, a Node image, or `@types/node` on its own. Where Dependabot is configured, keep Node typings major upgrades out of its routine queue, while still allowing updates within supported majors.
 

package/README.md

@@ -32,10 +32,10 @@ The source is licensed under Apache-2.0.
 
 ## Quick start
 
-Install the published ESM package below. The [2.11.1 release record](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_2_11_1.md), the [2.11.0 release record](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_2_11_0.md) and [changelog](https://github.com/Photivra/photivra/blob/main/CHANGELOG.md) describe the current release:
+Install the published ESM package below. The [2.12.0 release record](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_2_12_0.md) and [changelog](https://github.com/Photivra/photivra/blob/main/CHANGELOG.md) describe the current release:
 
 ```sh
-npm install @photivra/engine@2.11.1
+npm install @photivra/engine@2.12.0
 ```
 
 Simulate a photograph of a test chart with a generic camera, then read the developed sRGB pixels:
@@ -75,7 +75,7 @@ console.log(horizontal.provenance);
 
 Start with the [Developer Guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Then use the [Usage Guide](https://github.com/Photivra/photivra/blob/main/docs/USAGE.md) and the [API reference](https://github.com/Photivra/photivra/blob/main/docs/API_REFERENCE.md), which is generated from the package exports.
 
-Repository `main` may describe newer, unreleased work. For the stable contract, use the docs bundled in the published package, or the exact `v2.11.1` tag.
+Repository `main` may describe newer, unreleased work. For the stable contract, use the docs bundled in the published package, or the exact `v2.12.0` tag.
 
 ## Documentation
 
@@ -363,13 +363,13 @@ The application can then use those results, while the photography calculations t
 
 ## Status
 
-- Repository package version: `2.11.1` (release candidate prepared October 31, 2026; publication is separate)
-- Engine API contract: `2.11.1`
+- Repository package version: `2.12.0` (release candidate prepared October 31, 2026; publication is separate)
+- Engine API contract: `2.12.0`
 - Versioned generic tier reference assets: [GENERIC_TIER_PRESETS.md](https://github.com/Photivra/photivra/blob/main/docs/GENERIC_TIER_PRESETS.md).
 - Composed POC simulation API contract: `1.0.0`
 - Stability: 1.0 root-package compatibility policy; bounded scientific models and independent POC contract
 
-From 1.0.1, the package version and `ENGINE_API_VERSION` are equal. New captures/plans record 2.11.1; existing archives keep their original creator identities. Schema, model and POC contract versions stay independent.
+From 1.0.1, the package version and `ENGINE_API_VERSION` are equal. New captures/plans record 2.12.0; existing archives keep their original creator identities. Schema, model and POC contract versions stay independent.
 
 A breaking change to the root contracts now needs a new package major version. Additive and corrective changes follow [compatibility and migration](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_1_3_0.md). A 1.0 package is not a claim of calibrated physical accuracy.
 

package/SECURITY.md

@@ -4,7 +4,7 @@ Please do not open a public issue that contains vulnerability details.
 
 ## Supported versions
 
-The published 1.0.0 release started the 1.x root-package compatibility line, and 2.0.0 started the 2.x line. The current release is **2.10.0**, published on October 27, 2026 (see [CHANGELOG.md](CHANGELOG.md)).
+The published 1.0.0 release started the 1.x root-package compatibility line, and 2.0.0 started the 2.x line. The current release is **2.11.1**, published on October 31, 2026 (see [CHANGELOG.md](CHANGELOG.md)).
 
 Security fixes target the current maintained development and release line. Do not assume that older 1.x releases, snapshots or pre-1.0 releases will receive fixes.
 

package/dist/core/version.d.ts

@@ -6,4 +6,4 @@
  * own versions. Release checks confirm it matches package.json and the packed package.
  * @see docs/RELEASE_1_0_1.md
  */
-export declare const ENGINE_API_VERSION: "2.11.1";
+export declare const ENGINE_API_VERSION: "2.12.0";

package/dist/core/version.js

@@ -7,5 +7,5 @@
  * own versions. Release checks confirm it matches package.json and the packed package.
  * @see docs/RELEASE_1_0_1.md
  */
-export const ENGINE_API_VERSION = "2.11.1";
+export const ENGINE_API_VERSION = "2.12.0";
 //# sourceMappingURL=version.js.map

package/dist/core/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/core/version.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,QAAiB,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Version of the engine release. Since 1.0.1 it equals the npm package version.\n *\n * New captures and plans record this version as their creator. Archived records keep the\n * version they were made with. Proof-of-concept (POC), schema and model contracts have their\n * own versions. Release checks confirm it matches package.json and the packed package.\n * @see docs/RELEASE_1_0_1.md\n */\nexport const ENGINE_API_VERSION = \"2.11.1\" as const;\n"]}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/core/version.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,QAAiB,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Version of the engine release. Since 1.0.1 it equals the npm package version.\n *\n * New captures and plans record this version as their creator. Archived records keep the\n * version they were made with. Proof-of-concept (POC), schema and model contracts have their\n * own versions. Release checks confirm it matches package.json and the packed package.\n * @see docs/RELEASE_1_0_1.md\n */\nexport const ENGINE_API_VERSION = \"2.12.0\" as const;\n"]}

package/dist/facade/simulate-capture.d.ts

@@ -1,5 +1,6 @@
 import type { EvidenceProvenance } from "../core/evidence-provenance.js";
 import { type GenericEquipmentTier, type GenericEquipmentTierPreset } from "../equipment/generic-tier-assets.js";
+import { type ExposureResolutionConstraint } from "../exposure/exposure-mode-resolver.js";
 import { resolveColorTemperatureWhiteBalance, type ResolvedWhiteBalanceState } from "../color/white-balance.js";
 import { type CaptureWhiteBalanceIntent } from "../capture/simulated-capture.js";
 import { type NativeRawOutput, type NativeRawPlan } from "../capture/native-raw.js";
@@ -27,6 +28,37 @@ import { type ChartSizeOption, type CaptureIlluminant, type CallerMaterialScene,
 /** Version of how the facade builds requests. It changes whenever the same input would build a different request. */
 export declare const SIMULATE_CAPTURE_FACADE_VERSION: "1.0.0";
 export type SimulateCaptureExposureMode = "manual" | "aperture-priority" | "shutter-priority" | "program";
+/**
+ * #516: what aperture priority does with Auto ISO once the ISO reaches the body's Auto ISO maximum and the exposure is
+ * still under the meter target: `"allow-slower-shutter"` lengthens the shutter past the slowest preferred shutter to reach
+ * the target; `"hold-preferred-shutter"` keeps the preferred shutter and leaves the exposure under target.
+ */
+export type SimulateCaptureAutoIsoAfterMaximum = "allow-slower-shutter" | "hold-preferred-shutter";
+/**
+ * #516: how Auto ISO chose the ISO (`exposure.iso: "auto"`), reported in the result's `exposure.autoIso`. The full
+ * resolver output stays in the capture's `exposure.resolution`.
+ */
+export interface SimulateCaptureAutoIsoReport {
+    /** The ISO the meter target asked for at the resolved aperture and shutter, before the Auto ISO range and the ISO grid. */
+    idealIsoBeforeConstraints: number;
+    /** The Auto ISO range the ISO was chosen in: the body's Auto ISO bounds, or its ISO range when it declares none (the tiers: ISO 100 to their maximum). */
+    autoIsoMinimum: number;
+    autoIsoMaximum: number;
+    /** Whether the ISO was held at an end of the Auto ISO range. */
+    clamped: false | "minimum" | "maximum";
+    /**
+     * The constraint that limited the resolved exposure: the resolver's `targetResidual.limitingConstraint`, for example
+     * `"iso-maximum"` (the exposure stays under target at the Auto ISO maximum), `"iso-grid-quantization"` (the nearest
+     * selectable ISO) or `"none"` (on target).
+     */
+    limitingConstraint: ExposureResolutionConstraint;
+    /** The resolver's residual, log2(target / achieved exposure), in stops: positive when the exposure is under the meter target, negative when over it. */
+    residualStops: number;
+    /** Aperture priority only: the policy and slowest preferred shutter used, and whether the slower-shutter fallback ran. */
+    afterMaximumIso?: SimulateCaptureAutoIsoAfterMaximum;
+    slowestPreferredShutterSeconds?: number;
+    afterMaximumIsoFallbackUsed?: boolean;
+}
 export type SimulateCaptureOutputFormat = "srgb-8" | "srgb-16" | "jpeg" | "png" | "dng";
 export type SimulateCaptureWhiteBalance = "scene-illuminant" | "auto" | "none" | {
     kelvin: number;
@@ -191,8 +223,24 @@ export interface SimulateCaptureOptions {
     exposure?: {
         /** Default "manual". */
         mode?: SimulateCaptureExposureMode;
-        /** Default 100. */
-        iso?: number;
+        /**
+         * Default 100. #516: `"auto"` lets the body's Auto ISO choose the ISO from the meter target, within its Auto ISO range
+         * (the tiers: ISO 100 to their maximum), in every mode: manual keeps the aperture and shutter; aperture priority keeps the
+         * aperture and follows `autoIso`; shutter priority picks the aperture at the lowest Auto ISO (no wider than the target
+         * needs, so at most the widest) and raises the ISO for the rest; program picks the program line at the lowest Auto ISO and
+         * raises the ISO beyond the line's end. The result reports the ISO in `exposure.settings.iso` and how it was chosen in
+         * `exposure.autoIso`.
+         */
+        iso?: number | "auto";
+        /**
+         * #516: aperture priority with `iso: "auto"` only (required there). The shutter gets as long as
+         * `slowestPreferredShutterSeconds` (seconds, within the body's shutter range) at the lowest Auto ISO; beyond it the ISO
+         * rises; at the Auto ISO maximum `afterMaximumIso` decides (default `"allow-slower-shutter"`).
+         */
+        autoIso?: {
+            slowestPreferredShutterSeconds: number;
+            afterMaximumIso?: SimulateCaptureAutoIsoAfterMaximum;
+        };
         /** Shutter for manual and shutter-priority modes. Default 1/125 s. */
         shutterSeconds?: number;
         /** Exposure compensation applied to the meter target, in stops. Default 0. */
@@ -430,7 +478,18 @@ export interface SimulateCaptureResult {
         };
         /** Exposure value at ISO 100 of the settings, log2(N²/t). */
         ev100: number;
+        /** #516: `"automatic"` when the request asked for `iso: "auto"`, else `"manual"`. */
+        isoControl: "manual" | "automatic";
+        /** #516: present with `iso: "auto"`: how Auto ISO chose `settings.iso` and what limited it. */
+        autoIso?: SimulateCaptureAutoIsoReport;
         meteredSceneLuminanceCdPerSquareMeter: number;
+        /**
+         * #515: deviation, in stops, of the exposure used from the CIPA DC-004-2020 standard exposure for the metered luminance L:
+         * log2(N²/t) − log2(0.65·L·S/10). Positive is darker than the standard exposure (under), negative brighter (over). In an
+         * automatic mode it is the compensation with the opposite sign plus any step or limit the resolver hit. Finite, or null when
+         * the metered luminance is 0 (a black scene has no standard exposure).
+         */
+        standardExposureDeviationStops: number | null;
         /** Full output of the existing exposure-mode resolver. */
         resolution: unknown;
     };
@@ -619,6 +678,9 @@ export interface IdealReferenceResult {
             iso: number;
         };
         ev100: number;
+        /** #516: as in the capture result. */
+        isoControl: "manual" | "automatic";
+        autoIso?: SimulateCaptureAutoIsoReport;
     };
     scene: SimulateCaptureResult["scene"];
     region?: {
@@ -699,7 +761,7 @@ export interface DisplayViewResult {
             height: number;
         };
     };
-    /** The resolved exposure of the capture this view shows. */
+    /** The resolved exposure of the capture this view shows; `standardExposureDeviationStops` as in {@link SimulateCaptureResult}. */
     exposure: {
         mode: SimulateCaptureExposureMode;
         settings: {
@@ -708,6 +770,10 @@ export interface DisplayViewResult {
             iso: number;
         };
         ev100: number;
+        standardExposureDeviationStops: number | null;
+        /** #516: as in the capture result. */
+        isoControl: "manual" | "automatic";
+        autoIso?: SimulateCaptureAutoIsoReport;
     };
     scene: SimulateCaptureResult["scene"];
     /**
@@ -809,6 +875,13 @@ export interface DisplayViewRunContext {
         regimeId: string;
     }>;
     resolvedIso: number;
+    /** #516: how the ISO was chosen, reported in the view's `exposure`. */
+    isoReport: {
+        isoControl: "manual" | "automatic";
+        autoIso?: SimulateCaptureAutoIsoReport;
+    };
+    /** #515: the capture's `exposure.standardExposureDeviationStops`. */
+    standardExposureDeviationStops: number | null;
     sceneOption: unknown;
     scenePreset: "composite" | "uniform" | "patches" | "slanted-edge" | "siemens-star" | "step-wedge" | "grey-ramp" | "checkerboard" | "point-grid" | "dead-leaves" | "bar-groups" | "hyperbolic-wedge" | "zone-plate" | "slanted-squares" | "line-grid" | "fiducial" | "reflectance-function" | "radiance-function" | "material-function";
     shutterSeconds: number;

package/dist/facade/simulate-capture.js

@@ -30,6 +30,7 @@
  */
 import { markInternalNativeTileReader, markInternalSceneRadianceEvaluator, registerInternalRadianceAccess } from "../core/internal-radiance-evaluator.js";
 import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { InvalidScientificResultError } from "../core/validation.js";
 import { requireInputObject } from "../core/record-validation.js";
 import { ENGINE_API_VERSION } from "../core/version.js";
 import { GENERIC_TIER_ASSETS } from "../equipment/generic-tier-assets.js";
@@ -39,7 +40,7 @@ import { resolveGenericEquipmentExposureCapabilities } from "../equipment/exposu
 import { resolveGenericIsoSignalChain } from "../sensor/iso-signal-chain.js";
 import { meterRelativeExposure } from "../exposure/metering.js";
 import { createExposureMeterTargetFromMeteringResult, setExposureCompensationOnMeterTarget } from "../exposure/metering-target.js";
-import { resolveManualExposureMode, resolveAperturePriorityExposureMode, resolveShutterPriorityExposureMode, resolveProgramAutoExposureMode } from "../exposure/exposure-mode-resolver.js";
+import { resolveManualExposureMode, resolveAperturePriorityExposureMode, resolveAperturePriorityAutoIsoExposureMode, resolveShutterPriorityExposureMode, resolveProgramAutoExposureMode } from "../exposure/exposure-mode-resolver.js";
 import { parseExposureProgramLineProfile } from "../exposure/program-line.js";
 import { resolveCaptureGeometry } from "../output/capture-geometry.js";
 import { estimateCie1931ColorMatchingFunctions } from "../color/color-matching-functions.js";
@@ -121,6 +122,21 @@ const GREY_CARD_REFLECTANCE = 0.18;
 function sosReferenceLuminance(fNumber, shutterSeconds, iso) {
     return SOS_REFERENCE_EXPOSURE_NUMERATOR_LUX_SECONDS * fNumber ** 2 / (CAMERA_EQUATION_CONSTANT * shutterSeconds * iso);
 }
+/**
+ * #515: deviation, in stops, of the exposure the settings give from the CIPA DC-004-2020 standard exposure for the metered
+ * luminance L: Δ = log2(N²/t) − log2(0.65·L·S/10) = log2(L_ref(N, t, S) / L), with L_ref the luminance that the settings
+ * expose at H = 10/S (S = 10/H, §3.2; H = 0.65·L·t/N², §5.5 (4)). Positive is darker than the standard exposure (under).
+ * A scene with no metered luminance (L = 0, which manual mode still captures) has no standard exposure: null, never ±Infinity.
+ */
+function standardExposureDeviationStops(fNumber, shutterSeconds, iso, meteredLuminance) {
+    if (!(meteredLuminance > 0))
+        return null;
+    const deviation = Math.log2(sosReferenceLuminance(fNumber, shutterSeconds, iso) / meteredLuminance);
+    if (!Number.isFinite(deviation))
+        throw new InvalidScientificResultError("exposure.standardExposureDeviationStops is not finite (metered scene luminance " +
+            meteredLuminance + " cd/m²).");
+    return deviation;
+}
 /**
  * Default illuminance, lux: an 18 % Lambertian grey card (L = 0.18·E/π) then gets exactly the CIPA DC-004 standard
  * output sensitivity reference exposure H = 10/S at f/8, 1/125 s, ISO 100:
@@ -392,6 +408,21 @@ export function bilinearPhaseProfiles() {
             kernels: CHANNELS.map((c) => ({ outputChannelId: c, contributions: kernels[px + "," + py][c] })), evidence: FACADE_EVIDENCE,
             limitations: ["Bilinear interpolation of the RGGB mosaic; no edge-directed demosaic, false-colour suppression or calibration."] } }));
 }
+/**
+ * #516: the result's Auto ISO report, read from a resolved Auto ISO resolution (every mode's resolved Auto ISO branch carries
+ * `idealIsoBeforeConstraints`, `isoResolution` and a resolved `targetResidual`; aperture priority adds its fallback flag).
+ */
+function autoIsoReport(resolution, iso, aperturePriority) {
+    const r = resolution;
+    const ideal = r.idealIsoBeforeConstraints, residual = r.targetResidual?.residualStops, clamped = r.isoResolution?.clamped;
+    if (typeof ideal !== "number" || !Number.isFinite(ideal) || typeof residual !== "number" || !Number.isFinite(residual) || r.targetResidual?.status !== "resolved" ||
+        (clamped !== false && clamped !== "minimum" && clamped !== "maximum"))
+        throw new InvalidScientificResultError("Auto ISO resolution did not report a finite ideal ISO and residual.");
+    // The resolvers' Auto ISO range: the body's Auto ISO bounds, else its ISO range.
+    return { idealIsoBeforeConstraints: ideal, autoIsoMinimum: iso.autoIsoMinimum ?? iso.minimum, autoIsoMaximum: iso.autoIsoMaximum ?? iso.maximum, clamped,
+        limitingConstraint: r.targetResidual.limitingConstraint, residualStops: residual,
+        ...(aperturePriority ? { ...aperturePriority, afterMaximumIsoFallbackUsed: r.afterMaximumIsoFallbackUsed === true } : {}) };
+}
 function defaultProgramLine() {
     // Generic educational program line written for the engine, relative to the f/8, 1/125 s reference. For less light
     // it first opens the aperture toward f/4, then lengthens the shutter. For more light it first closes toward
@@ -1186,11 +1217,18 @@ export async function runCapture(options, run, viewOption, renderView) {
         registerInternalRadianceAccess(provider.evaluateRadiance, { keyOfDirection: materialOfDirection, radianceOfKey: provider.materialRadiance, tabulated: true });
     assume("model.scene-radiometry", "model", "lambertian-plane", "Radiance = reflectance × irradiance / π on one plane; illuminance from K_m = 683 lm/W and the engine's analytic CIE 1931 ȳ fit.");
     // Metering (CIPA DC-004 standard output sensitivity and camera equation) and exposure-mode resolution
-    const exposureOptions = allowKeys(top.exposure, "exposure", ["mode", "iso", "shutterSeconds", "compensationStops"]);
+    const exposureOptions = allowKeys(top.exposure, "exposure", ["mode", "iso", "shutterSeconds", "compensationStops", "autoIso"]);
     const mode = pick(exposureOptions, "mode", "exposure.mode", "manual", "Manual exposure.");
     if (!["manual", "aperture-priority", "shutter-priority", "program"].includes(mode))
         fail("Unknown exposure mode.");
-    const iso = positive(pick(exposureOptions, "iso", "exposure.iso", DEFAULTS.iso, "ISO 100, the tiers' base ISO."), "exposure.iso");
+    const isoOption = pick(exposureOptions, "iso", "exposure.iso", DEFAULTS.iso, "ISO 100, the tiers' base ISO.");
+    // #516: "auto" resolves the ISO with the mode's Auto ISO resolver; NaN marks the ISO as not yet known.
+    const automaticIso = isoOption === "auto";
+    if (typeof isoOption === "string" && !automaticIso)
+        fail('exposure.iso must be a positive finite number or "auto".');
+    const iso = automaticIso ? NaN : positive(isoOption, "exposure.iso");
+    if (exposureOptions.autoIso !== undefined && !(automaticIso && mode === "aperture-priority"))
+        fail('exposure.autoIso applies only to exposure.mode "aperture-priority" with exposure.iso "auto"; omit it.');
     const compensation = exposureOptions.compensationStops === undefined ? DEFAULTS.compensationStops : exposureOptions.compensationStops;
     if (typeof compensation !== "number" || !Number.isFinite(compensation) || Math.abs(compensation) > 10)
         fail("exposure.compensationStops must be within ±10.");
@@ -1238,9 +1276,34 @@ export async function runCapture(options, run, viewOption, renderView) {
             fail("exposure.shutterSeconds is resolved automatically in " + mode + " mode; omit it.");
         shutterSeconds = NaN;
     }
+    // #516: the resolvers' Auto ISO policies; their baseline is the lowest selectable ISO in the body's Auto ISO range.
+    const autoIsoBaseline = { isoBaseline: "minimum-selectable", isoQuantizationPolicy: "nearest-log2-lower-on-tie" };
+    let autoIsoAperturePriority;
+    if (automaticIso) {
+        if (capabilities.iso.autoIsoAvailability !== "supported")
+            fail('exposure.iso "auto" needs a body with Auto ISO; this camera\'s Auto ISO is ' + capabilities.iso.autoIsoAvailability + ".");
+        assume("exposure.autoIso", "model", { minimum: capabilities.iso.autoIsoMinimum ?? capabilities.iso.minimum, maximum: capabilities.iso.autoIsoMaximum ?? capabilities.iso.maximum, ...autoIsoBaseline }, "Auto ISO: the engine's exposure-mode resolver chooses the ISO from the meter target, starting from the lowest selectable ISO in the body's Auto ISO range and " +
+            "snapping to the nearest selectable ISO in log2 (the lower on a tie), held at the range's ends. A generic policy, not a manufacturer's Auto ISO.");
+    }
+    if (automaticIso && mode === "aperture-priority") {
+        const autoIsoOptions = allowKeys(exposureOptions.autoIso, "exposure.autoIso", ["slowestPreferredShutterSeconds", "afterMaximumIso"]);
+        if (autoIsoOptions.slowestPreferredShutterSeconds === undefined)
+            fail('exposure.autoIso.slowestPreferredShutterSeconds is required with exposure.mode "aperture-priority" and exposure.iso "auto": the slowest shutter, in seconds, before Auto ISO raises the ISO.');
+        const slowestPreferredShutterSeconds = positive(autoIsoOptions.slowestPreferredShutterSeconds, "exposure.autoIso.slowestPreferredShutterSeconds");
+        if (slowestPreferredShutterSeconds < capabilities.shutter.minimumSeconds || slowestPreferredShutterSeconds > capabilities.shutter.maximumSeconds)
+            fail("exposure.autoIso.slowestPreferredShutterSeconds must be within the body's shutter range, " + capabilities.shutter.minimumSeconds + " s to " + capabilities.shutter.maximumSeconds + " s.");
+        const afterMaximumIso = pick(autoIsoOptions, "afterMaximumIso", "exposure.autoIso.afterMaximumIso", "allow-slower-shutter", "At the Auto ISO maximum, the shutter may get slower than the slowest preferred shutter to reach the meter target.");
+        if (afterMaximumIso !== "allow-slower-shutter" && afterMaximumIso !== "hold-preferred-shutter")
+            fail('exposure.autoIso.afterMaximumIso must be "allow-slower-shutter" or "hold-preferred-shutter".');
+        autoIsoAperturePriority = { slowestPreferredShutterSeconds, afterMaximumIso };
+    }
     if (mode === "manual") {
         resolution = resolveManualExposureMode({ target, capabilities, referenceExposure: reference, manualAperture: fNumber, manualShutterSeconds: shutterSeconds,
-            isoControl: { kind: "manual", iso } });
+            isoControl: automaticIso ? { kind: "automatic", quantizationPolicy: autoIsoBaseline.isoQuantizationPolicy } : { kind: "manual", iso } });
+    }
+    else if (autoIsoAperturePriority) {
+        resolution = resolveAperturePriorityAutoIsoExposureMode({ target, capabilities, referenceExposure: reference, manualAperture: fNumber,
+            policy: { kind: "minimum-iso-until-slowest-preferred-shutter", ...autoIsoBaseline, shutterSelectionPolicy: "not-longer-than-target", ...autoIsoAperturePriority } });
     }
     else if (mode === "aperture-priority") {
         resolution = resolveAperturePriorityExposureMode({ target, capabilities, referenceExposure: reference, manualAperture: fNumber, manualIso: iso,
@@ -1248,17 +1311,23 @@ export async function runCapture(options, run, viewOption, renderView) {
     }
     else if (mode === "shutter-priority") {
         resolution = resolveShutterPriorityExposureMode({ target, capabilities, referenceExposure: reference, manualShutterSeconds: shutterSeconds,
-            isoControl: { kind: "manual", iso, apertureQuantizationPolicy: "nearest-log2-narrower-on-tie" } });
+            isoControl: automaticIso ? { kind: "automatic", policy: { kind: "minimum-iso-aperture-first", apertureSelectionPolicy: "not-wider-than-target", ...autoIsoBaseline } } :
+                { kind: "manual", iso, apertureQuantizationPolicy: "nearest-log2-narrower-on-tie" } });
     }
     else {
         assume("exposure.programLine", "model", "facade-generic-program-line", "Engine-authored generic program line (f/16 1/2000 s … f/8 1/125 s … f/4 1.024 s); not a manufacturer program.");
-        resolution = resolveProgramAutoExposureMode({ target, capabilities, referenceExposure: reference, programLine: defaultProgramLine(), isoControl: { kind: "manual", iso } });
+        resolution = resolveProgramAutoExposureMode({ target, capabilities, referenceExposure: reference, programLine: defaultProgramLine(),
+            isoControl: automaticIso ? { kind: "automatic", ...autoIsoBaseline } : { kind: "manual", iso } });
     }
     if (resolution.status !== "resolved" || !resolution.resolvedSettings)
         fail("Exposure could not be resolved (" + resolution.status + "); the scene may have no signal.");
     fNumber = resolution.resolvedSettings.aperture ?? fNumber;
     shutterSeconds = resolution.resolvedSettings.shutterSeconds ?? shutterSeconds;
     const resolvedIso = resolution.resolvedSettings.iso ?? iso;
+    if (!Number.isFinite(resolvedIso) || resolvedIso <= 0)
+        fail("Exposure could not be resolved: the resolved ISO is not a positive finite number.");
+    const isoReport = automaticIso ? { isoControl: "automatic", autoIso: autoIsoReport(resolution, capabilities.iso, autoIsoAperturePriority) } : { isoControl: "manual" };
+    const exposureDeviationStops = standardExposureDeviationStops(fNumber, shutterSeconds, resolvedIso, meteredLuminance);
     const defocusDisc = defocusModel === undefined ? undefined :
         resolveDefocusOption({ run, assume, focalLengthMm, fNumber, focusDistanceM, subjectDistanceM, pitch, diffraction: diffractionRadiusOption !== undefined });
     // #492: the capture applies the disc as an object-space convolution, which needs every disc point a site sees to be another site's scene point.
@@ -1699,7 +1768,7 @@ export async function runCapture(options, run, viewOption, renderView) {
     // Display view: the renderer that simulate-display-view.ts passes in reads this request's resolved state, so a bundle
     // that only captures does not contain the display view.
     if (displayView)
-        return await renderView({ ahd, fastReport, antiAliasing, aspect, assume, assumptions, axisChannelResponse, boxSamples, buildProvider, callerScene, chart, materialLayers, chartReport, chartSize, diffraction, defocus: displayViewDefocus, diffractionPsf, fNumber, focalLengthMm, focusDistanceM, height, highlightMode, illuminanceLux, illuminant, illuminantOption, imagingArea, intentOf, metresPerFrameUnit, noiseSeed, outputOptions, parsedView, pitch, preset, provider, regimeByChannel, resolvedIso, sceneOption, scenePreset, shutterSeconds, started, subjectDistanceM, toneCurve, whiteBalanceOption, whiteBalanceState, width, checkAbort, margin, mode, nativeHeight, nativeWidth, sourceSha256, yieldControl, kelvinWhiteBalanceInput });
+        return await renderView({ ahd, fastReport, antiAliasing, aspect, assume, assumptions, axisChannelResponse, boxSamples, buildProvider, callerScene, chart, materialLayers, chartReport, chartSize, diffraction, defocus: displayViewDefocus, diffractionPsf, fNumber, focalLengthMm, focusDistanceM, height, highlightMode, illuminanceLux, illuminant, illuminantOption, imagingArea, intentOf, metresPerFrameUnit, noiseSeed, outputOptions, parsedView, pitch, preset, provider, regimeByChannel, resolvedIso, isoReport, standardExposureDeviationStops: exposureDeviationStops, sceneOption, scenePreset, shutterSeconds, started, subjectDistanceM, toneCurve, whiteBalanceOption, whiteBalanceState, width, checkAbort, margin, mode, nativeHeight, nativeWidth, sourceSha256, yieldControl, kelvinWhiteBalanceInput });
     // Ideal reference (2.3): the scene without camera effects, at the capture's own exposure, white balance and encoding.
     if (idealReference) {
         const referenceStarted = clockMs();
@@ -1772,7 +1841,7 @@ export async function runCapture(options, run, viewOption, renderView) {
             "Each pixel samples the scene at its centre, like the capture's default point aperture; use sensor.pixelAperture \"box\" for photosite-averaged pixels.");
         return Object.freeze({ kind: "ideal-reference", label: "Ideal reference (no camera effects); not a capture.", facadeVersion: SIMULATE_CAPTURE_FACADE_VERSION, engineApiVersion: ENGINE_API_VERSION,
             image: { width: outputWidth, height: outputHeight, format, samples, ...(png ? { png, colorEncoding: colorEncoding } : {}) },
-            exposure: { mode, settings: { fNumber, shutterSeconds, iso: resolvedIso }, ev100: Math.log2(fNumber ** 2 / shutterSeconds) },
+            exposure: { mode, settings: { fNumber, shutterSeconds, iso: resolvedIso }, ev100: Math.log2(fNumber ** 2 / shutterSeconds), ...isoReport },
             scene: { sceneId: chart ? "chart:" + chart.preset : callerScene.sceneId, preset: scenePreset, parameters: chart ? chart.parameters : {},
                 illuminant: { id: illuminant.id, description: illuminant.description, illuminanceLux }, distanceM: subjectDistanceM,
                 framedWidthM: 2 * metresPerFrameUnit, framedHeightM: 2 * metresPerFrameUnit * aspect, ...(chartReport ? { chart: chartReport } : {}), sourceSha256 },
@@ -2062,8 +2131,8 @@ export async function runCapture(options, run, viewOption, renderView) {
         ...(region && regionNative ? { region: { ...region, frameWidth: width, frameHeight: height, nativeRect: { ...regionNative } } } : {}),
         request: { environmentRaw: finalRawInput, siteInput, development, whiteBalanceState,
             ...(diffraction ? { diffraction: { profile: diffraction, psf: diffractionPsf, execution: diffractionObjectSpace ? "object-space-convolution" : "environment-psf-quadrature" } } : {}) },
-        exposure: { mode, settings: { fNumber, shutterSeconds, iso: resolvedIso }, ev100: Math.log2(fNumber ** 2 / shutterSeconds),
-            meteredSceneLuminanceCdPerSquareMeter: meteredLuminance, resolution },
+        exposure: { mode, settings: { fNumber, shutterSeconds, iso: resolvedIso }, ev100: Math.log2(fNumber ** 2 / shutterSeconds), ...isoReport,
+            meteredSceneLuminanceCdPerSquareMeter: meteredLuminance, standardExposureDeviationStops: exposureDeviationStops, resolution },
         scene: { sceneId: chart ? "chart:" + chart.preset : callerScene.sceneId, preset: scenePreset, parameters: chart ? chart.parameters : {},
             illuminant: { id: illuminant.id, description: illuminant.description, illuminanceLux }, distanceM: subjectDistanceM,
             framedWidthM: 2 * metresPerFrameUnit, framedHeightM: 2 * metresPerFrameUnit * aspect, ...(chartReport ? { chart: chartReport } : {}), sourceSha256 },