@hyperdrive.bot/paseo-server 0.3.42 → 0.3.44

package/dist/server/server/workflow/workflow-progress.d.ts

@@ -86,10 +86,63 @@ export declare class WorkflowCycleError extends Error {
     readonly unresolved: string[];
     constructor(unresolved: string[]);
 }
+/**
+ * A graph that is malformed *before* dependencies are even considered: it declares no
+ * tasks at all, or it declares the same task id twice.
+ *
+ * Kept separate from {@link WorkflowCycleError} because neither defect is a dependency
+ * problem, and both callers (`session.ts` RPC, `mcp-server.ts` tool) forward
+ * `error.message` verbatim to a human - telling that human "dependency cycle" when the
+ * real defect is "you sent zero tasks" is the kind of message that costs an hour.
+ * `defect` is the stable discriminator; the message is the human-facing half.
+ */
+export declare class WorkflowInvalidGraphError extends Error {
+    readonly defect: "empty-graph" | "duplicate-task-id";
+    constructor(defect: "empty-graph" | "duplicate-task-id", message: string);
+}
 /**
  * Resolve the layered execution order for a graph. Prefer the graph's declared
  * `metadata.executionLayers`; otherwise compute layers from task dependencies.
  */
 export declare function resolveExecutionLayers(graph: TaskGraph): string[][];
+/**
+ * Assert that a task graph is schedulable: it declares at least one task, no task id is
+ * declared twice, every declared dependency names a task that exists in the graph, and
+ * the dependency relation is acyclic. Throws {@link WorkflowInvalidGraphError} for the
+ * two shape defects and {@link WorkflowCycleError} for the two dependency defects, on
+ * the first violation; returns `void` on success.
+ *
+ * WHY the shape defects are rejected here rather than tolerated: both produce a workflow
+ * that can never reach a terminal status, which is the exact failure this validator
+ * exists to prevent. An empty graph makes `startWorkflow` flip to `running`, spawn zero
+ * children and return - and `settleWorkflow` is only ever reached from a child terminal
+ * event, so with no children no event ever fires and the workflow sits `running`
+ * forever. Duplicate ids are worse than useless: two children spawn for one task id and
+ * the first of them to close settles the whole workflow to `completed` while its twin is
+ * still live, recording intent as fact. Neither is stopped downstream - the wire schema
+ * (`WorkflowTaskGraphSchema.tasks`) has no `.min(1)` and no uniqueness constraint - so
+ * submission time is the only place they can be stopped. The definition layer already
+ * rejects both (`steps: z.array(...).min(1)` and `collectDuplicateStepIds` in
+ * `protocol/src/workflow/definition.ts`); this closes the same two holes on the
+ * raw-graph path, which is the one the wire and the CLI can still reach directly.
+ *
+ * Pure: no I/O, no snapshot reads, no `Date` API (see the determinism rules above).
+ *
+ * WHY this cannot delegate to `resolveExecutionLayers`: that function (above) returns
+ * `graph.metadata.executionLayers` verbatim and unvalidated whenever it is non-empty,
+ * and `WorkflowTaskGraphSchema.metadata.executionLayers` is a REQUIRED wire field
+ * (`packages/protocol/src/messages.ts`), so every real graph carries declared layers and
+ * takes that branch. The Kahn check inside `computeLayersFromDependencies` therefore
+ * never runs for real traffic. This validator reads `TaskNode.dependencies` only and
+ * ignores the declared layering entirely, so a graph that *claims* to be layerable is
+ * still rejected when its dependencies say otherwise.
+ *
+ * It also deliberately does NOT share `computeLayersFromDependencies`' escape hatch
+ * (`|| !byId.has(dep)`, which treats an out-of-graph dependency as already satisfied).
+ * That clause is correct for the projection, which must keep layering graphs stored
+ * before this validator existed, and wrong for scheduling, where an out-of-graph
+ * dependency can never be met. Rejecting is done here, one level up, instead.
+ */
+export declare function assertSchedulableGraph(graph: TaskGraph): void;
 export {};
 //# sourceMappingURL=workflow-progress.d.ts.map

package/dist/server/server/workflow/workflow-progress.js

@@ -138,6 +138,23 @@ export class WorkflowCycleError extends Error {
         this.name = "WorkflowCycleError";
     }
 }
