@lsctech/polaris 0.1.0

package/dist/loop/continue.test.js

@@ -0,0 +1,337 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const continue_js_1 = require("./continue.js");
+const checkpoint_js_1 = require("./checkpoint.js");
+function makeTestDir() {
+    const dir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `polaris-loop-test-${Date.now()}`);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    // Minimal git repo so branch detection doesn't blow up
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(dir, ".git"), { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, ".git/HEAD"), "ref: refs/heads/test-branch\n");
+    return dir;
+}
+function writeState(dir, state) {
+    const stateFile = (0, node_path_1.join)(dir, ".polaris", "runs", "current-state.json");
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(dir, ".polaris", "runs"), { recursive: true });
+    (0, node_fs_1.writeFileSync)(stateFile, JSON.stringify(state, null, 2));
+    return stateFile;
+}
+(0, vitest_1.describe)("validateState", () => {
+    (0, vitest_1.it)("returns no errors for a valid state", () => {
+        const state = {
+            schema_version: "1.0",
+            run_id: "test-run-1",
+            cluster_id: "POL-5",
+            active_child: "POL-23",
+            completed_children: [],
+            open_children: ["POL-24"],
+            step_cursor: "03-execute-child",
+            context_budget: { children_completed: 0 },
+            status: "running",
+            next_open_child: "POL-24",
+        };
+        (0, vitest_1.expect)((0, checkpoint_js_1.validateState)(state)).toEqual([]);
+    });
+    (0, vitest_1.it)("returns errors for missing required fields", () => {
+        const errors = (0, checkpoint_js_1.validateState)({ schema_version: "1.0" });
+        (0, vitest_1.expect)(errors.length).toBeGreaterThan(0);
+        (0, vitest_1.expect)(errors.some((e) => e.includes("run_id"))).toBe(true);
+    });
+    (0, vitest_1.it)("rejects non-object input", () => {
+        (0, vitest_1.expect)((0, checkpoint_js_1.validateState)("string")).toContain("current-state.json must be a JSON object");
+        (0, vitest_1.expect)((0, checkpoint_js_1.validateState)(null)).toContain("current-state.json must be a JSON object");
+    });
+});
+(0, vitest_1.describe)("runLoopContinue", () => {
+    let testDir;
+    (0, vitest_1.beforeEach)(() => {
+        testDir = makeTestDir();
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(testDir, ".polaris", "bootstrap"), { recursive: true });
+    });
+    (0, vitest_1.afterEach)(() => {
+        (0, node_fs_1.rmSync)(testDir, { recursive: true, force: true });
+    });
+    (0, vitest_1.it)("writes a bootstrap packet to .polaris/bootstrap/", () => {
+        const state = {
+            schema_version: "1.0",
+            run_id: "pol-5-session-1",
+            cluster_id: "POL-5",
+            active_child: "POL-23",
+            completed_children: [],
+            open_children: ["POL-24", "POL-25", "POL-26", "POL-27"],
+            step_cursor: "03-execute-child",
+            context_budget: { children_completed: 0, max_children_per_session: 3 },
+            status: "running",
+            next_open_child: "POL-24",
+        };
+        const stateFile = writeState(testDir, state);
+        // Capture stdout
+        const stdoutChunks = [];
+        const originalWrite = process.stdout.write.bind(process.stdout);
+        process.stdout.write = (chunk) => {
+            stdoutChunks.push(chunk.toString());
+            return true;
+        };
+        try {
+            (0, continue_js_1.runLoopContinue)({ stateFile, repoRoot: testDir });
+        }
+        finally {
+            process.stdout.write = originalWrite;
+        }
+        // Bootstrap packet written to disk
+        const bootstrapDir = (0, node_path_1.join)(testDir, ".polaris", "bootstrap");
+        const packets = require("node:fs").readdirSync(bootstrapDir).filter((f) => f.endsWith(".json"));
+        (0, vitest_1.expect)(packets.length).toBe(1);
+        const packet = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(bootstrapDir, packets[0]), "utf-8"));
+        (0, vitest_1.expect)(packet.run_id).toBe("pol-5-session-1");
+        (0, vitest_1.expect)(packet.last_completed_child).toBe("POL-23");
+        (0, vitest_1.expect)(packet.current_state_sha).toBeTruthy();
+        (0, vitest_1.expect)(packet.open_children).toEqual(["POL-24", "POL-25", "POL-26", "POL-27"]);
+        (0, vitest_1.expect)(packet.execution_adapter.mode).toBe("terminal-cli");
+        (0, vitest_1.expect)(packet.execution_adapter.compact_bootstrap_state.child_id).toBe("POL-24");
+    });
+    (0, vitest_1.it)("updates current-state.json atomically (moves active_child to completed)", () => {
+        const state = {
+            schema_version: "1.0",
+            run_id: "pol-5-session-1",
+            cluster_id: "POL-5",
+            active_child: "POL-23",
+            completed_children: [],
+            open_children: ["POL-24"],
+            step_cursor: "03-execute-child",
+            context_budget: { children_completed: 0, max_children_per_session: 3 },
+            status: "running",
+            next_open_child: "POL-24",
+        };
+        const stateFile = writeState(testDir, state);
+        const originalWrite = process.stdout.write.bind(process.stdout);
+        process.stdout.write = () => true;
+        try {
+            (0, continue_js_1.runLoopContinue)({ stateFile, repoRoot: testDir });
+        }
+        finally {
+            process.stdout.write = originalWrite;
+        }
+        const updated = (0, checkpoint_js_1.readState)(stateFile);
+        (0, vitest_1.expect)(updated.completed_children).toContain("POL-23");
+        (0, vitest_1.expect)(updated.active_child).toBe("");
+        (0, vitest_1.expect)(updated.open_children).toEqual(["POL-24"]);
+        (0, vitest_1.expect)(updated.context_budget.children_completed).toBe(1);
+    });
+    (0, vitest_1.it)("removes completed child from open_children before selecting next child", () => {
+        const state = {
+            schema_version: "1.0",
+            run_id: "pol-5-session-1",
+            cluster_id: "POL-5",
+            active_child: "POL-23",
+            completed_children: [],
+            open_children: ["POL-23", "POL-24"],
+            step_cursor: "03-execute-child",
+            context_budget: { children_completed: 0, max_children_per_session: 3 },
+            status: "running",
+            next_open_child: "POL-23",
+        };
+        const stateFile = writeState(testDir, state);
+        const logs = [];
+        const origLog = console.log;
+        console.log = (...args) => logs.push(args.map(String).join(" "));
+        try {
+            (0, continue_js_1.runLoopContinue)({ stateFile, repoRoot: testDir });
+        }
+        finally {
+            console.log = origLog;
+        }
+        const updated = (0, checkpoint_js_1.readState)(stateFile);
+        const packet = JSON.parse(logs.join("\n"));
+        (0, vitest_1.expect)(updated.completed_children).toEqual(["POL-23"]);
+        (0, vitest_1.expect)(updated.open_children).toEqual(["POL-24"]);
+        (0, vitest_1.expect)(updated.next_open_child).toBe("POL-24");
+        (0, vitest_1.expect)(packet.open_children).toEqual(["POL-24"]);
+        (0, vitest_1.expect)(packet.execution_adapter.compact_bootstrap_state.child_id).toBe("POL-24");
+    });
+    (0, vitest_1.it)("appends a JSONL checkpoint event to telemetry file", () => {
+        const state = {
+            schema_version: "1.0",
+            run_id: "pol-5-session-1",
+            cluster_id: "POL-5",
+            active_child: "POL-23",
+            completed_children: [],
+            open_children: ["POL-24"],
+            step_cursor: "03-execute-child",
+            context_budget: { children_completed: 0, max_children_per_session: 3 },
+            status: "running",
+            next_open_child: "POL-24",
+            artifact_dir: (0, node_path_1.join)(testDir, ".taskchain_artifacts", "bootstrap-run"),
+        };
+        const stateFile = writeState(testDir, state);
+        const originalWrite = process.stdout.write.bind(process.stdout);
+        process.stdout.write = () => true;
+        try {
+            (0, continue_js_1.runLoopContinue)({ stateFile, repoRoot: testDir });
+        }
+        finally {
+            process.stdout.write = originalWrite;
+        }
+        const telemetryFile = (0, node_path_1.join)(testDir, ".taskchain_artifacts", "bootstrap-run", "runs", "pol-5-session-1", "telemetry.jsonl");
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)(telemetryFile)).toBe(true);
+        const lines = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8")
+            .trim()
+            .split("\n")
+            .map((l) => JSON.parse(l));
+        const line = lines.find((e) => e.event === "loop-checkpoint");
+        (0, vitest_1.expect)(line).toBeTruthy();
+        (0, vitest_1.expect)(line.run_id).toBe("pol-5-session-1");
+        (0, vitest_1.expect)(line.child_id).toBe("POL-23");
+    });
+    (0, vitest_1.it)("emits bootstrap packet JSON to stdout", () => {
+        const state = {
+            schema_version: "1.0",
+            run_id: "pol-5-session-1",
+            cluster_id: "POL-5",
+            active_child: "POL-23",
+            completed_children: [],
+            open_children: ["POL-24"],
+            step_cursor: "03-execute-child",
+            context_budget: { children_completed: 0, max_children_per_session: 3 },
+            status: "running",
+            next_open_child: "POL-24",
+        };
+        const stateFile = writeState(testDir, state);
+        const stdoutChunks = [];
+        const originalWrite = process.stdout.write.bind(process.stdout);
+        const originalLog = console.log;
+        const logs = [];
+        console.log = (...args) => logs.push(args.map(String).join(" "));
+        process.stdout.write = (chunk) => {
+            stdoutChunks.push(chunk.toString());
+            return true;
+        };
+        try {
+            (0, continue_js_1.runLoopContinue)({ stateFile, repoRoot: testDir });
+        }
+        finally {
+            process.stdout.write = originalWrite;
+            console.log = originalLog;
+        }
+        const output = logs.join("\n");
+        const packet = JSON.parse(output);
+        (0, vitest_1.expect)(packet.current_state_sha).toBeTruthy();
+        (0, vitest_1.expect)(packet.run_id).toBe("pol-5-session-1");
+    });
+    (0, vitest_1.it)("exits with error if state file missing", () => {
+        const exitSpy = vitest_1.vi.spyOn(process, "exit").mockImplementation(() => {
+            throw new Error("process.exit called");
+        });
+        (0, vitest_1.expect)(() => (0, continue_js_1.runLoopContinue)({
+            stateFile: (0, node_path_1.join)(testDir, "nonexistent.json"),
+            repoRoot: testDir,
+        })).toThrow();
+        exitSpy.mockRestore();
+    });
+    (0, vitest_1.it)("exits with error if state file is invalid", () => {
+        const stateFile = (0, node_path_1.join)(testDir, ".polaris", "runs", "current-state.json");
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(testDir, ".polaris", "runs"), { recursive: true });
+        (0, node_fs_1.writeFileSync)(stateFile, JSON.stringify({ schema_version: "1.0" }));
+        const exitSpy = vitest_1.vi.spyOn(process, "exit").mockImplementation(() => {
+            throw new Error("process.exit called");
+        });
+        const stderrSpy = vitest_1.vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        (0, vitest_1.expect)(() => (0, continue_js_1.runLoopContinue)({ stateFile, repoRoot: testDir })).toThrow();
+        exitSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+    (0, vitest_1.it)("sets boundary_enforcement in packet when analyze→implement boundary fires", () => {
+        const state = {
+            schema_version: "1.0",
+            run_id: "pol-5-session-1",
+            cluster_id: "POL-5",
+            active_child: "POL-23",
+            session_type: "analyze",
+            completed_children: [],
+            open_children: ["POL-24"],
+            open_children_meta: { "POL-24": { type: "implement" } },
+            step_cursor: "03-execute-child",
+            context_budget: { children_completed: 0, max_children_per_session: 3 },
+            status: "running",
+            next_open_child: "POL-24",
+        };
+        const stateFile = writeState(testDir, state);
+        const logs = [];
+        const origLog = console.log;
+        console.log = (...args) => logs.push(args.map(String).join(" "));
+        try {
+            (0, continue_js_1.runLoopContinue)({ stateFile, repoRoot: testDir });
+        }
+        finally {
+            console.log = origLog;
+        }
+        const packet = JSON.parse(logs.join("\n"));
+        (0, vitest_1.expect)(packet.boundary_enforcement).toContain("analyze-session-ended");
+    });
+    (0, vitest_1.it)("emits boundary JSONL event to telemetry when boundary fires", () => {
+        const state = {
+            schema_version: "1.0",
+            run_id: "pol-5-session-1",
+            cluster_id: "POL-5",
+            active_child: "POL-23",
+            session_type: "analyze",
+            completed_children: [],
+            open_children: ["POL-24"],
+            open_children_meta: { "POL-24": { type: "implement" } },
+            step_cursor: "03-execute-child",
+            context_budget: { children_completed: 0, max_children_per_session: 3 },
+            status: "running",
+            next_open_child: "POL-24",
+            artifact_dir: (0, node_path_1.join)(testDir, ".taskchain_artifacts", "bootstrap-run"),
+        };
+        const stateFile = writeState(testDir, state);
+        const origLog = console.log;
+        console.log = () => { };
+        try {
+            (0, continue_js_1.runLoopContinue)({ stateFile, repoRoot: testDir });
+        }
+        finally {
+            console.log = origLog;
+        }
+        const telemetryFile = (0, node_path_1.join)(testDir, ".taskchain_artifacts", "bootstrap-run", "runs", "pol-5-session-1", "telemetry.jsonl");
+        const lines = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8")
+            .trim()
+            .split("\n")
+            .map((l) => JSON.parse(l));
+        const boundaryEvent = lines.find((e) => e.event === "analyze-impl-boundary-enforced");
+        (0, vitest_1.expect)(boundaryEvent).toBeTruthy();
+        (0, vitest_1.expect)(boundaryEvent.stopped_before).toBe("POL-24");
+    });
+    (0, vitest_1.it)("does NOT set boundary_enforcement when both are implement type", () => {
+        const state = {
+            schema_version: "1.0",
+            run_id: "pol-5-session-1",
+            cluster_id: "POL-5",
+            active_child: "POL-23",
+            session_type: "implement",
+            completed_children: [],
+            open_children: ["POL-24"],
+            open_children_meta: { "POL-24": { type: "implement" } },
+            step_cursor: "03-execute-child",
+            context_budget: { children_completed: 0, max_children_per_session: 3 },
+            status: "running",
+            next_open_child: "POL-24",
+        };
+        const stateFile = writeState(testDir, state);
+        const logs = [];
+        const origLog = console.log;
+        console.log = (...args) => logs.push(args.map(String).join(" "));
+        try {
+            (0, continue_js_1.runLoopContinue)({ stateFile, repoRoot: testDir });
+        }
+        finally {
+            console.log = origLog;
+        }
+        const packet = JSON.parse(logs.join("\n"));
+        (0, vitest_1.expect)(packet.boundary_enforcement).toBeUndefined();
+    });
+});

