@lsctech/polaris 0.5.10 → 0.5.12

package/dist/tracker/local-graph.js

@@ -15,6 +15,7 @@ const migration_js_1 = require("./migration.js");
  */
 class LocalGraph {
     graph;
+    orderingDependenciesMerged = false;
     constructor(graph) {
         this.graph = graph;
     }
@@ -54,19 +55,76 @@ class LocalGraph {
     }
     /**
      * Persists the graph to `.polaris/clusters/{clusterId}/clusters.json`.
-     * Creates the directory if it does not exist.
+     * Children are sorted topologically before writing so the saved cluster
+     * definition reflects dependency order.
      *
      * @param clusterId The cluster ID to use as the directory name (e.g., "POL-198").
      * @param repoRoot The root directory of the repository.
      * @returns The absolute path of the written file.
      */
     async save(clusterId, repoRoot = process.cwd()) {
+        this.mergeOrderingDependencies();
+        const persistedGraph = {
+            ...this.graph,
+            clusters: Object.fromEntries(Object.entries(this.graph.clusters).map(([id, cluster]) => [
+                id,
+                Array.isArray(cluster.children) && cluster.children.length > 1
+                    ? { ...cluster, children: this.topoSortChildren(cluster.children) }
+                    : cluster,
+            ])),
+        };
         const dir = node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId);
         await (0, promises_1.mkdir)(dir, { recursive: true });
         const filePath = node_path_1.default.join(dir, "clusters.json");
-        await (0, promises_1.writeFile)(filePath, JSON.stringify(this.graph, null, 2), "utf-8");
+        await (0, promises_1.writeFile)(filePath, JSON.stringify(persistedGraph, null, 2), "utf-8");
         return filePath;
     }
+    /**
+     * Sort a list of children topologically using the graph dependencies.
+     * Children with no in-cluster dependencies come first; if a cycle exists,
+     * the remaining nodes are appended in their original order.
+     */
+    topoSortChildren(children) {
+        const childSet = new Set(children);
+        const inDegree = new Map();
+        const dependents = new Map();
+        for (const child of children) {
+            inDegree.set(child, 0);
+            dependents.set(child, []);
+        }
+        for (const child of children) {
+            for (const dep of this.getDependencies(child)) {
+                if (!childSet.has(dep))
+                    continue;
+                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 (sorted.length < children.length) {
+            const sortedSet = new Set(sorted);
+            for (const child of children) {
+                if (!sortedSet.has(child))
+                    sorted.push(child);
+            }
+        }
+        return sorted;
+    }
     /**
      * Returns the full v2 execution graph.
      */
@@ -87,12 +145,57 @@ class LocalGraph {
         return this.graph.nodes[id];
     }
     /**
-     * Returns the dependencies for a given node.
+     * Returns the dependencies for a given node, merging any dependencies declared
+     * in the node's `## Ordering` body section.
      * @param id The ID of the node to get dependencies for.
      * @returns An array of node IDs that the given node is blocked by.
      */
     getDependencies(id) {
+        this.mergeOrderingDependencies();
         return this.graph.dependencies[id] ?? [];
     }
+    /**
+     * Extracts issue IDs from the `## Ordering` section of a node body.
+     *
+     * Only lines that explicitly declare ordering ("depends on" or "after" / "sequence after")
+     * contribute, and "before or after" clauses are ignored because they are not strict.
+     */
+    extractOrderingIds(body) {
+        const sectionMatch = body.match(/##\s*Ordering\b([\s\S]*?)(?:\n##\s|\n\n(?=\n##\s)|$)/i);
+        if (!sectionMatch)
+            return [];
+        const section = sectionMatch[1];
+        const cleaned = section.replace(/before\s+or\s+after\s*\[[^\]]*\]/gi, "");
+        const ids = new Set();
+        const re = /(?:depends\s+on|after)\s*\[?\s*(\w+-\d+)\b/gi;
+        for (const line of cleaned.split("\n")) {
+            if (!/^\s*[-*]\s/.test(line))
+                continue;
+            for (const match of line.matchAll(re)) {
+                ids.add(match[1]);
+            }
+        }
+        return [...ids];
+    }
+    /**
+     * Merges dependencies declared in node body `## Ordering` sections into the
+     * graph's explicit dependency map. This is idempotent for the loaded graph.
+     */
+    mergeOrderingDependencies() {
+        if (this.orderingDependenciesMerged)
+            return;
+        for (const node of Object.values(this.graph.nodes)) {
+            const orderingIds = this.extractOrderingIds(node.body ?? "");
+            if (orderingIds.length === 0)
+                continue;
+            const existing = new Set(this.graph.dependencies[node.id] ?? []);
+            for (const dep of orderingIds) {
+                if (dep !== node.id)
+                    existing.add(dep);
+            }
+            this.graph.dependencies[node.id] = [...existing].sort();
+        }
+        this.orderingDependenciesMerged = true;
+    }
 }
 exports.LocalGraph = LocalGraph;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsctech/polaris",
-  "version": "0.5.10",
+  "version": "0.5.12",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris": "dist/cli/index.js",