@lsctech/polaris 0.1.0

package/dist/loop/dispatch-state.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * Worker dispatch state machine types and transition logic.
+ *
+ * This module defines the runtime state machine for tracking worker execution
+ * from packet creation through completion, failure, or orphaning.
+ *
+ * @module dispatch-state
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TIMEOUTS = exports.PRE_LAUNCH_STATES = exports.ACTIVE_STATES = exports.TERMINAL_STATES = void 0;
+exports.isTerminalState = isTerminalState;
+exports.isActiveState = isActiveState;
+exports.isPreLaunchState = isPreLaunchState;
+exports.resolveTimeoutConfig = resolveTimeoutConfig;
+exports.deriveDispatchState = deriveDispatchState;
+exports.isValidTransition = isValidTransition;
+exports.createStateHistoryEntry = createStateHistoryEntry;
+/**
+ * Terminal states - once reached, no further transitions.
+ */
+exports.TERMINAL_STATES = ["completed", "failed", "orphaned"];
+/**
+ * Active states - worker is still expected to produce telemetry.
+ */
+exports.ACTIVE_STATES = [
+    "launching",
+    "acknowledged",
+    "running",
+    "waiting-for-approval",
+    "blocked",
+];
+/**
+ * Pre-launch states - worker has not yet started.
+ */
+exports.PRE_LAUNCH_STATES = ["packet-created", "delegated"];
+/**
+ * Default timeout values.
+ */
+exports.DEFAULT_TIMEOUTS = {
+    launch_to_first_heartbeat_ms: 30000, // 30 seconds
+    heartbeat_interval_ms: 300000, // 5 minutes
+    orphan_timeout_ms: 600000, // 10 minutes
+    approval_timeout_ms: 3600000, // 1 hour
+    ack_to_first_heartbeat_ms: 120000, // 2 minutes
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// State Machine Logic
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Check if a state is terminal (no further transitions expected).
+ */
+function isTerminalState(state) {
+    return exports.TERMINAL_STATES.includes(state);
+}
+/**
+ * Check if a state represents an active worker (telemetry expected).
+ */
+function isActiveState(state) {
+    return exports.ACTIVE_STATES.includes(state);
+}
+/**
+ * Check if state is pre-launch (worker not yet started).
+ */
+function isPreLaunchState(state) {
+    return exports.PRE_LAUNCH_STATES.includes(state);
+}
+/**
+ * Get the timeout configuration with defaults applied.
+ */
+function resolveTimeoutConfig(config) {
+    return {
+        launch_to_first_heartbeat_ms: config?.launch_to_first_heartbeat_ms ?? exports.DEFAULT_TIMEOUTS.launch_to_first_heartbeat_ms,
+        heartbeat_interval_ms: config?.heartbeat_interval_ms ?? exports.DEFAULT_TIMEOUTS.heartbeat_interval_ms,
+        orphan_timeout_ms: config?.orphan_timeout_ms ?? exports.DEFAULT_TIMEOUTS.orphan_timeout_ms,
+        approval_timeout_ms: config?.approval_timeout_ms ?? exports.DEFAULT_TIMEOUTS.approval_timeout_ms,
+        ack_to_first_heartbeat_ms: config?.ack_to_first_heartbeat_ms ?? exports.DEFAULT_TIMEOUTS.ack_to_first_heartbeat_ms,
+    };
+}
+/**
+ * Derive the current dispatch state from events and configuration.
+ *
+ * This is the core state machine function that determines the current
+ * state based on telemetry events and timeout thresholds.
+ *
+ * For delegated mode, also considers Foreman coordination events:
+ * - worker-assignment-attempted
+ * - worker-assigned
+ * - worker-assignment-failed
+ * - escalation-initiated
+ */
+function deriveDispatchState(events, config, now = new Date()) {
+    // Sort events by timestamp
+    const sorted = [...events].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    // Find result event (terminal)
+    const resultEvent = sorted.find((e) => e.event === "worker-result");
+    if (resultEvent) {
+        return resultEvent.status === "success" ? "completed" : "failed";
+    }
+    // Find blocked event
+    const blockedEvents = sorted.filter((e) => e.event === "worker-blocked");
+    const lastBlocked = blockedEvents.at(-1);
+    if (lastBlocked) {
+        // Check for approval after this block
+        const approvalEvents = sorted.filter((e) => (e.event === "worker-approved" || e.event === "worker-auto-approved") &&
+            new Date(e.timestamp) > new Date(lastBlocked.timestamp));
+        if (approvalEvents.length === 0) {
+            // Still blocked - check for timeout
+            const blockedMs = now.getTime() - new Date(lastBlocked.timestamp).getTime();
+            if (blockedMs > config.approval_timeout_ms) {
+                return "failed";
+            }
+            return "waiting-for-approval";
+        }
+        // Approved - continue checking heartbeats below
+    }
+    // Find rejection event - context aware
+    // Only treat rejection as terminal if it's relevant to current unresolved cycle
+    // A rejection is relevant if:
+    // 1. It occurred after the most recent approval (if any approvals exist), OR
+    // 2. It matches the blocker_id of the current unresolved blocked event
+    const rejectionEvents = sorted.filter((e) => e.event === "worker-rejected");
+    if (rejectionEvents.length > 0) {
+        // Find the most recent approval timestamp (if any approvals exist)
+        const lastApproval = sorted
+            .filter((e) => e.event === "worker-approved" || e.event === "worker-auto-approved")
+            .at(-1);
+        const lastApprovalTimestamp = lastApproval ? new Date(lastApproval.timestamp).getTime() : 0;
+        // Find if there's a current unresolved blocked event with a blocker_id
+        const currentBlocked = lastBlocked;
+        const currentBlockerId = currentBlocked?.blocker_id;
+        // Check for relevant rejections
+        const relevantRejection = rejectionEvents.find((rejection) => {
+            const rejectionTimestamp = new Date(rejection.timestamp).getTime();
+            // Rejection is relevant if it happened after the last approval
+            if (rejectionTimestamp > lastApprovalTimestamp) {
+                return true;
+            }
+            // Or if it matches the current unresolved blocked event's blocker_id
+            if (currentBlockerId && rejection.blocker_id === currentBlockerId) {
+                return true;
+            }
+            return false;
+        });
+        if (relevantRejection) {
+            return "failed";
+        }
+    }
+    // Check heartbeats
+    const heartbeats = sorted.filter((e) => e.event === "worker-heartbeat");
+    const lastHeartbeat = heartbeats.at(-1);
+    if (lastHeartbeat) {
+        const msSinceHeartbeat = now.getTime() - new Date(lastHeartbeat.timestamp).getTime();
+        // Check for orphan timeout
+        if (msSinceHeartbeat > config.orphan_timeout_ms) {
+            return "orphaned";
+        }
+        // Check for blocked (stale heartbeat)
+        if (msSinceHeartbeat > config.heartbeat_interval_ms) {
+            return "blocked";
+        }
+        // Active worker
+        return "running";
+    }
+    // No heartbeats yet — check for worker-acknowledged event
+    const acknowledgedEvent = sorted.find((e) => e.event === "worker-acknowledged");
+    if (acknowledgedEvent) {
+        // Worker acknowledged packet but has not yet sent a heartbeat
+        // Check if the acknowledgement has aged out
+        const msSinceAck = now.getTime() - new Date(acknowledgedEvent.timestamp).getTime();
+        if (msSinceAck > config.ack_to_first_heartbeat_ms) {
+            // Ack timeout — worker never started actual work
+            return "failed";
+        }
+        return "acknowledged";
+    }
+    // No heartbeats yet - check for launch
+    const launchEvent = sorted.find((e) => e.event === "worker-launch");
+    if (launchEvent) {
+        const msSinceLaunch = now.getTime() - new Date(launchEvent.timestamp).getTime();
+        // Check for launch timeout
+        if (msSinceLaunch > config.launch_to_first_heartbeat_ms) {
+            return "blocked";
+        }
+        return "launching";
+    }
+    // No launch event - check for provider assignment
+    // This would require external knowledge, default to packet-created
+    return "packet-created";
+}
+/**
+ * Determine if a state transition is valid.
+ */
+function isValidTransition(from, to) {
+    // Cannot transition from terminal states
+    if (isTerminalState(from)) {
+        return false;
+    }
+    // Define valid transitions
+    const validTransitions = {
+        "packet-created": ["delegated", "launching", "acknowledged", "running", "failed"],
+        "delegated": ["launching", "acknowledged", "running", "completed", "failed", "blocked"],
+        "launching": ["acknowledged", "running", "waiting-for-approval", "blocked", "completed", "failed"],
+        "acknowledged": ["running", "failed"],
+        "running": ["waiting-for-approval", "blocked", "completed", "failed", "orphaned"],
+        "waiting-for-approval": ["running", "completed", "failed"],
+        "blocked": ["running", "completed", "failed", "orphaned"],
+        "completed": [],
+        "failed": [],
+        "orphaned": [],
+    };
+    return validTransitions[from]?.includes(to) ?? false;
+}
+/**
+ * Create a state history entry.
+ */
+function createStateHistoryEntry(state, evidence) {
+    return {
+        state,
+        entered_at: new Date().toISOString(),
+        evidence,
+    };
+}

package/dist/loop/dispatch-state.test.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * Tests for dispatch-state.ts — state machine transitions and backward compat helpers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const dispatch_state_js_1 = require("./dispatch-state.js");
+// ─────────────────────────────────────────────────────────────────────────────
+// Transition tests
+// ─────────────────────────────────────────────────────────────────────────────
+(0, vitest_1.describe)("isValidTransition — added transitions", () => {
+    (0, vitest_1.it)("packet-created → failed is valid", () => {
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("packet-created", "failed")).toBe(true);
+    });
+    (0, vitest_1.it)("running → orphaned is valid", () => {
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("running", "orphaned")).toBe(true);
+    });
+    (0, vitest_1.it)("delegated → blocked is valid", () => {
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("delegated", "blocked")).toBe(true);
+    });
+});
+(0, vitest_1.describe)("isValidTransition — pre-existing transitions still valid", () => {
+    (0, vitest_1.it)("packet-created → delegated", () => {
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("packet-created", "delegated")).toBe(true);
+    });
+    (0, vitest_1.it)("delegated → launching", () => {
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("delegated", "launching")).toBe(true);
+    });
+    (0, vitest_1.it)("running → completed", () => {
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("running", "completed")).toBe(true);
+    });
+    (0, vitest_1.it)("blocked → orphaned", () => {
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("blocked", "orphaned")).toBe(true);
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// POL-221: acknowledged state transitions
+// ─────────────────────────────────────────────────────────────────────────────
+(0, vitest_1.describe)("isValidTransition — acknowledged state (POL-221)", () => {
+    (0, vitest_1.it)("launching → acknowledged is valid", () => {
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("launching", "acknowledged")).toBe(true);
+    });
+    (0, vitest_1.it)("acknowledged → running is valid", () => {
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("acknowledged", "running")).toBe(true);
+    });
+    (0, vitest_1.it)("acknowledged → failed is valid", () => {
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("acknowledged", "failed")).toBe(true);
+    });
+    (0, vitest_1.it)("launching → running is still valid for backward compat", () => {
+        // The state machine allows this, but deriveDispatchState now routes through acknowledged
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("launching", "running")).toBe(true);
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// POL-221: deriveDispatchState with worker-acknowledged event
+// ─────────────────────────────────────────────────────────────────────────────
+function makeBaseEvent(event, overrides = {}) {
+    return {
+        event,
+        event_id: "evt-001",
+        dispatch_id: "dispatch-001",
+        run_id: "run-001",
+        child_id: "POL-221",
+        timestamp: new Date().toISOString(),
+        ...overrides,
+    };
+}
+(0, vitest_1.describe)("deriveDispatchState — acknowledged (POL-221)", () => {
+    const now = new Date();
+    (0, vitest_1.it)("returns 'acknowledged' when worker-acknowledged event present and no heartbeat", () => {
+        const events = [
+            makeBaseEvent("worker-launch"),
+            makeBaseEvent("worker-acknowledged", { worker_id: "worker-uuid", packet_sha: "abc123" }),
+        ];
+        (0, vitest_1.expect)((0, dispatch_state_js_1.deriveDispatchState)(events, dispatch_state_js_1.DEFAULT_TIMEOUTS, now)).toBe("acknowledged");
+    });
+    (0, vitest_1.it)("returns 'acknowledged' without a prior launch event if only acknowledged present", () => {
+        const events = [
+            makeBaseEvent("worker-acknowledged", { worker_id: "worker-uuid", packet_sha: "abc123" }),
+        ];
+        (0, vitest_1.expect)((0, dispatch_state_js_1.deriveDispatchState)(events, dispatch_state_js_1.DEFAULT_TIMEOUTS, now)).toBe("acknowledged");
+    });
+    (0, vitest_1.it)("returns 'running' when heartbeat present after acknowledgment", () => {
+        const events = [
+            makeBaseEvent("worker-launch"),
+            makeBaseEvent("worker-acknowledged", { worker_id: "worker-uuid", packet_sha: "abc123" }),
+            makeBaseEvent("worker-heartbeat", { step_cursor: "step-1" }),
+        ];
+        (0, vitest_1.expect)((0, dispatch_state_js_1.deriveDispatchState)(events, dispatch_state_js_1.DEFAULT_TIMEOUTS, now)).toBe("running");
+    });
+    (0, vitest_1.it)("does NOT return 'running' from launching without acknowledgment (proxy retirement)", () => {
+        // Without worker-acknowledged or heartbeat, should be 'launching', not 'running'
+        const events = [
+            makeBaseEvent("worker-launch"),
+        ];
+        const state = (0, dispatch_state_js_1.deriveDispatchState)(events, dispatch_state_js_1.DEFAULT_TIMEOUTS, now);
+        (0, vitest_1.expect)(state).toBe("launching");
+        (0, vitest_1.expect)(state).not.toBe("running");
+    });
+});
+(0, vitest_1.describe)("isValidTransition — terminal states cannot transition", () => {
+    (0, vitest_1.it)("completed → running is invalid", () => {
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("completed", "running")).toBe(false);
+    });
+    (0, vitest_1.it)("failed → running is invalid", () => {
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("failed", "running")).toBe(false);
+    });
+    (0, vitest_1.it)("orphaned → running is invalid", () => {
+        (0, vitest_1.expect)((0, dispatch_state_js_1.isValidTransition)("orphaned", "running")).toBe(false);
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Backward-compat helper tests for ChildDispatchRecord optional fields
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Resolve worker_id with backward-compat fallback.
+ * Records created before worker_id was added fall back to dispatch_id.
+ */
+function resolveWorkerId(record) {
+    return record.worker_id ?? record.dispatch_id;
+}
+function resolveSessionId(record) {
+    return record.session_id !== undefined ? record.session_id : null;
+}
+function resolveAttachmentCapable(record) {
+    return record.attachment_capable ?? false;
+}
+function resolveHeartbeatCount(record) {
+    return record.heartbeat_count ?? 0;
+}
+(0, vitest_1.describe)("ChildDispatchRecord backward compat", () => {
+    const legacyRecord = {
+        dispatch_id: "legacy-dispatch-id",
+        child_id: "POL-001",
+        run_id: "run-1",
+        cluster_id: "cluster-1",
+        packet_path: "/path/to/packet",
+        expected_result_path: "/path/to/result",
+        dispatched_at: new Date().toISOString(),
+        status: "dispatched",
+    };
+    (0, vitest_1.it)("worker_id falls back to dispatch_id when absent", () => {
+        (0, vitest_1.expect)(resolveWorkerId(legacyRecord)).toBe("legacy-dispatch-id");
+    });
+    (0, vitest_1.it)("session_id defaults to null when absent", () => {
+        (0, vitest_1.expect)(resolveSessionId(legacyRecord)).toBeNull();
+    });
+    (0, vitest_1.it)("attachment_capable defaults to false when absent", () => {
+        (0, vitest_1.expect)(resolveAttachmentCapable(legacyRecord)).toBe(false);
+    });
+    (0, vitest_1.it)("heartbeat_count defaults to 0 when absent", () => {
+        (0, vitest_1.expect)(resolveHeartbeatCount(legacyRecord)).toBe(0);
+    });
+});
+(0, vitest_1.describe)("ChildDispatchRecord new fields when present", () => {
+    const newRecord = {
+        dispatch_id: "dispatch-abc",
+        child_id: "POL-219",
+        run_id: "run-2",
+        cluster_id: "cluster-2",
+        packet_path: "/path/to/packet",
+        expected_result_path: "/path/to/result",
+        dispatched_at: new Date().toISOString(),
+        status: "dispatched",
+        worker_id: "worker-uuid-xyz",
+        session_id: "session-123",
+        attachment_capable: true,
+        heartbeat_count: 5,
+        first_heartbeat_at: "2026-05-29T00:00:00.000Z",
+    };
+    (0, vitest_1.it)("worker_id uses explicit value", () => {
+        (0, vitest_1.expect)(resolveWorkerId(newRecord)).toBe("worker-uuid-xyz");
+    });
+    (0, vitest_1.it)("session_id returns explicit value", () => {
+        (0, vitest_1.expect)(resolveSessionId(newRecord)).toBe("session-123");
+    });
+    (0, vitest_1.it)("attachment_capable returns true when set", () => {
+        (0, vitest_1.expect)(resolveAttachmentCapable(newRecord)).toBe(true);
+    });
+    (0, vitest_1.it)("heartbeat_count returns explicit count", () => {
+        (0, vitest_1.expect)(resolveHeartbeatCount(newRecord)).toBe(5);
+    });
+    (0, vitest_1.it)("first_heartbeat_at is present", () => {
+        (0, vitest_1.expect)(newRecord.first_heartbeat_at).toBe("2026-05-29T00:00:00.000Z");
+    });
+});