@memberjunction/task-graph 6.1.0-edge.1 → 6.1.0-edge.2

package/dist/TaskGraphService.js

@@ -15,8 +15,9 @@
  *
  * @module @memberjunction/task-graph
  */
-import { LogError, LogStatus, RunView, } from '@memberjunction/core';
-import { FormatValidationErrors, NormalizeDependency, ValidateTaskGraphSpec, } from '@memberjunction/ai-core-plus';
+import { LogError, LogStatus, RunInEntityTransaction, RunView, } from '@memberjunction/core';
+import { FormatValidationErrors, NormalizeDependency, RankGraphNodes, ValidateTaskGraphSpec, ConfigOf, } from '@memberjunction/ai-core-plus';
+import { UUIDsEqual } from '@memberjunction/global';
 /**
  * Continuation chains are bounded separately from graph nesting.
  *
@@ -31,6 +32,7 @@ export const MAX_REINVOKE_DEPTH = 5;
 const DEFAULT_PARENT_METADATA = {
     continuation: 'message',
     reinvokeDepth: 0,
+    failureSemantics: 'block',
     submittedByAgentRunID: null,
     submittedByUserID: null,
 };
@@ -61,6 +63,7 @@ export function ParseTaskGraphParentMetadata(raw) {
             continuation: parsed.continuation === 'reinvoke' || parsed.continuation === 'none'
                 ? parsed.continuation
                 : 'message',
+            failureSemantics: parsed.failureSemantics === 'edges' ? 'edges' : 'block',
             reinvokeDepth: Number.isFinite(parsed.reinvokeDepth) ? Number(parsed.reinvokeDepth) : 0,
         };
     }
@@ -74,6 +77,181 @@ export function IsReinvokeCapReached(meta) {
 }
 /** Name of the task type used for agent-orchestrated graphs. */
 const TASK_TYPE_NAME = 'AI Workflow';
