@photivra/engine 0.5.1 → 1.0.0

package/dist/capture/focus-control.js

@@ -0,0 +1,664 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Module boundary and integration notes.
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary. Focus is a
+ * longitudinal plane or explicit infinity state, never a screen-space distance. The ideal actuator
+ * resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring scale or
+ * acquisition latency. Target loss, reacquisition, focus lock and release priority remain separate
+ * state transitions.
+ * Create the initial ideal focus-controller state from an explicit profile, focus plane and public
+ * state identity. Focus is a longitudinal plane or explicit infinity state, never a screen-space
+ * distance. The ideal actuator resolves supplied target observations; it does not infer a commercial
+ * AF sensor, focus-ring scale or acquisition latency. Target loss, reacquisition, focus lock and
+ * release priority remain separate state transitions.
+ * @see docs/SIMULATED_CAPTURE.md for equations, coordinate/unit conventions, blockers and support
+ * limits.
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { parseEvidenceList } from "../core/evidence-provenance.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { parseFocusPlane } from "../optics/focus-state.js";
+export const FOCUS_CONTROL_PROFILE_SCHEMA_VERSION = "0.1.0";
+export const FOCUS_CONTROL_STATE_VERSION = "0.1.0";
+const FOCUS_MODES = new Set([
+    "manual",
+    "single-af",
+    "continuous-af"
+]);
+const RELEASE_PRIORITIES = new Set([
+    "focus-priority",
+    "release-priority",
+    "balanced"
+]);
+const TARGET_LOSS_REASONS = new Set([
+    "occluded",
+    "out-of-frame",
+    "identity-lost",
+    "outside-focus-area"
+]);
+function requireRecord(value, path) {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value)) {
+        throw new InvalidConfigurationError(path + " must be an object.");
+    }
+    return value;
+}
+function requireNonEmptyString(value, path) {
+    if (typeof value !== "string" ||
+        value.trim().length === 0) {
+        throw new InvalidConfigurationError(path +
+            " must be a non-empty string.");
+    }
+    return value.trim();
+}
+function requireScientificNonEmptyString(value, path) {
+    if (typeof value !== "string" ||
+        value.trim().length === 0) {
+        throw new InvalidScientificInputError(path +
+            " must be a non-empty string.");
+    }
+    return value.trim();
+}
+function requireScientificNonNegativeFinite(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        value < 0) {
+        throw new InvalidScientificInputError(path +
+            " must be finite and greater than or equal to zero.");
+    }
+    return value;
+}
+function requireScientificPositiveFinite(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 parseLimitations(value, path) {
+    if (!Array.isArray(value)) {
+        throw new InvalidConfigurationError(path + " must be an array.");
+    }
+    const parsed = value.map((entry, index) => requireNonEmptyString(entry, path +
+        "[" +
+        index +
+        "]"));
+    if (new Set(parsed).size !==
+        parsed.length) {
+        throw new InvalidConfigurationError(path +
+            " must not contain duplicates.");
+    }
+    return parsed;
+}
+function parseUniqueEnumList(value, path, allowed) {
+    if (!Array.isArray(value) ||
+        value.length === 0) {
+        throw new InvalidConfigurationError(path +
+            " must be a non-empty array.");
+    }
+    const parsed = value.map((entry, index) => {
+        if (typeof entry !==
+            "string" ||
+            !allowed.has(entry)) {
+            throw new InvalidConfigurationError(path +
+                "[" +
+                index +
+                "] is invalid.");
+        }
+        return entry;
+    });
+    if (new Set(parsed).size !==
+        parsed.length) {
+        throw new InvalidConfigurationError(path +
+            " must not contain duplicates.");
+    }
+    return parsed;
+}
+/**
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary.
+ *
+ * Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
+ * actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
+ * scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
+ * separate state transitions.
+ * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
+ * @returns FocusControlProfile. 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 parseFocusControlProfile(value) {
+    const record = requireRecord(value, "focusControlProfile");
+    if (record.schemaVersion !==
+        FOCUS_CONTROL_PROFILE_SCHEMA_VERSION) {
+        throw new InvalidConfigurationError('focusControlProfile.schemaVersion must be "' +
+            FOCUS_CONTROL_PROFILE_SCHEMA_VERSION +
+            '".');
+    }
+    if (record.scientificStatus !==
+        "approximation") {
+        throw new InvalidConfigurationError('focusControlProfile.scientificStatus must be "approximation".');
+    }
+    const actuator = requireRecord(record.actuator, "focusControlProfile.actuator");
+    if (actuator.kind !==
+        "ideal-instantaneous") {
+        throw new InvalidConfigurationError('focusControlProfile.actuator.kind must be "ideal-instantaneous" in schema 0.1.0.');
+    }
+    if (record
+        .continuousTargetLossPolicy !==
+        "hold-last-focus-require-explicit-reacquisition") {
+        throw new InvalidConfigurationError('focusControlProfile.continuousTargetLossPolicy must be "hold-last-focus-require-explicit-reacquisition".');
+    }
+    return {
+        schemaVersion: FOCUS_CONTROL_PROFILE_SCHEMA_VERSION,
+        profileId: requireNonEmptyString(record.profileId, "focusControlProfile.profileId"),
+        profileVersion: requireNonEmptyString(record.profileVersion, "focusControlProfile.profileVersion"),
+        scientificStatus: "approximation",
+        supportedModes: parseUniqueEnumList(record.supportedModes, "focusControlProfile.supportedModes", FOCUS_MODES),
+        actuator: {
+            kind: "ideal-instantaneous",
+            evidence: parseEvidenceList(actuator.evidence, "focusControlProfile.actuator.evidence")
+        },
+        continuousTargetLossPolicy: "hold-last-focus-require-explicit-reacquisition",
+        supportedReleasePriorities: parseUniqueEnumList(record
+            .supportedReleasePriorities, "focusControlProfile.supportedReleasePriorities", RELEASE_PRIORITIES),
+        evidence: parseEvidenceList(record.evidence, "focusControlProfile.evidence"),
+        limitations: parseLimitations(record.limitations, "focusControlProfile.limitations")
+    };
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function deepFreeze(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        Object.isFrozen(value)) {
+        return value;
+    }
+    Object.freeze(value);
+    for (const child of Object.values(value)) {
+        deepFreeze(child);
+    }
+    return value;
+}
+function immutableState(state) {
+    return deepFreeze(cloneJson(state));
+}
+function stateBase(stateId, profile, mode, focus, acquisitionState, eventTimeSeconds, focusResolvedAtSeconds, activeTargetId, activeFocusAreaId, lock) {
+    return immutableState({
+        version: FOCUS_CONTROL_STATE_VERSION,
+        stateId: requireScientificNonEmptyString(stateId, "stateId"),
+        sourceProfile: {
+            profileId: profile.profileId,
+            profileVersion: profile.profileVersion
+        },
+        profileLimitations: [
+            ...profile.limitations
+        ],
+        mode,
+        acquisitionState,
+        focus: parseFocusPlane(focus),
+        ...(activeTargetId ===
+            undefined
+            ? {}
+            : {
+                activeTargetId
+            }),
+        ...(activeFocusAreaId ===
+            undefined
+            ? {}
+            : {
+                activeFocusAreaId
+            }),
+        lastEventTimeSeconds: eventTimeSeconds,
+        focusResolvedAtSeconds,
+        locked: acquisitionState ===
+            "locked",
+        ...(lock === undefined
+            ? {}
+            : {
+                lock
+            }),
+        actuatorModel: "ideal-instantaneous",
+        continuousTargetLossPolicy: profile
+            .continuousTargetLossPolicy,
+        exposureModified: false,
+        meteringModified: false,
+        whiteBalanceModified: false,
+        subjectTrackingRecognitionModeled: false,
+        rendererCoordinatesConsumed: false,
+        limitations: [
+            ...profile.limitations,
+            "Focus target observations use longitudinal camera-space/conjugate distance, not renderer ray length.",
+            "Ideal instantaneous focus actuation is an approximation and does not represent commercial AF speed, error, hunting, recognition, or low-light behavior.",
+            "Focus control does not modify exposure, metering, white balance, or scene illumination."
+        ]
+    });
+}
+function requireSupportedMode(profile, mode) {
+    if (!profile.supportedModes
+        .includes(mode)) {
+        throw new InvalidScientificInputError("Selected focus-control mode is not supported by the profile.");
+    }
+}
+function requireMonotonicEventTime(current, eventTimeSeconds) {
+    const parsed = requireScientificNonNegativeFinite(eventTimeSeconds, "eventTimeSeconds");
+    if (parsed <
+        current.lastEventTimeSeconds) {
+        throw new InvalidScientificInputError("Focus-control event time must not move backward.");
+    }
+    return parsed;
+}
+function verifyStateProfile(state, profile) {
+    if (state.sourceProfile
+        .profileId !==
+        profile.profileId ||
+        state.sourceProfile
+            .profileVersion !==
+            profile.profileVersion) {
+        throw new InvalidScientificInputError("Focus-control state/profile identity does not match.");
+    }
+}
+/**
+ * Create the initial ideal focus-controller state from an explicit profile, focus plane and public
+ * state identity.
+ *
+ * Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
+ * actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
+ * scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
+ * separate state transitions.
+ * @param input - CreateFocusControlStateInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns FocusControlState. 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 createFocusControlState(input) {
+    const profile = parseFocusControlProfile(input.profile);
+    requireSupportedMode(profile, input.mode);
+    const time = input.initialTimeSeconds ===
+        undefined
+        ? 0
+        : requireScientificNonNegativeFinite(input.initialTimeSeconds, "initialTimeSeconds");
+    return stateBase(input.stateId, profile, input.mode, input.initialFocus, "idle", time, time);
+}
+function stateProfileView(state) {
+    return {
+        schemaVersion: FOCUS_CONTROL_PROFILE_SCHEMA_VERSION,
+        profileId: state.sourceProfile
+            .profileId,
+        profileVersion: state.sourceProfile
+            .profileVersion,
+        scientificStatus: "approximation",
+        supportedModes: [
+            state.mode
+        ],
+        actuator: {
+            kind: "ideal-instantaneous",
+            evidence: []
+        },
+        continuousTargetLossPolicy: state
+            .continuousTargetLossPolicy,
+        supportedReleasePriorities: [
+            "focus-priority",
+            "release-priority",
+            "balanced"
+        ],
+        evidence: [],
+        limitations: state.profileLimitations
+    };
+}
+/**
+ * Return a manual focus transition to the supplied finite/infinity plane without inventing a lens
+ * actuator or focus-ring conversion.
+ *
+ * Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
+ * actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
+ * scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
+ * separate state transitions.
+ * @param input - SetManualFocusStateInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns FocusControlState. 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 setManualFocusState(input) {
+    if (input.state.mode !==
+        "manual") {
+        throw new InvalidScientificInputError("setManualFocusState requires manual focus mode.");
+    }
+    if (input.state.locked) {
+        throw new InvalidScientificInputError("Manual focus cannot change while focus lock is active.");
+    }
+    if (input.commandId !==
+        undefined) {
+        requireScientificNonEmptyString(input.commandId, "commandId");
+    }
+    const time = requireMonotonicEventTime(input.state, input.eventTimeSeconds);
+    return stateBase(input.stateId, stateProfileView(input.state), "manual", input.focus, "idle", time, time);
+}
+function parseObservation(observation) {
+    const targetId = requireScientificNonEmptyString(observation.targetId, "observation.targetId");
+    const observedAtSeconds = requireScientificNonNegativeFinite(observation
+        .observedAtSeconds, "observation.observedAtSeconds");
+    const focusAreaId = observation.focusAreaId ===
+        undefined
+        ? undefined
+        : requireScientificNonEmptyString(observation.focusAreaId, "observation.focusAreaId");
+    if (observation.kind ===
+        "finite-surface") {
+        return {
+            kind: "finite-surface",
+            targetId,
+            ...(focusAreaId ===
+                undefined
+                ? {}
+                : {
+                    focusAreaId
+                }),
+            observedAtSeconds,
+            longitudinalDistanceM: requireScientificPositiveFinite(observation
+                .longitudinalDistanceM, "observation.longitudinalDistanceM")
+        };
+    }
+    if (observation.kind ===
+        "infinity-environment") {
+        return {
+            kind: "infinity-environment",
+            targetId,
+            ...(focusAreaId ===
+                undefined
+                ? {}
+                : {
+                    focusAreaId
+                }),
+            observedAtSeconds
+        };
+    }
+    if (observation.kind ===
+        "unavailable" &&
+        TARGET_LOSS_REASONS.has(observation.reason)) {
+        return {
+            kind: "unavailable",
+            targetId,
+            ...(focusAreaId ===
+                undefined
+                ? {}
+                : {
+                    focusAreaId
+                }),
+            observedAtSeconds,
+            reason: observation.reason
+        };
+    }
+    throw new InvalidScientificInputError("observation.kind/reason is invalid.");
+}
+function focusFromObservation(observation) {
+    if (observation.kind ===
+        "infinity-environment") {
+        return {
+            kind: "infinity"
+        };
+    }
+    return {
+        kind: "finite",
+        distanceM: observation
+            .longitudinalDistanceM
+    };
+}
+function focusEquals(a, b) {
+    if (a.kind !== b.kind) {
+        return false;
+    }
+    if (a.kind === "infinity" ||
+        b.kind === "infinity") {
+        return true;
+    }
+    return (a.distanceM ===
+        b.distanceM);
+}
+function stateFromResolvedTarget(input, observation) {
+    const focus = focusFromObservation(observation);
+    const state = stateBase(input.stateId, stateProfileView(input.state), input.state.mode, focus, "acquired", observation
+        .observedAtSeconds, observation
+        .observedAtSeconds, observation.targetId, observation.focusAreaId);
+    return {
+        state,
+        targetObservationApplied: true,
+        focusChanged: !focusEquals(input.state.focus, focus),
+        acquisitionEvent: input.event,
+        actuatorModel: "ideal-instantaneous",
+        silentRetargetingPerformed: false
+    };
+}
+function unchangedResolution(input) {
+    return {
+        state: input.state,
+        targetObservationApplied: false,
+        focusChanged: false,
+        acquisitionEvent: input.event,
+        actuatorModel: "ideal-instantaneous",
+        silentRetargetingPerformed: false
+    };
+}
+/**
+ * Resolve an explicit available/lost target observation under the selected single/continuous AF
+ * policy, retaining acquisition and reacquisition disposition.
+ *
+ * Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
+ * actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
+ * scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
+ * separate state transitions.
+ * @param input - ResolveFocusTargetObservationInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns FocusTargetResolution. 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 resolveFocusTargetObservation(input) {
+    if (input.event !== "acquire" &&
+        input.event !== "update") {
+        throw new InvalidScientificInputError('Focus target event must be "acquire" or "update".');
+    }
+    if (input.state.mode ===
+        "manual") {
+        throw new InvalidScientificInputError("Manual focus does not automatically consume autofocus target observations.");
+    }
+    const observation = parseObservation(input.observation);
+    requireMonotonicEventTime(input.state, observation
+        .observedAtSeconds);
+    if (input.state.locked) {
+        return unchangedResolution(input);
+    }
+    if (input.state.mode ===
+        "single-af") {
+        if (input.event ===
+            "update" &&
+            input.state
+                .acquisitionState ===
+                "acquired") {
+            return unchangedResolution(input);
+        }
+        if (input.event !==
+            "acquire") {
+            throw new InvalidScientificInputError("Single AF requires an explicit acquire event before target updates.");
+        }
+        if (observation.kind ===
+            "unavailable") {
+            const state = stateBase(input.stateId, stateProfileView(input.state), "single-af", input.state.focus, "target-lost", observation
+                .observedAtSeconds, input.state
+                .focusResolvedAtSeconds, observation.targetId, observation.focusAreaId);
+            return {
+                state,
+                targetObservationApplied: true,
+                focusChanged: false,
+                acquisitionEvent: input.event,
+                actuatorModel: "ideal-instantaneous",
+                silentRetargetingPerformed: false
+            };
+        }
+        return stateFromResolvedTarget(input, observation);
+    }
+    if (input.event ===
+        "update") {
+        if (input.state
+            .activeTargetId ===
+            undefined) {
+            throw new InvalidScientificInputError("Continuous AF requires an explicit acquire event before updates.");
+        }
+        if (observation.targetId !==
+            input.state
+                .activeTargetId) {
+            throw new InvalidScientificInputError("Continuous AF update targetId must match the active target; silent retargeting is not permitted.");
+        }
+        if (input.state
+            .acquisitionState ===
+            "target-lost") {
+            throw new InvalidScientificInputError("Continuous AF target loss requires an explicit acquire event before reacquisition.");
+        }
+    }
+    if (observation.kind ===
+        "unavailable") {
+        const state = stateBase(input.stateId, stateProfileView(input.state), "continuous-af", input.state.focus, "target-lost", observation
+            .observedAtSeconds, input.state
+            .focusResolvedAtSeconds, observation.targetId, observation.focusAreaId);
+        return {
+            state,
+            targetObservationApplied: true,
+            focusChanged: false,
+            acquisitionEvent: input.event,
+            actuatorModel: "ideal-instantaneous",
+            silentRetargetingPerformed: false
+        };
+    }
+    return stateFromResolvedTarget(input, observation);
+}
+/**
+ * Return an explicit lock/unlock transition without changing the underlying physical focus plane.
+ *
+ * Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
+ * actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
+ * scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
+ * separate state transitions.
+ * @param input - SetFocusLockInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns FocusControlState. 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 setFocusLock(input) {
+    const time = requireMonotonicEventTime(input.state, input.eventTimeSeconds);
+    if (input.locked) {
+        if (input.state.locked) {
+            return input.state;
+        }
+        return stateBase(input.stateId, stateProfileView(input.state), input.state.mode, input.state.focus, "locked", time, input.state
+            .focusResolvedAtSeconds, input.state
+            .activeTargetId, input.state
+            .activeFocusAreaId, {
+            lockedAtSeconds: time,
+            resumeAcquisitionState: input.state
+                .acquisitionState
+        });
+    }
+    if (!input.state.locked) {
+        return input.state;
+    }
+    const resume = input.state.lock
+        ?.resumeAcquisitionState;
+    if (resume === undefined) {
+        throw new InvalidScientificInputError("Locked focus state is missing its resume acquisition state.");
+    }
+    return stateBase(input.stateId, stateProfileView(input.state), input.state.mode, input.state.focus, resume, time, input.state
+        .focusResolvedAtSeconds, input.state
+        .activeTargetId, input.state
+        .activeFocusAreaId);
+}
+/**
+ * Report whether release may proceed under focus-priority or release-priority policy; this does not
+ * operate a shutter.
+ *
+ * Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
+ * actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
+ * scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
+ * separate state transitions.
+ * @param input - AssessFocusReleaseGateInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns FocusReleaseGateAssessment. Read structured blockers before consuming an authorization.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export function assessFocusReleaseGate(input) {
+    const profile = parseFocusControlProfile(input.profile);
+    verifyStateProfile(input.state, profile);
+    if (!profile
+        .supportedReleasePriorities
+        .includes(input.priority)) {
+        throw new InvalidScientificInputError("Selected focus/release priority is not supported by the profile.");
+    }
+    if (input.priority ===
+        "release-priority") {
+        return {
+            priority: input.priority,
+            releaseAuthorized: true,
+            reason: "release-priority-bypasses-focus-gate",
+            requiresProfileSpecificBalancedPolicy: false,
+            opticalFocusModified: false,
+            exposureModified: false
+        };
+    }
+    if (input.priority ===
+        "balanced") {
+        return {
+            priority: input.priority,
+            releaseAuthorized: false,
+            reason: "balanced-policy-not-modeled",
+            requiresProfileSpecificBalancedPolicy: true,
+            opticalFocusModified: false,
+            exposureModified: false
+        };
+    }
+    if (input.state.mode ===
+        "manual") {
+        return {
+            priority: input.priority,
+            releaseAuthorized: true,
+            reason: "manual-focus-state",
+            requiresProfileSpecificBalancedPolicy: false,
+            opticalFocusModified: false,
+            exposureModified: false
+        };
+    }
+    if (input.state
+        .acquisitionState ===
+        "locked") {
+        return {
+            priority: input.priority,
+            releaseAuthorized: true,
+            reason: "focus-locked",
+            requiresProfileSpecificBalancedPolicy: false,
+            opticalFocusModified: false,
+            exposureModified: false
+        };
+    }
+    if (input.state
+        .acquisitionState ===
+        "acquired") {
+        return {
+            priority: input.priority,
+            releaseAuthorized: true,
+            reason: "focus-acquired",
+            requiresProfileSpecificBalancedPolicy: false,
+            opticalFocusModified: false,
+            exposureModified: false
+        };
+    }
+    return {
+        priority: input.priority,
+        releaseAuthorized: false,
+        reason: "focus-not-acquired",
+        requiresProfileSpecificBalancedPolicy: false,
+        opticalFocusModified: false,
+        exposureModified: false
+    };
+}
+//# sourceMappingURL=focus-control.js.map