@photivra/engine 0.6.0 → 1.0.1

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

@@ -0,0 +1,1905 @@
+// 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.
+ */
+import { InvalidScientificInputError } from "../core/validation.js";
+import { EXPOSURE_METER_TARGET_SCHEMA_VERSION } from "./metering-target.js";
+import { parseExposureProgramLineProfile } from "./program-line.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.");
+    }
+    return value;
+}
+function requirePositiveFinite(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        value <= 0) {
+        throw new InvalidScientificInputError(path +
+            " must be finite and greater than zero.");
+    }
+    return value;
+}
+function settingEquals(left, right) {
+    const scale = Math.max(Math.abs(left), Math.abs(right), 1);
+    return (Math.abs(left - right) <=
+        Number.EPSILON * 32 * scale);
+}
+function validateSettingAgainstGrid(value, minimum, maximum, grid, path) {
+    if (value < minimum ||
+        value > maximum) {
+        throw new InvalidScientificInputError(path +
+            " lies outside the resolved equipment capability range.");
+    }
+    if (grid.kind ===
+        "discrete-values" &&
+        !grid.values.some((candidate) => settingEquals(candidate, value))) {
+        throw new InvalidScientificInputError(path +
+            " is not present in the resolved discrete equipment setting grid.");
+    }
+}
+function validateTarget(value) {
+    const record = requireRecord(value, "target");
+    if (record.schemaVersion !==
+        EXPOSURE_METER_TARGET_SCHEMA_VERSION) {
+        throw new InvalidScientificInputError('target.schemaVersion must be "' +
+            EXPOSURE_METER_TARGET_SCHEMA_VERSION +
+            '".');
+    }
+    if (record.scientificStatus !==
+        "approximation" ||
+        record.inputDomain !==
+            "relative-pre-exposure-linear-signal" ||
+        record.intendedConsumer !==
+            "exposure-mode-resolver" ||
+        record.automaticExposureResolved !==
+            false ||
+        record.sourceMeterSnapshotPreserved !==
+            true) {
+        throw new InvalidScientificInputError("target does not satisfy the exposure-mode resolver boundary.");
+    }
+    const targetId = record.targetId;
+    if (typeof targetId !== "string" ||
+        targetId.trim().length === 0) {
+        throw new InvalidScientificInputError("target.targetId must be a non-empty string.");
+    }
+    requireRecord(record.sourceMeterSnapshot, "target.sourceMeterSnapshot");
+    if (record.status === "resolved") {
+        requirePositiveFinite(record
+            .requiredExposureScaleToTarget, "target.requiredExposureScaleToTarget");
+        if (typeof record
+            .exposureOffsetStopsToTarget !==
+            "number" ||
+            !Number.isFinite(record
+                .exposureOffsetStopsToTarget)) {
+            throw new InvalidScientificInputError("target.exposureOffsetStopsToTarget must be finite.");
+        }
+    }
+    else if (record.status !== "no-signal") {
+        throw new InvalidScientificInputError("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.");
+    }
+    return value.trim();
+}
+function validateResolvedGrid(grid, minimum, maximum, path) {
+    if (grid.kind ===
+        "continuous-within-range") {
+        return;
+    }
+    if (grid.kind !== "discrete-values" ||
+        !Array.isArray(grid.values) ||
+        grid.values.length === 0) {
+        throw new InvalidScientificInputError(path +
+            " must be a continuous grid or a non-empty discrete-values grid.");
+    }
+    let previous = Number.NEGATIVE_INFINITY;
+    for (let index = 0; index < grid.values.length; index += 1) {
+        const value = requirePositiveFinite(grid.values[index], path +
+            ".values[" +
+            index +
+            "]");
+        if (value <= previous) {
+            throw new InvalidScientificInputError(path +
+                ".values must be strictly increasing with no duplicates.");
+        }
+        if (value < minimum ||
+            value > maximum) {
+            throw new InvalidScientificInputError(path +
+                ".values must stay inside the resolved capability range.");
+        }
+        previous = value;
+    }
+}
+function validateCapabilities(value) {
+    if (value.schemaVersion !== "0.1.0" ||
+        value.scientificStatus !==
+            "approximation") {
+        throw new InvalidScientificInputError("capabilities do not satisfy the generic equipment exposure-capability boundary.");
+    }
+    requirePositiveFinite(value.selectedFocalLengthMm, "capabilities.selectedFocalLengthMm");
+    requirePositiveFinite(value.aperture
+        .widestAvailableFNumber, "capabilities.aperture.widestAvailableFNumber");
+    requirePositiveFinite(value.aperture
+        .narrowestAvailableFNumber, "capabilities.aperture.narrowestAvailableFNumber");
+    requirePositiveFinite(value.shutter.minimumSeconds, "capabilities.shutter.minimumSeconds");
+    requirePositiveFinite(value.shutter.maximumSeconds, "capabilities.shutter.maximumSeconds");
+    requirePositiveFinite(value.iso.minimum, "capabilities.iso.minimum");
+    requirePositiveFinite(value.iso.maximum, "capabilities.iso.maximum");
+    if (value.aperture
+        .widestAvailableFNumber >
+        value.aperture
+            .narrowestAvailableFNumber) {
+        throw new InvalidScientificInputError("capabilities aperture range is invalid.");
+    }
+    if (value.shutter.minimumSeconds >
+        value.shutter.maximumSeconds) {
+        throw new InvalidScientificInputError("capabilities shutter range is invalid.");
+    }
+    if (value.iso.minimum >
+        value.iso.maximum) {
+        throw new InvalidScientificInputError("capabilities ISO range is invalid.");
+    }
+    const hasAutoMinimum = value.iso.autoIsoMinimum !==
+        undefined;
+    const hasAutoMaximum = value.iso.autoIsoMaximum !==
+        undefined;
+    if (hasAutoMinimum !==
+        hasAutoMaximum) {
+        throw new InvalidScientificInputError("capabilities Auto ISO bounds must provide both minimum and maximum or neither.");
+    }
+    if (hasAutoMinimum &&
+        hasAutoMaximum) {
+        const autoMinimum = requirePositiveFinite(value.iso.autoIsoMinimum, "capabilities.iso.autoIsoMinimum");
+        const autoMaximum = requirePositiveFinite(value.iso.autoIsoMaximum, "capabilities.iso.autoIsoMaximum");
+        if (value.iso
+            .autoIsoAvailability !==
+            "supported" ||
+            autoMinimum >
+                autoMaximum ||
+            autoMinimum <
+                value.iso.minimum ||
+            autoMaximum >
+                value.iso.maximum) {
+            throw new InvalidScientificInputError("capabilities Auto ISO bounds must be ordered, inside the manual ISO range, and used only when Auto ISO is supported.");
+        }
+    }
+    requireNonEmptyString(value.bodyProfile.profileId, "capabilities.bodyProfile.profileId");
+    requireNonEmptyString(value.bodyProfile.profileVersion, "capabilities.bodyProfile.profileVersion");
+    requireNonEmptyString(value.lensProfile.profileId, "capabilities.lensProfile.profileId");
+    requireNonEmptyString(value.lensProfile.profileVersion, "capabilities.lensProfile.profileVersion");
+    if (value.iso
+        .autoIsoAvailability !==
+        "supported" &&
+        value.iso
+            .autoIsoAvailability !==
+            "unsupported" &&
+        value.iso
+            .autoIsoAvailability !==
+            "unknown") {
+        throw new InvalidScientificInputError("capabilities.iso.autoIsoAvailability is invalid.");
+    }
+    validateResolvedGrid(value.aperture.settingGrid, value.aperture
+        .widestAvailableFNumber, value.aperture
+        .narrowestAvailableFNumber, "capabilities.aperture.settingGrid");
+    validateResolvedGrid(value.shutter.settingGrid, value.shutter.minimumSeconds, value.shutter.maximumSeconds, "capabilities.shutter.settingGrid");
+    validateResolvedGrid(value.iso.settingGrid, value.iso.minimum, value.iso.maximum, "capabilities.iso.settingGrid");
+}
+function validateReferenceExposure(reference, capabilities) {
+    const aperture = requirePositiveFinite(reference.aperture, "referenceExposure.aperture");
+    const shutterSeconds = requirePositiveFinite(reference.shutterSeconds, "referenceExposure.shutterSeconds");
+    const iso = requirePositiveFinite(reference.iso, "referenceExposure.iso");
+    validateSettingAgainstGrid(aperture, capabilities.aperture
+        .widestAvailableFNumber, capabilities.aperture
+        .narrowestAvailableFNumber, capabilities.aperture
+        .settingGrid, "referenceExposure.aperture");
+    validateSettingAgainstGrid(shutterSeconds, capabilities.shutter
+        .minimumSeconds, capabilities.shutter
+        .maximumSeconds, capabilities.shutter
+        .settingGrid, "referenceExposure.shutterSeconds");
+    validateSettingAgainstGrid(iso, capabilities.iso.minimum, capabilities.iso.maximum, capabilities.iso.settingGrid, "referenceExposure.iso");
+    return {
+        aperture,
+        shutterSeconds,
+        iso
+    };
+}
+function opticalExposureFactor(aperture, shutterSeconds, reference) {
+    const current = shutterSeconds /
+        (aperture * aperture);
+    const referenceOptical = reference.shutterSeconds /
+        (reference.aperture *
+            reference.aperture);
+    const factor = current /
+        referenceOptical;
+    if (!Number.isFinite(factor) ||
+        factor <= 0) {
+        throw new InvalidScientificInputError("Optical exposure factor must remain finite and greater than zero.");
+    }
+    return factor;
+}
+function targetResidual(target, achievedScale, limitingConstraint) {
+    if (target.status ===
+        "no-signal") {
+        return {
+            status: "target-unresolved",
+            state: "target-unresolved",
+            reason: "no-signal-target"
+        };
+    }
+    const targetScale = target
+        .requiredExposureScaleToTarget;
+    const targetStops = target
+        .exposureOffsetStopsToTarget;
+    const achievedStops = Math.log2(achievedScale);
+    const residualStops = Math.log2(targetScale /
+        achievedScale);
+    if (!Number.isFinite(achievedStops) ||
+        !Number.isFinite(residualStops)) {
+        throw new InvalidScientificInputError("Exposure target residual must remain finite.");
+    }
+    const toleranceStops = 1e-12;
+    const state = Math.abs(residualStops) <=
+        toleranceStops
+        ? "matched"
+        : residualStops > 0
+            ? "under-target"
+            : "over-target";
+    return {
+        status: "resolved",
+        state,
+        targetExposureStops: targetStops,
+        achievedExposureStops: achievedStops,
+        residualStops,
+        limitingConstraint
+    };
+}
+function nearestDiscreteIso(idealIso, values) {
+    const first = values[0];
+    const last = values[values.length - 1];
+    if (idealIso < first) {
+        return {
+            iso: first,
+            quantized: true,
+            clamped: "minimum",
+            limitingConstraint: "iso-minimum"
+        };
+    }
+    if (idealIso > last) {
+        return {
+            iso: last,
+            quantized: true,
+            clamped: "maximum",
+            limitingConstraint: "iso-maximum"
+        };
+    }
+    let selected = first;
+    let selectedDistance = Math.abs(Math.log2(idealIso / first));
+    for (let index = 1; index < values.length; index += 1) {
+        const candidate = values[index];
+        const distance = Math.abs(Math.log2(idealIso /
+            candidate));
+        if (distance <
+            selectedDistance -
+                1e-15 ||
+            (Math.abs(distance -
+                selectedDistance) <= 1e-15 &&
+                candidate < selected)) {
+            selected = candidate;
+            selectedDistance =
+                distance;
+        }
+    }
+    const quantized = !settingEquals(selected, idealIso);
+    return {
+        iso: selected,
+        quantized,
+        clamped: false,
+        limitingConstraint: quantized
+            ? "iso-grid-quantization"
+            : "none"
+    };
+}
+function autoIsoBounds(capabilities) {
+    return {
+        minimum: capabilities.iso
+            .autoIsoMinimum ??
+            capabilities.iso.minimum,
+        maximum: capabilities.iso
+            .autoIsoMaximum ??
+            capabilities.iso.maximum
+    };
+}
+function resolveAutomaticIso(idealIso, capabilities) {
+    const grid = capabilities.iso.settingGrid;
+    const bounds = autoIsoBounds(capabilities);
+    if (grid.kind ===
+        "discrete-values") {
+        const autoValues = grid.values.filter((value) => value >= bounds.minimum &&
+            value <= bounds.maximum);
+        if (autoValues.length === 0) {
+            throw new InvalidScientificInputError("Auto ISO bounds contain no selectable values from the resolved ISO grid.");
+        }
+        const discrete = nearestDiscreteIso(idealIso, autoValues);
+        return {
+            ...discrete,
+            kind: "discrete"
+        };
+    }
+    if (idealIso <
+        bounds.minimum) {
+        return {
+            iso: bounds.minimum,
+            kind: "continuous",
+            quantized: false,
+            clamped: "minimum",
+            limitingConstraint: "iso-minimum"
+        };
+    }
+    if (idealIso >
+        bounds.maximum) {
+        return {
+            iso: bounds.maximum,
+            kind: "continuous",
+            quantized: false,
+            clamped: "maximum",
+            limitingConstraint: "iso-maximum"
+        };
+    }
+    return {
+        iso: idealIso,
+        kind: "continuous",
+        quantized: false,
+        clamped: false,
+        limitingConstraint: "none"
+    };
+}
+function nearestDiscreteShutter(idealShutterSeconds, values) {
+    const first = values[0];
+    const last = values[values.length - 1];
+    if (idealShutterSeconds < first) {
+        return {
+            shutterSeconds: first,
+            quantized: true,
+            clamped: "minimum",
+            limitingConstraint: "shutter-minimum"
+        };
+    }
+    if (idealShutterSeconds > last) {
+        return {
+            shutterSeconds: last,
+            quantized: true,
+            clamped: "maximum",
+            limitingConstraint: "shutter-maximum"
+        };
+    }
+    let selected = first;
+    let selectedDistance = Math.abs(Math.log2(idealShutterSeconds /
+        first));
+    for (let index = 1; index < values.length; index += 1) {
+        const candidate = values[index];
+        const distance = Math.abs(Math.log2(idealShutterSeconds /
+            candidate));
+        if (distance <
+            selectedDistance -
+                1e-15 ||
+            (Math.abs(distance -
+                selectedDistance) <= 1e-15 &&
+                candidate < selected)) {
+            selected = candidate;
+            selectedDistance =
+                distance;
+        }
+    }
+    const quantized = !settingEquals(selected, idealShutterSeconds);
+    return {
+        shutterSeconds: selected,
+        quantized,
+        clamped: false,
+        limitingConstraint: quantized
+            ? "shutter-grid-quantization"
+            : "none"
+    };
+}
+function resolveAutomaticShutter(idealShutterSeconds, capabilities) {
+    const grid = capabilities.shutter.settingGrid;
+    if (grid.kind ===
+        "discrete-values") {
+        const discrete = nearestDiscreteShutter(idealShutterSeconds, grid.values);
+        return {
+            ...discrete,
+            kind: "discrete"
+        };
+    }
+    if (idealShutterSeconds <
+        capabilities.shutter
+            .minimumSeconds) {
+        return {
+            shutterSeconds: capabilities.shutter
+                .minimumSeconds,
+            kind: "continuous",
+            quantized: false,
+            clamped: "minimum",
+            limitingConstraint: "shutter-minimum"
+        };
+    }
+    if (idealShutterSeconds >
+        capabilities.shutter
+            .maximumSeconds) {
+        return {
+            shutterSeconds: capabilities.shutter
+                .maximumSeconds,
+            kind: "continuous",
+            quantized: false,
+            clamped: "maximum",
+            limitingConstraint: "shutter-maximum"
+        };
+    }
+    return {
+        shutterSeconds: idealShutterSeconds,
+        kind: "continuous",
+        quantized: false,
+        clamped: false,
+        limitingConstraint: "none"
+    };
+}
+function minimumSelectableIso(capabilities) {
+    const grid = capabilities.iso.settingGrid;
+    const bounds = autoIsoBounds(capabilities);
+    if (grid.kind ===
+        "continuous-within-range") {
+        return bounds.minimum;
+    }
+    const first = grid.values.find((value) => value >= bounds.minimum &&
+        value <= bounds.maximum);
+    if (first === undefined) {
+        throw new InvalidScientificInputError("Auto ISO bounds contain no selectable values from the resolved ISO grid.");
+    }
+    return first;
+}
+function selectShutterNotLongerThanTarget(targetSeconds, capabilities) {
+    const minimum = capabilities.shutter.minimumSeconds;
+    const maximum = capabilities.shutter.maximumSeconds;
+    const grid = capabilities.shutter.settingGrid;
+    if (grid.kind === "continuous-within-range") {
+        if (targetSeconds < minimum) {
+            return {
+                shutterSeconds: minimum,
+                kind: "continuous",
+                quantized: false,
+                clamped: "minimum",
+                limitingConstraint: "shutter-minimum"
+            };
+        }
+        if (targetSeconds > maximum) {
+            return {
+                shutterSeconds: maximum,
+                kind: "continuous",
+                quantized: false,
+                clamped: "maximum",
+                limitingConstraint: "shutter-maximum"
+            };
+        }
+        return {
+            shutterSeconds: targetSeconds,
+            kind: "continuous",
+            quantized: false,
+            clamped: false,
+            limitingConstraint: "none"
+        };
+    }
+    const values = grid.values;
+    const first = values[0];
+    const last = values[values.length - 1];
+    if (targetSeconds < first) {
+        return {
+            shutterSeconds: first,
+            kind: "discrete",
+            quantized: true,
+            clamped: "minimum",
+            limitingConstraint: "shutter-minimum"
+        };
+    }
+    if (targetSeconds >= last) {
+        return {
+            shutterSeconds: targetSeconds > last
+                ? last
+                : targetSeconds,
+            kind: "discrete",
+            quantized: !settingEquals(targetSeconds, last),
+            clamped: targetSeconds > last
+                ? "maximum"
+                : false,
+            limitingConstraint: targetSeconds > last
+                ? "shutter-maximum"
+                : "none"
+        };
+    }
+    let selected = first;
+    for (const candidate of values) {
+        if (candidate > targetSeconds) {
+            break;
+        }
+        selected = candidate;
+    }
+    const quantized = !settingEquals(selected, targetSeconds);
+    return {
+        shutterSeconds: selected,
+        kind: "discrete",
+        quantized,
+        clamped: false,
+        limitingConstraint: quantized
+            ? "shutter-grid-quantization"
+            : "none"
+    };
+}
+function nearestDiscreteAperture(idealFNumber, values) {
+    const first = values[0];
+    const last = values[values.length - 1];
+    if (idealFNumber < first) {
+        return {
+            aperture: first,
+            quantized: true,
+            clamped: "widest",
+            limitingConstraint: "aperture-widest"
+        };
+    }
+    if (idealFNumber > last) {
+        return {
+            aperture: last,
+            quantized: true,
+            clamped: "narrowest",
+            limitingConstraint: "aperture-narrowest"
+        };
+    }
+    let selected = first;
+    let selectedDistance = Math.abs(Math.log2(idealFNumber /
+        first));
+    for (let index = 1; index < values.length; index += 1) {
+        const candidate = values[index];
+        const distance = Math.abs(Math.log2(idealFNumber /
+            candidate));
+        if (distance <
+            selectedDistance -
+                1e-15 ||
+            (Math.abs(distance -
+                selectedDistance) <= 1e-15 &&
+                candidate > selected)) {
+            selected = candidate;
+            selectedDistance =
+                distance;
+        }
+    }
+    const quantized = !settingEquals(selected, idealFNumber);
+    return {
+        aperture: selected,
+        quantized,
+        clamped: false,
+        limitingConstraint: quantized
+            ? "aperture-grid-quantization"
+            : "none"
+    };
+}
+function resolveAutomaticAperture(idealFNumber, capabilities) {
+    const minimum = capabilities.aperture
+        .widestAvailableFNumber;
+    const maximum = capabilities.aperture
+        .narrowestAvailableFNumber;
+    const grid = capabilities.aperture.settingGrid;
+    if (grid.kind === "discrete-values") {
+        return {
+            ...nearestDiscreteAperture(idealFNumber, grid.values),
+            kind: "discrete"
+        };
+    }
+    if (idealFNumber < minimum) {
+        return {
+            aperture: minimum,
+            kind: "continuous",
+            quantized: false,
+            clamped: "widest",
+            limitingConstraint: "aperture-widest"
+        };
+    }
+    if (idealFNumber > maximum) {
+        return {
+            aperture: maximum,
+            kind: "continuous",
+            quantized: false,
+            clamped: "narrowest",
+            limitingConstraint: "aperture-narrowest"
+        };
+    }
+    return {
+        aperture: idealFNumber,
+        kind: "continuous",
+        quantized: false,
+        clamped: false,
+        limitingConstraint: "none"
+    };
+}
+function selectApertureNotWiderThanTarget(idealFNumber, capabilities) {
+    const minimum = capabilities.aperture
+        .widestAvailableFNumber;
+    const maximum = capabilities.aperture
+        .narrowestAvailableFNumber;
+    const grid = capabilities.aperture.settingGrid;
+    if (grid.kind === "continuous-within-range") {
+        if (idealFNumber < minimum) {
+            return {
+                aperture: minimum,
+                kind: "continuous",
+                quantized: false,
+                clamped: "widest",
+                limitingConstraint: "aperture-widest"
+            };
+        }
+        if (idealFNumber > maximum) {
+            return {
+                aperture: maximum,
+                kind: "continuous",
+                quantized: false,
+                clamped: "narrowest",
+                limitingConstraint: "aperture-narrowest"
+            };
+        }
+        return {
+            aperture: idealFNumber,
+            kind: "continuous",
+            quantized: false,
+            clamped: false,
+            limitingConstraint: "none"
+        };
+    }
+    const values = grid.values;
+    const first = values[0];
+    const last = values[values.length - 1];
+    if (idealFNumber <= first) {
+        return {
+            aperture: first,
+            kind: "discrete",
+            quantized: !settingEquals(idealFNumber, first),
+            clamped: idealFNumber < first
+                ? "widest"
+                : false,
+            limitingConstraint: idealFNumber < first
+                ? "aperture-widest"
+                : "none"
+        };
+    }
+    if (idealFNumber > last) {
+        return {
+            aperture: last,
+            kind: "discrete",
+            quantized: true,
+            clamped: "narrowest",
+            limitingConstraint: "aperture-narrowest"
+        };
+    }
+    const selected = values.find((candidate) => candidate >= idealFNumber) ?? last;
+    const quantized = !settingEquals(selected, idealFNumber);
+    return {
+        aperture: selected,
+        kind: "discrete",
+        quantized,
+        clamped: false,
+        limitingConstraint: quantized
+            ? "aperture-grid-quantization"
+            : "none"
+    };
+}
+function idealApertureForTarget(targetScale, shutterSeconds, iso, reference) {
+    const numerator = reference.aperture *
+        reference.aperture *
+        (shutterSeconds /
+            reference.shutterSeconds) *
+        (iso /
+            reference.iso);
+    const squared = numerator / targetScale;
+    const aperture = Math.sqrt(squared);
+    if (!Number.isFinite(aperture) ||
+        aperture <= 0) {
+        throw new InvalidScientificInputError("Ideal automatic aperture must remain finite and greater than zero.");
+    }
+    return aperture;
+}
+function validateProgramLineForResolution(value, referenceExposure, capabilities) {
+    const profile = parseExposureProgramLineProfile(value);
+    const toleranceStops = 1e-9;
+    for (const node of profile.nodes) {
+        if (node.aperture <
+            capabilities.aperture
+                .widestAvailableFNumber ||
+            node.aperture >
+                capabilities.aperture
+                    .narrowestAvailableFNumber) {
+            throw new InvalidScientificInputError("Program-line aperture lies outside the resolved equipment capability range.");
+        }
+        if (node.shutterSeconds <
+            capabilities.shutter
+                .minimumSeconds ||
+            node.shutterSeconds >
+                capabilities.shutter
+                    .maximumSeconds) {
+            throw new InvalidScientificInputError("Program-line shutter duration lies outside the resolved equipment capability range.");
+        }
+        const computedStops = Math.log2(opticalExposureFactor(node.aperture, node.shutterSeconds, referenceExposure));
+        if (!Number.isFinite(computedStops) ||
+            Math.abs(computedStops -
+                node
+                    .opticalExposureStopsFromReference) > toleranceStops) {
+            throw new InvalidScientificInputError("Program-line node opticalExposureStopsFromReference is inconsistent with its aperture/shutter pair and the selected reference exposure.");
+        }
+    }
+    return profile;
+}
+function selectProgramLineSettings(requestedOpticalStops, profile, capabilities) {
+    if (!Number.isFinite(requestedOpticalStops)) {
+        throw new InvalidScientificInputError("Requested program-line optical exposure stops must be finite.");
+    }
+    const first = profile.nodes[0];
+    const last = profile.nodes[profile.nodes.length - 1];
+    let position;
+    let selectedStops;
+    let interpolationPhase;
+    let idealAperture;
+    let idealShutterSeconds;
+    if (requestedOpticalStops <=
+        first
+            .opticalExposureStopsFromReference) {
+        position =
+            requestedOpticalStops <
+                first
+                    .opticalExposureStopsFromReference
+                ? "below-line"
+                : "within-line";
+        selectedStops =
+            first
+                .opticalExposureStopsFromReference;
+        interpolationPhase = null;
+        idealAperture = first.aperture;
+        idealShutterSeconds =
+            first.shutterSeconds;
+    }
+    else if (requestedOpticalStops >=
+        last
+            .opticalExposureStopsFromReference) {
+        position =
+            requestedOpticalStops >
+                last
+                    .opticalExposureStopsFromReference
+                ? "above-line"
+                : "within-line";
+        selectedStops =
+            last
+                .opticalExposureStopsFromReference;
+        interpolationPhase = null;
+        idealAperture = last.aperture;
+        idealShutterSeconds =
+            last.shutterSeconds;
+    }
+    else {
+        position = "within-line";
+        let left = first;
+        let right = profile.nodes[1];
+        for (let index = 1; index < profile.nodes.length; index += 1) {
+            const candidate = profile.nodes[index];
+            if (requestedOpticalStops <=
+                candidate
+                    .opticalExposureStopsFromReference) {
+                left =
+                    profile.nodes[index - 1];
+                right = candidate;
+                break;
+            }
+        }
+        const span = right
+            .opticalExposureStopsFromReference -
+            left
+                .opticalExposureStopsFromReference;
+        const phase = (requestedOpticalStops -
+            left
+                .opticalExposureStopsFromReference) /
+            span;
+        interpolationPhase = phase;
+        selectedStops =
+            requestedOpticalStops;
+        const logAperture = Math.log2(left.aperture) +
+            phase *
+                (Math.log2(right.aperture) -
+                    Math.log2(left.aperture));
+        const logShutter = Math.log2(left.shutterSeconds) +
+            phase *
+                (Math.log2(right.shutterSeconds) -
+                    Math.log2(left.shutterSeconds));
+        idealAperture =
+            Math.pow(2, logAperture);
+        idealShutterSeconds =
+            Math.pow(2, logShutter);
+    }
+    const aperture = resolveAutomaticAperture(idealAperture, capabilities);
+    const shutter = resolveAutomaticShutter(idealShutterSeconds, capabilities);
+    return {
+        profileId: profile.profileId,
+        profileVersion: profile.profileVersion,
+        requestedOpticalExposureStopsFromReference: requestedOpticalStops,
+        selectedOpticalExposureStopsFromReference: selectedStops,
+        position,
+        interpolationPhase,
+        idealAperture,
+        idealShutterSeconds,
+        resolvedAperture: aperture.aperture,
+        resolvedShutterSeconds: shutter.shutterSeconds,
+        apertureQuantized: aperture.quantized,
+        shutterQuantized: shutter.quantized,
+        apertureClamped: aperture.clamped,
+        shutterClamped: shutter.clamped
+    };
+}
+function programLineResidualConstraint(selection) {
+    if (selection.apertureClamped ===
+        "widest") {
+        return "aperture-widest";
+    }
+    if (selection.apertureClamped ===
+        "narrowest") {
+        return "aperture-narrowest";
+    }
+    if (selection.shutterClamped ===
+        "minimum") {
+        return "shutter-minimum";
+    }
+    if (selection.shutterClamped ===
+        "maximum") {
+        return "shutter-maximum";
+    }
+    if (selection.apertureQuantized) {
+        return "aperture-grid-quantization";
+    }
+    if (selection.shutterQuantized) {
+        return "shutter-grid-quantization";
+    }
+    return "none";
+}
+/**
+ * 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.
+ */
+export function resolveManualExposureMode(input) {
+    const target = validateTarget(input.target);
+    validateCapabilities(input.capabilities);
+    const referenceExposure = validateReferenceExposure(input.referenceExposure, input.capabilities);
+    const manualAperture = requirePositiveFinite(input.manualAperture, "manualAperture");
+    const manualShutterSeconds = requirePositiveFinite(input.manualShutterSeconds, "manualShutterSeconds");
+    validateSettingAgainstGrid(manualAperture, input.capabilities.aperture
+        .widestAvailableFNumber, input.capabilities.aperture
+        .narrowestAvailableFNumber, input.capabilities.aperture
+        .settingGrid, "manualAperture");
+    validateSettingAgainstGrid(manualShutterSeconds, input.capabilities.shutter
+        .minimumSeconds, input.capabilities.shutter
+        .maximumSeconds, input.capabilities.shutter
+        .settingGrid, "manualShutterSeconds");
+    const base = {
+        resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
+        mode: "manual",
+        axisOwnership: {
+            aperture: "manual",
+            shutter: "manual",
+            iso: input.isoControl.kind ===
+                "manual"
+                ? "manual"
+                : "automatic"
+        },
+        targetId: target.targetId,
+        targetSourceMeterSnapshot: target.sourceMeterSnapshot,
+        capabilityProfiles: {
+            bodyProfileId: input.capabilities
+                .bodyProfile.profileId,
+            bodyProfileVersion: input.capabilities
+                .bodyProfile.profileVersion,
+            lensProfileId: input.capabilities
+                .lensProfile.profileId,
+            lensProfileVersion: input.capabilities
+                .lensProfile.profileVersion
+        },
+        selectedFocalLengthMm: input.capabilities
+            .selectedFocalLengthMm,
+        referenceExposure,
+        manualAperture,
+        manualShutterSeconds,
+        apertureMutatedByResolver: false,
+        shutterMutatedByResolver: false,
+        exposureCompensationAppliedByResolver: false,
+        meterRecomputedByResolver: false,
+        isoNoiseOrGainTopologyInferred: false,
+        flashPolicyApplied: false,
+        safetyShiftApplied: false
+    };
+    const opticalFactor = opticalExposureFactor(manualAperture, manualShutterSeconds, referenceExposure);
+    if (input.isoControl.kind !==
+        "manual" &&
+        input.isoControl.kind !==
+            "automatic") {
+        throw new InvalidScientificInputError("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".');
+    }
+    if (input.isoControl.kind ===
+        "manual") {
+        const manualIso = requirePositiveFinite(input.isoControl.iso, "isoControl.iso");
+        validateSettingAgainstGrid(manualIso, input.capabilities.iso.minimum, input.capabilities.iso.maximum, input.capabilities.iso.settingGrid, "isoControl.iso");
+        const achievedScale = opticalFactor *
+            (manualIso /
+                referenceExposure.iso);
+        return {
+            ...base,
+            status: "resolved",
+            isoControl: "manual",
+            resolvedSettings: {
+                aperture: manualAperture,
+                shutterSeconds: manualShutterSeconds,
+                iso: manualIso
+            },
+            idealIsoBeforeConstraints: null,
+            isoResolution: {
+                kind: "manual-preserved",
+                quantized: false,
+                clamped: false
+            },
+            targetResidual: targetResidual(target, achievedScale, "none")
+        };
+    }
+    const availability = input.capabilities.iso
+        .autoIsoAvailability;
+    if (availability !== "supported") {
+        return {
+            ...base,
+            status: "blocked",
+            isoControl: "automatic",
+            resolvedSettings: {
+                aperture: manualAperture,
+                shutterSeconds: manualShutterSeconds
+            },
+            idealIsoBeforeConstraints: null,
+            blocker: availability ===
+                "unknown"
+                ? "auto-iso-unknown"
+                : "auto-iso-unsupported",
+            targetResidual: {
+                status: "target-unresolved",
+                state: "target-unresolved",
+                reason: "auto-iso-unavailable"
+            }
+        };
+    }
+    if (target.status === "no-signal") {
+        return {
+            ...base,
+            status: "blocked",
+            isoControl: "automatic",
+            resolvedSettings: {
+                aperture: manualAperture,
+                shutterSeconds: manualShutterSeconds
+            },
+            idealIsoBeforeConstraints: null,
+            blocker: "target-no-signal",
+            targetResidual: {
+                status: "target-unresolved",
+                state: "target-unresolved",
+                reason: "no-signal-target"
+            }
+        };
+    }
+    const idealIso = referenceExposure.iso *
+        (target
+            .requiredExposureScaleToTarget /
+            opticalFactor);
+    if (!Number.isFinite(idealIso) ||
+        idealIso <= 0) {
+        throw new InvalidScientificInputError("Ideal Auto ISO must remain finite and greater than zero.");
+    }
+    const automatic = resolveAutomaticIso(idealIso, input.capabilities);
+    const achievedScale = opticalFactor *
+        (automatic.iso /
+            referenceExposure.iso);
+    const residual = targetResidual(target, achievedScale, automatic
+        .limitingConstraint);
+    return {
+        ...base,
+        status: "resolved",
+        isoControl: "automatic",
+        resolvedSettings: {
+            aperture: manualAperture,
+            shutterSeconds: manualShutterSeconds,
+            iso: automatic.iso
+        },
+        idealIsoBeforeConstraints: idealIso,
+        isoResolution: {
+            kind: automatic.kind,
+            quantizationPolicy: input.isoControl
+                .quantizationPolicy,
+            quantized: automatic.quantized,
+            clamped: automatic.clamped
+        },
+        targetResidual: residual
+    };
+}
+/**
+ * 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.
+ */
+export function resolveAperturePriorityExposureMode(input) {
+    const target = validateTarget(input.target);
+    validateCapabilities(input.capabilities);
+    const referenceExposure = validateReferenceExposure(input.referenceExposure, input.capabilities);
+    const manualAperture = requirePositiveFinite(input.manualAperture, "manualAperture");
+    const manualIso = requirePositiveFinite(input.manualIso, "manualIso");
+    validateSettingAgainstGrid(manualAperture, input.capabilities.aperture
+        .widestAvailableFNumber, input.capabilities.aperture
+        .narrowestAvailableFNumber, input.capabilities.aperture
+        .settingGrid, "manualAperture");
+    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".');
+    }
+    const base = {
+        resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
+        mode: "aperture-priority",
+        axisOwnership: {
+            aperture: "manual",
+            shutter: "automatic",
+            iso: "manual"
+        },
+        targetId: target.targetId,
+        targetSourceMeterSnapshot: target.sourceMeterSnapshot,
+        capabilityProfiles: {
+            bodyProfileId: input.capabilities
+                .bodyProfile.profileId,
+            bodyProfileVersion: input.capabilities
+                .bodyProfile.profileVersion,
+            lensProfileId: input.capabilities
+                .lensProfile.profileId,
+            lensProfileVersion: input.capabilities
+                .lensProfile.profileVersion
+        },
+        selectedFocalLengthMm: input.capabilities
+            .selectedFocalLengthMm,
+        referenceExposure,
+        manualAperture,
+        manualIso,
+        apertureMutatedByResolver: false,
+        isoMutatedByResolver: false,
+        shutterResolvedByResolver: true,
+        exposureCompensationAppliedByResolver: false,
+        meterRecomputedByResolver: false,
+        isoNoiseOrGainTopologyInferred: false,
+        flashPolicyApplied: false,
+        safetyShiftApplied: false
+    };
+    if (target.status === "no-signal") {
+        return {
+            ...base,
+            status: "blocked",
+            resolvedSettings: {
+                aperture: manualAperture,
+                iso: manualIso
+            },
+            idealShutterSecondsBeforeConstraints: null,
+            blocker: "target-no-signal",
+            targetResidual: {
+                status: "target-unresolved",
+                state: "target-unresolved",
+                reason: "no-signal-target"
+            }
+        };
+    }
+    const fixedAxisFactorAtReferenceShutter = opticalExposureFactor(manualAperture, referenceExposure
+        .shutterSeconds, referenceExposure) *
+        (manualIso /
+            referenceExposure.iso);
+    if (!Number.isFinite(fixedAxisFactorAtReferenceShutter) ||
+        fixedAxisFactorAtReferenceShutter <= 0) {
+        throw new InvalidScientificInputError("Aperture Priority fixed-axis exposure factor must remain finite and greater than zero.");
+    }
+    const idealShutterSeconds = referenceExposure
+        .shutterSeconds *
+        (target
+            .requiredExposureScaleToTarget /
+            fixedAxisFactorAtReferenceShutter);
+    if (!Number.isFinite(idealShutterSeconds) ||
+        idealShutterSeconds <= 0) {
+        throw new InvalidScientificInputError("Ideal automatic shutter duration must remain finite and greater than zero.");
+    }
+    const automatic = resolveAutomaticShutter(idealShutterSeconds, input.capabilities);
+    const achievedScale = opticalExposureFactor(manualAperture, automatic.shutterSeconds, referenceExposure) *
+        (manualIso /
+            referenceExposure.iso);
+    const residual = targetResidual(target, achievedScale, automatic
+        .limitingConstraint);
+    return {
+        ...base,
+        status: "resolved",
+        resolvedSettings: {
+            aperture: manualAperture,
+            shutterSeconds: automatic.shutterSeconds,
+            iso: manualIso
+        },
+        idealShutterSecondsBeforeConstraints: idealShutterSeconds,
+        shutterResolution: {
+            kind: automatic.kind,
+            quantizationPolicy: input
+                .shutterQuantizationPolicy,
+            quantized: automatic.quantized,
+            clamped: automatic.clamped
+        },
+        targetResidual: residual
+    };
+}
+function validateAutoIsoAvailability(capabilities) {
+    return capabilities.iso.autoIsoAvailability;
+}
+function buildPriorityAutoIsoBlocked(mode, target, referenceExposure, reason, resolvedSettings) {
+    return {
+        resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
+        mode,
+        status: "blocked",
+        targetId: target.targetId,
+        targetSourceMeterSnapshot: target.sourceMeterSnapshot,
+        referenceExposure,
+        resolvedSettings,
+        blocker: reason,
+        targetResidual: {
+            status: "target-unresolved",
+            state: "target-unresolved",
+            reason: reason === "target-no-signal"
+                ? "no-signal-target"
+                : "auto-iso-unavailable"
+        }
+    };
+}
+/**
+ * Hold aperture fixed, follow the declared minimum-shutter policy and use bounded Auto ISO to absorb
+ * remaining target residual.
+ *
+ * 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.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export function resolveAperturePriorityAutoIsoExposureMode(input) {
+    const target = validateTarget(input.target);
+    validateCapabilities(input.capabilities);
+    const referenceExposure = validateReferenceExposure(input.referenceExposure, input.capabilities);
+    const manualAperture = requirePositiveFinite(input.manualAperture, "manualAperture");
+    validateSettingAgainstGrid(manualAperture, input.capabilities.aperture
+        .widestAvailableFNumber, input.capabilities.aperture
+        .narrowestAvailableFNumber, input.capabilities.aperture
+        .settingGrid, "manualAperture");
+    const policy = input.policy;
+    if (policy.kind !==
+        "minimum-iso-until-slowest-preferred-shutter" ||
+        policy.isoBaseline !==
+            "minimum-selectable" ||
+        policy.isoQuantizationPolicy !==
+            "nearest-log2-lower-on-tie" ||
+        policy.shutterSelectionPolicy !==
+            "not-longer-than-target" ||
+        (policy.afterMaximumIso !==
+            "allow-slower-shutter" &&
+            policy.afterMaximumIso !==
+                "hold-preferred-shutter")) {
+        throw new InvalidScientificInputError("Aperture Priority Auto ISO policy is invalid.");
+    }
+    const slowestPreferred = requirePositiveFinite(policy.slowestPreferredShutterSeconds, "policy.slowestPreferredShutterSeconds");
+    if (slowestPreferred <
+        input.capabilities.shutter
+            .minimumSeconds ||
+        slowestPreferred >
+            input.capabilities.shutter
+                .maximumSeconds) {
+        throw new InvalidScientificInputError("policy.slowestPreferredShutterSeconds lies outside the resolved shutter capability range.");
+    }
+    const availability = validateAutoIsoAvailability(input.capabilities);
+    const commonBlocked = (blocker) => {
+        const raw = buildPriorityAutoIsoBlocked("aperture-priority", target, referenceExposure, blocker, { aperture: manualAperture });
+        return {
+            ...raw,
+            axisOwnership: {
+                aperture: "manual",
+                shutter: "automatic",
+                iso: "automatic"
+            },
+            manualAperture,
+            policy,
+            apertureMutatedByResolver: false,
+            exposureCompensationAppliedByResolver: false,
+            meterRecomputedByResolver: false,
+            flashPolicyApplied: false,
+            safetyShiftApplied: false
+        };
+    };
+    if (availability !== "supported") {
+        return commonBlocked(availability === "unknown"
+            ? "auto-iso-unknown"
+            : "auto-iso-unsupported");
+    }
+    if (target.status === "no-signal") {
+        return commonBlocked("target-no-signal");
+    }
+    const baselineIso = minimumSelectableIso(input.capabilities);
+    const factorAtReferenceShutter = opticalExposureFactor(manualAperture, referenceExposure
+        .shutterSeconds, referenceExposure) *
+        (baselineIso /
+            referenceExposure.iso);
+    const idealAtBaseline = referenceExposure
+        .shutterSeconds *
+        (target
+            .requiredExposureScaleToTarget /
+            factorAtReferenceShutter);
+    if (!Number.isFinite(idealAtBaseline) ||
+        idealAtBaseline <= 0) {
+        throw new InvalidScientificInputError("Ideal Aperture Priority shutter duration at baseline ISO must remain finite and greater than zero.");
+    }
+    const desiredPreferred = Math.min(idealAtBaseline, slowestPreferred);
+    let shutter = selectShutterNotLongerThanTarget(desiredPreferred, input.capabilities);
+    const isoPass = resolveManualExposureMode({
+        target,
+        capabilities: input.capabilities,
+        referenceExposure,
+        manualAperture,
+        manualShutterSeconds: shutter.shutterSeconds,
+        isoControl: {
+            kind: "automatic",
+            quantizationPolicy: policy.isoQuantizationPolicy
+        }
+    });
+    if (isoPass.status !== "resolved" ||
+        isoPass.isoControl !== "automatic") {
+        throw new InvalidScientificInputError("Aperture Priority Auto ISO could not resolve its ISO pass.");
+    }
+    let fallbackUsed = false;
+    let shutterSelectionPolicy = "not-longer-than-target";
+    if (isoPass.isoResolution.clamped ===
+        "maximum" &&
+        isoPass.targetResidual.state ===
+            "under-target" &&
+        policy.afterMaximumIso ===
+            "allow-slower-shutter") {
+        const maxIso = isoPass.resolvedSettings.iso;
+        const fixedAtReference = opticalExposureFactor(manualAperture, referenceExposure
+            .shutterSeconds, referenceExposure) *
+            (maxIso /
+                referenceExposure.iso);
+        const fallbackIdeal = referenceExposure
+            .shutterSeconds *
+            (target
+                .requiredExposureScaleToTarget /
+                fixedAtReference);
+        shutter =
+            resolveAutomaticShutter(fallbackIdeal, input.capabilities);
+        fallbackUsed = true;
+        shutterSelectionPolicy =
+            "nearest-log2-shorter-on-tie";
+        const achievedScale = opticalExposureFactor(manualAperture, shutter.shutterSeconds, referenceExposure) *
+            (maxIso /
+                referenceExposure.iso);
+        const residual = targetResidual(target, achievedScale, shutter.limitingConstraint);
+        return {
+            resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
+            mode: "aperture-priority",
+            status: "resolved",
+            axisOwnership: {
+                aperture: "manual",
+                shutter: "automatic",
+                iso: "automatic"
+            },
+            targetId: target.targetId,
+            targetSourceMeterSnapshot: target.sourceMeterSnapshot,
+            referenceExposure,
+            manualAperture,
+            policy,
+            baselineIso,
+            idealShutterAtBaselineIsoSeconds: idealAtBaseline,
+            preferredShutterSeconds: desiredPreferred,
+            afterMaximumIsoFallbackUsed: fallbackUsed,
+            resolvedSettings: {
+                aperture: manualAperture,
+                shutterSeconds: shutter.shutterSeconds,
+                iso: maxIso
+            },
+            shutterResolution: {
+                kind: shutter.kind,
+                quantized: shutter.quantized,
+                clamped: shutter.clamped,
+                selectionPolicy: shutterSelectionPolicy
+            },
+            idealIsoBeforeConstraints: isoPass
+                .idealIsoBeforeConstraints,
+            isoResolution: isoPass.isoResolution,
+            targetResidual: residual,
+            apertureMutatedByResolver: false,
+            shutterResolvedByResolver: true,
+            isoResolvedByResolver: true,
+            exposureCompensationAppliedByResolver: false,
+            meterRecomputedByResolver: false,
+            flashPolicyApplied: false,
+            safetyShiftApplied: false
+        };
+    }
+    return {
+        resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
+        mode: "aperture-priority",
+        status: "resolved",
+        axisOwnership: {
+            aperture: "manual",
+            shutter: "automatic",
+            iso: "automatic"
+        },
+        targetId: target.targetId,
+        targetSourceMeterSnapshot: target.sourceMeterSnapshot,
+        referenceExposure,
+        manualAperture,
+        policy,
+        baselineIso,
+        idealShutterAtBaselineIsoSeconds: idealAtBaseline,
+        preferredShutterSeconds: desiredPreferred,
+        afterMaximumIsoFallbackUsed: fallbackUsed,
+        resolvedSettings: isoPass.resolvedSettings,
+        shutterResolution: {
+            kind: shutter.kind,
+            quantized: shutter.quantized,
+            clamped: shutter.clamped,
+            selectionPolicy: shutterSelectionPolicy
+        },
+        idealIsoBeforeConstraints: isoPass
+            .idealIsoBeforeConstraints,
+        isoResolution: isoPass.isoResolution,
+        targetResidual: isoPass.targetResidual,
+        apertureMutatedByResolver: false,
+        shutterResolvedByResolver: true,
+        isoResolvedByResolver: true,
+        exposureCompensationAppliedByResolver: false,
+        meterRecomputedByResolver: false,
+        flashPolicyApplied: false,
+        safetyShiftApplied: false
+    };
+}
+/**
+ * Hold shutter fixed and resolve aperture plus optional Auto ISO against the exact capability
+ * envelope.
+ *
+ * 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.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export function resolveShutterPriorityExposureMode(input) {
+    const target = validateTarget(input.target);
+    validateCapabilities(input.capabilities);
+    const referenceExposure = validateReferenceExposure(input.referenceExposure, input.capabilities);
+    const manualShutterSeconds = requirePositiveFinite(input.manualShutterSeconds, "manualShutterSeconds");
+    validateSettingAgainstGrid(manualShutterSeconds, input.capabilities.shutter
+        .minimumSeconds, input.capabilities.shutter
+        .maximumSeconds, input.capabilities.shutter
+        .settingGrid, "manualShutterSeconds");
+    const base = {
+        resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
+        mode: "shutter-priority",
+        targetId: target.targetId,
+        targetSourceMeterSnapshot: target.sourceMeterSnapshot,
+        referenceExposure,
+        manualShutterSeconds,
+        shutterMutatedByResolver: false,
+        apertureResolvedByResolver: true,
+        exposureCompensationAppliedByResolver: false,
+        meterRecomputedByResolver: false,
+        flashPolicyApplied: false,
+        safetyShiftApplied: false
+    };
+    if (input.isoControl.kind === "manual") {
+        const manualIso = requirePositiveFinite(input.isoControl.iso, "isoControl.iso");
+        validateSettingAgainstGrid(manualIso, input.capabilities.iso.minimum, input.capabilities.iso.maximum, input.capabilities.iso.settingGrid, "isoControl.iso");
+        if (input.isoControl
+            .apertureQuantizationPolicy !==
+            "nearest-log2-narrower-on-tie") {
+            throw new InvalidScientificInputError('isoControl.apertureQuantizationPolicy must be "nearest-log2-narrower-on-tie".');
+        }
+        if (target.status === "no-signal") {
+            return {
+                ...base,
+                status: "blocked",
+                axisOwnership: {
+                    aperture: "automatic",
+                    shutter: "manual",
+                    iso: "manual"
+                },
+                isoControl: "manual",
+                resolvedSettings: {
+                    shutterSeconds: manualShutterSeconds
+                },
+                blocker: "target-no-signal",
+                targetResidual: {
+                    status: "target-unresolved",
+                    state: "target-unresolved",
+                    reason: "no-signal-target"
+                }
+            };
+        }
+        const idealAperture = idealApertureForTarget(target
+            .requiredExposureScaleToTarget, manualShutterSeconds, manualIso, referenceExposure);
+        const aperture = resolveAutomaticAperture(idealAperture, input.capabilities);
+        const achievedScale = opticalExposureFactor(aperture.aperture, manualShutterSeconds, referenceExposure) *
+            (manualIso /
+                referenceExposure.iso);
+        return {
+            ...base,
+            status: "resolved",
+            axisOwnership: {
+                aperture: "automatic",
+                shutter: "manual",
+                iso: "manual"
+            },
+            isoControl: "manual",
+            manualIso,
+            idealApertureBeforeConstraints: idealAperture,
+            resolvedSettings: {
+                aperture: aperture.aperture,
+                shutterSeconds: manualShutterSeconds,
+                iso: manualIso
+            },
+            apertureResolution: {
+                kind: aperture.kind,
+                quantizationPolicy: input.isoControl
+                    .apertureQuantizationPolicy,
+                quantized: aperture.quantized,
+                clamped: aperture.clamped
+            },
+            targetResidual: targetResidual(target, achievedScale, aperture
+                .limitingConstraint)
+        };
+    }
+    if (input.isoControl.kind !==
+        "automatic") {
+        throw new InvalidScientificInputError("isoControl.kind is invalid for Shutter Priority.");
+    }
+    const policy = input.isoControl.policy;
+    if (policy.kind !==
+        "minimum-iso-aperture-first" ||
+        policy.isoBaseline !==
+            "minimum-selectable" ||
+        policy.isoQuantizationPolicy !==
+            "nearest-log2-lower-on-tie" ||
+        policy.apertureSelectionPolicy !==
+            "not-wider-than-target") {
+        throw new InvalidScientificInputError("Shutter Priority Auto ISO policy is invalid.");
+    }
+    const availability = validateAutoIsoAvailability(input.capabilities);
+    if (availability !== "supported") {
+        const raw = buildPriorityAutoIsoBlocked("shutter-priority", target, referenceExposure, availability === "unknown"
+            ? "auto-iso-unknown"
+            : "auto-iso-unsupported", {
+            shutterSeconds: manualShutterSeconds
+        });
+        return {
+            ...base,
+            ...raw,
+            axisOwnership: {
+                aperture: "automatic",
+                shutter: "manual",
+                iso: "automatic"
+            },
+            isoControl: "automatic"
+        };
+    }
+    if (target.status === "no-signal") {
+        return {
+            ...base,
+            status: "blocked",
+            axisOwnership: {
+                aperture: "automatic",
+                shutter: "manual",
+                iso: "automatic"
+            },
+            isoControl: "automatic",
+            resolvedSettings: {
+                shutterSeconds: manualShutterSeconds
+            },
+            blocker: "target-no-signal",
+            targetResidual: {
+                status: "target-unresolved",
+                state: "target-unresolved",
+                reason: "no-signal-target"
+            }
+        };
+    }
+    const baselineIso = minimumSelectableIso(input.capabilities);
+    const idealAtBaseline = idealApertureForTarget(target
+        .requiredExposureScaleToTarget, manualShutterSeconds, baselineIso, referenceExposure);
+    const aperture = selectApertureNotWiderThanTarget(idealAtBaseline, input.capabilities);
+    const isoPass = resolveManualExposureMode({
+        target,
+        capabilities: input.capabilities,
+        referenceExposure,
+        manualAperture: aperture.aperture,
+        manualShutterSeconds,
+        isoControl: {
+            kind: "automatic",
+            quantizationPolicy: policy.isoQuantizationPolicy
+        }
+    });
+    if (isoPass.status !== "resolved" ||
+        isoPass.isoControl !== "automatic") {
+        throw new InvalidScientificInputError("Shutter Priority Auto ISO could not resolve its ISO pass.");
+    }
+    return {
+        ...base,
+        status: "resolved",
+        axisOwnership: {
+            aperture: "automatic",
+            shutter: "manual",
+            iso: "automatic"
+        },
+        isoControl: "automatic",
+        policy,
+        baselineIso,
+        idealApertureAtBaselineIso: idealAtBaseline,
+        resolvedSettings: isoPass.resolvedSettings,
+        apertureResolution: {
+            kind: aperture.kind,
+            quantized: aperture.quantized,
+            clamped: aperture.clamped,
+            selectionPolicy: policy.apertureSelectionPolicy
+        },
+        idealIsoBeforeConstraints: isoPass
+            .idealIsoBeforeConstraints,
+        isoResolution: isoPass.isoResolution,
+        targetResidual: isoPass.targetResidual
+    };
+}
+/**
+ * Evaluate the declared generic program line in log2 exposure space, quantize aperture/shutter and
+ * optionally use Auto ISO for residual 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 - 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.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export function resolveProgramAutoExposureMode(input) {
+    const target = validateTarget(input.target);
+    validateCapabilities(input.capabilities);
+    const referenceExposure = validateReferenceExposure(input.referenceExposure, input.capabilities);
+    const programLine = validateProgramLineForResolution(input.programLine, referenceExposure, input.capabilities);
+    if (input.isoControl.kind !==
+        "manual" &&
+        input.isoControl.kind !==
+            "automatic") {
+        throw new InvalidScientificInputError("isoControl.kind is invalid for Program Auto.");
+    }
+    if (target.status === "no-signal") {
+        return {
+            resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
+            mode: "program-auto",
+            status: "blocked",
+            axisOwnership: {
+                aperture: "automatic",
+                shutter: "automatic",
+                iso: input.isoControl.kind ===
+                    "manual"
+                    ? "manual"
+                    : "automatic"
+            },
+            isoControl: input.isoControl.kind,
+            targetId: target.targetId,
+            targetSourceMeterSnapshot: target.sourceMeterSnapshot,
+            referenceExposure,
+            blocker: "target-no-signal",
+            targetResidual: {
+                status: "target-unresolved",
+                state: "target-unresolved",
+                reason: "no-signal-target"
+            },
+            exposureCompensationAppliedByResolver: false,
+            meterRecomputedByResolver: false,
+            flashPolicyApplied: false,
+            safetyShiftApplied: false
+        };
+    }
+    if (input.isoControl.kind ===
+        "manual") {
+        const manualIso = requirePositiveFinite(input.isoControl.iso, "isoControl.iso");
+        validateSettingAgainstGrid(manualIso, input.capabilities.iso.minimum, input.capabilities.iso.maximum, input.capabilities.iso.settingGrid, "isoControl.iso");
+        const requestedOpticalStops = target
+            .exposureOffsetStopsToTarget -
+            Math.log2(manualIso /
+                referenceExposure.iso);
+        const selection = selectProgramLineSettings(requestedOpticalStops, programLine, input.capabilities);
+        const achievedScale = opticalExposureFactor(selection.resolvedAperture, selection
+            .resolvedShutterSeconds, referenceExposure) *
+            (manualIso /
+                referenceExposure.iso);
+        return {
+            resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
+            mode: "program-auto",
+            status: "resolved",
+            axisOwnership: {
+                aperture: "automatic",
+                shutter: "automatic",
+                iso: "manual"
+            },
+            isoControl: "manual",
+            targetId: target.targetId,
+            targetSourceMeterSnapshot: target.sourceMeterSnapshot,
+            referenceExposure,
+            programLineSelection: selection,
+            apertureResolvedByResolver: true,
+            shutterResolvedByResolver: true,
+            exposureCompensationAppliedByResolver: false,
+            meterRecomputedByResolver: false,
+            flashPolicyApplied: false,
+            safetyShiftApplied: false,
+            manualIso,
+            resolvedSettings: {
+                aperture: selection
+                    .resolvedAperture,
+                shutterSeconds: selection
+                    .resolvedShutterSeconds,
+                iso: manualIso
+            },
+            targetResidual: targetResidual(target, achievedScale, programLineResidualConstraint(selection))
+        };
+    }
+    if (input.isoControl
+        .isoBaseline !==
+        "minimum-selectable" ||
+        input.isoControl
+            .isoQuantizationPolicy !==
+            "nearest-log2-lower-on-tie") {
+        throw new InvalidScientificInputError("Program Auto ISO policy is invalid.");
+    }
+    const availability = validateAutoIsoAvailability(input.capabilities);
+    if (availability !== "supported") {
+        return {
+            resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
+            mode: "program-auto",
+            status: "blocked",
+            axisOwnership: {
+                aperture: "automatic",
+                shutter: "automatic",
+                iso: "automatic"
+            },
+            isoControl: "automatic",
+            targetId: target.targetId,
+            targetSourceMeterSnapshot: target.sourceMeterSnapshot,
+            referenceExposure,
+            blocker: availability === "unknown"
+                ? "auto-iso-unknown"
+                : "auto-iso-unsupported",
+            targetResidual: {
+                status: "target-unresolved",
+                state: "target-unresolved",
+                reason: "auto-iso-unavailable"
+            },
+            exposureCompensationAppliedByResolver: false,
+            meterRecomputedByResolver: false,
+            flashPolicyApplied: false,
+            safetyShiftApplied: false
+        };
+    }
+    const baselineIso = minimumSelectableIso(input.capabilities);
+    const requestedOpticalStops = target
+        .exposureOffsetStopsToTarget -
+        Math.log2(baselineIso /
+            referenceExposure.iso);
+    const selection = selectProgramLineSettings(requestedOpticalStops, programLine, input.capabilities);
+    const isoPass = resolveManualExposureMode({
+        target,
+        capabilities: input.capabilities,
+        referenceExposure,
+        manualAperture: selection.resolvedAperture,
+        manualShutterSeconds: selection
+            .resolvedShutterSeconds,
+        isoControl: {
+            kind: "automatic",
+            quantizationPolicy: input.isoControl
+                .isoQuantizationPolicy
+        }
+    });
+    if (isoPass.status !== "resolved" ||
+        isoPass.isoControl !== "automatic") {
+        throw new InvalidScientificInputError("Program Auto could not resolve its Auto ISO pass.");
+    }
+    return {
+        resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
+        mode: "program-auto",
+        status: "resolved",
+        axisOwnership: {
+            aperture: "automatic",
+            shutter: "automatic",
+            iso: "automatic"
+        },
+        isoControl: "automatic",
+        targetId: target.targetId,
+        targetSourceMeterSnapshot: target.sourceMeterSnapshot,
+        referenceExposure,
+        programLineSelection: selection,
+        apertureResolvedByResolver: true,
+        shutterResolvedByResolver: true,
+        exposureCompensationAppliedByResolver: false,
+        meterRecomputedByResolver: false,
+        flashPolicyApplied: false,
+        safetyShiftApplied: false,
+        baselineIso,
+        idealIsoBeforeConstraints: isoPass
+            .idealIsoBeforeConstraints,
+        isoResolution: isoPass.isoResolution,
+        resolvedSettings: isoPass.resolvedSettings,
+        targetResidual: isoPass.targetResidual
+    };
+}
+/**
+ * Resolve aperture, shutter and ISO under an explicit generic Full Auto exposure policy. Autofocus,
+ * WB, flash, drive and scene recognition remain unresolved.
+ *
+ * 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.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export function resolveFullAutoExposureMode(input) {
+    const target = validateTarget(input.target);
+    validateCapabilities(input.capabilities);
+    const referenceExposure = validateReferenceExposure(input.referenceExposure, input.capabilities);
+    if (input.policy.kind !==
+        "generic-program-line-minimum-iso" ||
+        input.policy.isoBaseline !==
+            "minimum-selectable" ||
+        input.policy
+            .isoQuantizationPolicy !==
+            "nearest-log2-lower-on-tie") {
+        throw new InvalidScientificInputError("Full Auto exposure policy is invalid.");
+    }
+    const programLine = validateProgramLineForResolution(input.policy.programLine, referenceExposure, input.capabilities);
+    const blocked = (blocker) => ({
+        resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
+        mode: "full-auto-exposure",
+        status: "blocked",
+        axisOwnership: {
+            aperture: "automatic",
+            shutter: "automatic",
+            iso: "automatic"
+        },
+        policy: input.policy,
+        targetId: target.targetId,
+        targetSourceMeterSnapshot: target.sourceMeterSnapshot,
+        referenceExposure,
+        blocker,
+        targetResidual: {
+            status: "target-unresolved",
+            state: "target-unresolved",
+            reason: blocker ===
+                "target-no-signal"
+                ? "no-signal-target"
+                : "auto-iso-unavailable"
+        },
+        exposureCompensationAppliedByResolver: false,
+        meterRecomputedByResolver: false,
+        flashPolicyApplied: false,
+        safetyShiftApplied: false,
+        autofocusResolved: false,
+        whiteBalanceResolved: false,
+        flashResolved: false,
+        driveResolved: false,
+        sceneRecognitionResolved: false,
+        stabilizationPolicyResolved: false
+    });
+    if (target.status === "no-signal") {
+        return blocked("target-no-signal");
+    }
+    const availability = validateAutoIsoAvailability(input.capabilities);
+    if (availability !== "supported") {
+        return blocked(availability === "unknown"
+            ? "auto-iso-unknown"
+            : "auto-iso-unsupported");
+    }
+    const baselineIso = minimumSelectableIso(input.capabilities);
+    const requestedOpticalStops = target
+        .exposureOffsetStopsToTarget -
+        Math.log2(baselineIso /
+            referenceExposure.iso);
+    const selection = selectProgramLineSettings(requestedOpticalStops, programLine, input.capabilities);
+    const isoPass = resolveManualExposureMode({
+        target,
+        capabilities: input.capabilities,
+        referenceExposure,
+        manualAperture: selection.resolvedAperture,
+        manualShutterSeconds: selection
+            .resolvedShutterSeconds,
+        isoControl: {
+            kind: "automatic",
+            quantizationPolicy: input.policy
+                .isoQuantizationPolicy
+        }
+    });
+    if (isoPass.status !== "resolved" ||
+        isoPass.isoControl !== "automatic") {
+        throw new InvalidScientificInputError("Full Auto exposure could not resolve its Auto ISO pass.");
+    }
+    return {
+        resolverVersion: EXPOSURE_MODE_RESOLVER_VERSION,
+        mode: "full-auto-exposure",
+        status: "resolved",
+        axisOwnership: {
+            aperture: "automatic",
+            shutter: "automatic",
+            iso: "automatic"
+        },
+        policy: input.policy,
+        targetId: target.targetId,
+        targetSourceMeterSnapshot: target.sourceMeterSnapshot,
+        referenceExposure,
+        programLineSelection: selection,
+        apertureResolvedByResolver: true,
+        shutterResolvedByResolver: true,
+        exposureCompensationAppliedByResolver: false,
+        meterRecomputedByResolver: false,
+        flashPolicyApplied: false,
+        safetyShiftApplied: false,
+        baselineIso,
+        idealIsoBeforeConstraints: isoPass
+            .idealIsoBeforeConstraints,
+        isoResolution: isoPass.isoResolution,
+        resolvedSettings: isoPass.resolvedSettings,
+        targetResidual: isoPass.targetResidual,
+        autofocusResolved: false,
+        whiteBalanceResolved: false,
+        flashResolved: false,
+        driveResolved: false,
+        sceneRecognitionResolved: false,
+        stabilizationPolicyResolved: false
+    };
+}
+//# sourceMappingURL=exposure-mode-resolver.js.map