@lsctech/polaris 0.1.0

package/dist/loop/budget.test.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Unit tests for budget policy evaluation (src/loop/budget.ts).
+ *
+ * Covers:
+ * - fixed-cap mode: stop after max_children, continue before cap
+ * - run-until-done mode: always continue regardless of count
+ * - stop-on-fail mode: halt when lastChildStatus is "failed"
+ * - stop_on_fail flag: halts across all modes when a child fails
+ * - No-config default: 3-child fixed-cap (backwards compatibility)
+ * - policyFromConfig: precedence of config over state
+ * - policyFromState: backwards-compat shim
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const budget_js_1 = require("./budget.js");
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function makePolicy(overrides = {}) {
+    return {
+        mode: "fixed-cap",
+        maxChildrenPerSession: 3,
+        stopOnFail: false,
+        ...overrides,
+    };
+}
+// ── fixed-cap mode ────────────────────────────────────────────────────────────
+(0, vitest_1.describe)("checkBudget / fixed-cap", () => {
+    (0, vitest_1.it)("returns ok when children completed is below cap", () => {
+        const result = (0, budget_js_1.checkBudget)({
+            childrenCompleted: 2,
+            policy: makePolicy({ mode: "fixed-cap", maxChildrenPerSession: 3 }),
+        });
+        (0, vitest_1.expect)(result.status).toBe("ok");
+    });
+    (0, vitest_1.it)("returns exhausted when children completed equals cap", () => {
+        const result = (0, budget_js_1.checkBudget)({
+            childrenCompleted: 3,
+            policy: makePolicy({ mode: "fixed-cap", maxChildrenPerSession: 3 }),
+        });
+        (0, vitest_1.expect)(result.status).toBe("exhausted");
+        if (result.status === "exhausted") {
+            (0, vitest_1.expect)(result.reason).toMatch(/3 of 3/);
+        }
+    });
+    (0, vitest_1.it)("returns exhausted when children completed exceeds cap", () => {
+        const result = (0, budget_js_1.checkBudget)({
+            childrenCompleted: 5,
+            policy: makePolicy({ mode: "fixed-cap", maxChildrenPerSession: 3 }),
+        });
+        (0, vitest_1.expect)(result.status).toBe("exhausted");
+    });
+    (0, vitest_1.it)("respects a custom cap of 5", () => {
+        const policy = makePolicy({ mode: "fixed-cap", maxChildrenPerSession: 5 });
+        // 4 done → ok
+        (0, vitest_1.expect)((0, budget_js_1.checkBudget)({ childrenCompleted: 4, policy }).status).toBe("ok");
+        // 5 done → exhausted
+        (0, vitest_1.expect)((0, budget_js_1.checkBudget)({ childrenCompleted: 5, policy }).status).toBe("exhausted");
+    });
+    (0, vitest_1.it)("returns ok at 0 children with cap 3 (no-config default behavior)", () => {
+        const result = (0, budget_js_1.checkBudget)({
+            childrenCompleted: 0,
+            policy: makePolicy({ mode: "fixed-cap", maxChildrenPerSession: 3 }),
+        });
+        (0, vitest_1.expect)(result.status).toBe("ok");
+    });
+});
+// ── run-until-done mode ───────────────────────────────────────────────────────
+(0, vitest_1.describe)("checkBudget / run-until-done", () => {
+    (0, vitest_1.it)("always returns ok regardless of children completed", () => {
+        const policy = makePolicy({ mode: "run-until-done", maxChildrenPerSession: 3 });
+        for (const n of [0, 3, 10, 100]) {
+            (0, vitest_1.expect)((0, budget_js_1.checkBudget)({ childrenCompleted: n, policy }).status).toBe("ok");
+        }
+    });
+    (0, vitest_1.it)("runs all open children without stopping at 3", () => {
+        const policy = makePolicy({ mode: "run-until-done", maxChildrenPerSession: 3 });
+        // Even at 50 completed, budget is not exhausted
+        (0, vitest_1.expect)((0, budget_js_1.checkBudget)({ childrenCompleted: 50, policy }).status).toBe("ok");
+    });
+});
+// ── stop-on-fail mode ─────────────────────────────────────────────────────────
+(0, vitest_1.describe)("checkBudget / stop-on-fail mode", () => {
+    (0, vitest_1.it)("returns ok when no child has failed", () => {
+        const policy = makePolicy({ mode: "stop-on-fail", stopOnFail: true, maxChildrenPerSession: 100 });
+        (0, vitest_1.expect)((0, budget_js_1.checkBudget)({ childrenCompleted: 5, policy }).status).toBe("ok");
+    });
+    (0, vitest_1.it)("does not halt on successful child status", () => {
+        const policy = makePolicy({ mode: "stop-on-fail", stopOnFail: true, maxChildrenPerSession: 100 });
+        (0, vitest_1.expect)((0, budget_js_1.checkBudget)({ childrenCompleted: 1, lastChildStatus: "done", policy }).status).toBe("ok");
+    });
+});
+// ── stopOnFail flag (cross-mode) ──────────────────────────────────────────────
+(0, vitest_1.describe)("checkBudget / stopOnFail flag", () => {
+    (0, vitest_1.it)("halts when lastChildStatus is 'failed' and stopOnFail is true", () => {
+        const policy = makePolicy({ mode: "fixed-cap", maxChildrenPerSession: 10, stopOnFail: true });
+        const result = (0, budget_js_1.checkBudget)({ childrenCompleted: 1, lastChildStatus: "failed", policy });
+        (0, vitest_1.expect)(result.status).toBe("exhausted");
+        if (result.status === "exhausted") {
+            (0, vitest_1.expect)(result.reason).toMatch(/stop_on_fail/);
+        }
+    });
+    (0, vitest_1.it)("does not halt when lastChildStatus is 'failed' but stopOnFail is false", () => {
+        const policy = makePolicy({ mode: "fixed-cap", maxChildrenPerSession: 10, stopOnFail: false });
+        const result = (0, budget_js_1.checkBudget)({ childrenCompleted: 1, lastChildStatus: "failed", policy });
+        (0, vitest_1.expect)(result.status).toBe("ok");
+    });
+    (0, vitest_1.it)("halts on failed child in run-until-done mode when stopOnFail is true", () => {
+        const policy = makePolicy({ mode: "run-until-done", maxChildrenPerSession: 100, stopOnFail: true });
+        const result = (0, budget_js_1.checkBudget)({ childrenCompleted: 2, lastChildStatus: "failed", policy });
+        (0, vitest_1.expect)(result.status).toBe("exhausted");
+    });
+});
+// ── policyFromConfig ──────────────────────────────────────────────────────────
+(0, vitest_1.describe)("policyFromConfig", () => {
+    (0, vitest_1.it)("uses default 3-child fixed-cap when no config provided", () => {
+        const policy = (0, budget_js_1.policyFromConfig)({});
+        (0, vitest_1.expect)(policy.mode).toBe("fixed-cap");
+        (0, vitest_1.expect)(policy.maxChildrenPerSession).toBe(3);
+        (0, vitest_1.expect)(policy.stopOnFail).toBe(false);
+    });
+    (0, vitest_1.it)("falls back to state max_children_per_session when no config budget", () => {
+        const policy = (0, budget_js_1.policyFromConfig)({ max_children_per_session: 7 });
+        (0, vitest_1.expect)(policy.maxChildrenPerSession).toBe(7);
+    });
+    (0, vitest_1.it)("config max_children overrides state max_children_per_session", () => {
+        const policy = (0, budget_js_1.policyFromConfig)({ max_children_per_session: 2 }, { mode: "fixed-cap", max_children: 5 });
+        (0, vitest_1.expect)(policy.maxChildrenPerSession).toBe(5);
+    });
+    (0, vitest_1.it)("reads run-until-done mode from config", () => {
+        const policy = (0, budget_js_1.policyFromConfig)({}, { mode: "run-until-done" });
+        (0, vitest_1.expect)(policy.mode).toBe("run-until-done");
+    });
+    (0, vitest_1.it)("reads stop_on_fail from config", () => {
+        const policy = (0, budget_js_1.policyFromConfig)({}, { stop_on_fail: true });
+        (0, vitest_1.expect)(policy.stopOnFail).toBe(true);
+    });
+});
+// ── policyFromState (backwards compat) ────────────────────────────────────────
+(0, vitest_1.describe)("policyFromState (backwards compat)", () => {
+    (0, vitest_1.it)("returns 3-child fixed-cap when state has no max_children_per_session", () => {
+        const policy = (0, budget_js_1.policyFromState)({});
+        (0, vitest_1.expect)(policy.mode).toBe("fixed-cap");
+        (0, vitest_1.expect)(policy.maxChildrenPerSession).toBe(3);
+    });
+    (0, vitest_1.it)("respects max_children_per_session from state", () => {
+        const policy = (0, budget_js_1.policyFromState)({ max_children_per_session: 5 });
+        (0, vitest_1.expect)(policy.maxChildrenPerSession).toBe(5);
+    });
+});
+// ── no-config default backwards compatibility ─────────────────────────────────
+(0, vitest_1.describe)("no-config default (backwards compatibility)", () => {
+    (0, vitest_1.it)("defaults to 3-child fixed-cap with policyFromConfig and empty state", () => {
+        const policy = (0, budget_js_1.policyFromConfig)({}, undefined);
+        (0, vitest_1.expect)(policy.mode).toBe("fixed-cap");
+        (0, vitest_1.expect)(policy.maxChildrenPerSession).toBe(3);
+        (0, vitest_1.expect)(policy.stopOnFail).toBe(false);
+    });
+    (0, vitest_1.it)("exhausts after 3 children with default policy", () => {
+        const policy = (0, budget_js_1.policyFromConfig)({}, undefined);
+        (0, vitest_1.expect)((0, budget_js_1.checkBudget)({ childrenCompleted: 2, policy }).status).toBe("ok");
+        (0, vitest_1.expect)((0, budget_js_1.checkBudget)({ childrenCompleted: 3, policy }).status).toBe("exhausted");
+    });
+});

