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

package/dist/TaskGraphDispatcher.d.ts

@@ -0,0 +1,548 @@
+import { UserInfo } from '@memberjunction/core';
+import { IShutdownable } from '@memberjunction/global';
+import { ProviderFactory, TaskActionRunner, TaskAgentRunner, TaskPromptRunner, TaskGraphDispatcherConfig, type TaskContinuationDeliverer, type TaskGraphObserver } from './types.js';
+export declare class TaskGraphDispatcher implements IShutdownable {
+    private readonly providerFactory;
+    private readonly agentRunner;
+    private readonly contextUser;
+    /**
+     * 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.
+     */
+    private readonly continuationDeliverer?;
+    /**
+     * Optional. Absent means nobody is watching — the dispatcher behaves identically, it just
+     * announces nothing.
+     */
+    private readonly observer?;
+    /**
+     * Optional. Absent means this host cannot run action nodes; they stay Pending and visible
+     * rather than being failed, because "nobody here can run this" is not "this ran and broke".
+     */
+    private readonly actionRunner?;
+    /**
+     * Optional. Absent means this host cannot run prompt nodes; they stay Pending and visible
+     * rather than being failed, for the same reason action nodes do.
+     */
+    private readonly promptRunner?;
+    private readonly config;
+    private readonly claims;
+    private readonly conditionEvaluator;
+    private running;
+    private pollTimer;
+    private reconcileTimer;
+    /** Tasks this instance is currently executing — bounds concurrency and drives heartbeats. */
+    private readonly inFlight;
+    /** Guards against a slow poll overlapping the next tick. */
+    private polling;
+    /**
+     * The poll pass currently running, so `Stop` can wait for it.
+     *
+     * `clearInterval` cannot cancel a tick that has already fired, and a pass is a long sequence of
+     * awaits (provider, rollup, claim query) — so without this, `Stop` returns while a pass is still
+     * mid-flight and about to claim. Its tasks then land in `inFlight` AFTER the drain loop already
+     * saw an empty set, which is precisely the state the drain exists to prevent.
+     */
+    private pollPass;
+    /** Graph → owning user, from the parent's durable metadata. Ownership never changes, so this never goes stale. */
+    private readonly ownerByParentID;
+    constructor(providerFactory: ProviderFactory, agentRunner: TaskAgentRunner, contextUser: UserInfo, config: Partial<TaskGraphDispatcherConfig> & Pick<TaskGraphDispatcherConfig, 'InstanceID'>, 
+    /**
+     * 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?: TaskContinuationDeliverer, 
+    /**
+     * Optional. Absent means nobody is watching — the dispatcher behaves identically, it just
+     * announces nothing.
+     */
+    observer?: TaskGraphObserver, 
+    /**
+     * Optional. Absent means this host cannot run action nodes; they stay Pending and visible
+     * rather than being failed, because "nobody here can run this" is not "this ran and broke".
+     */
+    actionRunner?: TaskActionRunner, 
+    /**
+     * Optional. Absent means this host cannot run prompt nodes; they stay Pending and visible
+     * rather than being failed, for the same reason action nodes do.
+     */
+    promptRunner?: TaskPromptRunner);
+    /**
+     * 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.
+     */
+    private emit;
+    /**
+     * 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.
+     */
+    private resolveOwner;
+    /**
+     * 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".
+     */
+    Start(): Promise<void>;
+    /**
+     * 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.
+     */
+    Stop(): Promise<void>;
+    /** Name shown in the shutdown drain log. */
+    readonly ShutdownName = "TaskGraphDispatcher";
+    /** {@link IShutdownable} — idempotent by way of `Stop`'s `running` guard. */
+    Shutdown(): Promise<void>;
+    /**
+     * 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.
+     */
+    Reconcile(): Promise<void>;
+    /**
+     * 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.
+     */
+    private pollOnce;
+    /**
+     * 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.
+     */
+    private executeClaimed;
+    /**
+     * 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.
+     */
+    private propagateAndRollup;
+    /**
+     * Credits a finished graph's spending back to the agent run that submitted it.
+     *
+     * **Why this cannot happen during the run.** `BaseAgent` totals a run by walking its steps in
+     * memory at finalization — but a submitting run *ends at submission*. Submit-and-detach is the
+     * point: the run returns as soon as the graph is durable, and the graph executes afterwards,
+     * possibly minutes later on a different instance. At the moment the run computes its totals the
+     * spending has not happened yet, so there is nothing to count. The only place the number can be
+     * known is here, when the graph settles.
+     *
+     * **Why the `…Rollup` columns and not the plain ones.** `AIAgentRun` has carried six `…Rollup`
+     * columns since v3 that nothing has ever written — they exist for exactly this distinction:
+     *
+     * - `TotalCost` — what the run itself spent. For a Flow agent that is genuinely near zero: it
+     *   compiled a graph and handed it off. This value is already final and is never rewritten here,
+     *   so nothing that reads it today changes meaning, and no guardrail that already evaluated
+     *   against it is retroactively falsified.
+     * - `TotalCostRollup` — the run plus everything it caused. Provisional until the graph settles,
+     *   which is now.
+     *
+     * **The tree is the authority; these columns are its settlement-time cache.** The total is a SUM
+     * over `GetAgentRunTree`, not arithmetic of its own. The previous version walked the graph's
+     * child tasks and added each one's agent run, which was wrong in two ways that no test could
+     * see: a `Prompt` task has no agent run at all, so every prompt step's spend was simply missing;
+     * and it read each nested run's `…Rollup ?? …Total`, mixing a descendant-inclusive number with an
+     * own-spend one and depending on whether that nested graph happened to have settled yet. The
+     * tree already models every one of those cases — it reaches prompt runs through
+     * `Configuration.runtime.promptRunID`, and it descends into nested runs and their graphs
+     * structurally — so summing it cannot disagree with what the run viewer shows, because it IS
+     * what the run viewer shows.
+     *
+     * **This refuses rather than guesses.** A tree that failed to load, hit the depth cap, or does
+     * not contain the settling graph would still produce a number — a lower bound. Writing one would
+     * put an authoritative-looking total in a column every cost surface reads. Each of those cases
+     * logs and leaves the column alone, so `?? TotalCost` keeps its honest meaning: not settled.
+     *
+     * A graph with no submitting run (a scheduled job, a remote-operation caller) simply has nobody
+     * to credit — its own Task rows still carry the truth, and this returns quietly.
+     */
+    private rollUpCostToSubmittingRun;
+    /**
+     * Clears a rollup that can no longer be trusted, and says why.
+     *
+     * **Why clear rather than leave.** The four `…Rollup` columns are a cache of the run tree, and
+     * every reader treats a value there as the total. When the tree cannot be summed, any value
+     * already in the column was computed from an EARLIER settlement — it excludes the graph that
+     * just finished, so it is not merely incomplete, it is a wrong total presented as a right one.
+     * `?? TotalCost` protects a reader from null, not from stale.
+     *
+     * Nulling restores the invariant this whole design rests on: **when the column is present, it
+     * equals the tree.** Absent means not settled, which is exactly what a reader should conclude.
+     * A run with no rollup yet is untouched — there is nothing stale to clear, and writing nulls
+     * over nulls would churn Record Changes for nothing.
+     */
+    private clearStaleRollup;
+    /**
+     * Whether the settling graph is actually reachable from the submitting run's tree.
+     *
+     * Matched on the graph's parent Task id, which is the node the `TaskGraph` member of the query
+     * emits. A run that submitted a graph but recorded no `parentTaskID` produces a tree that stops
+     * at the run — structurally indistinguishable, at the SUM, from a run that never dispatched
+     * anything. This is the check that tells those two apart.
+     */
+    private treeContainsGraph;
+    /**
+     * Ends a graph early because a prompt said the work is finished.
+     *
+     * **Why `Skipped` and not `Cancelled`.** Nothing went wrong and nobody intervened — the workflow
+     * reached its own conclusion before running every drawn step, which is exactly what a reasoning
+     * step is for. `Cancelled` would tell a reader someone stopped it; `Skipped` says these routes
+     * were not taken, which is true and already the vocabulary the fork machinery uses.
+     *
+     * The message is written to the parent so the graph carries its own answer, rather than the
+     * answer living only on the step that produced it.
+     */
+    private endGraphEarly;
+    /**
+     * How deep the continuation chain already is, read from the graph's parent metadata.
+     *
+     * A run started by a graph inherits that graph's depth **plus one**. Without this every spawned
+     * run begins at zero, so a self-referencing flow — one that dispatches a graph containing itself
+     * — recurses without bound while the cap it should be hitting compares against a permanent zero.
+     */
+    private graphContext;
+    /**
+     * Which failures the workflow drew a way out of.
+     *
+     * A Failed task with a **satisfied outgoing edge** is a handled failure: its author drew a
+     * recovery route and that route is now live. Downstream work should be released along it, and the
+     * parent should not roll up Failed because of a step the workflow explicitly planned around.
+     *
+     * Scoped to `failureSemantics: 'edges'` on purpose. Under `'block'` — every agent-emitted graph —
+     * a failure is terminal for its dependents whatever edges exist, because nobody drew those edges
+     * as a recovery path; they are ordinary sequencing, and treating them as recovery would let a
+     * graph sail past a failure it never anticipated.
+     */
+    private computeHandledFailures;
+    /** The graph's child tasks, with the fields the rollup needs. */
+    private loadChildTasks;
+    /**
+     * 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.
+     */
+    private deliverContinuation;
+    /** Reads the parent's durable continuation metadata through the shared parser. */
+    private readParentMetadata;
+    /**
+     * 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.
+     */
+    private claimContinuation;
+    /** One line describing how the graph ended, for the completion log and message delivery. */
+    private buildContinuationSummary;
+    /**
+     * 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.
+     */
+    private notifyHumanTaskReady;
+    /**
+     * 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.
+     */
+    private findActiveGraphIDs;
+    /**
+     * 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.
+     */
+    private findClaimableTasks;
+    /**
+     * Marks a human task as notified, so the request is raised exactly once.
+     *
+     * Written even when delivery threw. Retrying on every poll is a worse failure than one missed
+     * notification: the task stays visible in the inbox either way, whereas a notification storm is
+     * not self-correcting.
+     */
+    private markHumanTaskNotified;
+    /**
+     * Raises the `MJ: AI Agent Requests` row a person answers to release this step.
+     *
+     * **Why that entity rather than something new.** It already models everything a workflow's human
+     * step needs — who is being asked, what for, a typed response schema, priority, expiry, and an
+     * inbox surface people already use. A second HITL substrate beside it would split the inbox in
+     * two and leave one of them without expiry or permissions.
+     *
+     * **What it deliberately does NOT set is `ResumingAgentRunID`.** A request normally suspends an
+     * agent run and resumes it. A workflow needs none of that: the graph OUTLIVES the run that
+     * submitted it, so nothing is suspended — the task sits Pending, every other branch keeps
+     * running, and answering settles the task. That column staying null is meaningful, not missing.
+     */
+    private raiseHumanRequest;
+    /**
+     * The agent that owns this task's workflow — who the request is asked on behalf of.
+     *
+     * Reads the graph's parent row, falling back to the run that submitted it. A human step has no
+     * agent of its own by design: `AgentID` names what EXECUTES a step, and a person is not an agent.
+     */
+    private owningAgentOf;
+    /** The still-open request for a task, if one exists. */
+    private findOpenRequest;
+    /**
+     * Settles a human task from the request a person answered.
+     *
+     * Runs on the poll rather than on a save hook, because the answer can arrive through any surface
+     * — the inbox, the API, a conversation — and only the dispatcher knows how to release the rest
+     * of the graph afterwards.
+     *
+     * **`ResponseData` becomes the task's output.** That is what makes a human step useful rather
+     * than a gate: a downstream edge can branch on what the person actually said, typed by the
+     * request's own ResponseSchema. A step that only recorded "approved" would force every decision
+     * back into a separate action.
+     */
+    private settleAnsweredHumanTasks;
+    /**
+     * Re-opens a human step whose request was CANCELLED.
+     *
+     * `answeredRequestFor` deliberately excludes `Canceled`, because cancelling withdraws the ASK
+     * rather than deciding the step — the task is supposed to keep waiting "for whatever replaces
+     * it". Nothing replaced it. `raiseHumanRequest` refuses to raise twice (the notified marker on
+     * `ClaimedBy` is what stops the notification storm), so a cancelled request left the task Pending
+     * with no open request and no path to acquiring one: a workflow waiting forever on a question
+     * nobody is being asked.
+     *
+     * Clearing the marker is the whole fix — the next poll sees an un-notified Pending human task
+     * and raises a fresh request, which is exactly the replacement the design assumed. Bounded by
+     * human action: it takes another person cancelling again to come back here.
+     */
+    private reopenCancelledHumanTasks;
+    /** The answered (or expired) request for a task, if any. */
+    private answeredRequestFor;
+    /**
+     * Expires requests whose deadline has passed.
+     *
+     * A deadline that nothing enforces is a comment. Without this an `ExpiresAt` in the past leaves
+     * the request `Requested` forever and the workflow waiting on it just as long.
+     */
+    private expireOverdueRequests;
+    /** The agent run that submitted this task's graph, for provenance on the request. */
+    private submittingRunOf;
+    /** Loads a graph's children and edges in the shapes both the algorithms and mutation need. */
+    private loadGraphState;
+    /**
+     * 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.
+     */
+    private evaluateEdgeCondition;
+    /**
+     * An exclusive edge's condition as a three-way outcome.
+     *
+     * `ResolveExclusiveGroups` needs to tell "false" from "could not be evaluated": the first loses
+     * the branch, the second holds the whole group. The generic keep/drop path cannot express that
+     * difference, which is why exclusive edges take this route instead.
+     */
+    private evaluateExclusiveCondition;
+    /**
+     * Everything an edge condition can see — the SUPERSET of both dialects.
+     *
+     * A flow condition is written against `payload` / `stepResult` / `flowContext` / `data` /
+     * `context`; the dispatcher's own conditions are written against `status` / `succeeded` /
+     * `failed` / `output` / `errorMessage`. Compiling flows onto this engine without the flow
+     * dialect would make every `payload.x` condition evaluate against nothing — silently, since an
+     * undefined property is simply falsy. Both dialects are readable here so a condition means the
+     * same thing on either engine.
+     *
+     * `payload` is the ORIGIN task's post-step snapshot. There is deliberately no "graph-wide
+     * payload": each task's output is its own, and inventing a merged one would give conditions a
+     * value the flow engine never had.
+     */
+    private buildConditionContext;
+    /** Parsed `OutputPayload` of each completed dependency, keyed by that task's ID. */
+    private loadDependencyOutputs;
+    /**
+     * Runs one task's body, whatever kind of step it is.
+     *
+     * **Routing is on `StepType`, not on which key happens to be set.** A loop step carries the same
+     * `ActionID` or `AgentID` as an ordinary step — that key is what the loop *repeats* — so the old
+     * `task.ActionID ? action : agent` test would have run a loop exactly once and called it done.
+     * `StepType` is the only field that distinguishes them.
+     *
+     * Every branch is normalized to one shape so the recording path above stays single: an action has
+     * no agent run to point at, because its forensics live in `ActionExecutionLog` instead.
+     */
+    private runTaskBody;
+    /**
+     * Runs a loop step: its body once per iteration, with the item and index in scope.
+     *
+     * The loop's own `Configuration` supplies the definition; the row's `ActionID` / `AgentID`
+     * supplies what to repeat. Per-iteration inputs are resolved fresh each pass — the bindings are
+     * merged into the payload before the mapping is applied, which is how a body can reference the
+     * current item at all.
+     */
+    private runLoopTask;
+    /**
+     * Folds one pass's result into the loop's running payload.
+     *
+     * **With a body mapping**, the pass's declared outputs are filed where the author said to put
+     * them — including `name[]`, which appends, so a ForEach can collect one entry per item. That is
+     * the whole point of a loop over a collection, and it is only expressible per pass.
+     *
+     * **Without one**, the raw result is deep-merged, which is the pre-existing behaviour and the
+     * right default for a `While` that converges on a value: each pass refines what the condition
+     * reads. It is the wrong default for a ForEach that collects — hence the mapping.
+     *
+     * An unmapped output is reported per pass rather than swallowed, for the same reason
+     * {@link applyStepOutputMapping} reports it: a mapping that names something the body never
+     * returned means the pass did work that went nowhere, while everything reports success.
+     */
+    private foldIterationOutput;
+    /**
+     * Files a step's result into the payload it hands downstream.
+     *
+     * **This is what makes a branch condition possible.** A workflow that branches on
+     * `payload.stockPrice` has that value only because this step mapped `CurrentPrice -> stockPrice`.
+     * Without it the condition reads `undefined` — merely falsy — so the workflow takes the other
+     * branch, finishes, and reports success with nothing to indicate anything went wrong.
+     *
+     * The incoming payload is carried through as well as the update, so a value written three steps
+     * back is still readable here. Returning only this step's own output is what used to limit a
+     * condition's view to its immediate predecessor.
+     */
+    private applyStepOutputMapping;
+    /**
+     * Runs an Agent step, telling the runner where in the graph it sits.
+     *
+     * Depth and provenance are read together because they come from the same row: the graph's parent
+     * task knows both how many continuation hops led here and which run submitted it.
+     */
+    private runAgentNode;
+    /**
+     * Completes the agent run that parked on this graph.
+     *
+     * **This is the other half of submit-and-detach.** A run that dispatches a graph does not
+     * complete at submission — it ends `Paused`, because reporting `Completed` above a workflow
+     * where nothing has happened yet is a claim the row cannot support. The run's lifecycle is
+     * finished HERE, when the graph it was waiting on actually settles, which is the first moment
+     * the answer exists.
+     *
+     * Doing it from the dispatcher rather than by awaiting in the agent is what keeps the properties
+     * that made detach right in the first place: a graph containing a human approval can park for
+     * days without holding a conversation turn open, and a graph reclaimed by another instance after
+     * a crash still settles its submitting run, because the settling happens wherever the graph
+     * finishes rather than wherever it started.
+     *
+     * **Only a parked run is touched.** A run that is already `Completed`, `Failed` or `Cancelled`
+     * reached that state for its own reasons — a second graph settling later, a run the user
+     * cancelled, a run that failed after submitting — and overwriting it would rewrite history from
+     * the outside. The `Paused` predicate is the whole guard.
+     *
+     * @param graphStatus the parent rollup's status: what the workflow as a whole did
+     */
+    private settleSubmittingRun;
+    /**
+     * Gives every step that lacks one a position, once the graph has finished.
+     *
+     * **Why the run stores geometry at all.** A `TaskGraphSpec` is a logical structure with no
+     * layout field, so a graph an agent emitted has no opinion about where its boxes go. Every
+     * viewer was therefore laying it out for itself at render time — and a viewer that failed to
+     * (because the canvas measures nodes it has not drawn yet) fell back to every node at the
+     * origin, piled on one another, with the zoom-to-fit that follows fitting a one-node bounding
+     * box. Settling it once, server-side, means the agent-run canvas, the Workflows runs tab and
+     * anything built later all draw the same picture, and none of them has to compute it.
+     *
+     * **An authored position is never overwritten.** A workflow compiled from a Flow agent carries
+     * the arrangement someone dragged into place; replacing it with an algorithm's guess would
+     * discard a deliberate act. Only steps with no geometry get one, so a partially-arranged graph
+     * keeps what it has.
+     *
+     * Failure here is logged and swallowed: this is presentation. A graph whose work completed must
+     * not be reported as failed because its picture could not be saved.
+     */
+    private persistComputedLayout;
+    /**
+     * The earliest moment any step in the graph began, or null when none has.
+     *
+     * Null is a real answer — a graph whose tasks are all still Pending has not started — and is
+     * deliberately not collapsed to "now", which would date the graph from whenever this pass
+     * happened to run.
+     */
+    private earliestStart;
+    /**
+     * The step's Configuration with this run's artefacts folded in, or `undefined` to leave it be.
+     *
+     * **Merged into the authored bag, never written over it.** The Configuration column holds the
+     * step's definition — its loop body, its mappings, its policy, the position someone dragged it
+     * to. Writing a fresh object containing only `runtime` would erase all of that the first time a
+     * prompt step completed, which is the kind of loss that surfaces much later as a workflow that
+     * mysteriously stopped mapping its output.
+     *
+     * Returns `undefined` when there is nothing to record, so the guarded write omits the column
+     * rather than rewriting it with what it already held.
+     */
+    private configurationWithRuntime;
+    /**
+     * Reads a step's Configuration bag, tolerating a row whose JSON cannot be parsed.
+     *
+     * Unparseable configuration is logged rather than thrown: the step has already RUN by the time
+     * this is called, and refusing to record its outcome because its definition is malformed would
+     * discard the result of real work and leave the task claimed until the claim lapsed.
+     */
+    private parseConfiguration;
+    /**
+     * The payload a step sees: everything its prerequisites produced, plus its own declared input.
+     *
+     * **Why the outputs are merged rather than kept per-task.** A flow carried ONE payload that
+     * accumulated as it went, so a condition on the edge into step C could read a value step A wrote.
+     * Handing each task only its immediate predecessor's output would silently narrow that: the
+     * condition reads `undefined`, which is falsy, and the workflow quietly takes a different route
+     * than the flow it was compiled from. Merging in dependency order restores the accumulation.
+     *
+     * Later prerequisites win on a key collision, matching a flow's own last-write-wins behaviour.
+     */
+    private mergedPayload;
+}
+//# sourceMappingURL=TaskGraphDispatcher.d.ts.map

package/dist/TaskGraphDispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskGraphDispatcher.d.ts","sourceRoot":"","sources":["../src/TaskGraphDispatcher.ts"],"names":[],"mappings":"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"}