+/**
+ * The node kinds a `Task` row can actually represent, and therefore the ones the dispatcher can run.
+ *
+ * `Agent` and `Action` have their own foreign keys; `Human` is a task with an assignee; `ForEach`
+ * and `While` carry their loop definition in `Task.Configuration` and their repeated body in the
+ * same `AgentID` / `ActionID` keys.
+ *
+ * `Prompt` joins them now that `TaskPromptRunner` exists — it carries `Task.PromptID`. `External`
+ * remains absent: it is completed by a system that has no way to report back, so persisting one
+ * would produce a task that waits forever.
+ */
+const DISPATCHABLE_KINDS = [
+    'Agent', 'Action', 'Human', 'ForEach', 'While', 'Prompt',
+];
+/**
+ * Reports the node kinds this dispatcher cannot execute, or `null` when the graph is fully runnable.
+ *
+ * **Why this is a submit-time check and not a validation rule.** `ValidateTaskGraphSpec` is a pure
+ * function over the spec: it answers "is this a well-formed graph?", and its answer has to be the
+ * same in a browser, a CLI and a server. "Can it run *here*?" is a different question whose answer
+ * changes as runners are added, so it belongs to the runtime that owns the runners.
+ *
+ * **Why refuse rather than persist-and-stall.** Before this existed, `persistTasks` keyed off which
+ * configuration field happened to be populated and fell through to "Human task assigned to the
+ * submitter" for everything else — so a loop step silently became an approval request nobody asked
+ * for and nothing would ever complete. A graph that hangs forever while *looking* like it is waiting
+ * on a person is the most expensive failure available here. Refusing at the door instead names the
+ * offending step while the workflow is still the author's to edit.
+ */
+/**
+ * Projects a spec node onto the `Task.Configuration` bag.
+ *
+ * Everything the row cannot hold in a column of its own: the kind-specific settings, the payload
+ * mappings, and the execution policy. Returning `null` for an empty result keeps `Configuration`
+ * NULL rather than `"{}"`, so "this step has no settings" reads the same in the database as it does
+ * in the spec.
+ *
+ * **The mappings are the point.** They are how a step's result reaches the payload, and every
+ * branch condition downstream reads the payload — so a step persisted without them produces a
+ * workflow whose conditions all evaluate against nothing. Undefined is falsy, so that failure looks
+ * exactly like a branch legitimately not being taken.
+ */
+export function BuildStepConfiguration(node) {
+    const config = {};
+    const agent = ConfigOf(node, 'Agent');
+    if (agent?.message || agent?.templateParameters) {
+        config.agent = { message: agent.message, templateParameters: agent.templateParameters };
+    }
+    const prompt = ConfigOf(node, 'Prompt');
+    if (prompt?.templateParameters)
+        config.prompt = { templateParameters: prompt.templateParameters };
+    const forEach = ConfigOf(node, 'ForEach');
+    if (forEach)
+        config.forEach = forEach;
+    const whileOp = ConfigOf(node, 'While');
+    if (whileOp)
+        config.while = whileOp;
+    // `expiresInHours` as well as instructions: dropping it here is what would leave the deadline in
+    // the spec and out of the row the dispatcher actually reads, so the request would be raised with
+    // no ExpiresAt and the author's timeout would silently not exist.
+    const human = ConfigOf(node, 'Human');
+    if (human?.instructions || human?.expiresInHours) {
+        config.human = { instructions: human.instructions, expiresInHours: human.expiresInHours };
+    }
+    const external = ConfigOf(node, 'External');
+    if (external)
+        config.external = external;
+    // Mappings live on the Action arm of the spec, but they are not action-specific: a loop step
+    // carries them too, which is how its per-iteration inputs and results are wired.
+    const action = ConfigOf(node, 'Action');
+    const inputMapping = action?.inputMapping;
+    const outputMapping = action?.outputMapping;
+    if (inputMapping)
+        config.inputMapping = inputMapping;
+    if (outputMapping)
+        config.outputMapping = outputMapping;
+    if (node.policy) {
+        config.policy = {
+            timeoutSeconds: node.policy.timeoutSeconds,
+            retryCount: node.policy.retryCount,
+            onError: node.policy.onError,
+        };
+    }
+    // The author's own arrangement, carried through so a hand-drawn workflow runs — and appears in
+    // run history — in the shape they drew. Dropping it (as this did) meant a workflow someone had
+    // laid out carefully came back as a machine-arranged graph the first time they watched it run.
+    // Only authored geometry is stored: a graph with none has its layout derived at render time, and
+    // persisting a derived layout would freeze one rendering of a graph that can still change.
+    if (node.layout && Object.keys(node.layout).length > 0) {
+        config.layout = {
+            x: node.layout.x,
+            y: node.layout.y,
+            width: node.layout.width,
+            height: node.layout.height,
+        };
+    }
+    return Object.keys(config).length > 0 ? config : null;
+}
+/** Internal alias so the persistence path reads as a step, not as a projection. */
+const buildStepConfiguration = BuildStepConfiguration;
+/**
+ * The loop definition on a node, whichever loop kind it is.
+ *
+ * ForEach and While differ in how they decide to iterate, not in what they repeat, so everything
+ * downstream of that decision — body resolution, name collection, persistence — treats them alike.
+ */
+export function LoopOperationOf(node) {
+    return ConfigOf(node, 'ForEach') ?? ConfigOf(node, 'While') ?? null;
+}
+/** Every agent name a node references, including the sub-agent a loop repeats. */
+function agentNamesIn(node) {
+    const names = [ConfigOf(node, 'Agent')?.agentName, LoopOperationOf(node)?.subAgent?.name];
+    return names.filter((n) => !!n);
+}
+/** Every prompt name a node references, including the prompt a loop repeats. */
+function promptNamesIn(node) {
+    const names = [ConfigOf(node, 'Prompt')?.promptName, LoopOperationOf(node)?.prompt?.name];
+    return names.filter((n) => !!n);
+}
+/** Every action name a node references, including the action a loop repeats. */
+function actionNamesIn(node) {
+    const names = [ConfigOf(node, 'Action')?.actionName, LoopOperationOf(node)?.action?.name];
+    return names.filter((n) => !!n);
+}
+/**
+ * The transaction capability of a provider, when it has one.
+ *
+ * `IMetadataProvider` does not declare transaction support — a browser provider genuinely has none —
+ * so this narrows by CAPABILITY rather than asserting a type the interface does not promise. A
+ * provider without it returns undefined and `RunInEntityTransaction` runs the work directly, which
+ * is the honest degradation: server submissions get atomicity, and a client submission behaves
+ * exactly as it did before rather than failing at a call site that claimed something untrue.
+ */
+function asTransactionCapable(provider) {
+    const candidate = provider;
+    return candidate.SupportsEntityTransactions === true && typeof candidate.BeginEntityTransaction === 'function'
+        ? candidate
+        : undefined;
+}
+export function FindUnrunnableKinds(spec) {
+    const offenders = spec.tasks.filter((t) => !DISPATCHABLE_KINDS.includes(t.kind));
+    if (offenders.length === 0)
+        return null;
+    const detail = offenders.map((t) => `"${t.name}" (${t.kind})`).join(', ');
+    return (`"${spec.workflowName}" cannot be run yet: ${detail}. ` +
+        `The dispatcher runs agent, action, person and loop steps. Prompt steps and steps completed ` +
+        `by an outside system are not supported yet — replace them, or split them out of this workflow.`);
+}
+/**
+ * Reports human steps assigned to someone other than the submitter, or `null` when there are none.
+ *
+ * Cross-user assignment needs an authorization model (#3524) — deciding that A may put work in B's
+ * inbox is a permissions question, not a graph question. Until it lands, a workflow can only ask the
+ * person who started it.
+ *
+ * **Why refuse rather than reassign.** Persist wrote `task.UserID = submitter` unconditionally, so
+ * an authored `assignToUserID` was overwritten in silence. Every layer above accepts the field —
+ * the flow compiler reads it into the spec, the validator passes it, the spec type declares it — so
+ * silence here is indistinguishable from support: the graph submits, a step appears in the WRONG
+ * person's inbox, the named person is never told, and the author has no reason to suspect any of it.
+ * Refusing while the graph is still the author's to edit is the only point at which saying so costs
+ * nothing.
+ */
+export function FindCrossUserAssignments(spec, submitterUserID) {
+    const offenders = spec.tasks.filter((t) => {
+        const assignTo = ConfigOf(t, 'Human')?.assignToUserID;
+        return !!assignTo && !UUIDsEqual(assignTo, submitterUserID);
+    });
+    if (offenders.length === 0)
+        return null;
+    const detail = offenders.map((t) => `"${t.name}"`).join(', ');
+    return (`"${spec.workflowName}" was not started: ${detail} asks a person other than whoever runs the ` +
+        `workflow. Assigning a step to someone else is not available yet (#3524) — a workflow can ` +
+        `only ask the person who started it. Remove assignToUserID from those steps.`);
+}
 export class TaskGraphService {
     /**
      * Validates and persists a task graph, returning as soon as it is durable.
@@ -92,20 +270,87 @@ export class TaskGraphService {
             LogError(`[TaskGraphService] ${message}`);
             return { Success: false, ErrorMessage: message };
         }
+        // 1b. Representability. Validation asks "is this a well-formed graph?"; this asks "can THIS
+        //     dispatcher run it?" — a different question, and one the pure validator has no business
+        //     answering, since capability is a property of the runtime, not of the spec.
+        const unrunnable = this.findUnrunnableKinds(spec);
+        if (unrunnable) {
+            LogError(`[TaskGraphService] ${unrunnable}`);
+            return { Success: false, ErrorMessage: unrunnable };
+        }
+        // 1b-ii. Assignability. Same question, narrower: this dispatcher can only ask the person who
+        //        submitted the graph. Persist used to overwrite an authored `assignToUserID` with
+        //        the submitter and say nothing, so a step meant for someone else landed in the
+        //        wrong inbox and the named person was never told. The compiler accepts the field and
+        //        the validator passes it, which makes silence here indistinguishable from support.
+        const misassigned = FindCrossUserAssignments(spec, context.ContextUser.ID);
+        if (misassigned) {
+            LogError(`[TaskGraphService] ${misassigned}`);
+            return { Success: false, ErrorMessage: misassigned };
+        }
+        // 1c. Chain depth. A flow that dispatches a graph containing itself recurses without bound,
+        //     and each hop costs real money and real rows before anyone notices. The cap is checked
+        //     HERE rather than at execution because refusing to write the graph is the only point at
+        //     which nothing has happened yet.
+        const depth = context.ReinvokeDepth ?? 0;
+        if (depth >= MAX_REINVOKE_DEPTH) {
+            const message = `"${spec.workflowName}" was not started: it is ${depth} levels deep in a chain of ` +
+                `workflows starting workflows, which is the limit. A workflow that reaches this is ` +
+                `almost always calling itself, directly or through another one.`;
+            LogError(`[TaskGraphService] ${message}`);
+            return { Success: false, ErrorMessage: message };
+        }
         try {
-            // 2. Resolve every agent BEFORE writing anything. An unresolvable agent is a hard
-            //    error, not a skipped node: silently dropping a task executes the graph with holes
-            //    where the caller's work should have been.
+            // 2. Resolve every agent and action BEFORE writing anything. An unresolvable name is a
+            //    hard error, not a skipped node: silently dropping a task executes the graph with
+            //    holes where the caller's work should have been.
             const agentIDsByName = await this.resolveAgents(spec, context);
             if (!agentIDsByName.Success) {
                 return { Success: false, ErrorMessage: agentIDsByName.ErrorMessage };
             }
+            const actionIDsByName = await this.resolveActions(spec, context);
+            if (!actionIDsByName.Success) {
+                return { Success: false, ErrorMessage: actionIDsByName.ErrorMessage };
+            }
+            const promptIDsByName = await this.resolvePrompts(spec, context);
+            if (!promptIDsByName.Success) {
+                return { Success: false, ErrorMessage: promptIDsByName.ErrorMessage };
+            }
             const taskTypeID = await this.ensureTaskType(context);
-            // 3. Persist. Parent first so children have a ParentID, then children, then edges —
-            //    edges last because they reference two child IDs that must both exist.
-            const parentTaskID = await this.persistParent(spec, taskTypeID, context);
-            const taskIDMap = await this.persistChildren(spec, parentTaskID, taskTypeID, agentIDsByName.Map, context);
-            await this.persistDependencies(spec, taskIDMap, context);
+            // 3. Persist — ALL of it, or none of it.
+            //
+            // ── The whole graph becomes visible together, or not at all ─────────────────────────
+            // The dispatcher discovers work by polling for child tasks in 'Pending'. Writing the
+            // children first and their dependencies afterwards leaves a window — milliseconds, but
+            // real — in which every task exists with NO prerequisites recorded yet. A poll landing
+            // there sees a graph of independent tasks and claims all of them at once.
+            //
+            // Observed, not theorised: in graph C08B36E3 the dependency gating `Research: focused`
+            // was written at 00:00:59.653 and that task STARTED at 00:00:59.647 — six milliseconds
+            // before the edge that was supposed to hold it back existed. `Close out: approved` ran
+            // in the same wave as the research steps, before the draft it was meant to judge had
+            // been written. The graph then reported Complete, having executed in an order its author
+            // never drew.
+            //
+            // A transaction is the whole fix: the dispatcher cannot observe a half-built graph
+            // because a half-built graph is never visible. `RunInEntityTransaction` degrades to
+            // running the work as-is on a provider that cannot transact, which is the correct
+            // fallback rather than a silent failure.
+            //
+            // The PARENT is inside it too. Written outside, a failure while persisting children or
+            // edges would roll those back and leave a childless parent durably in 'Pending' — which
+            // never settles (the rollup deliberately skips a graph with no nodes) and never dies, so
+            // the active-graph scan picks it up on every poll forever: permanent debris plus a
+            // permanent tick of wasted work for each failed submit. Ordering inside the transaction
+            // is unchanged, because edges only ever reference child IDs.
+            const { parentTaskID, taskIDMap } = await RunInEntityTransaction(asTransactionCapable(context.Provider), async () => {
+                // Parent first so children have a ParentID, then children, then edges — edges
+                // last because they reference two child IDs that must both exist.
+                const parentID = await this.persistParent(spec, taskTypeID, context);
+                const map = await this.persistChildren(spec, parentID, taskTypeID, agentIDsByName.Map, actionIDsByName.Map, promptIDsByName.Map, context);
+                await this.persistDependencies(spec, map, context);
+                return { parentTaskID: parentID, taskIDMap: map };
+            });
             LogStatus(`[TaskGraphService] Submitted "${spec.workflowName}": parent ${parentTaskID}, ${taskIDMap.size} task(s). ` +
                 `Awaiting dispatcher pickup.`);
             return { Success: true, ParentTaskID: parentTaskID, TaskIDMap: taskIDMap };
@@ -135,6 +380,13 @@ export class TaskGraphService {
                     LogError(`[TaskGraphService] Failed to cancel task ${child.ID}: ${child.LatestResult?.CompleteMessage ?? 'unknown error'}`);
                 }
             }
+            // Withdraw the questions too. A human step that was waiting has an open
+            // `MJ: AI Agent Requests` row, and cancelling only the Task left that row `Requested`
+            // FOREVER: the person keeps seeing "a workflow is waiting on you" in their inbox for a
+            // workflow that no longer exists, and answering it settles nothing because the task is
+            // already Cancelled. Nothing else ever closes these — the dispatcher only expires rows
+            // that carry a deadline, and most do not.
+            await this.cancelOpenRequests(children.map((c) => c.ID), context);
             const parent = await context.Provider.GetEntityObject('MJ: Tasks', context.ContextUser);
             if (!(await parent.Load(parentTaskID)))
                 return false;
@@ -147,6 +399,50 @@ export class TaskGraphService {
             return false;
         }
     }
+    /**
+     * Closes the still-open requests raised for a set of tasks.
+     *
+     * `Canceled` rather than `Expired`: nobody ran out of time, the ask was withdrawn — and the two
+     * mean different things downstream, since the dispatcher treats an expired human step as a
+     * FAILURE a give-up edge can route around, which would be a lie about a graph somebody stopped
+     * on purpose.
+     *
+     * Failures here are logged and never propagated: the graph is already cancelled, and refusing to
+     * finish that because an inbox row would not close would leave the graph in a worse state than
+     * the debris it is trying to avoid.
+     */
+    async cancelOpenRequests(taskIDs, context) {
+        if (taskIDs.length === 0)
+            return;
+        try {
+            const idList = taskIDs.map((id) => `'${id}'`).join(',');
+            const open = await RunView.FromMetadataProvider(context.Provider).RunView({
+                EntityName: 'MJ: AI Agent Requests',
+                ExtraFilter: `Status='Requested' AND OriginatingTaskID IN (${idList})`,
+                ResultType: 'entity_object',
+                BypassCache: true,
+            }, context.ContextUser);
+            if (!open.Success) {
+                LogError(`[TaskGraphService] Could not read open requests to cancel: ${open.ErrorMessage}`);
+                return;
+            }
+            for (const request of open.Results ?? []) {
+                request.Status = 'Canceled';
+                request.Comments = 'The workflow that asked this was cancelled.';
+                if (!(await request.Save())) {
+                    LogError(`[TaskGraphService] Could not withdraw request ${request.ID}: ` +
+                        `${request.LatestResult?.CompleteMessage ?? 'unknown error'}. It will keep showing ` +
+                        `in someone's inbox for a workflow that no longer exists.`);
+                }
+            }
+            if ((open.Results ?? []).length > 0) {
+                LogStatus(`[TaskGraphService] Withdrew ${open.Results.length} open request(s) for the cancelled graph.`);
+            }
+        }
+        catch (e) {
+            LogError(`[TaskGraphService] Could not withdraw open requests: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
     /**
      * Returns a failed task to `Pending` so the dispatcher can run it again.
      *
@@ -193,7 +489,10 @@ export class TaskGraphService {
     // ────────────────────────────────────────────────────────────────────────
     /** Maps every referenced agent name to its ID, or reports all unresolvable names at once. */
     async resolveAgents(spec, context) {
-        const names = [...new Set(spec.tasks.filter((t) => !!t.agentName).map((t) => t.agentName))];
+        // A loop's repeated sub-agent counts as a referenced agent. Collecting only the Agent nodes
+        // left a loop body pointing at a name nothing had resolved, so the row got no AgentID and
+        // the loop had nothing to run.
+        const names = [...new Set(spec.tasks.flatMap(agentNamesIn))];
         if (names.length === 0)
             return { Success: true, Map: new Map() };
         const quoted = names.map((n) => `'${n.replace(/'/g, "''")}'`).join(',');
@@ -209,6 +508,54 @@ export class TaskGraphService {
         }
         return { Success: true, Map: found };
     }
+    /**
+     * Maps every referenced action name to its ID, or reports all unresolvable names at once.
+     *
+     * Deliberately a mirror of {@link resolveAgents} rather than a generalization of it: the two
+     * read different entities and produce different error prose, and the shared shape is three
+     * lines. Collapsing them would trade a readable failure message for a parameterized lookup.
+     */
+    /**
+     * Maps every referenced prompt name to its ID.
+     *
+     * A prompt is addressed by name in the spec and stored as a foreign key on the row, exactly like
+     * agents and actions — a name in JSON cannot be joined, checked, or survive a rename.
+     */
+    async resolvePrompts(spec, context) {
+        const names = [...new Set(spec.tasks.flatMap(promptNamesIn))];
+        if (names.length === 0)
+            return { Success: true, Map: new Map() };
+        const quoted = names.map((n) => `'${n.replace(/'/g, "''")}'`).join(',');
+        const result = await RunView.FromMetadataProvider(context.Provider).RunView({ EntityName: 'MJ: AI Prompts', ExtraFilter: `Name IN (${quoted})`, Fields: ['ID', 'Name'], ResultType: 'simple' }, context.ContextUser);
+        const found = new Map((result.Results ?? []).map((r) => [r.Name, r.ID]));
+        const missing = names.filter((n) => !found.has(n));
+        if (missing.length > 0) {
+            return {
+                Success: false,
+                ErrorMessage: `Task graph "${spec.workflowName}" references ${missing.length} unknown prompt(s): ${missing.join(', ')}. ` +
+                    `Submitting would execute the graph with holes where those steps should be.`,
+            };
+        }
+        return { Success: true, Map: found };
+    }
+    async resolveActions(spec, context) {
+        // Includes a loop's repeated action — see the note in resolveAgents.
+        const names = [...new Set(spec.tasks.flatMap(actionNamesIn))];
+        if (names.length === 0)
+            return { Success: true, Map: new Map() };
+        const quoted = names.map((n) => `'${n.replace(/'/g, "''")}'`).join(',');
+        const result = await RunView.FromMetadataProvider(context.Provider).RunView({ EntityName: 'MJ: Actions', ExtraFilter: `Name IN (${quoted})`, Fields: ['ID', 'Name'], ResultType: 'simple' }, context.ContextUser);
+        const found = new Map((result.Results ?? []).map((r) => [r.Name, r.ID]));
+        const missing = names.filter((n) => !found.has(n));
+        if (missing.length > 0) {
+            return {
+                Success: false,
+                ErrorMessage: `Task graph "${spec.workflowName}" references ${missing.length} unknown action(s): ${missing.join(', ')}. ` +
+                    `Submitting would execute the graph with holes where those tasks should be.`,
+            };
+        }
+        return { Success: true, Map: found };
+    }
     /** Finds or creates the task type used for orchestrated graphs. */
     async ensureTaskType(context) {
         const existing = await RunView.FromMetadataProvider(context.Provider).RunView({ EntityName: 'MJ: Task Types', ExtraFilter: `Name='${TASK_TYPE_NAME}'`, Fields: ['ID'], ResultType: 'simple', MaxRows: 1 }, context.ContextUser);
@@ -235,6 +582,11 @@ export class TaskGraphService {
         parent.ConversationDetailID = context.ConversationDetailID ?? null;
         parent.Status = 'In Progress';
         parent.PercentComplete = 0;
+        // The run that submitted this graph, in the COLUMN and not only in the metadata JSON below.
+        // A json field cannot be joined, so provenance that lives only there is unavailable to any
+        // query — which is how a human step ended up with no agent to ask on behalf of, and how a
+        // dispatched run had no parent to roll its cost up to.
+        parent.AgentRunID = context.AgentRunID ?? null;
         // The parent row carries what happens AFTER the graph settles. It lives here rather than in
         // dispatcher memory because the dispatcher that finishes a graph is frequently not the
         // process that accepted it — a restart, a second instance, or simply a long-running graph
@@ -242,6 +594,7 @@ export class TaskGraphService {
         parent.InputPayload = JSON.stringify({
             continuation: spec.continuation ?? 'message',
             reinvokeDepth: context.ReinvokeDepth ?? 0,
+            failureSemantics: spec.failureSemantics ?? 'block',
             submittedByAgentRunID: context.AgentRunID ?? null,
             submittedByUserID: context.ContextUser?.ID ?? null,
         });
@@ -251,8 +604,11 @@ export class TaskGraphService {
         return parent.ID;
     }
     /** Writes each child task, returning the tempId -> real ID mapping edges will need. */
-    async persistChildren(spec, parentTaskID, taskTypeID, agentIDsByName, context) {
+    async persistChildren(spec, parentTaskID, taskTypeID, agentIDsByName, actionIDsByName, promptIDsByName, context) {
         const map = new Map();
+        // Resolved ONCE over the whole graph: a rank is a node's position in the topology, so it
+        // cannot be computed per node without seeing all of them.
+        const ranks = RankGraphNodes(spec.tasks.map((t) => t.tempId), spec.tasks.flatMap((t) => (t.dependsOn ?? []).map((d) => ({ From: NormalizeDependency(d).tempId, To: t.tempId }))));
         for (const node of spec.tasks) {
             const task = await context.Provider.GetEntityObject('MJ: Tasks', context.ContextUser);
             task.NewRecord();
@@ -264,14 +620,69 @@ export class TaskGraphService {
             task.ConversationDetailID = context.ConversationDetailID ?? null;
             task.Status = 'Pending';
             task.PercentComplete = 0;
-            if (node.agentName) {
-                task.AgentID = agentIDsByName.get(node.agentName);
-            }
-            else {
-                // Human task. Assigned to the submitting user only — cross-user assignment stays
-                // rejected until the authorization model in #3524 lands.
-                task.UserID = context.ContextUser.ID;
+            // The discriminator the dispatcher routes on. Written first because everything below —
+            // and everything the dispatcher later does with this row — reads it.
+            task.StepType = node.kind;
+            // Switching on `kind` rather than on which config field happens to be populated. The
+            // old shape — "agentName? then agent; actionName? then action; ELSE human" — turned
+            // every kind it did not know about into a Human task assigned to the submitter, so a
+            // ForEach step became an approval request that nobody had asked for and nothing would
+            // ever complete. A graph that stalls forever while LOOKING like it is waiting on a
+            // person is the worst available failure. `findUnrunnableKinds` refuses unsupported
+            // kinds before anything is written; this switch is what keeps the two in step.
+            switch (node.kind) {
+                case 'Agent':
+                    task.AgentID = agentIDsByName.get(ConfigOf(node, 'Agent').agentName);
+                    break;
+                case 'Action':
+                    task.ActionID = actionIDsByName.get(ConfigOf(node, 'Action').actionName);
+                    break;
+                case 'Human':
+                    // Assigned to the submitting user only — cross-user assignment stays rejected
+                    // until the authorization model in #3524 lands, and `findCrossUserAssignments`
+                    // has already refused any graph that asked for someone else.
+                    task.UserID = context.ContextUser.ID;
+                    break;
+                case 'Prompt':
+                    task.PromptID = promptIDsByName.get(ConfigOf(node, 'Prompt').promptName);
+                    break;
+                case 'ForEach':
+                case 'While': {
+                    // A loop's key points at what it REPEATS, not at the loop itself. That keeps the
+                    // reference a real foreign key — joinable, constrained, rename-proof — instead
+                    // of a name buried in JSON, and CK_Task_Assignment still holds because a loop
+                    // body is exactly one thing.
+                    const op = LoopOperationOf(node);
+                    if (op?.action)
+                        task.ActionID = actionIDsByName.get(op.action.name);
+                    else if (op?.subAgent)
+                        task.AgentID = agentIDsByName.get(op.subAgent.name);
+                    else if (op?.prompt)
+                        task.PromptID = promptIDsByName.get(op.prompt.name);
+                    else {
+                        throw new Error(`Task "${node.name}" is a loop with nothing to repeat. Choose an action, ` +
+                            `a prompt, or a sub-agent for it to run on each pass.`);
+                    }
+                    break;
+                }
+                default:
+                    // Unreachable: findUnrunnableKinds rejected these before any write. Throwing
+                    // rather than falling through means a kind added later fails loudly here
+                    // instead of quietly becoming somebody's to-do item.
+                    throw new Error(`Task "${node.name}" has kind "${node.kind}", which cannot be persisted for dispatch.`);
             }
+            // Everything about the step that has no column of its own. Dropping this is what used
+            // to lose the input/output mappings — and with them the payload values every branch
+            // condition downstream reads.
+            //
+            // The step's rank in the graph's own order rides along. `Task` has no sequence column,
+            // so without it every consumer listing a graph's steps falls back to creation order —
+            // the compiler's walk, which is neither the order they were drawn in nor the order they
+            // run in. A graph that has not started yet has no timestamps to sort by, so its
+            // structure is the only order available, and it is available from the moment it is
+            // compiled.
+            const configuration = { ...buildStepConfiguration(node), sequence: ranks.get(node.tempId) };
+            task.Configuration = JSON.stringify(configuration);
             // Input rides in its own column; Description stays human-readable.
             task.InputPayload = node.inputPayload ? JSON.stringify(node.inputPayload) : null;
             if (!(await task.Save())) {
@@ -281,6 +692,25 @@ export class TaskGraphService {
         }
         return map;
     }
+    /**
+     * Reports the node kinds this dispatcher cannot yet execute, or `null` when the graph is
+     * entirely runnable.
+     *
+     * **Why this is a submit-time check and not a validation rule.** `ValidateTaskGraphSpec` is a
+     * pure function over the spec: it answers "is this a well-formed graph?", and its answer must be
+     * the same in a browser, a CLI and a server. "Can it run *here*?" is a different question whose
+     * answer changes as runners are added, so it belongs to the runtime that owns the runners.
+     *
+     * **Why refuse rather than persist-and-stall.** `Prompt`, `ForEach`, `While` and `External`
+     * are legitimate parts of the spec, but the `Task` row has nowhere to carry a node's `kind` or
+     * its typed `configuration` — so a persisted one could not be dispatched even if a runner
+     * existed. Refusing at the door tells the author which step is the problem while the graph is
+     * still theirs to edit. The alternative is a graph that submits successfully and then never
+     * finishes, which costs an operator an afternoon to diagnose.
+     */
+    findUnrunnableKinds(spec) {
+        return FindUnrunnableKinds(spec);
+    }
     /** Writes the dependency edges, translating tempIds to persisted IDs. */
     async persistDependencies(spec, taskIDMap, context) {
         for (const node of spec.tasks) {
@@ -300,6 +730,15 @@ export class TaskGraphService {
                 // NULL for an unconditional edge, matching AIAgentStepPath — so a graph authored in
                 // the flow editor and one emitted by an agent store the same thing.
                 dep.Condition = edge.condition ?? null;
+                // The exclusive-choice fields. Dropping these was silent and severe: without an
+                // ExclusiveGroup the dispatcher sees a plain fan-out and runs EVERY branch, so a
+                // workflow that should pick one route would take all of them — doing work its author
+                // never intended and, in the Demo workflow's case, calling two different APIs where
+                // the flow calls one. Priority and Sequence are what decide which branch wins, so a
+                // group without them resolves arbitrarily.
+                dep.ExclusiveGroup = edge.exclusiveGroup ?? null;
+                dep.Priority = edge.priority ?? 0;
+                dep.Sequence = edge.sequence ?? 0;
                 if (!(await dep.Save())) {
                     throw new Error(`Could not create dependency ${node.tempId} -> ${edge.tempId}: ${dep.LatestResult?.CompleteMessage ?? 'unknown error'}`);
                 }