@photivra/engine 1.5.0 → 2.0.0

package/dist/exposure/exposure-mode-resolver.js

@@ -1,23 +1,30 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Resolves Manual exposure with either manual ISO or Auto ISO. Aperture and shutter are always
- * caller-owned and are never changed. The relative meter target is normalized by an explicit reference
- * exposure anchor; no ISO-100 or other hidden absolute calibration is assumed.
- * Resolves Aperture Priority with manual ISO. Aperture and ISO remain caller-owned. Shutter is the
- * only automatic axis. The target/reference relationship is the same relative exposure model used by
- * Manual + Auto ISO; no new mode-specific exposure equation is introduced.
- * @see docs/USAGE.md for equations, coordinate/unit conventions, blockers and support limits.
+ * Exposure modes: Manual, Aperture Priority, Shutter Priority, Program and Full Auto, each with
+ * manual ISO or Auto ISO where the mode allows it.
+ *
+ * Every exposure mode applies its control policy to one shared relative exposure equation, with an
+ * explicit reference anchor. Exposure compensation is already part of the frozen meter target. Manual
+ * settings are never changed. Automatic settings snap to the declared setting grids, and the result
+ * reports the signed leftover (residual) stops and any limits hit. A target with zero signal cannot
+ * be used to make up an exposure.
+ *
+ * The relative meter target is normalized by an explicit reference exposure anchor. No ISO 100 or
+ * other hidden absolute calibration is assumed.
+ * @see docs/USAGE.md for the equations, units, coordinate conventions, known blockers and support
+ * limits.
  */
 import { InvalidScientificInputError } from "../core/validation.js";
 import { EXPOSURE_METER_TARGET_SCHEMA_VERSION } from "./metering-target.js";
 import { parseExposureProgramLineProfile } from "./program-line.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
 export const EXPOSURE_MODE_RESOLVER_VERSION = "0.5.0";
 function requireRecord(value, path) {
     if (typeof value !== "object" ||
         value === null ||
         Array.isArray(value)) {
-        throw new InvalidScientificInputError(path + " must be an object.");
+        throw new InvalidConfigurationError(path + " must be an object.");
     }
     return value;
 }
