@lsctech/polaris 0.1.0

package/dist/loop/run-bootstrap.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * Polaris Run Bootstrap Delegator
+ *
+ * The run bootstrap delegator is the runtime gate to the dispatch machinery.
+ * Parent sessions may NOT hand-create run state. The runtime MUST initialize
+ * the loop before any child can be selected or dispatched.
+ *
+ * Enforcement:
+ *   - `polaris loop bootstrap` is the ONLY command that may create initial
+ *     run state. It writes a RunBootstrapSeal into current-state.json.
+ *   - `polaris loop dispatch` and `polaris loop run` verify the seal before
+ *     allowing any child to be selected. If the seal is absent or invalid,
+ *     dispatch is refused with a hard exit(1).
+ *
+ * The seal binds:
+ *   - The run_id and cluster_id (must match state fields)
+ *   - A SHA-256 of the initial open_children list (forensic tamper record)
+ *   - The sealer identity ("polaris-loop-bootstrap" — only this value is valid)
+ *
+ * This module also exports the CLI handler runLoopBootstrapInit(), which
+ * is registered as `polaris loop bootstrap` in src/loop/index.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BOOTSTRAP_REQUIRED_ERROR = void 0;
+exports.computeChildrenSha = computeChildrenSha;
+exports.createBootstrapSeal = createBootstrapSeal;
+exports.deriveRunId = deriveRunId;
+exports.assertBootstrapSeal = assertBootstrapSeal;
+exports.runLoopBootstrapInit = runLoopBootstrapInit;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const checkpoint_js_1 = require("./checkpoint.js");
+const dispatch_boundary_js_1 = require("./dispatch-boundary.js");
+const dispatch_boundary_js_2 = require("./dispatch-boundary.js");
+const store_js_1 = require("../cluster-state/store.js");
+const git_custody_js_1 = require("./git-custody.js");
+// ──────────────────────────────────────────────────────────────────────────────
+// Error constants
+// ──────────────────────────────────────────────────────────────────────────────
+exports.BOOTSTRAP_REQUIRED_ERROR = "Run state must be initialized through 'polaris loop bootstrap' before dispatch. " +
+    "Parent sessions may not hand-create run state. " +
+    "Use: npm run polaris -- loop bootstrap --cluster-id <ID> --children <CSV>";
+// ──────────────────────────────────────────────────────────────────────────────
+// Seal helpers
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Compute a deterministic SHA-256 of an open_children list.
+ * Sorts the list before hashing to ensure stability.
+ */
+function computeChildrenSha(openChildren) {
+    const sorted = [...openChildren].sort();
+    return (0, node_crypto_1.createHash)("sha256").update(sorted.join(",")).digest("hex");
+}
+/**
+ * Create a bootstrap seal for the given run/cluster/children.
+ */
+function createBootstrapSeal(runId, clusterId, openChildren) {
+    return {
+        sealer: "polaris-loop-bootstrap",
+        run_id: runId,
+        cluster_id: clusterId,
+        open_children_sha: computeChildrenSha(openChildren),
+        sealed_at: new Date().toISOString(),
+    };
+}
+/**
+ * Derive a run_id from a cluster ID and the current date.
+ * Format: polaris-run-<cluster-slug>-<YYYY-MM-DD>-001
+ */
+function deriveRunId(clusterId) {
+    const slug = clusterId.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    const date = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+    return `polaris-run-${slug}-${date}-001`;
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Enforcement guard
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Assert that the current state was initialized through `polaris loop bootstrap`.
+ *
+ * Verifies:
+ *   1. `run_bootstrap_seal` is present in state
+ *   2. `seal.sealer === "polaris-loop-bootstrap"`
+ *   3. `seal.run_id === state.run_id`
+ *   4. `seal.cluster_id === state.cluster_id`
+ *
+ * Emits a `dispatch-required` telemetry event on failure and throws.
+ * The caller must NOT mutate state after this throws.
+ *
+ * @throws Error with BOOTSTRAP_REQUIRED_ERROR if seal is absent or invalid
+ */
+function assertBootstrapSeal(state, telemetryFile) {
+    const seal = state.run_bootstrap_seal;
+    let reason = null;
+    if (!seal) {
+        reason = `No run_bootstrap_seal found in state. ${exports.BOOTSTRAP_REQUIRED_ERROR}`;
+    }
+    else if (seal.sealer !== "polaris-loop-bootstrap") {
+        reason = `Invalid run_bootstrap_seal.sealer: "${seal.sealer}". Only "polaris-loop-bootstrap" is accepted.`;
+    }
+    else if (seal.run_id !== state.run_id) {
+        reason = `run_bootstrap_seal.run_id "${seal.run_id}" does not match state.run_id "${state.run_id}".`;
+    }
+    else if (seal.cluster_id !== state.cluster_id) {
+        reason = `run_bootstrap_seal.cluster_id "${seal.cluster_id}" does not match state.cluster_id "${state.cluster_id}".`;
+    }
+    if (reason) {
+        (0, dispatch_boundary_js_1.appendDispatchViolationEvent)(telemetryFile, {
+            event: "dispatch-required",
+            run_id: state.run_id,
+            from_state: "unbootstrapped",
+            to_state: "dispatched",
+            reason,
+            timestamp: new Date().toISOString(),
+        });
+        throw new Error(reason);
+    }
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Bootstrap init command handler
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Create the initial run state and write it to the state file.
+ *
+ * This is the CLI handler for `polaris loop bootstrap`. It is the ONLY
+ * legitimate path to creating a new current-state.json. Any state file
+ * that was not written by this function will be refused by dispatch.
+ */
+function runLoopBootstrapInit(options) {
+    const { clusterId, openChildren, openChildrenMeta, stateFile, repoRoot, branch, sessionType, maxChildrenPerSession, artifactDir, overwrite, } = options;
+    if (!clusterId) {
+        process.stderr.write("Error: --cluster-id is required\n");
+        process.exit(1);
+    }
+    if (!openChildren || openChildren.length === 0) {
+        process.stderr.write("Error: --children is required and must be non-empty\n");
+        process.exit(1);
+    }
+    const runId = options.runId ?? deriveRunId(clusterId);
+    const seal = createBootstrapSeal(runId, clusterId, openChildren);
+    const deliveryBranch = branch ?? (0, git_custody_js_1.buildDeliveryBranchName)(clusterId);
+    const initialState = {
+        schema_version: "1.0",
+        run_id: runId,
+        cluster_id: clusterId,
+        skill: "polaris-run",
+        branch: deliveryBranch,
+        session_type: sessionType ?? "implement",
+        active_child: "",
+        completed_children: [],
+        open_children: openChildren,
+        open_children_meta: openChildrenMeta,
+        step_cursor: null,
+        context_budget: {
+            children_completed: 0,
+            max_children_per_session: maxChildrenPerSession ?? 1,
+        },
+        status: "running",
+        next_open_child: openChildren[0] ?? null,
+        artifact_dir: artifactDir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run"),
+        dispatch_boundary: (0, dispatch_boundary_js_2.initialDispatchBoundary)(),
+        run_bootstrap_seal: seal,
+    };
+    // Check if current-state.json already exists before making any modifications
+    if ((0, node_fs_1.existsSync)(stateFile)) {
+        if (!overwrite) {
+            process.stderr.write(`Error: State file already exists at ${stateFile}\n` +
+                `Cannot overwrite existing run state. Either:\n` +
+                `  1. Use --overwrite to archive the existing state and start fresh, or\n` +
+                `  2. Use a different --state-file path\n`);
+            process.exit(1);
+        }
+        // Archive the existing state before overwriting
+        const backupPath = `${stateFile}.${Date.now()}.bak`;
+        (0, node_fs_1.renameSync)(stateFile, backupPath);
+        process.stderr.write(`Warning: Archived existing state to ${backupPath}\n`);
+    }
+    // Initialize cluster-state.json if it doesn't exist.
+    // This is best-effort and must not block bootstrap state creation.
+    const clusterStateInitPromise = (async () => {
+        try {
+            const existingClusterState = await (0, store_js_1.readClusterState)(clusterId, repoRoot);
+            if (!existingClusterState) {
+                process.stderr.write(`Initializing new cluster-state.json for ${clusterId}...\n`);
+                await (0, store_js_1.initializeClusterState)(clusterId, repoRoot);
+                // Bind the delivery branch immediately so finalize doesn't inherit stale metadata
+                const freshState = await (0, store_js_1.readClusterState)(clusterId, repoRoot);
+                if (freshState && !freshState.delivery_branch) {
+                    await (0, store_js_1.writeClusterState)(clusterId, {
+                        ...freshState,
+                        state_generation: (freshState.state_generation ?? 0) + 1,
+                        delivery_branch: deliveryBranch,
+                        base_branch: "main",
+                    }, repoRoot);
+                }
+            }
+            else if (!existingClusterState.delivery_branch) {
+                // Existing cluster state without delivery branch — bind it now
+                await (0, store_js_1.writeClusterState)(clusterId, {
+                    ...existingClusterState,
+                    state_generation: (existingClusterState.state_generation ?? 0) + 1,
+                    delivery_branch: deliveryBranch,
+                    base_branch: existingClusterState.base_branch ?? "main",
+                }, repoRoot);
+            }
+        }
+        catch (error) {
+            process.stderr.write(`Warning: Failed to initialize cluster-state.json for ${clusterId}: ${error instanceof Error ? error.message : String(error)}\n`);
+            // Continue without hard-failing bootstrap.
+        }
+    })();
+    // Validate the state we're about to write
+    // (uses validateState from checkpoint.ts — but we don't import it here to
+    //  avoid circular deps; validateState is called by dispatch which is downstream)
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(stateFile), { recursive: true });
+    const sha = (0, checkpoint_js_1.writeStateAtomic)(stateFile, initialState);
+    const summary = {
+        run_id: runId,
+        cluster_id: clusterId,
+        children: openChildren.length,
+        first_child: openChildren[0],
+        state_file: stateFile,
+        seal_sha: sha.slice(0, 12),
+        sealed_at: seal.sealed_at,
+    };
+    process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+    process.stderr.write(`Bootstrap complete. State initialized at: ${stateFile}\n` +
+        `Run ID: ${runId}\n` +
+        `Children: ${openChildren.join(", ")}\n` +
+        `Next: npm run polaris -- loop dispatch\n`);
+    return clusterStateInitPromise;
+}

package/dist/loop/run-preflight.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureClusterRunState = ensureClusterRunState;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const store_js_1 = require("../cluster-state/store.js");
+const local_graph_js_1 = require("../tracker/local-graph.js");
+const index_js_1 = require("../tracker/adapters/linear/index.js");
+const loader_js_1 = require("../config/loader.js");
+const checkpoint_js_1 = require("./checkpoint.js");
+function getClusterStatePath(clusterId, repoRoot) {
+    return (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "cluster-state.json");
+}
+function isEnoent(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+async function loadOrSyncGraph(clusterId, repoRoot) {
+    try {
+        return await local_graph_js_1.LocalGraph.load(clusterId, repoRoot);
+    }
+    catch (error) {
+        if (!isEnoent(error)) {
+            throw error;
+        }
+        const config = (0, loader_js_1.loadConfig)(repoRoot);
+        if (!config.tracker?.linear?.enabled) {
+            throw new Error(`No local cluster graph found for ${clusterId}. Run 'npm run polaris -- tracker sync-in ${clusterId}' or bootstrap with --children.`);
+        }
+        const graph = await new index_js_1.LinearAdapter(config).syncIn(clusterId);
+        await graph.save(clusterId, repoRoot);
+        return graph;
+    }
+}
+function topoSort(children, getDeps) {
+    // Kahn's algorithm — only sorts within the given children set
+    const childSet = new Set(children);
+    const inDegree = new Map();
+    const dependents = new Map(); // dep → [children that need dep]
+    for (const child of children) {
+        inDegree.set(child, 0);
+        dependents.set(child, []);
+    }
+    for (const child of children) {
+        for (const dep of getDeps(child)) {
+            if (!childSet.has(dep))
+                continue; // external dep — ignore for ordering
+            inDegree.set(child, (inDegree.get(child) ?? 0) + 1);
+            dependents.get(dep).push(child);
+        }
+    }
+    const queue = [];
+    for (const [child, deg] of inDegree) {
+        if (deg === 0)
+            queue.push(child);
+    }
+    const sorted = [];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        sorted.push(node);
+        for (const dependent of dependents.get(node) ?? []) {
+            const newDeg = (inDegree.get(dependent) ?? 1) - 1;
+            inDegree.set(dependent, newDeg);
+            if (newDeg === 0)
+                queue.push(dependent);
+        }
+    }
+    // If sort is incomplete (cycle), fall back to original order for remaining nodes
+    if (sorted.length < children.length) {
+        const sortedSet = new Set(sorted);
+        for (const child of children) {
+            if (!sortedSet.has(child))
+                sorted.push(child);
+        }
+    }
+    return sorted;
+}
+function buildBootstrapPlan(clusterId, graph) {
+    const activeCluster = graph.getActiveCluster();
+    // Exclude the cluster root from runnable children when it has implementation
+    // children. The root is a context/coordination node. If after filtering nothing
+    // remains (leaf cluster), fall back to [clusterId] so the root runs as the sole
+    // work item — matching single-target leaf semantics.
+    const clusterRoot = activeCluster.cluster_root;
+    const runnableChildren = clusterRoot
+        ? activeCluster.children.filter((id) => id !== clusterRoot)
+        : activeCluster.children;
+    const unsortedChildren = runnableChildren.length > 0 ? runnableChildren : [clusterId];
+    const openChildren = topoSort(unsortedChildren, (id) => graph.getDependencies(id));
+    const openChildrenMeta = {};
+    const clusterNode = graph.getNode(clusterId);
+    openChildrenMeta[clusterId] = {
+        title: clusterNode?.title ?? activeCluster.title,
+        ...(clusterNode?.body ? { body: clusterNode.body } : {}),
+    };
+    for (const childId of openChildren) {
+        const node = graph.getNode(childId);
+        openChildrenMeta[childId] = {
+            ...openChildrenMeta[childId],
+            title: node?.title ?? openChildrenMeta[childId]?.title ?? childId,
+            ...(node?.body ? { body: node.body } : {}),
+        };
+    }
+    return { openChildren, openChildrenMeta };
+}
+function preserveMismatchedState(stateFile) {
+    const suffix = (() => {
+        try {
+            const state = (0, checkpoint_js_1.readState)(stateFile);
+            return `${state.run_id || "state"}-${Date.now()}`;
+        }
+        catch {
+            return `state-${Date.now()}`;
+        }
+    })();
+    (0, node_fs_1.renameSync)(stateFile, `${stateFile}.${suffix}.bak`);
+}
+async function isGhostCompleteState(clusterId, repoRoot, completedChildren, status) {
+    if (status !== "cluster-complete" && completedChildren.length === 0) {
+        return false;
+    }
+    const clusterState = await (0, store_js_1.readClusterState)(clusterId, repoRoot);
+    if (!clusterState) {
+        return false;
+    }
+    const unfinishedStatuses = new Set(["ready", "claimed", "dispatched", "running", "failed", "blocked"]);
+    return clusterState.child_states.some((child) => {
+        if (!completedChildren.includes(child.id) && status !== "cluster-complete") {
+            return false;
+        }
+        return unfinishedStatuses.has(child.status);
+    });
+}
+async function assertCanonicalClusterState(clusterId, repoRoot, state) {
+    const clusterStatePath = getClusterStatePath(clusterId, repoRoot);
+    const clusterState = await (0, store_js_1.readClusterState)(clusterId, repoRoot);
+    if (!clusterState) {
+        throw new Error(`run-preflight: missing canonical cluster-state for ${clusterId} at ${clusterStatePath}. ` +
+            "The live execution state must exist before Polaris reuses current-state.json.");
+    }
+    const clusterChildIds = new Set(clusterState.child_states.map((child) => child.id));
+    const referencedChildren = new Set([
+        ...state.completed_children ?? [],
+        ...state.open_children ?? [],
+        ...(state.active_child && state.active_child.length > 0
+            ? [state.active_child]
+            : []),
+    ]);
+    const missingChildren = [...referencedChildren].filter((childId) => !clusterChildIds.has(childId));
+    if (missingChildren.length > 0) {
+        throw new Error(`run-preflight: cluster-state for ${clusterId} is missing children referenced by current-state.json: ${missingChildren.join(", ")}`);
+    }
+}
+async function ensureClusterRunState(options) {
+    const { clusterId, stateFile, repoRoot, bootstrapHandler } = options;
+    if ((0, node_fs_1.existsSync)(stateFile)) {
+        let existingState;
+        try {
+            existingState = (0, checkpoint_js_1.readState)(stateFile);
+        }
+        catch (err) {
+            if (!isEnoent(err)) {
+                console.warn(`run-preflight: failed to read state file ${stateFile}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            // ENOENT (race condition) or parse/IO error — proceed to bootstrap
+        }
+        if (existingState !== undefined) {
+            const validationErrors = (0, checkpoint_js_1.validateState)(existingState);
+            if (existingState.cluster_id === clusterId) {
+                if (await isGhostCompleteState(clusterId, repoRoot, existingState.completed_children ?? [], existingState.status)) {
+                    preserveMismatchedState(stateFile);
+                }
+                else {
+                    // Valid state for this cluster — no bootstrap needed
+                    if (validationErrors.length === 0) {
+                        await assertCanonicalClusterState(clusterId, repoRoot, existingState);
+                        return;
+                    }
+                    // Leave invalid in-place so downstream validation reports the real state error.
+                    return;
+                }
+            }
+            else {
+                if (!existingState.cluster_id && validationErrors.length > 0) {
+                    return;
+                }
+                // Mismatched cluster_id — always preserve, with a warning if also invalid
+                if (validationErrors.length > 0) {
+                    console.warn(`run-preflight: state file ${stateFile} has cluster_id "${existingState.cluster_id}" (expected "${clusterId}") and failed validation; preserving for inspection.`);
+                }
+                preserveMismatchedState(stateFile);
+            }
+        }
+    }
+    const { openChildren, openChildrenMeta } = buildBootstrapPlan(clusterId, await loadOrSyncGraph(clusterId, repoRoot));
+    await bootstrapHandler({
+        clusterId,
+        openChildren,
+        openChildrenMeta,
+        stateFile,
+        repoRoot,
+        artifactDir: (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run"),
+    });
+}