@smithers-orchestrator/graph 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/graph",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Framework-neutral Smithers workflow graph model and extraction helpers",
   "type": "module",
   "sideEffects": false,
@@ -22,7 +22,7 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/errors": "0.21.0"
+    "@smithers-orchestrator/errors": "0.23.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/extract.js

@@ -1,5 +1,7 @@
 import { isAbsolute, resolve as resolvePath } from "node:path";
+import { getTableName } from "drizzle-orm";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { validateForkSources } from "./validateForkSources.js";
 /** @typedef {import("./TaskDescriptor.ts").TaskDescriptor} TaskDescriptor */
 /** @typedef {import("./XmlNode.ts").XmlNode} XmlNode */
 /** @typedef {import("./ExtractOptions.ts").ExtractOptions} ExtractOptions */
@@ -58,23 +60,18 @@ function isZodObject(value) {
 }
 /**
  * @param {unknown} value
- * @returns {string | undefined}
+ * @returns {boolean}
  */
-function maybeTableName(value) {
+function isDrizzleTable(value) {
     if (!value || typeof value !== "object")
-        return undefined;
-    const symbols = Object.getOwnPropertySymbols(value);
-    for (const symbol of symbols) {
-        const key = String(symbol);
-        if (key.includes("drizzle") || key.includes("Name")) {
-            const symbolValue = value[symbol];
-            if (typeof symbolValue === "string" && symbolValue.length > 0) {
-                return symbolValue;
-            }
-        }
+        return false;
+    try {
+        const name = getTableName(value);
+        return typeof name === "string" && name.length > 0;
+    }
+    catch {
+        return false;
     }
-    const named = value.name;
-    return typeof named === "string" && named.length > 0 ? named : undefined;
 }
 /**
  * @param {Record<string, unknown>} raw
@@ -90,13 +87,17 @@ function resolveOutput(raw) {
             outputSchema: undefined,
         };
     }
-    const outputRef = isZodObject(outputRaw) ? outputRaw : undefined;
-    const tableName = typeof outputRaw === "string" ? outputRaw : maybeTableName(outputRaw) ?? "";
-    const outputTable = outputRef ? null : typeof outputRaw === "string" ? null : outputRaw;
+    const outputTable = isDrizzleTable(outputRaw) ? outputRaw : null;
+    const outputTableName = outputTable
+        ? getTableName(outputTable)
+        : typeof outputRaw === "string"
+            ? outputRaw
+            : "";
+    const outputRef = !outputTable && isZodObject(outputRaw) ? outputRaw : undefined;
     const outputSchema = isZodObject(raw.outputSchema) ? raw.outputSchema : outputRef;
     return {
         outputTable,
-        outputTableName: tableName,
+        outputTableName,
         outputRef,
         outputSchema,
     };
@@ -308,13 +309,13 @@ export function extractGraph(root, opts) {
     const seenTcf = new Set();
     let ordinal = 0;
     /**
-   * @param {Record<string, unknown>} raw
    * @param {string} nodeId
+   * @param {string} kind
    * @param {Omit<TaskDescriptor, "ordinal" | "nodeId">} descriptor
    */
-    function addDescriptor(raw, nodeId, descriptor) {
+    function addDescriptor(nodeId, kind, descriptor) {
         if (seen.has(nodeId)) {
-            throw new SmithersError("DUPLICATE_ID", `Duplicate ${String(raw.__smithersKind ?? "Task")} id detected: ${nodeId}`, { id: nodeId });
+            throw new SmithersError("DUPLICATE_ID", `Duplicate ${kind} id detected: ${nodeId}`, { id: nodeId });
         }
         seen.add(nodeId);
         tasks.push({ nodeId, ordinal: ordinal++, ...descriptor });
@@ -399,7 +400,7 @@ export function extractGraph(root, opts) {
                 requireOutput(raw, nodeId, "Subflow");
                 const { retries, retryPolicy } = resolveRetryConfig(raw);
                 const output = resolveOutput(raw);
-                addDescriptor(raw, nodeId, {
+                addDescriptor(nodeId, "Subflow", {
                     ...common,
                     ...output,
                     needsApproval: false,
@@ -432,7 +433,7 @@ export function extractGraph(root, opts) {
             const { retries, retryPolicy } = resolveRetryConfig(raw);
             const output = resolveOutput(raw);
             const runtime = raw.__smithersSandboxRuntime ?? raw.runtime;
-            addDescriptor(raw, nodeId, {
+            addDescriptor(nodeId, "Sandbox", {
                 ...common,
                 ...output,
                 needsApproval: false,
@@ -479,7 +480,7 @@ export function extractGraph(root, opts) {
             requireOutput(raw, nodeId, "WaitForEvent");
             const output = resolveOutput(raw);
             const onTimeout = raw.__smithersOnTimeout ?? raw.onTimeout ?? "fail";
-            addDescriptor(raw, nodeId, {
+            addDescriptor(nodeId, "WaitForEvent", {
                 ...common,
                 ...output,
                 needsApproval: false,
@@ -524,7 +525,7 @@ export function extractGraph(root, opts) {
             if (raw.every !== undefined) {
                 throw new SmithersError("INVALID_INPUT", `Timer ${nodeId} uses every=, but recurring timers are not supported yet.`, { nodeId, every: raw.every });
             }
-            addDescriptor(raw, nodeId, {
+            addDescriptor(nodeId, "Timer", {
                 ...common,
                 outputTable: null,
                 outputTableName: "",
@@ -588,9 +589,10 @@ export function extractGraph(root, opts) {
             if (prompt === "[object Object]") {
                 throw new SmithersError("MDX_PRELOAD_INACTIVE", `Task "${logicalNodeId}" prompt resolved to [object Object].`);
             }
-            addDescriptor(raw, nodeId, {
+            addDescriptor(nodeId, "Task", {
                 ...common,
                 ...output,
+                forkSource: typeof raw.fork === "string" && raw.fork ? raw.fork : undefined,
                 needsApproval: Boolean(raw.needsApproval),
                 waitAsync: Boolean(raw.waitAsync),
                 approvalMode,
@@ -652,6 +654,7 @@ export function extractGraph(root, opts) {
         worktreeStack: [],
         loopStack: [],
     });
+    validateForkSources(tasks);
     return { xml: toXmlNode(root), tasks, mountedTaskIds };
 }
 export const extractFromHost = extractGraph;

package/src/types.ts

@@ -133,6 +133,8 @@ export type TaskDescriptor = {
   ralphId?: string;
   dependsOn?: string[];
   needs?: Record<string, string>;
+  /** Logical id of the task whose final agent session this task forks. Gates execution and seeds the session. */
+  forkSource?: string;
   worktreeId?: string;
   worktreePath?: string;
   worktreeBranch?: string;

package/src/validateForkSources.js

@@ -0,0 +1,107 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+
+/** @typedef {import("./TaskDescriptor.ts").TaskDescriptor} TaskDescriptor */
+
+/**
+ * Strip the loop-scope suffix (`@@ralph=0,...`) from a node id to recover the
+ * logical task id authored in JSX. `fork` and `dependsOn` reference logical ids.
+ * @param {string} nodeId
+ * @returns {string}
+ */
+function logicalId(nodeId) {
+    const atIdx = nodeId.indexOf("@@");
+    return atIdx === -1 ? nodeId : nodeId.slice(0, atIdx);
+}
+
+/**
+ * Validate `<Task fork>` references across the extracted task list. Throws a
+ * typed SmithersError for fork sources that can never resolve to a usable
+ * session snapshot, so authoring mistakes fail fast at graph-build time rather
+ * than deadlocking the scheduler.
+ *
+ * Detects:
+ *   - TASK_FORK_SOURCE_NOT_FOUND — fork id absent from the graph (covers a
+ *     source that only exists in an unselected branch).
+ *   - TASK_FORK_SESSION_UNAVAILABLE — the forking task is not an agent task and
+ *     therefore has no session to seed.
+ *   - TASK_FORK_CYCLE — the fork edge closes a dependency cycle, directly or
+ *     indirectly (via `dependsOn` and/or other fork edges).
+ *
+ * Loop semantics are intentionally not validated here: `fork` resolves to the
+ * latest completed snapshot for a task id at execution time, so a source inside
+ * a loop is valid as long as its logical id appears in the graph.
+ *
+ * @param {readonly TaskDescriptor[]} tasks
+ * @returns {void}
+ */
+export function validateForkSources(tasks) {
+    const forks = tasks.filter((task) => typeof task.forkSource === "string" && task.forkSource);
+    if (forks.length === 0) {
+        return;
+    }
+    const presentLogicalIds = new Set(tasks.map((task) => logicalId(task.nodeId)));
+    // Union of dependency edges keyed by logical id: dependsOn entries plus the
+    // fork edge. Used only for cycle detection.
+    /** @type {Map<string, Set<string>>} */
+    const adjacency = new Map();
+    const addEdge = (from, to) => {
+        const cleanedFrom = logicalId(from);
+        const cleanedTo = logicalId(to);
+        let set = adjacency.get(cleanedFrom);
+        if (!set) {
+            set = new Set();
+            adjacency.set(cleanedFrom, set);
+        }
+        set.add(cleanedTo);
+    };
+    for (const task of tasks) {
+        const from = logicalId(task.nodeId);
+        for (const dep of task.dependsOn ?? []) {
+            addEdge(from, dep);
+        }
+        if (typeof task.forkSource === "string" && task.forkSource) {
+            addEdge(from, task.forkSource);
+        }
+    }
+    /**
+     * @param {string} from
+     * @param {string} target
+     * @returns {boolean}
+     */
+    const canReach = (from, target) => {
+        const stack = [from];
+        const visited = new Set();
+        while (stack.length > 0) {
+            const current = /** @type {string} */ (stack.pop());
+            if (current === target) {
+                return true;
+            }
+            if (visited.has(current)) {
+                continue;
+            }
+            visited.add(current);
+            const neighbors = adjacency.get(current);
+            if (neighbors) {
+                for (const next of neighbors) {
+                    stack.push(next);
+                }
+            }
+        }
+        return false;
+    };
+    for (const task of forks) {
+        const forkSource = /** @type {string} */ (task.forkSource);
+        const nodeLogicalId = logicalId(task.nodeId);
+        if (!presentLogicalIds.has(forkSource)) {
+            throw new SmithersError("TASK_FORK_SOURCE_NOT_FOUND", `Task "${task.nodeId}" forks "${forkSource}", which is not present in the workflow graph.`, { nodeId: task.nodeId, forkSource });
+        }
+        if (!task.agent) {
+            throw new SmithersError("TASK_FORK_SESSION_UNAVAILABLE", `Task "${task.nodeId}" uses fork but is not an agent task. Only agent tasks can fork a session.`, { nodeId: task.nodeId, forkSource });
+        }
+        // The fork edge is nodeLogicalId -> forkSource. A cycle exists iff
+        // forkSource can already reach nodeLogicalId through the dependency graph.
+        if (canReach(forkSource, nodeLogicalId)) {
+            throw new SmithersError("TASK_FORK_CYCLE", `Task "${task.nodeId}" forks "${forkSource}", which creates a dependency cycle.`, { nodeId: task.nodeId, forkSource });
+        }
+    }
+}