+/**
+ * A graph that is malformed *before* dependencies are even considered: it declares no
+ * tasks at all, or it declares the same task id twice.
+ *
+ * Kept separate from {@link WorkflowCycleError} because neither defect is a dependency
+ * problem, and both callers (`session.ts` RPC, `mcp-server.ts` tool) forward
+ * `error.message` verbatim to a human - telling that human "dependency cycle" when the
+ * real defect is "you sent zero tasks" is the kind of message that costs an hour.
+ * `defect` is the stable discriminator; the message is the human-facing half.
+ */
+export class WorkflowInvalidGraphError extends Error {
+    constructor(defect, message) {
+        super(message);
+        this.defect = defect;
+        this.name = "WorkflowInvalidGraphError";
+    }
+}
 /**
  * Resolve the layered execution order for a graph. Prefer the graph's declared
  * `metadata.executionLayers`; otherwise compute layers from task dependencies.
@@ -175,4 +192,83 @@ function computeLayersFromDependencies(tasks) {
     }
     return layers;
 }
+/**
+ * Assert that a task graph is schedulable: it declares at least one task, no task id is
+ * declared twice, every declared dependency names a task that exists in the graph, and
+ * the dependency relation is acyclic. Throws {@link WorkflowInvalidGraphError} for the
+ * two shape defects and {@link WorkflowCycleError} for the two dependency defects, on
+ * the first violation; returns `void` on success.
+ *
+ * WHY the shape defects are rejected here rather than tolerated: both produce a workflow
+ * that can never reach a terminal status, which is the exact failure this validator
+ * exists to prevent. An empty graph makes `startWorkflow` flip to `running`, spawn zero
+ * children and return - and `settleWorkflow` is only ever reached from a child terminal
+ * event, so with no children no event ever fires and the workflow sits `running`
+ * forever. Duplicate ids are worse than useless: two children spawn for one task id and
+ * the first of them to close settles the whole workflow to `completed` while its twin is
+ * still live, recording intent as fact. Neither is stopped downstream - the wire schema
+ * (`WorkflowTaskGraphSchema.tasks`) has no `.min(1)` and no uniqueness constraint - so
+ * submission time is the only place they can be stopped. The definition layer already
+ * rejects both (`steps: z.array(...).min(1)` and `collectDuplicateStepIds` in
+ * `protocol/src/workflow/definition.ts`); this closes the same two holes on the
+ * raw-graph path, which is the one the wire and the CLI can still reach directly.
+ *
+ * Pure: no I/O, no snapshot reads, no `Date` API (see the determinism rules above).
+ *
+ * WHY this cannot delegate to `resolveExecutionLayers`: that function (above) returns
+ * `graph.metadata.executionLayers` verbatim and unvalidated whenever it is non-empty,
+ * and `WorkflowTaskGraphSchema.metadata.executionLayers` is a REQUIRED wire field
+ * (`packages/protocol/src/messages.ts`), so every real graph carries declared layers and
+ * takes that branch. The Kahn check inside `computeLayersFromDependencies` therefore
+ * never runs for real traffic. This validator reads `TaskNode.dependencies` only and
+ * ignores the declared layering entirely, so a graph that *claims* to be layerable is
+ * still rejected when its dependencies say otherwise.
+ *
+ * It also deliberately does NOT share `computeLayersFromDependencies`' escape hatch
+ * (`|| !byId.has(dep)`, which treats an out-of-graph dependency as already satisfied).
+ * That clause is correct for the projection, which must keep layering graphs stored
+ * before this validator existed, and wrong for scheduling, where an out-of-graph
+ * dependency can never be met. Rejecting is done here, one level up, instead.
+ */
+export function assertSchedulableGraph(graph) {
+    // Pass 0 - shape. Runs before anything reads `dependencies`, because a graph this
+    // malformed has no dependency verdict worth reporting.
+    if (graph.tasks.length === 0) {
+        throw new WorkflowInvalidGraphError("empty-graph", "Workflow task graph declares no tasks: a workflow must declare at least one task.");
+    }
+    // Built by hand rather than `new Map(graph.tasks.map(...))` precisely so the collision
+    // is observable: the Map constructor silently keeps the LAST entry for a repeated key,
+    // which is how a duplicate id survives every downstream check.
+    const byId = new Map();
+    for (const task of graph.tasks) {
+        if (byId.has(task.id)) {
+            throw new WorkflowInvalidGraphError("duplicate-task-id", `Workflow task graph declares duplicate task id: ${task.id}`);
+        }
+        byId.set(task.id, task);
+    }
+    // Pass 1 - dangling dependencies. Runs FIRST so a dependency on a task that does not
+    // exist is never misreported as a cycle. First offender in graph order, for a
+    // deterministic message.
+    for (const task of graph.tasks) {
+        for (const dep of task.dependencies) {
+            if (!byId.has(dep)) {
+                throw new WorkflowCycleError([`${task.id} -> ${dep}`]);
+            }
+        }
+    }
+    // Pass 2 - cycles. Kahn-style sweep over `dependencies` only; no out-of-graph escape,
+    // which is safe precisely because pass 1 proved every dependency is in-graph.
+    const resolved = new Set();
+    let remaining = graph.tasks;
+    while (remaining.length > 0) {
+        const layer = remaining.filter((task) => task.dependencies.every((dep) => resolved.has(dep)));
+        if (layer.length === 0) {
+            throw new WorkflowCycleError(remaining.map((task) => task.id));
+        }
+        for (const task of layer) {
+            resolved.add(task.id);
+        }
+        remaining = remaining.filter((task) => !resolved.has(task.id));
+    }
+}
 //# sourceMappingURL=workflow-progress.js.map