package/dist/loop/dispatch-boundary.js

@@ -0,0 +1,335 @@
+"use strict";
+/**
+ * Polaris Dispatch Boundary Enforcement
+ *
+ * The dispatch boundary is a hard runtime constraint enforced by the Polaris
+ * runtime. The parent/orchestrator MUST call `polaris loop dispatch` before
+ * any child execution. Inline child execution by the parent/orchestrator is
+ * FORBIDDEN. Models do not decide execution legality — the runtime owns it.
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * Allowed state transitions (enforced at runtime):
+ *
+ *   selected       → dispatched        (via polaris loop dispatch)
+ *   dispatched     → worker-running    (via adapter dispatch)
+ *   worker-running → worker-completed  (via worker CompactReturn)
+ *   worker-completed → checkpointed    (via polaris loop continue)
+ *   dispatched     → checkpointed      (worker wrote own completion)
+ *   checkpointed   → dispatched        (via polaris loop dispatch, next child)
+ *   checkpointed   → cluster-complete  (no remaining children)
+ *   *              → blocked           (via polaris loop abort)
+ *   *              → budget-exhausted  (via budget check)
+ *
+ * Disallowed transitions (hard failure + telemetry):
+ *
+ *   selected → completed               (no dispatch: inline completion)
+ *   selected → checkpointed            (no dispatch: fake checkpoint)
+ *   selected → implementation-inline   (parent doing child work directly)
+ *   idle     → worker-completed        (worker completed without dispatch)
+ *   idle     → checkpointed            (continue called without dispatch)
+ * ──────────────────────────────────────────────────────────────────────────
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DISALLOWED_TRANSITIONS = exports.ALLOWED_TRANSITIONS = exports.DISPATCH_REQUIRED_ERROR = exports.LIBRARIAN_GATE_ERROR = exports.INLINE_EXECUTION_ERROR = void 0;
+exports.getMachineState = getMachineState;
+exports.appendDispatchViolationEvent = appendDispatchViolationEvent;
+exports.assertNoActiveChildBeforeDispatch = assertNoActiveChildBeforeDispatch;
+exports.assertContinueRequiresDispatch = assertContinueRequiresDispatch;
+exports.assertDispatchedBeforeCompletion = assertDispatchedBeforeCompletion;
+exports.validateTransition = validateTransition;
+exports.initialDispatchBoundary = initialDispatchBoundary;
+exports.advanceDispatchEpoch = advanceDispatchEpoch;
+exports.advanceContinueEpoch = advanceContinueEpoch;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ──────────────────────────────────────────────────────────────────────────────
+// Error constants
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Error emitted when the parent/orchestrator attempts inline child execution.
+ * This is the canonical error message for dispatch boundary violations.
+ */
+exports.INLINE_EXECUTION_ERROR = "Child execution requires dispatch boundary. Parent/orchestrator may not implement child inline. Use npm run polaris -- loop dispatch.";
+/**
+ * Error emitted when PR creation is attempted without a passing Librarian gate.
+ */
+exports.LIBRARIAN_GATE_ERROR = "PR creation requires Closeout Librarian gate. Generate packet with `polaris librarian packet <cluster-id>`, dispatch the Librarian, then re-run finalize.";
+/**
+ * Error emitted when `polaris loop continue` is called without a prior dispatch.
+ */
+exports.DISPATCH_REQUIRED_ERROR = "Dispatch required before continuation. Call `npm run polaris -- loop dispatch` first, then run the worker before calling continue.";
+/**
+ * Allowed transitions in the dispatch state machine.
+ * Format: [from, to, command-that-drives-transition]
+ */
+exports.ALLOWED_TRANSITIONS = [
+    // Primary dispatch flow
+    ["idle", "dispatched", "polaris loop dispatch"],
+    ["checkpointed", "dispatched", "polaris loop dispatch"],
+    ["dispatched", "worker-running", "adapter-dispatch"],
+    ["worker-running", "worker-completed", "worker-compact-return"],
+    ["dispatched", "worker-completed", "worker-compact-return"],
+    ["worker-completed", "checkpointed", "polaris loop continue"],
+    ["dispatched", "checkpointed", "polaris loop continue"], // Worker wrote own completion
+    ["checkpointed", "cluster-complete", "polaris loop continue"],
+    // Halt paths (allowed from any operational state)
+    ["idle", "blocked", "polaris loop abort"],
+    ["dispatched", "blocked", "polaris loop abort"],
+    ["worker-running", "blocked", "polaris loop abort"],
+    ["worker-completed", "blocked", "polaris loop abort"],
+    ["checkpointed", "blocked", "polaris loop abort"],
+    // Budget exhaustion (allowed from any operational state)
+    ["idle", "budget-exhausted", "budget-check"],
+    ["dispatched", "budget-exhausted", "budget-check"],
+    ["checkpointed", "budget-exhausted", "budget-check"],
+    // Librarian phase (post cluster-complete, pre PR-creation)
+    ["cluster-complete", "librarian-dispatched", "polaris librarian packet + dispatch"],
+    ["librarian-dispatched", "librarian-complete", "librarian-sealed-result"],
+    ["librarian-complete", "librarian-complete", "finalize-delivery-attempt"], // delivery proceeds after librarian gate
+];
+/**
+ * Transitions that are explicitly forbidden. These represent illegal paths
+ * that indicate inline execution or state machine violations.
+ */
+exports.DISALLOWED_TRANSITIONS = [
+    ["idle", "worker-completed", "attempted worker completion without prior dispatch"],
+    ["idle", "checkpointed", "attempted continue without prior dispatch"],
+    ["idle", "cluster-complete", "attempted cluster completion without dispatch"],
+    ["selected", "completed", "attempted inline completion without dispatch"],
+    ["selected", "checkpointed", "attempted checkpoint without dispatch"],
+    ["selected", "implementation-inline", "parent doing child work directly (forbidden)"],
+];
+// ──────────────────────────────────────────────────────────────────────────────
+// State derivation
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Derive the logical dispatch machine state from the current LoopState.
+ * Uses dispatch_boundary epochs when present; falls back to step_cursor
+ * for states written before dispatch_boundary was introduced.
+ */
+function getMachineState(state) {
+    // Terminal status values map directly to machine states
+    if (state.status === "cluster-complete")
+        return "cluster-complete";
+    if (state.status === "blocked")
+        return "blocked";
+    if (state.status === "budget-exhausted")
+        return "budget-exhausted";
+    const boundary = state.dispatch_boundary;
+    if (boundary) {
+        const { dispatch_epoch, continue_epoch } = boundary;
+        if (dispatch_epoch > continue_epoch) {
+            // Dispatch was called more times than continue — either dispatched or worker-completed
+            if (state.active_child && state.active_child !== "") {
+                // active_child is set → dispatch in progress, worker may be running
+                return "dispatched";
+            }
+            // active_child is cleared by worker → worker has returned, awaiting continue
+            return "worker-completed";
+        }
+        // dispatch_epoch === continue_epoch
+        if (dispatch_epoch === 0 && continue_epoch === 0)
+            return "idle";
+        return "checkpointed";
+    }
+    // Legacy fallback: no dispatch_boundary field present
+    // Infer from step_cursor and active_child
+    if (state.step_cursor === "dispatch") {
+        return state.active_child ? "dispatched" : "worker-completed";
+    }
+    if (state.step_cursor === "checkpoint") {
+        // Could be checkpointed (after continue) or worker-completed (before continue)
+        // We cannot distinguish safely, so treat as checkpointed (the safe state)
+        return "checkpointed";
+    }
+    return "idle";
+}
+/**
+ * Append a dispatch boundary violation event to the telemetry file.
+ * Must only emit on failure paths, not normal flow.
+ *
+ * Telemetry write failures are silently swallowed to ensure the
+ * enforcement error is always surfaced to the caller.
+ */
+function appendDispatchViolationEvent(telemetryFile, event) {
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+        (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(event) + "\n", "utf-8");
+    }
+    catch {
+        // Telemetry write failure must not mask the underlying enforcement error
+    }
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Enforcement guards
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Assert that no child is already active before the parent/orchestrator
+ * attempts to dispatch another child.
+ *
+ * If `active_child` is set, it means a previous dispatch was not properly
+ * completed. The parent must NOT re-dispatch or complete inline — it must
+ * halt and require manual resolution.
+ *
+ * @throws Error with INLINE_EXECUTION_ERROR if active_child is already set
+ */
+function assertNoActiveChildBeforeDispatch(state, telemetryFile) {
+    if (state.active_child && state.active_child !== "") {
+        appendDispatchViolationEvent(telemetryFile, {
+            event: "invalid-inline-attempt",
+            run_id: state.run_id,
+            child_id: state.active_child,
+            from_state: getMachineState(state),
+            to_state: "dispatched",
+            reason: `active_child is already set to "${state.active_child}". Previous dispatch not completed. ` + exports.INLINE_EXECUTION_ERROR,
+            timestamp: new Date().toISOString(),
+        });
+        throw new Error(`active_child is already set to "${state.active_child}". Previous dispatch was not completed. ` +
+            exports.INLINE_EXECUTION_ERROR +
+            " Use `npm run polaris -- loop abort` to reset blocked state.");
+    }
+}
+/**
+ * Assert that `polaris loop dispatch` was called before allowing
+ * `polaris loop continue` to checkpoint state.
+ *
+ * The check uses dispatch_boundary epochs when present (primary),
+ * and falls back to step_cursor for legacy states.
+ *
+ * @throws Error with DISPATCH_REQUIRED_ERROR if no dispatch preceded this continue
+ */
+function assertContinueRequiresDispatch(state, telemetryFile) {
+    const boundary = state.dispatch_boundary;
+    let wasDispatched;
+    if (boundary) {
+        // Primary check: dispatch_epoch must be strictly greater than continue_epoch
+        wasDispatched = boundary.dispatch_epoch > boundary.continue_epoch;
+    }
+    else {
+        // Legacy fallback: no dispatch_boundary field present.
+        //
+        // dispatch.ts is the ONLY place that sets active_child. If active_child is
+        // non-empty, dispatch was called (and the worker hasn't cleared it yet).
+        // If step_cursor is "dispatch", dispatch was called (standard case).
+        // If step_cursor is "checkpoint" with active_child cleared, we cannot tell
+        // for certain — a conservative rejection would break existing flows, so we
+        // accept it for legacy states (dispatch_boundary was not yet tracking).
+        wasDispatched =
+            (state.active_child !== "" && state.active_child !== undefined && state.active_child !== null) ||
+                state.step_cursor === "dispatch" ||
+                state.step_cursor === "checkpoint";
+    }
+    if (!wasDispatched) {
+        appendDispatchViolationEvent(telemetryFile, {
+            event: "dispatch-required",
+            run_id: state.run_id,
+            child_id: state.active_child || undefined,
+            from_state: getMachineState(state),
+            to_state: "checkpointed",
+            reason: exports.DISPATCH_REQUIRED_ERROR,
+            timestamp: new Date().toISOString(),
+        });
+        throw new Error(exports.DISPATCH_REQUIRED_ERROR);
+    }
+}
+/**
+ * Assert that a dispatched child completion is valid.
+ *
+ * Before the parent/orchestrator advances state to mark a child as completed,
+ * verify that the dispatch boundary was properly established. If no dispatch
+ * was recorded, the child cannot be marked as complete.
+ *
+ * @param state - Current (post-worker-return) loop state
+ * @param childId - Child being completed
+ * @param telemetryFile - Telemetry file path
+ * @throws Error with INLINE_EXECUTION_ERROR if dispatch boundary was not set
+ */
+function assertDispatchedBeforeCompletion(state, childId, telemetryFile) {
+    const boundary = state.dispatch_boundary;
+    let dispatchHappened;
+    if (boundary) {
+        // dispatch_epoch > continue_epoch means dispatch was called and not yet matched
+        dispatchHappened =
+            boundary.dispatch_epoch > boundary.continue_epoch &&
+                (boundary.last_dispatched_child === childId || !boundary.last_dispatched_child);
+    }
+    else {
+        // Legacy: step_cursor "dispatch" set by polaris loop dispatch
+        dispatchHappened =
+            state.step_cursor === "dispatch" ||
+                // Worker may have already updated step_cursor to "checkpoint"
+                (state.step_cursor === "checkpoint" && state.active_child === "");
+    }
+    if (!dispatchHappened) {
+        appendDispatchViolationEvent(telemetryFile, {
+            event: "illegal-state-transition",
+            run_id: state.run_id,
+            child_id: childId,
+            from_state: getMachineState(state),
+            to_state: "checkpointed",
+            reason: `Attempted to complete child "${childId}" without a prior dispatch event. ` +
+                exports.INLINE_EXECUTION_ERROR,
+            timestamp: new Date().toISOString(),
+        });
+        throw new Error(`Cannot complete child "${childId}" without a prior dispatch. ` + exports.INLINE_EXECUTION_ERROR);
+    }
+}
+/**
+ * Validate a state transition against the allowed transition graph.
+ *
+ * Returns an error message if the transition is illegal, or null if allowed.
+ * Emits an `illegal-state-transition` telemetry event on rejection.
+ * This function does NOT throw — the caller decides how to handle the error.
+ */
+function validateTransition(from, to, runId, telemetryFile, childId) {
+    const allowed = exports.ALLOWED_TRANSITIONS.some(([f, t]) => f === from && t === to);
+    if (allowed)
+        return null;
+    const reason = `Illegal state transition: ${from} → ${to}. Only transitions through polaris loop dispatch → worker → polaris loop continue are allowed.`;
+    appendDispatchViolationEvent(telemetryFile, {
+        event: "illegal-state-transition",
+        run_id: runId,
+        child_id: childId,
+        from_state: from,
+        to_state: to,
+        reason,
+        timestamp: new Date().toISOString(),
+    });
+    return reason;
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Dispatch boundary record builders
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Build an initial dispatch boundary record for a fresh state.
+ */
+function initialDispatchBoundary() {
+    return { dispatch_epoch: 0, continue_epoch: 0, last_dispatched_child: null };
+}
+/**
+ * Return the updated dispatch_boundary after a dispatch call.
+ * Increments dispatch_epoch and records the dispatched child.
+ */
+function advanceDispatchEpoch(current, childId) {
+    const base = current ?? initialDispatchBoundary();
+    return {
+        dispatch_epoch: base.dispatch_epoch + 1,
+        continue_epoch: base.continue_epoch,
+        last_dispatched_child: childId,
+    };
+}
+/**
+ * Return the updated dispatch_boundary after a successful continue call.
+ * Increments continue_epoch to match the consumed dispatch.
+ */
+function advanceContinueEpoch(current) {
+    // If no boundary exists yet, return a fresh one without incrementing
+    if (current === undefined || current === null) {
+        return initialDispatchBoundary();
+    }
+    return {
+        dispatch_epoch: current.dispatch_epoch,
+        continue_epoch: current.continue_epoch + 1,
+        last_dispatched_child: current.last_dispatched_child,
+    };
+}