package/dist/loop/checkpoint.js

@@ -0,0 +1,325 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readState = readState;
+exports.validateState = validateState;
+exports.writeStateAtomic = writeStateAtomic;
+exports.appendCheckpointEvent = appendCheckpointEvent;
+exports.appendCompactReturnReceivedEvent = appendCompactReturnReceivedEvent;
+exports.appendWorkerScopeFidelityEvent = appendWorkerScopeFidelityEvent;
+exports.appendBoundaryEvent = appendBoundaryEvent;
+exports.appendAbortEvent = appendAbortEvent;
+exports.appendStaleDispatchAbortedEvent = appendStaleDispatchAbortedEvent;
+exports.readBodyFromClusterSnapshot = readBodyFromClusterSnapshot;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const monotonic_timestamp_js_1 = require("../utils/monotonic-timestamp.js");
+function readState(stateFile) {
+    const raw = (0, node_fs_1.readFileSync)(stateFile, "utf-8");
+    return JSON.parse(raw);
+}
+function validateState(state) {
+    const errors = [];
+    if (typeof state !== "object" || state === null) {
+        return ["current-state.json must be a JSON object"];
+    }
+    const s = state;
+    if (typeof s["schema_version"] !== "string")
+        errors.push("missing schema_version");
+    if (typeof s["run_id"] !== "string" || !s["run_id"])
+        errors.push("missing run_id");
+    if (typeof s["cluster_id"] !== "string" || !s["cluster_id"])
+        errors.push("missing cluster_id");
+    if (typeof s["active_child"] !== "string")
+        errors.push("missing active_child");
+    if (!Array.isArray(s["completed_children"]))
+        errors.push("completed_children must be an array");
+    if (!Array.isArray(s["open_children"]))
+        errors.push("open_children must be an array");
+    if (s["step_cursor"] !== null && typeof s["step_cursor"] !== "string")
+        errors.push("missing step_cursor");
+    if (typeof s["context_budget"] !== "object" || s["context_budget"] === null) {
+        errors.push("missing context_budget");
+    }
+    else {
+        const budget = s["context_budget"];
+        if (typeof budget["children_completed"] !== "number" || !isFinite(budget["children_completed"]))
+            errors.push("missing or invalid context_budget.children_completed");
+    }
+    if (typeof s["status"] !== "string")
+        errors.push("missing status");
+    // Validate completed_children_results if present
+    if ("completed_children_results" in s && s["completed_children_results"] !== undefined) {
+        if (typeof s["completed_children_results"] !== "object" || s["completed_children_results"] === null || Array.isArray(s["completed_children_results"])) {
+            errors.push("completed_children_results must be an object");
+        }
+        else {
+            const results = s["completed_children_results"];
+            for (const [childId, value] of Object.entries(results)) {
+                if (typeof value !== "object" || value === null || Array.isArray(value)) {
+                    errors.push(`completed_children_results["${childId}"] must be an object`);
+                    continue;
+                }
+                const childResult = value;
+                if (typeof childResult["status"] !== "string" || !["done", "failed", "blocked", "error"].includes(childResult["status"]))
+                    errors.push(`completed_children_results["${childId}"].status must be "done", "failed", "blocked", or "error"`);
+                if (typeof childResult["validation"] !== "string" || !["passed", "failed", "skipped"].includes(childResult["validation"]))
+                    errors.push(`completed_children_results["${childId}"].validation must be "passed", "failed", or "skipped"`);
+                if (childResult["commit"] !== null && typeof childResult["commit"] !== "string")
+                    errors.push(`completed_children_results["${childId}"].commit must be a string or null`);
+                if (typeof childResult["next_recommended_action"] !== "string" || !["continue", "stop", "investigate"].includes(childResult["next_recommended_action"]))
+                    errors.push(`completed_children_results["${childId}"].next_recommended_action must be "continue", "stop", or "investigate"`);
+                if ("result_data" in childResult && childResult["result_data"] !== undefined) {
+                    if (typeof childResult["result_data"] !== "object" || childResult["result_data"] === null || Array.isArray(childResult["result_data"])) {
+                        errors.push(`completed_children_results["${childId}"].result_data must be an object`);
+                    }
+                }
+            }
+        }
+    }
+    // Validate open_children_meta if present
+    if ("open_children_meta" in s && s["open_children_meta"] !== undefined) {
+        if (typeof s["open_children_meta"] !== "object" || s["open_children_meta"] === null || Array.isArray(s["open_children_meta"])) {
+            errors.push("open_children_meta must be an object");
+        }
+        else {
+            const meta = s["open_children_meta"];
+            for (const [childId, value] of Object.entries(meta)) {
+                if (typeof value !== "object" || value === null || Array.isArray(value)) {
+                    errors.push(`open_children_meta["${childId}"] must be an object`);
+                    continue;
+                }
+                const childMeta = value;
+                if ("type" in childMeta && childMeta["type"] !== undefined && typeof childMeta["type"] !== "string") {
+                    errors.push(`open_children_meta["${childId}"].type must be a string`);
+                }
+                if ("title" in childMeta && childMeta["title"] !== undefined && typeof childMeta["title"] !== "string") {
+                    errors.push(`open_children_meta["${childId}"].title must be a string`);
+                }
+                if ("body" in childMeta && childMeta["body"] !== undefined && typeof childMeta["body"] !== "string") {
+                    errors.push(`open_children_meta["${childId}"].body must be a string`);
+                }
+                if ("labels" in childMeta && childMeta["labels"] !== undefined) {
+                    if (!Array.isArray(childMeta["labels"]) || !childMeta["labels"].every((l) => typeof l === "string")) {
+                        errors.push(`open_children_meta["${childId}"].labels must be an array of strings`);
+                    }
+                }
+                // Validate dispatch_record if present
+                if ("dispatch_record" in childMeta && childMeta["dispatch_record"] !== undefined) {
+                    const dr = childMeta["dispatch_record"];
+                    if (typeof dr !== "object" || dr === null || Array.isArray(dr)) {
+                        errors.push(`open_children_meta["${childId}"].dispatch_record must be an object`);
+                    }
+                    else {
+                        if ("dispatch_mode" in dr && dr["dispatch_mode"] !== undefined) {
+                            if (!["delegated", "direct-worker"].includes(dr["dispatch_mode"])) {
+                                errors.push(`open_children_meta["${childId}"].dispatch_record.dispatch_mode must be "delegated" or "direct-worker"`);
+                            }
+                        }
+                        if ("runtime_state" in dr && dr["runtime_state"] !== undefined) {
+                            const validStates = ["packet-created", "delegated", "launching", "acknowledged", "running", "waiting-for-approval", "blocked", "completed", "failed", "orphaned"];
+                            if (!validStates.includes(dr["runtime_state"])) {
+                                errors.push(`open_children_meta["${childId}"].dispatch_record.runtime_state must be a valid WorkerRuntimeState`);
+                            }
+                        }
+                        if ("last_heartbeat_at" in dr && dr["last_heartbeat_at"] !== undefined && typeof dr["last_heartbeat_at"] !== "string") {
+                            errors.push(`open_children_meta["${childId}"].dispatch_record.last_heartbeat_at must be a string`);
+                        }
+                        if ("last_heartbeat_step" in dr && dr["last_heartbeat_step"] !== undefined && typeof dr["last_heartbeat_step"] !== "string") {
+                            errors.push(`open_children_meta["${childId}"].dispatch_record.last_heartbeat_step must be a string`);
+                        }
+                        // Validate worker_assignment if present
+                        if ("worker_assignment" in dr && dr["worker_assignment"] !== undefined) {
+                            const wa = dr["worker_assignment"];
+                            if (typeof wa !== "object" || wa === null || Array.isArray(wa)) {
+                                errors.push(`open_children_meta["${childId}"].dispatch_record.worker_assignment must be an object`);
+                            }
+                            else {
+                                if (typeof wa["assigned_at"] !== "string") {
+                                    errors.push(`open_children_meta["${childId}"].dispatch_record.worker_assignment.assigned_at must be a string`);
+                                }
+                                const validAssignmentTypes = ["subagent", "external-process", "human-handoff", "pending-escalation"];
+                                if (!validAssignmentTypes.includes(wa["assignment_type"])) {
+                                    errors.push(`open_children_meta["${childId}"].dispatch_record.worker_assignment.assignment_type must be a valid assignment type`);
+                                }
+                                // Conditional field validation based on assignment_type
+                                const assignmentType = wa["assignment_type"];
+                                if (assignmentType === "subagent") {
+                                    if (typeof wa["subagent_session_id"] !== "string" || wa["subagent_session_id"].length === 0) {
+                                        errors.push(`open_children_meta["${childId}"].dispatch_record.worker_assignment.subagent_session_id must be a non-empty string for subagent assignments`);
+                                    }
+                                }
+                                else if (assignmentType === "external-process") {
+                                    if (typeof wa["process_pid"] !== "number" || wa["process_pid"] <= 0) {
+                                        errors.push(`open_children_meta["${childId}"].dispatch_record.worker_assignment.process_pid must be a number greater than 0 for external-process assignments`);
+                                    }
+                                }
+                                else if (assignmentType === "human-handoff") {
+                                    if (typeof wa["handoff_token"] !== "string" || wa["handoff_token"].length === 0) {
+                                        errors.push(`open_children_meta["${childId}"].dispatch_record.worker_assignment.handoff_token must be a non-empty string for human-handoff assignments`);
+                                    }
+                                }
+                                else if (assignmentType === "pending-escalation") {
+                                    if (typeof wa["escalation_reason"] !== "string" || wa["escalation_reason"].length === 0) {
+                                        errors.push(`open_children_meta["${childId}"].dispatch_record.worker_assignment.escalation_reason must be a non-empty string for pending-escalation assignments`);
+                                    }
+                                }
+                            }
+                        }
+                        // Validate new ChildDispatchRecord fields
+                        if ("worker_id" in dr && dr["worker_id"] !== undefined) {
+                            if (typeof dr["worker_id"] !== "string" || dr["worker_id"].length === 0) {
+                                errors.push(`open_children_meta["${childId}"].dispatch_record.worker_id must be a non-empty string if present`);
+                            }
+                        }
+                        if ("session_id" in dr && dr["session_id"] !== undefined) {
+                            if (dr["session_id"] !== null && typeof dr["session_id"] !== "string") {
+                                errors.push(`open_children_meta["${childId}"].dispatch_record.session_id must be a string or null`);
+                            }
+                        }
+                        if ("attachment_capable" in dr && dr["attachment_capable"] !== undefined) {
+                            if (typeof dr["attachment_capable"] !== "boolean") {
+                                errors.push(`open_children_meta["${childId}"].dispatch_record.attachment_capable must be a boolean`);
+                            }
+                        }
+                        if ("heartbeat_count" in dr && dr["heartbeat_count"] !== undefined) {
+                            if (typeof dr["heartbeat_count"] !== "number" || !Number.isInteger(dr["heartbeat_count"]) || dr["heartbeat_count"] < 0) {
+                                errors.push(`open_children_meta["${childId}"].dispatch_record.heartbeat_count must be a non-negative integer`);
+                            }
+                        }
+                        if ("first_heartbeat_at" in dr && dr["first_heartbeat_at"] !== undefined) {
+                            if (typeof dr["first_heartbeat_at"] !== "string") {
+                                errors.push(`open_children_meta["${childId}"].dispatch_record.first_heartbeat_at must be a string (ISO timestamp) if present`);
+                            }
+                        }
+                        // Validate role context fields
+                        if ("role" in dr && dr["role"] !== undefined) {
+                            if (typeof dr["role"] !== "string") {
+                                errors.push(`open_children_meta["${childId}"].dispatch_record.role must be a string if present`);
+                            }
+                        }
+                        if ("role_authority" in dr && dr["role_authority"] !== undefined) {
+                            if (typeof dr["role_authority"] !== "string") {
+                                errors.push(`open_children_meta["${childId}"].dispatch_record.role_authority must be a string if present`);
+                            }
+                        }
+                        if ("may_implement" in dr && dr["may_implement"] !== undefined) {
+                            if (typeof dr["may_implement"] !== "boolean") {
+                                errors.push(`open_children_meta["${childId}"].dispatch_record.may_implement must be a boolean if present`);
+                            }
+                        }
+                        if ("session_type" in dr && dr["session_type"] !== undefined) {
+                            if (typeof dr["session_type"] !== "string") {
+                                errors.push(`open_children_meta["${childId}"].dispatch_record.session_type must be a string if present`);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Validate run_bootstrap_seal if present
+    if ("run_bootstrap_seal" in s && s["run_bootstrap_seal"] !== undefined) {
+        if (typeof s["run_bootstrap_seal"] !== "object" || s["run_bootstrap_seal"] === null || Array.isArray(s["run_bootstrap_seal"])) {
+            errors.push("run_bootstrap_seal must be an object");
+        }
+        else {
+            const seal = s["run_bootstrap_seal"];
+            if (seal["sealer"] !== "polaris-loop-bootstrap") {
+                errors.push(`run_bootstrap_seal.sealer must be "polaris-loop-bootstrap"`);
+            }
+            if (typeof seal["run_id"] !== "string" || !seal["run_id"]) {
+                errors.push("run_bootstrap_seal.run_id must be a non-empty string");
+            }
+            if (typeof seal["cluster_id"] !== "string" || !seal["cluster_id"]) {
+                errors.push("run_bootstrap_seal.cluster_id must be a non-empty string");
+            }
+            if (typeof seal["open_children_sha"] !== "string") {
+                errors.push("run_bootstrap_seal.open_children_sha must be a string");
+            }
+            if (typeof seal["sealed_at"] !== "string") {
+                errors.push("run_bootstrap_seal.sealed_at must be a string");
+            }
+        }
+    }
+    // Validate dispatch_boundary if present
+    if ("dispatch_boundary" in s && s["dispatch_boundary"] !== undefined) {
+        if (typeof s["dispatch_boundary"] !== "object" || s["dispatch_boundary"] === null || Array.isArray(s["dispatch_boundary"])) {
+            errors.push("dispatch_boundary must be an object");
+        }
+        else {
+            const db = s["dispatch_boundary"];
+            if (typeof db["dispatch_epoch"] !== "number" || !Number.isInteger(db["dispatch_epoch"]) || db["dispatch_epoch"] < 0) {
+                errors.push("dispatch_boundary.dispatch_epoch must be a non-negative integer");
+            }
+            if (typeof db["continue_epoch"] !== "number" || !Number.isInteger(db["continue_epoch"]) || db["continue_epoch"] < 0) {
+                errors.push("dispatch_boundary.continue_epoch must be a non-negative integer");
+            }
+            if (db["dispatch_epoch"] !== undefined && db["continue_epoch"] !== undefined) {
+                if (db["dispatch_epoch"] < db["continue_epoch"]) {
+                    errors.push("dispatch_boundary.dispatch_epoch must be >= continue_epoch");
+                }
+            }
+            if (db["last_dispatched_child"] !== null && typeof db["last_dispatched_child"] !== "string") {
+                errors.push("dispatch_boundary.last_dispatched_child must be a string or null");
+            }
+        }
+    }
+    return errors;
+}
+function writeStateAtomic(stateFile, state) {
+    const content = JSON.stringify(state, null, 2);
+    const tmp = `${stateFile}.tmp`;
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(stateFile), { recursive: true });
+    (0, node_fs_1.writeFileSync)(tmp, content, "utf-8");
+    (0, node_fs_1.renameSync)(tmp, stateFile);
+    return (0, node_crypto_1.createHash)("sha256").update(content).digest("hex");
+}
+function appendCheckpointEvent(telemetryFile, event) {
+    const timestampedEvent = { ...event, timestamp: (0, monotonic_timestamp_js_1.getMonotonicTimestamp)() };
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(timestampedEvent) + "\n", "utf-8");
+}
+function appendCompactReturnReceivedEvent(telemetryFile, event) {
+    const timestampedEvent = { ...event, timestamp: (0, monotonic_timestamp_js_1.getMonotonicTimestamp)() };
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(timestampedEvent) + "\n", "utf-8");
+}
+function appendWorkerScopeFidelityEvent(telemetryFile, event) {
+    const timestampedEvent = { ...event, timestamp: (0, monotonic_timestamp_js_1.getMonotonicTimestamp)() };
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(timestampedEvent) + "\n", "utf-8");
+}
+function appendBoundaryEvent(telemetryFile, event) {
+    const timestampedEvent = { ...event, timestamp: (0, monotonic_timestamp_js_1.getMonotonicTimestamp)() };
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(timestampedEvent) + "\n", "utf-8");
+}
+function appendAbortEvent(telemetryFile, event) {
+    const timestampedEvent = { ...event, timestamp: (0, monotonic_timestamp_js_1.getMonotonicTimestamp)() };
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(timestampedEvent) + "\n", "utf-8");
+}
+function appendStaleDispatchAbortedEvent(telemetryFile, event) {
+    const timestampedEvent = { ...event, timestamp: (0, monotonic_timestamp_js_1.getMonotonicTimestamp)() };
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(timestampedEvent) + "\n", "utf-8");
+}
+/**
+ * Reads the issue body for a node from the durable cluster snapshot at
+ * `.polaris/clusters/<clusterId>/clusters.json`. Returns undefined when the
+ * snapshot is absent, unparseable, or the node has no body field.
+ * Never throws.
+ */
+function readBodyFromClusterSnapshot(clusterId, nodeId, repoRoot) {
+    try {
+        const snapshotPath = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "clusters.json");
+        const raw = (0, node_fs_1.readFileSync)(snapshotPath, "utf-8");
+        const graph = JSON.parse(raw);
+        const body = graph?.nodes?.[nodeId]?.body;
+        return typeof body === "string" && body.trim().length > 0 ? body : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/loop/compact-return.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * CompactReturn — the structured summary a worker writes to stdout before exiting.
+ *
+ * The parent loop parses this to determine how to advance cluster state.
+ * Workers MUST write exactly one JSON line (the CompactReturn) as the last
+ * line of stdout and then exit immediately — no continuation to the next child.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCompactReturn = validateCompactReturn;
+/**
+ * Validate an unknown value against the CompactReturn schema.
+ * Returns an array of error strings; empty means valid.
+ */
+function validateCompactReturn(value) {
+    const errors = [];
+    if (typeof value !== 'object' || value === null) {
+        return ['CompactReturn must be a JSON object'];
+    }
+    const r = value;
+    if (typeof r['child_id'] !== 'string' || !r['child_id']) {
+        errors.push('missing or empty child_id');
+    }
+    if (r['status'] !== 'done' && r['status'] !== 'failed' && r['status'] !== 'blocked') {
+        errors.push('status must be "done", "failed", or "blocked"');
+    }
+    if (r['commit'] !== null && typeof r['commit'] !== 'string') {
+        errors.push('commit must be a string or null');
+    }
+    if (r['validation'] !== 'passed' && r['validation'] !== 'failed' && r['validation'] !== 'skipped') {
+        errors.push('validation must be "passed", "failed", or "skipped"');
+    }
+    if (typeof r['tracker_updated'] !== 'boolean') {
+        errors.push('tracker_updated must be a boolean');
+    }
+    if (typeof r['state_updated'] !== 'boolean') {
+        errors.push('state_updated must be a boolean');
+    }
+    if (typeof r['telemetry_updated'] !== 'boolean') {
+        errors.push('telemetry_updated must be a boolean');
+    }
+    if (r['next_recommended_action'] !== 'continue' &&
+        r['next_recommended_action'] !== 'stop' &&
+        r['next_recommended_action'] !== 'investigate') {
+        errors.push('next_recommended_action must be "continue", "stop", or "investigate"');
+    }
+    if ('result_data' in r && r['result_data'] !== undefined) {
+        if (typeof r['result_data'] !== 'object' || r['result_data'] === null || Array.isArray(r['result_data'])) {
+            errors.push('result_data must be an object');
+        }
+    }
+    if ('work_note_paths' in r && r['work_note_paths'] !== undefined) {
+        if (!Array.isArray(r['work_note_paths']) ||
+            r['work_note_paths'].some((path) => typeof path !== 'string')) {
+            errors.push('work_note_paths must be an array of strings');
+        }
+    }
+    return errors;
+}