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

package/dist/TaskGraphDispatcher.js

@@ -0,0 +1,735 @@
+/**
+ * @fileoverview Durable, host-agnostic execution of submitted task graphs.
+ *
+ * The dispatcher is what makes task graphs survive things the old client-driven path could not: a
+ * page reload, the submitting agent run ending, a server restart, or a second server instance
+ * running the same table. It polls for claimable work, claims atomically, executes with a fresh
+ * provider per task, and reconciles orphaned state on a timer.
+ *
+ * **What it deliberately does not do.** It does not decide graph semantics. Eligibility, failure
+ * propagation, parent rollup and stall detection all come from the pure algorithms in
+ * `@memberjunction/ai-core-plus` — the same functions the in-run executor consumes. That is
+ * the whole reason those were factored out dependency-free: the in-run executor and the durable
+ * executor cannot drift apart if neither owns the rules.
+ *
+ * **Host-agnostic by construction.** Provider minting and agent execution arrive as injected
+ * dependencies (`ProviderFactory`, `TaskAgentRunner`), so this package never imports MJServer. The
+ * dependency runs MJServer -> task-graph, never the reverse.
+ *
+ * @module @memberjunction/task-graph
+ */
+import { ComputeEligibleTasks, ComputeParentRollup, ComputeTasksToBlock, IsGraphStalled, } from '@memberjunction/ai-core-plus';
+import { LogError, LogStatus, RunView } from '@memberjunction/core';
+import { ShutdownRegistry } from '@memberjunction/global';
+import { TaskClaimStore } from './TaskClaimStore.js';
+import { DispatcherConditionEvaluator } from './DispatcherConditionEvaluator.js';
+import { NotificationEngine } from '@memberjunction/notifications';
+/** Metadata-seeded notification type for human tasks (metadata/notifications/.task-assignment-type.json). */
+const HUMAN_TASK_NOTIFICATION_TYPE = 'Task Assignment';
+/**
+ * Written to a human task's `ClaimedBy` once its assignee has been told it is ready.
+ *
+ * A human task has no executor, so the claim column is otherwise unused — which makes it the natural
+ * place to record a fact that must survive a restart. Reconciliation already exempts human tasks
+ * from reclamation, so this value is never mistaken for a live claim.
+ */
+const HUMAN_TASK_NOTIFIED_MARKER = '__human-notified__';
+import { IsReinvokeCapReached, MAX_REINVOKE_DEPTH, ParseTaskGraphParentMetadata } from './TaskGraphService.js';
+import { DEFAULT_DISPATCHER_CONFIG, } from './types.js';
+export class TaskGraphDispatcher {
+    constructor(providerFactory, agentRunner, contextUser, config, 
+    /**
+     * Optional. Absent means a host that cannot post messages or start agent turns — a worker,
+     * a test. The dispatcher still records and logs every completion, so a graph's outcome is
+     * never lost; it simply is not announced.
+     */
+    continuationDeliverer, 
+    /**
+     * Optional. Absent means nobody is watching — the dispatcher behaves identically, it just
+     * announces nothing.
+     */
+    observer) {
+        this.providerFactory = providerFactory;
+        this.agentRunner = agentRunner;
+        this.contextUser = contextUser;
+        this.continuationDeliverer = continuationDeliverer;
+        this.observer = observer;
+        this.running = false;
+        this.pollTimer = null;
+        this.reconcileTimer = null;
+        /** Tasks this instance is currently executing — bounds concurrency and drives heartbeats. */
+        this.inFlight = new Set();
+        /** Guards against a slow poll overlapping the next tick. */
+        this.polling = false;
+        /** Graph → owning user, from the parent's durable metadata. Ownership never changes, so this never goes stale. */
+        this.ownerByParentID = new Map();
+        /** Name shown in the shutdown drain log. */
+        this.ShutdownName = 'TaskGraphDispatcher';
+        this.config = { ...DEFAULT_DISPATCHER_CONFIG, ...config };
+        this.claims = new TaskClaimStore(this.config.InstanceID, this.config.ClaimTTLSeconds);
+        this.conditionEvaluator = new DispatcherConditionEvaluator();
+    }
+    /**
+     * Announce something that happened, and never let the announcement matter.
+     *
+     * A frame is commentary on work, never a step of it, so an observer that throws must not be able
+     * to fail a task or stall a graph. Swallowing here rather than asking every implementation to be
+     * careful means one place enforces it.
+     */
+    emit(frame) {
+        if (!this.observer)
+            return;
+        try {
+            this.observer.OnFrame(frame);
+        }
+        catch (e) {
+            LogError(`[TaskGraphDispatcher] Observer threw on ${frame.Kind} (ignored): ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /**
+     * Who a graph belongs to, memoized for the process's lifetime.
+     *
+     * Read from the parent's durable metadata rather than a column, because `Task.UserID` means
+     * "the person this task is waiting on" — setting it on a parent would make every graph look
+     * like a human task. Memoized because frames are emitted per step: without the cache, watching
+     * a run would cost one query per event, and observability that scales with work is the thing a
+     * push mechanism exists to avoid. Ownership never changes for a given graph, so the cache can
+     * never go stale.
+     *
+     * Skipped entirely when nobody is observing — the lookup exists only to address frames.
+     */
+    async resolveOwner(provider, parentTaskID) {
+        if (!this.observer)
+            return null;
+        const cached = this.ownerByParentID.get(parentTaskID);
+        if (cached !== undefined)
+            return cached;
+        let owner = null;
+        try {
+            const parent = await provider.GetEntityObject('MJ: Tasks', this.contextUser);
+            if (await parent.Load(parentTaskID)) {
+                owner = this.readParentMetadata(parent).submittedByUserID ?? null;
+            }
+        }
+        catch (e) {
+            LogError(`[TaskGraphDispatcher] Could not resolve owner for graph ${parentTaskID}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        this.ownerByParentID.set(parentTaskID, owner);
+        return owner;
+    }
+    /**
+     * Begins dispatching.
+     *
+     * Runs reconciliation FIRST, before accepting any new work. On a restart this instance may be
+     * looking at tasks its own previous incarnation claimed and never released — reclaiming those
+     * up front is what turns a crash from "work stranded forever" into "work resumes".
+     */
+    async Start() {
+        if (this.running)
+            return;
+        this.running = true;
+        // Self-register rather than make each host remember to stop us. A dispatcher that keeps
+        // polling through a graceful shutdown would claim work the process is about to abandon,
+        // which is exactly the orphaned-claim state reconciliation exists to clean up.
+        ShutdownRegistry.Instance.Register(this);
+        LogStatus(`[TaskGraphDispatcher] Starting as instance '${this.config.InstanceID}'.`);
+        await this.Reconcile();
+        this.pollTimer = setInterval(() => { void this.pollOnce(); }, this.config.PollIntervalSeconds * 1000);
+        this.reconcileTimer = setInterval(() => { void this.Reconcile(); }, this.config.ReconciliationIntervalSeconds * 1000);
+    }
+    /**
+     * Stops accepting new work and waits for in-flight tasks to finish.
+     *
+     * Deliberately does NOT release claims on the way out: an abandoned claim expires on its own,
+     * and releasing eagerly would hand a still-running task to another instance mid-execution.
+     * Letting the TTL do it is the safer failure mode.
+     */
+    async Stop() {
+        this.running = false;
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        if (this.reconcileTimer) {
+            clearInterval(this.reconcileTimer);
+            this.reconcileTimer = null;
+        }
+        const deadline = Date.now() + 30_000;
+        while (this.inFlight.size > 0 && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 250));
+        }
+        if (this.inFlight.size > 0) {
+            LogError(`[TaskGraphDispatcher] Stopped with ${this.inFlight.size} task(s) still in flight; their claims will expire.`);
+        }
+        LogStatus(`[TaskGraphDispatcher] Stopped.`);
+    }
+    /** {@link IShutdownable} — idempotent by way of `Stop`'s `running` guard. */
+    async Shutdown() {
+        await this.Stop();
+    }
+    /**
+     * Reclaims expired claims and reports anomalies.
+     *
+     * Also enforces the two schema promises that previously had no enforcer anywhere: agent tasks
+     * left `In Progress` with no claim are surfaced loudly rather than silently corrected, since
+     * that shape indicates tampering or a bug and Record Changes already carries the audit trail.
+     */
+    async Reconcile() {
+        let provider = null;
+        try {
+            provider = await this.providerFactory.CreateProvider();
+            const released = await this.claims.ReleaseExpiredClaims(provider, this.contextUser);
+            const orphaned = await this.claims.FindOrphanedInProgress(provider, this.contextUser);
+            if (released.length > 0 || orphaned.length > 0) {
+                LogStatus(`[TaskGraphDispatcher] Reconciliation: ${released.length} expired claim(s) released, ` +
+                    `${orphaned.length} orphaned task(s) reported.`);
+            }
+        }
+        catch (e) {
+            LogError(`[TaskGraphDispatcher] Reconciliation failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /**
+     * One dispatch pass: find claimable work, claim what fits under the concurrency cap, execute.
+     *
+     * Overlap-guarded — a pass that runs long simply skips the next tick rather than stacking, which
+     * would otherwise let a slow database multiply in-flight work past the cap.
+     */
+    async pollOnce() {
+        if (!this.running || this.polling)
+            return;
+        const capacity = this.config.MaxConcurrentTasks - this.inFlight.size;
+        if (capacity <= 0)
+            return;
+        this.polling = true;
+        try {
+            const provider = await this.providerFactory.CreateProvider();
+            // Settle graphs before picking new work, so a failure earlier in this pass stops its
+            // branch immediately rather than after another wave has already launched.
+            await this.propagateAndRollup(provider);
+            const candidates = await this.findClaimableTasks(provider, capacity);
+            for (const task of candidates) {
+                if (this.inFlight.size >= this.config.MaxConcurrentTasks)
+                    break;
+                if (!(await this.claims.TryClaim(provider, task.ID, this.contextUser))) {
+                    // Another instance won the race, or the task is no longer Pending. Normal.
+                    continue;
+                }
+                this.inFlight.add(task.ID);
+                // Intentionally not awaited — the poll loop must keep dispatching while this runs.
+                void this.executeClaimed(task.ID).finally(() => this.inFlight.delete(task.ID));
+            }
+        }
+        catch (e) {
+            LogError(`[TaskGraphDispatcher] Poll failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        finally {
+            this.polling = false;
+        }
+    }
+    /**
+     * Executes one claimed task on its own provider, heartbeating until it settles.
+     *
+     * A fresh provider per task is the point of `ProviderFactory`: parallel tasks must not share a
+     * transaction scope or entity instances, or one task's work becomes visible inside another's.
+     */
+    async executeClaimed(taskID) {
+        let heartbeat = null;
+        try {
+            const provider = await this.providerFactory.CreateProvider();
+            const task = await provider.GetEntityObject('MJ: Tasks', this.contextUser);
+            if (!(await task.Load(taskID))) {
+                LogError(`[TaskGraphDispatcher] Claimed task ${taskID} could not be loaded.`);
+                return;
+            }
+            heartbeat = setInterval(() => {
+                void this.claims.Heartbeat(provider, taskID, this.contextUser).then((ok) => {
+                    if (!ok) {
+                        // Lost ownership — reconciliation reclaimed it, or a human intervened.
+                        LogError(`[TaskGraphDispatcher] Lost claim on task ${taskID} while executing; another instance may take it over.`);
+                    }
+                });
+            }, this.config.HeartbeatIntervalSeconds * 1000);
+            // Emitted after the claim is held, not before: a frame saying "started" for work another
+            // instance actually took would be a lie a viewer cannot detect.
+            const graphID = task.ParentID ?? taskID;
+            const ownerUserID = await this.resolveOwner(provider, graphID);
+            this.emit({ Kind: 'TaskStarted', ParentTaskID: graphID, OwnerUserID: ownerUserID, TaskID: taskID, TaskName: task.Name, Status: 'In Progress' });
+            const dependencyOutputs = await this.loadDependencyOutputs(provider, taskID);
+            let inputPayload = null;
+            if (task.InputPayload) {
+                try {
+                    inputPayload = JSON.parse(task.InputPayload);
+                }
+                catch (e) {
+                    LogError(`[TaskGraphDispatcher] Task ${taskID} has malformed InputPayload: ${e}`);
+                }
+            }
+            const result = await this.agentRunner.RunAgentForTask({
+                TaskID: taskID,
+                AgentID: task.AgentID,
+                InputPayload: inputPayload,
+                DependencyOutputs: dependencyOutputs,
+                Provider: provider,
+                ContextUser: this.contextUser,
+            });
+            const recorded = await this.claims.CompleteClaimed(provider, taskID, {
+                Status: result.Success ? 'Complete' : 'Failed',
+                OutputPayload: result.Output != null ? JSON.stringify(result.Output) : null,
+                ErrorMessage: result.ErrorMessage ?? null,
+                AgentRunID: result.AgentRunID ?? null,
+            }, this.contextUser);
+            if (!recorded) {
+                // The guarded write refused: the row changed underneath us (cancelled, reassigned,
+                // or reclaimed). Deferring to whoever owns it now is correct — overwriting would
+                // undo a newer, deliberate decision.
+                LogError(`[TaskGraphDispatcher] Could not record outcome for ${taskID}; the task is no longer owned by this instance.`);
+            }
+            else {
+                // Only announced when the guarded write actually landed. Announcing an outcome we
+                // failed to persist would show a viewer a completion the database never recorded.
+                this.emit({
+                    Kind: result.Success ? 'TaskCompleted' : 'TaskFailed',
+                    ParentTaskID: graphID,
+                    OwnerUserID: ownerUserID,
+                    TaskID: taskID,
+                    TaskName: task.Name,
+                    Status: result.Success ? 'Complete' : 'Failed',
+                    ErrorMessage: result.Success ? undefined : (result.ErrorMessage ?? undefined),
+                });
+            }
+        }
+        catch (e) {
+            LogError(`[TaskGraphDispatcher] Execution failed for ${taskID}: ${e instanceof Error ? e.message : String(e)}`);
+            try {
+                const provider = await this.providerFactory.CreateProvider();
+                await this.claims.CompleteClaimed(provider, taskID, { Status: 'Failed', ErrorMessage: e instanceof Error ? e.message : String(e) }, this.contextUser);
+            }
+            catch { /* already logged; nothing further to do */ }
+        }
+        finally {
+            if (heartbeat)
+                clearInterval(heartbeat);
+        }
+    }
+    /**
+     * Applies failure propagation and parent rollup across every graph with active work.
+     *
+     * All four decisions — what is eligible, what must block, what the parent status is, whether the
+     * graph is wedged — are delegated to the pure algorithms, unchanged from Phase 1.
+     */
+    async propagateAndRollup(provider) {
+        for (const parentID of await this.findActiveGraphIDs(provider)) {
+            const graph = await this.loadGraphState(provider, parentID);
+            if (graph.nodes.length === 0)
+                continue;
+            const toBlock = new Set([...ComputeTasksToBlock(graph.nodes, graph.edges), ...graph.unreachableTaskIDs]);
+            for (const taskID of toBlock) {
+                const entity = graph.entityById.get(taskID);
+                if (!entity)
+                    continue;
+                entity.Status = 'Blocked';
+                if (await entity.Save()) {
+                    LogStatus(`[TaskGraphDispatcher] Blocked '${entity.Name}' (${taskID}) — a dependency can never be satisfied.`);
+                    // Worth announcing on its own: a blocked step is the one outcome a viewer would
+                    // otherwise see as a task that simply never starts.
+                    this.emit({
+                        Kind: 'TaskBlocked',
+                        ParentTaskID: parentID,
+                        OwnerUserID: await this.resolveOwner(provider, parentID),
+                        TaskID: taskID,
+                        TaskName: entity.Name,
+                        Status: 'Blocked',
+                    });
+                }
+            }
+            if (IsGraphStalled(graph.nodes, graph.edges)) {
+                LogError(`[TaskGraphDispatcher] Graph ${parentID} is stalled: pending work with no satisfiable path.`);
+            }
+            const fresh = await this.loadGraphState(provider, parentID);
+            // ComputeParentRollup treats an empty child set as Complete-and-terminal, which is right
+            // for a graph that genuinely has no children and catastrophic for one whose reload came
+            // back empty transiently — it would mark live work finished and fire its continuation.
+            // The outer guard covered the first load only.
+            if (fresh.nodes.length === 0)
+                continue;
+            const rollup = ComputeParentRollup(fresh.nodes);
+            const parent = await provider.GetEntityObject('MJ: Tasks', this.contextUser);
+            if (!(await parent.Load(parentID)))
+                continue;
+            if (parent.Status !== rollup.status || parent.PercentComplete !== rollup.percentComplete) {
+                parent.Status = rollup.status;
+                parent.PercentComplete = rollup.percentComplete;
+                if (rollup.isTerminal)
+                    parent.CompletedAt = new Date();
+                await parent.Save();
+            }
+            if (rollup.isTerminal) {
+                // Emitted before the continuation is delivered, and outside its once-only guard: a
+                // viewer watching the run should learn it finished whether or not this instance is
+                // the one that wins the delivery CAS.
+                this.emit({
+                    Kind: 'GraphSettled',
+                    ParentTaskID: parentID,
+                    OwnerUserID: await this.resolveOwner(provider, parentID),
+                    Status: rollup.status,
+                    CompletedCount: fresh.nodes.filter((n) => n.status === 'Complete').length,
+                    TotalCount: fresh.nodes.length,
+                });
+                await this.deliverContinuation(provider, parent, fresh);
+            }
+        }
+    }
+    /**
+     * Runs the graph's continuation exactly once, now that it has settled.
+     *
+     * **Why the delivery marker is written before the side effect.** Delivery is at-least-once by
+     * nature: the process can die between "the graph is done" and "the user has been told". Marking
+     * first and acting second means the worst case is a *missed* notification that shows up in the
+     * task record as delivered — recoverable, visible, and inspectable. Marking after would make the
+     * worst case a *repeated* notification on every reconciliation sweep, forever, which is both
+     * user-visible noise and, for `reinvoke`, an unbounded agent-run loop. Given one of the two has
+     * to be chosen, the quiet failure is the safe one.
+     *
+     * The marker is written with a compare-and-swap read-back, so two instances reconciling the same
+     * completed graph produce one winner rather than two.
+     */
+    async deliverContinuation(provider, parent, graph) {
+        const meta = this.readParentMetadata(parent);
+        if (meta.continuationDeliveredAt)
+            return;
+        // At the cap, downgrade rather than refuse: the results still reach the user, the chain just
+        // stops growing. Refusing outright would lose the outcome of work that actually completed.
+        const mode = IsReinvokeCapReached(meta) ? 'message' : meta.continuation;
+        if (mode !== 'none' && IsReinvokeCapReached(meta) && meta.continuation === 'reinvoke') {
+            LogStatus(`[TaskGraphDispatcher] Graph ${parent.ID} hit the reinvoke cap (${MAX_REINVOKE_DEPTH}); ` +
+                `delivering results as a message instead of starting another turn.`);
+        }
+        if (!(await this.claimContinuation(provider, parent.ID, meta)))
+            return;
+        if (mode === 'none')
+            return;
+        const summary = this.buildContinuationSummary(parent, graph);
+        LogStatus(`[TaskGraphDispatcher] Graph ${parent.ID} finished — ${summary}`);
+        if (!this.continuationDeliverer)
+            return;
+        const params = {
+            ParentTaskID: parent.ID,
+            WorkflowName: parent.Name,
+            ConversationDetailID: parent.ConversationDetailID ?? null,
+            SubmittedByAgentRunID: meta.submittedByAgentRunID,
+            ReinvokeDepth: meta.reinvokeDepth,
+            Tasks: [...graph.entityById.values()].map((t) => ({
+                TaskID: t.ID,
+                Name: t.Name,
+                Status: t.Status,
+                // A reference, not the payload. Inlining every task's output would swamp the
+                // continuation turn's context; the agent pulls what it needs by task ID.
+                Summary: t.OutputPayload ? `output available (${t.OutputPayload.length} chars)` : undefined,
+                ErrorMessage: t.ErrorMessage ?? undefined,
+            })),
+            Summary: summary,
+        };
+        try {
+            // Reinvoke degrades to a message when the host cannot start agent turns. Degrading is
+            // right rather than throwing: the work genuinely ran, and the user losing the results
+            // because nobody could start a follow-up turn would be the worse outcome.
+            if (mode === 'reinvoke' && this.continuationDeliverer.Reinvoke) {
+                await this.continuationDeliverer.Reinvoke(params);
+            }
+            else {
+                if (mode === 'reinvoke') {
+                    LogStatus(`[TaskGraphDispatcher] Graph ${parent.ID}: host cannot reinvoke; delivering as a message.`);
+                }
+                await this.continuationDeliverer.PostMessage(params);
+            }
+        }
+        catch (e) {
+            // Already marked delivered, so this will not retry. That is the deliberate trade stated
+            // on the marker: a missed notification visible in the record beats one repeated forever.
+            LogError(`[TaskGraphDispatcher] Continuation delivery failed for ${parent.ID}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /** Reads the parent's durable continuation metadata through the shared parser. */
+    readParentMetadata(parent) {
+        return ParseTaskGraphParentMetadata(parent.InputPayload);
+    }
+    /**
+     * Stamps the delivery marker and confirms this instance won the race.
+     *
+     * `MJ: Tasks` stays user-writable (D20), so a plain "read, decide, write" is not enough — the
+     * read-back is what makes a lost race observable instead of producing a duplicate delivery.
+     */
+    async claimContinuation(provider, parentID, meta) {
+        const row = await provider.GetEntityObject('MJ: Tasks', this.contextUser);
+        if (!(await row.Load(parentID)))
+            return false;
+        const current = this.readParentMetadata(row);
+        if (current.continuationDeliveredAt)
+            return false; // a peer got there first
+        row.InputPayload = JSON.stringify({ ...meta, continuationDeliveredAt: new Date().toISOString() });
+        if (!(await row.Save())) {
+            LogError(`[TaskGraphDispatcher] Could not mark continuation delivered for ${parentID}; skipping to avoid a duplicate.`);
+            return false;
+        }
+        return true;
+    }
+    /** One line describing how the graph ended, for the completion log and message delivery. */
+    buildContinuationSummary(parent, graph) {
+        const counts = new Map();
+        for (const node of graph.nodes)
+            counts.set(node.status, (counts.get(node.status) ?? 0) + 1);
+        const breakdown = [...counts.entries()].map(([status, n]) => `${n} ${status}`).join(', ');
+        return `"${parent.Name}": ${graph.nodes.length} task(s) — ${breakdown}.`;
+    }
+    /**
+     * Tells the assignee that a human task is ready, exactly once.
+     *
+     * **Once** matters more than it looks: eligibility is recomputed on every poll, so a task parked
+     * on a person for three days would otherwise re-notify every five seconds until they acted. The
+     * marker is the task's own `ClaimedBy` — a human task has no executor to claim it, so the column
+     * is free, and reusing it means the "already notified" fact is as durable and as crash-safe as
+     * every other piece of graph state. A restart cannot resend.
+     *
+     * Best-effort by design. A notification that fails to send must not stop the graph or the poll
+     * loop; the task is still visible in the Tasks UI, so the work is discoverable even when the
+     * nudge does not arrive.
+     */
+    async notifyHumanTaskReady(task, provider) {
+        if (task.ClaimedBy === HUMAN_TASK_NOTIFIED_MARKER)
+            return;
+        if (!task.UserID)
+            return; // unassigned human task — nobody to tell
+        try {
+            await NotificationEngine.Instance.Config(false, this.contextUser);
+            await NotificationEngine.Instance.SendNotification({
+                userId: task.UserID,
+                typeNameOrId: HUMAN_TASK_NOTIFICATION_TYPE,
+                title: `Action needed: ${task.Name}`,
+                message: task.Description || 'A workflow is waiting on you to complete this task.',
+                resourceConfiguration: { type: 'Task', taskId: task.ID, parentTaskId: task.ParentID ?? '' },
+            }, this.contextUser);
+        }
+        catch (e) {
+            LogError(`[TaskGraphDispatcher] Could not notify ${task.UserID} about task ${task.ID}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        // Marked even when delivery threw. Retrying a notification on every five-second poll is a
+        // worse failure than one that was missed: the task remains visible in the Tasks UI either
+        // way, whereas a notification storm is not self-correcting.
+        task.ClaimedBy = HUMAN_TASK_NOTIFIED_MARKER;
+        if (!(await task.Save())) {
+            LogError(`[TaskGraphDispatcher] Could not mark task ${task.ID} as notified; it may notify again.`);
+        }
+        // Emitted once, alongside the marker, so a viewer sees the graph stop on a person rather
+        // than appearing to stall for no reason.
+        this.emit({
+            Kind: 'TaskAwaitingHuman',
+            ParentTaskID: task.ParentID ?? task.ID,
+            OwnerUserID: await this.resolveOwner(provider, task.ParentID ?? task.ID),
+            TaskID: task.ID,
+            TaskName: task.Name,
+            Status: task.Status,
+            AssignedUserID: task.UserID,
+        });
+    }
+    /**
+     * Parent tasks that still have work to do.
+     *
+     * `BypassCache` for the reason the caching guide names explicitly: **the claim protocol mutates
+     * these rows through direct SQL**, because the CAS guarantee IS the database's atomicity and a
+     * `BaseEntity.Save()` cannot express a guarded UPDATE. Direct DML fires no invalidation event,
+     * so a cached read of this query is stale the instant any task is claimed or completed — and
+     * the dispatcher would then be reading its own work queue through a cache its own writes never
+     * invalidate. Left cached, a completed task keeps reading as `In Progress` and the graph never
+     * rolls up: submitted work simply never settles.
+     */
+    async findActiveGraphIDs(provider) {
+        const rv = RunView.FromMetadataProvider(provider);
+        // TWO queries, because "has work left to do" and "needs attention" are not the same set.
+        //
+        // Selecting only graphs with non-terminal CHILDREN looks right and is subtly fatal: the
+        // moment the last child completes, the graph leaves that set — so the pass that would have
+        // rolled the parent up never sees it. A graph whose tasks all succeed therefore stays
+        // In Progress forever and its continuation never fires. (A graph that FAILS happened to
+        // survive this, because blocking its dependents left them non-terminal for one more pass —
+        // which is why the bug hid behind a passing failure-path test.)
+        //
+        // The second query closes it: a parent that is itself non-terminal still needs looking at,
+        // whatever its children are doing.
+        const [withPendingWork, unsettledParents] = await rv.RunViews([
+            {
+                EntityName: 'MJ: Tasks',
+                ExtraFilter: `ParentID IS NOT NULL AND Status IN ('Pending','In Progress')`,
+                Fields: ['ParentID'],
+                ResultType: 'simple',
+                BypassCache: true,
+            },
+            {
+                EntityName: 'MJ: Tasks',
+                ExtraFilter: `ParentID IS NULL AND Status IN ('Pending','In Progress')`,
+                Fields: ['ID'],
+                ResultType: 'simple',
+                BypassCache: true,
+            },
+        ], this.contextUser);
+        const ids = new Set();
+        for (const r of (withPendingWork?.Results ?? [])) {
+            if (r.ParentID)
+                ids.add(r.ParentID);
+        }
+        // Childless tasks match the second query too; propagateAndRollup skips anything with no
+        // nodes, so they cost one empty load and nothing else.
+        for (const r of (unsettledParents?.Results ?? [])) {
+            if (r.ID)
+                ids.add(r.ID);
+        }
+        return [...ids];
+    }
+    /**
+     * Tasks eligible to claim right now, across all active graphs.
+     *
+     * Eligibility is decided by the pure algorithm rather than by SQL: expressing "all prerequisites
+     * complete" as a query is possible but would be a second, independently-maintained definition of
+     * the same rule, free to drift from the one the in-run executor uses.
+     */
+    async findClaimableTasks(provider, limit) {
+        const claimable = [];
+        for (const parentID of await this.findActiveGraphIDs(provider)) {
+            if (claimable.length >= limit)
+                break;
+            const graph = await this.loadGraphState(provider, parentID);
+            for (const node of ComputeEligibleTasks(graph.nodes, graph.edges)) {
+                const entity = graph.entityById.get(node.id);
+                if (!entity)
+                    continue;
+                // Human tasks are never dispatched — a person completes them. But "eligible" is the
+                // moment that person can finally act, and nothing else in the system knows it has
+                // arrived: the task sat Pending behind prerequisites, and no save touched it when
+                // they cleared. Without a notification here a workflow simply stops, waiting on
+                // someone who was never told. That silent stall is the failure mode this exists to
+                // prevent, so it happens on the eligibility check rather than at submission.
+                if (!entity.AgentID) {
+                    await this.notifyHumanTaskReady(entity, provider);
+                    continue;
+                }
+                if (this.inFlight.has(entity.ID))
+                    continue;
+                claimable.push(entity);
+                if (claimable.length >= limit)
+                    break;
+            }
+        }
+        return claimable;
+    }
+    /** Loads a graph's children and edges in the shapes both the algorithms and mutation need. */
+    async loadGraphState(provider, parentTaskID) {
+        const rv = RunView.FromMetadataProvider(provider);
+        // BypassCache throughout: task status is written by the claim protocol's direct SQL, which
+        // fires no cache invalidation. See findActiveGraphIDs.
+        const childrenResult = await rv.RunView({ EntityName: 'MJ: Tasks', ExtraFilter: `ParentID='${parentTaskID}'`, ResultType: 'entity_object', BypassCache: true }, this.contextUser);
+        const children = (childrenResult.Success ? childrenResult.Results : []) ?? [];
+        if (children.length === 0)
+            return { nodes: [], edges: [], entityById: new Map(), unreachableTaskIDs: new Set() };
+        const idList = children.map((c) => `'${c.ID}'`).join(',');
+        const depsResult = await rv.RunView({ EntityName: 'MJ: Task Dependencies', ExtraFilter: `TaskID IN (${idList})`, ResultType: 'entity_object', BypassCache: true }, this.contextUser);
+        const deps = (depsResult.Success ? depsResult.Results : []) ?? [];
+        const entityById = new Map(children.map((c) => [c.ID, c]));
+        // Conditional edges are resolved HERE, before eligibility runs, by dropping edges whose
+        // condition does not hold. Expressing it as edge removal rather than as a second rule inside
+        // the eligibility algorithm is what keeps one definition of "ready": a task with no live
+        // incoming edges is ready for exactly the same reason a task with no edges at all is.
+        //
+        // An edge whose condition cannot be evaluated is KEPT, which is the opposite of the flow
+        // executor's choice and deliberately so. There, a broken condition means an edge is not
+        // followed and the graph moves on. Here it would mean a prerequisite silently disappears and
+        // the dependent task runs early — turning a typo into out-of-order execution. Keeping the
+        // edge instead stalls the graph, which the stall detector already reports loudly.
+        const liveEdges = [];
+        // A definitely-false edge must not merely disappear. Removing a task's only prerequisite
+        // makes it eligible in the very next wave — so "this branch was not taken" would execute the
+        // branch, potentially before the node that gated it. The dependent is recorded as
+        // unreachable instead, and blocked before anything can claim it.
+        const droppedInto = new Set();
+        const stillReachable = new Set();
+        for (const d of deps) {
+            if (d.Condition?.trim()) {
+                const outcome = this.evaluateEdgeCondition(d, entityById);
+                if (outcome === 'drop') {
+                    droppedInto.add(d.TaskID);
+                    continue;
+                }
+            }
+            stillReachable.add(d.TaskID);
+            liveEdges.push({
+                taskId: d.TaskID,
+                dependsOnTaskId: d.DependsOnTaskID,
+                dependencyType: d.DependencyType,
+            });
+        }
+        // Only unreachable when EVERY route in was cut. A node still holding a live edge is simply
+        // waiting on it, and a node reached by an alternate branch is genuinely reachable.
+        const unreachableTaskIDs = new Set([...droppedInto].filter((id) => !stillReachable.has(id)));
+        return {
+            nodes: children.map((c) => ({ id: c.ID, status: c.Status })),
+            edges: liveEdges,
+            entityById,
+            unreachableTaskIDs,
+        };
+    }
+    /**
+     * Decides whether a conditional dependency edge is live.
+     *
+     * The condition sees the upstream task's outcome — its status and parsed output — which is the
+     * only information a runtime graph has to branch on. Returns `'drop'` only on a definite false;
+     * an unevaluable condition keeps the edge for the reason stated at the call site.
+     */
+    evaluateEdgeCondition(dep, entityById) {
+        const upstream = entityById.get(dep.DependsOnTaskID);
+        if (!upstream)
+            return 'keep';
+        let output = null;
+        if (upstream.OutputPayload) {
+            try {
+                output = JSON.parse(upstream.OutputPayload);
+            }
+            catch { /* a malformed payload is not grounds to drop a prerequisite */ }
+        }
+        const result = this.conditionEvaluator.Evaluate(dep.Condition, {
+            status: upstream.Status,
+            succeeded: upstream.Status === 'Complete',
+            failed: upstream.Status === 'Failed',
+            output,
+            errorMessage: upstream.ErrorMessage ?? null,
+        });
+        if (!result.Success) {
+            LogError(`[TaskGraphDispatcher] Dependency ${dep.ID} has an unevaluable condition ` +
+                `(${result.ErrorMessage}); keeping the edge so the graph stalls visibly rather than ` +
+                `running ${dep.TaskID} out of order.`);
+            return 'keep';
+        }
+        return result.Value ? 'keep' : 'drop';
+    }
+    /** Parsed `OutputPayload` of each completed dependency, keyed by that task's ID. */
+    async loadDependencyOutputs(provider, taskID) {
+        const outputs = new Map();
+        const rv = RunView.FromMetadataProvider(provider);
+        // BypassCache: an upstream task's OutputPayload is written on the completion path, so a
+        // cached read here can hand a dependent task the previous run's output — or none at all.
+        const deps = await rv.RunView({ EntityName: 'MJ: Task Dependencies', ExtraFilter: `TaskID='${taskID}'`, ResultType: 'entity_object', BypassCache: true }, this.contextUser);
+        for (const dep of (deps.Success ? deps.Results : []) ?? []) {
+            const upstream = await provider.GetEntityObject('MJ: Tasks', this.contextUser);
+            if (!(await upstream.Load(dep.DependsOnTaskID)))
+                continue;
+            if (!upstream.OutputPayload)
+                continue;
+            try {
+                outputs.set(dep.DependsOnTaskID, JSON.parse(upstream.OutputPayload));
+            }
+            catch (e) {
+                LogError(`[TaskGraphDispatcher] Task ${dep.DependsOnTaskID} has malformed OutputPayload: ${e}`);
+            }
+        }
+        return outputs;
+    }
+}
+//# sourceMappingURL=TaskGraphDispatcher.js.map