@@ -52,7 +59,7 @@ function validateTarget(value) {
     const record = requireRecord(value, "target");
     if (record.schemaVersion !==
         EXPOSURE_METER_TARGET_SCHEMA_VERSION) {
-        throw new InvalidScientificInputError('target.schemaVersion must be "' +
+        throw new InvalidConfigurationError('target.schemaVersion must be "' +
             EXPOSURE_METER_TARGET_SCHEMA_VERSION +
             '".');
     }
@@ -71,7 +78,7 @@ function validateTarget(value) {
     const targetId = record.targetId;
     if (typeof targetId !== "string" ||
         targetId.trim().length === 0) {
-        throw new InvalidScientificInputError("target.targetId must be a non-empty string.");
+        throw new InvalidConfigurationError("target.targetId must be a non-empty string.");
     }
     requireRecord(record.sourceMeterSnapshot, "target.sourceMeterSnapshot");
     if (record.status === "resolved") {
@@ -86,18 +93,19 @@ function validateTarget(value) {
         }
     }
     else if (record.status !== "no-signal") {
-        throw new InvalidScientificInputError("target.status is invalid.");
+        throw new InvalidConfigurationError("target.status is invalid.");
     }
     return value;
 }
 function requireNonEmptyString(value, path) {
     if (typeof value !== "string" ||
         value.trim().length === 0) {
-        throw new InvalidScientificInputError(path + " must be a non-empty string.");
+        throw new InvalidConfigurationError(path + " must be a non-empty string.");
     }
     return value.trim();
 }
 function validateResolvedGrid(grid, minimum, maximum, path) {
+    requireRecord(grid, path);
     if (grid.kind ===
         "continuous-within-range") {
         return;
@@ -105,7 +113,7 @@ function validateResolvedGrid(grid, minimum, maximum, path) {
     if (grid.kind !== "discrete-values" ||
         !Array.isArray(grid.values) ||
         grid.values.length === 0) {
-        throw new InvalidScientificInputError(path +
+        throw new InvalidConfigurationError(path +
             " must be a continuous grid or a non-empty discrete-values grid.");
     }
     let previous = Number.NEGATIVE_INFINITY;
@@ -127,6 +135,10 @@ function validateResolvedGrid(grid, minimum, maximum, path) {
     }
 }
 function validateCapabilities(value) {
+    requireRecord(value, "capabilities");
+    for (const key of ["aperture", "shutter", "iso", "bodyProfile", "lensProfile"]) {
+        requireRecord(value[key], "capabilities." + key);
+    }
     if (value.schemaVersion !== "0.1.0" ||
         value.scientificStatus !==
             "approximation") {
@@ -192,7 +204,7 @@ function validateCapabilities(value) {
         value.iso
             .autoIsoAvailability !==
             "unknown") {
-        throw new InvalidScientificInputError("capabilities.iso.autoIsoAvailability is invalid.");
+        throw new InvalidConfigurationError("capabilities.iso.autoIsoAvailability is invalid.");
     }
     validateResolvedGrid(value.aperture.settingGrid, value.aperture
         .widestAvailableFNumber, value.aperture
@@ -201,6 +213,7 @@ function validateCapabilities(value) {
     validateResolvedGrid(value.iso.settingGrid, value.iso.minimum, value.iso.maximum, "capabilities.iso.settingGrid");
 }
 function validateReferenceExposure(reference, capabilities) {
+    requireRecord(reference, "referenceExposure");
     const aperture = requirePositiveFinite(reference.aperture, "referenceExposure.aperture");
     const shutterSeconds = requirePositiveFinite(reference.shutterSeconds, "referenceExposure.shutterSeconds");
     const iso = requirePositiveFinite(reference.iso, "referenceExposure.iso");
@@ -506,6 +519,19 @@ function selectShutterNotLongerThanTarget(targetSeconds, capabilities) {
     const values = grid.values;
     const first = values[0];
     const last = values[values.length - 1];
+    // A grid value within settingEquals tolerance of the target counts as an
+    // exact match. Floating-point error in the computed target must not push the
+    // choice one grid step shorter (#272).
+    const exactMatch = values.find((candidate) => settingEquals(candidate, targetSeconds));
+    if (exactMatch !== undefined) {
+        return {
+            shutterSeconds: exactMatch,
+            kind: "discrete",
+            quantized: false,
+            clamped: false,
+            limitingConstraint: "none"
+        };
+    }
     if (targetSeconds < first) {
         return {
             shutterSeconds: first,
@@ -515,19 +541,13 @@ function selectShutterNotLongerThanTarget(targetSeconds, capabilities) {
             limitingConstraint: "shutter-minimum"
         };
     }
-    if (targetSeconds >= last) {
+    if (targetSeconds > last) {
         return {
-            shutterSeconds: targetSeconds > last
-                ? last
-                : targetSeconds,
+            shutterSeconds: last,
             kind: "discrete",
-            quantized: !settingEquals(targetSeconds, last),
-            clamped: targetSeconds > last
-                ? "maximum"
-                : false,
-            limitingConstraint: targetSeconds > last
-                ? "shutter-maximum"
-                : "none"
+            quantized: true,
+            clamped: "maximum",
+            limitingConstraint: "shutter-maximum"
         };
     }
     let selected = first;
@@ -669,17 +689,26 @@ function selectApertureNotWiderThanTarget(idealFNumber, capabilities) {
     const values = grid.values;
     const first = values[0];
     const last = values[values.length - 1];
-    if (idealFNumber <= first) {
+    // A grid value within settingEquals tolerance of the ideal counts as an
+    // exact match. Floating-point error in the computed ideal must not push the
+    // choice one grid step narrower (#272).
+    const exactMatch = values.find((candidate) => settingEquals(candidate, idealFNumber));
+    if (exactMatch !== undefined) {
+        return {
+            aperture: exactMatch,
+            kind: "discrete",
+            quantized: false,
+            clamped: false,
+            limitingConstraint: "none"
+        };
+    }
+    if (idealFNumber < first) {
         return {
             aperture: first,
             kind: "discrete",
-            quantized: !settingEquals(idealFNumber, first),
-            clamped: idealFNumber < first
-                ? "widest"
-                : false,
-            limitingConstraint: idealFNumber < first
-                ? "aperture-widest"
-                : "none"
+            quantized: true,
+            clamped: "widest",
+            limitingConstraint: "aperture-widest"
         };
     }
     if (idealFNumber > last) {
@@ -879,11 +908,13 @@ function programLineResidualConstraint(selection) {
 /**
  * Resolves Manual exposure with either manual ISO or Auto ISO.
  *
- * Aperture and shutter are always caller-owned and are never changed.
- * The relative meter target is normalized by an explicit reference exposure
- * anchor; no ISO-100 or other hidden absolute calibration is assumed.
+ * The caller sets aperture and shutter; they are never changed. The relative
+ * meter target is normalized by an explicit reference exposure anchor. No
+ * ISO 100 or other hidden absolute calibration is assumed.
  */
 export function resolveManualExposureMode(input) {
+    requireInputKeys(input, "resolveManualExposureMode", ["target", "capabilities", "referenceExposure", "manualAperture", "manualShutterSeconds", "isoControl"]);
+    requireRecord(input.isoControl, "isoControl");
     const target = validateTarget(input.target);
     validateCapabilities(input.capabilities);
     const referenceExposure = validateReferenceExposure(input.referenceExposure, input.capabilities);
@@ -938,14 +969,14 @@ export function resolveManualExposureMode(input) {
         "manual" &&
         input.isoControl.kind !==
             "automatic") {
-        throw new InvalidScientificInputError("isoControl.kind is invalid.");
+        throw new InvalidConfigurationError("isoControl.kind is invalid.");
     }
     if (input.isoControl.kind ===
         "automatic" &&
         input.isoControl
             .quantizationPolicy !==
             "nearest-log2-lower-on-tie") {
-        throw new InvalidScientificInputError('isoControl.quantizationPolicy must be "nearest-log2-lower-on-tie".');
+        throw new InvalidConfigurationError('isoControl.quantizationPolicy must be "nearest-log2-lower-on-tie".');
     }
     if (input.isoControl.kind ===
         "manual") {
@@ -1050,11 +1081,12 @@ export function resolveManualExposureMode(input) {
 /**
  * Resolves Aperture Priority with manual ISO.
  *
- * Aperture and ISO remain caller-owned. Shutter is the only automatic axis.
- * The target/reference relationship is the same relative exposure model used
- * by Manual + Auto ISO; no new mode-specific exposure equation is introduced.
+ * The caller sets aperture and ISO. Only the shutter is automatic. The target
+ * and reference use the same relative exposure model as Manual + Auto ISO; no
+ * new exposure equation is added for this mode.
  */
 export function resolveAperturePriorityExposureMode(input) {
+    requireInputKeys(input, "resolveAperturePriorityExposureMode", ["target", "capabilities", "referenceExposure", "manualAperture", "manualIso", "shutterQuantizationPolicy"]);
     const target = validateTarget(input.target);
     validateCapabilities(input.capabilities);
     const referenceExposure = validateReferenceExposure(input.referenceExposure, input.capabilities);
@@ -1067,7 +1099,7 @@ export function resolveAperturePriorityExposureMode(input) {
     validateSettingAgainstGrid(manualIso, input.capabilities.iso.minimum, input.capabilities.iso.maximum, input.capabilities.iso.settingGrid, "manualIso");
     if (input.shutterQuantizationPolicy !==
         "nearest-log2-shorter-on-tie") {
-        throw new InvalidScientificInputError('shutterQuantizationPolicy must be "nearest-log2-shorter-on-tie".');
+        throw new InvalidConfigurationError('shutterQuantizationPolicy must be "nearest-log2-shorter-on-tie".');
     }
     const base = {
         resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
@@ -1185,19 +1217,22 @@ function buildPriorityAutoIsoBlocked(mode, target, referenceExposure, reason, re
     };
 }
 /**
- * Hold aperture fixed, follow the declared minimum-shutter policy and use bounded Auto ISO to absorb
- * remaining target residual.
+ * Aperture Priority with Auto ISO. Keeps the aperture fixed, follows the declared minimum-shutter
+ * policy, and uses Auto ISO (within its limits) to make up the rest of the exposure.
  *
- * Exposure modes apply control policy to one shared relative exposure equation and an explicit
- * reference anchor. Compensation is already included in the immutable meter target. Manual axes remain
- * unchanged; automatic axes use declared setting grids and expose signed residual stops and limit
- * diagnostics. A zero-signal target cannot authorize an invented exposure.
- * @param input - ResolveAperturePriorityAutoIsoExposureModeInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns AperturePriorityAutoIsoExposureModeResolution. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Every exposure mode applies its control policy to one shared relative exposure equation, with an
+ * explicit reference anchor. Exposure compensation is already part of the frozen meter target. Manual
+ * settings are never changed. Automatic settings snap to the declared setting grids, and the result
+ * reports the signed leftover (residual) stops and any limits hit. A target with zero signal cannot
+ * be used to make up an exposure.
+ * @param input - ResolveAperturePriorityAutoIsoExposureModeInput. See that type for coordinates, units and profile binding.
+ * @returns AperturePriorityAutoIsoExposureModeResolution. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function resolveAperturePriorityAutoIsoExposureMode(input) {
+    requireInputKeys(input, "resolveAperturePriorityAutoIsoExposureMode", ["target", "capabilities", "referenceExposure", "manualAperture", "policy"]);
+    requireRecord(input.policy, "policy");
     const target = validateTarget(input.target);
     validateCapabilities(input.capabilities);
     const referenceExposure = validateReferenceExposure(input.referenceExposure, input.capabilities);
@@ -1219,7 +1254,7 @@ export function resolveAperturePriorityAutoIsoExposureMode(input) {
             "allow-slower-shutter" &&
             policy.afterMaximumIso !==
                 "hold-preferred-shutter")) {
-        throw new InvalidScientificInputError("Aperture Priority Auto ISO policy is invalid.");
+        throw new InvalidConfigurationError("Aperture Priority Auto ISO policy is invalid.");
     }
     const slowestPreferred = requirePositiveFinite(policy.slowestPreferredShutterSeconds, "policy.slowestPreferredShutterSeconds");
     if (slowestPreferred <
@@ -1396,19 +1431,22 @@ export function resolveAperturePriorityAutoIsoExposureMode(input) {
     };
 }
 /**
- * Hold shutter fixed and resolve aperture plus optional Auto ISO against the exact capability
- * envelope.
+ * Shutter Priority. Keeps the shutter fixed and chooses the aperture, plus optional Auto ISO, within
+ * exactly what the equipment can do.
  *
- * Exposure modes apply control policy to one shared relative exposure equation and an explicit
- * reference anchor. Compensation is already included in the immutable meter target. Manual axes remain
- * unchanged; automatic axes use declared setting grids and expose signed residual stops and limit
- * diagnostics. A zero-signal target cannot authorize an invented exposure.
- * @param input - ResolveShutterPriorityExposureModeInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ShutterPriorityExposureModeResolution. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Every exposure mode applies its control policy to one shared relative exposure equation, with an
+ * explicit reference anchor. Exposure compensation is already part of the frozen meter target. Manual
+ * settings are never changed. Automatic settings snap to the declared setting grids, and the result
+ * reports the signed leftover (residual) stops and any limits hit. A target with zero signal cannot
+ * be used to make up an exposure.
+ * @param input - ResolveShutterPriorityExposureModeInput. See that type for coordinates, units and profile binding.
+ * @returns ShutterPriorityExposureModeResolution. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function resolveShutterPriorityExposureMode(input) {
+    requireInputKeys(input, "resolveShutterPriorityExposureMode", ["target", "capabilities", "referenceExposure", "manualShutterSeconds", "isoControl"]);
+    requireRecord(input.isoControl, "isoControl");
     const target = validateTarget(input.target);
     validateCapabilities(input.capabilities);
     const referenceExposure = validateReferenceExposure(input.referenceExposure, input.capabilities);
@@ -1437,7 +1475,7 @@ export function resolveShutterPriorityExposureMode(input) {
         if (input.isoControl
             .apertureQuantizationPolicy !==
             "nearest-log2-narrower-on-tie") {
-            throw new InvalidScientificInputError('isoControl.apertureQuantizationPolicy must be "nearest-log2-narrower-on-tie".');
+            throw new InvalidConfigurationError('isoControl.apertureQuantizationPolicy must be "nearest-log2-narrower-on-tie".');
         }
         if (target.status === "no-signal") {
             return {
@@ -1495,9 +1533,10 @@ export function resolveShutterPriorityExposureMode(input) {
     }
     if (input.isoControl.kind !==
         "automatic") {
-        throw new InvalidScientificInputError("isoControl.kind is invalid for Shutter Priority.");
+        throw new InvalidConfigurationError("isoControl.kind is invalid for Shutter Priority.");
     }
     const policy = input.isoControl.policy;
+    requireRecord(policy, "isoControl.policy");
     if (policy.kind !==
         "minimum-iso-aperture-first" ||
         policy.isoBaseline !==
@@ -1506,7 +1545,7 @@ export function resolveShutterPriorityExposureMode(input) {
             "nearest-log2-lower-on-tie" ||
         policy.apertureSelectionPolicy !==
             "not-wider-than-target") {
-        throw new InvalidScientificInputError("Shutter Priority Auto ISO policy is invalid.");
+        throw new InvalidConfigurationError("Shutter Priority Auto ISO policy is invalid.");
     }
     const availability = validateAutoIsoAvailability(input.capabilities);
     if (availability !== "supported") {
@@ -1592,19 +1631,22 @@ export function resolveShutterPriorityExposureMode(input) {
     };
 }
 /**
- * Evaluate the declared generic program line in log2 exposure space, quantize aperture/shutter and
- * optionally use Auto ISO for residual exposure.
+ * Program auto exposure. Follows the declared generic program line in log2 exposure space, snaps
+ * aperture and shutter to their grids, and can use Auto ISO for any exposure left over.
  *
- * Exposure modes apply control policy to one shared relative exposure equation and an explicit
- * reference anchor. Compensation is already included in the immutable meter target. Manual axes remain
- * unchanged; automatic axes use declared setting grids and expose signed residual stops and limit
- * diagnostics. A zero-signal target cannot authorize an invented exposure.
- * @param input - ResolveProgramAutoExposureModeInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ProgramAutoExposureModeResolution. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Every exposure mode applies its control policy to one shared relative exposure equation, with an
+ * explicit reference anchor. Exposure compensation is already part of the frozen meter target. Manual
+ * settings are never changed. Automatic settings snap to the declared setting grids, and the result
+ * reports the signed leftover (residual) stops and any limits hit. A target with zero signal cannot
+ * be used to make up an exposure.
+ * @param input - ResolveProgramAutoExposureModeInput. See that type for coordinates, units and profile binding.
+ * @returns ProgramAutoExposureModeResolution. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function resolveProgramAutoExposureMode(input) {
+    requireInputKeys(input, "resolveProgramAutoExposureMode", ["target", "capabilities", "referenceExposure", "programLine", "isoControl"]);
+    requireRecord(input.isoControl, "isoControl");
     const target = validateTarget(input.target);
     validateCapabilities(input.capabilities);
     const referenceExposure = validateReferenceExposure(input.referenceExposure, input.capabilities);
@@ -1613,7 +1655,7 @@ export function resolveProgramAutoExposureMode(input) {
         "manual" &&
         input.isoControl.kind !==
             "automatic") {
-        throw new InvalidScientificInputError("isoControl.kind is invalid for Program Auto.");
+        throw new InvalidConfigurationError("isoControl.kind is invalid for Program Auto.");
     }
     if (target.status === "no-signal") {
         return {
@@ -1694,7 +1736,7 @@ export function resolveProgramAutoExposureMode(input) {
         input.isoControl
             .isoQuantizationPolicy !==
             "nearest-log2-lower-on-tie") {
-        throw new InvalidScientificInputError("Program Auto ISO policy is invalid.");
+        throw new InvalidConfigurationError("Program Auto ISO policy is invalid.");
     }
     const availability = validateAutoIsoAvailability(input.capabilities);
     if (availability !== "supported") {
@@ -1777,19 +1819,22 @@ export function resolveProgramAutoExposureMode(input) {
     };
 }
 /**
- * Resolve aperture, shutter and ISO under an explicit generic Full Auto exposure policy. Autofocus,
- * WB, flash, drive and scene recognition remain unresolved.
+ * Full Auto. Chooses aperture, shutter and ISO under an explicit generic Full Auto exposure policy.
+ * Autofocus, white balance (WB), flash, drive mode and scene recognition are not resolved.
  *
- * Exposure modes apply control policy to one shared relative exposure equation and an explicit
- * reference anchor. Compensation is already included in the immutable meter target. Manual axes remain
- * unchanged; automatic axes use declared setting grids and expose signed residual stops and limit
- * diagnostics. A zero-signal target cannot authorize an invented exposure.
- * @param input - ResolveFullAutoExposureModeInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns FullAutoExposureModeResolution. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Every exposure mode applies its control policy to one shared relative exposure equation, with an
+ * explicit reference anchor. Exposure compensation is already part of the frozen meter target. Manual
+ * settings are never changed. Automatic settings snap to the declared setting grids, and the result
+ * reports the signed leftover (residual) stops and any limits hit. A target with zero signal cannot
+ * be used to make up an exposure.
+ * @param input - ResolveFullAutoExposureModeInput. See that type for coordinates, units and profile binding.
+ * @returns FullAutoExposureModeResolution. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function resolveFullAutoExposureMode(input) {
+    requireInputKeys(input, "resolveFullAutoExposureMode", ["target", "capabilities", "referenceExposure", "policy"]);
+    requireRecord(input.policy, "policy");
     const target = validateTarget(input.target);
     validateCapabilities(input.capabilities);
     const referenceExposure = validateReferenceExposure(input.referenceExposure, input.capabilities);
@@ -1800,7 +1845,7 @@ export function resolveFullAutoExposureMode(input) {
         input.policy
             .isoQuantizationPolicy !==
             "nearest-log2-lower-on-tie") {
-        throw new InvalidScientificInputError("Full Auto exposure policy is invalid.");
+        throw new InvalidConfigurationError("Full Auto exposure policy is invalid.");
     }
     const programLine = validateProgramLineForResolution(input.policy.programLine, referenceExposure, input.capabilities);
     const blocked = (blocker) => ({