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

package/dist/task-predicates.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Who completes a task — a dispatcher, or a person.
+ *
+ * **Why this is a module and not three inline predicates.** The distinction is asked in SQL (claim
+ * reclamation, the human settle/expiry sweeps) and in TypeScript (claim routing), by code in two
+ * files, and it has been written down four different ways:
+ *
+ *   `AgentID IS NOT NULL OR ActionID IS NOT NULL`                    — claim reclamation
+ *   `StepType='Human'`                                               — human settle, human expiry
+ *   `StepType='Human' OR (StepType IS NULL AND UserID IS NOT NULL)`  — human reopen
+ *   `if (ActionID) … else if (PromptID) … else if (!AgentID) human`  — claim routing
+ *
+ * Those were co-extensive when they were written and are not any more, and the way that surfaced is
+ * the reason this file exists. The first form predates the `PromptID` column: a Prompt step (and a
+ * ForEach/While with a prompt body) carries `PromptID` with both `AgentID` and `ActionID` null, so a
+ * prompt task whose owner crashed is claimed normally, expires normally, and is then **invisible to
+ * both reclamation statements** — `TryClaim` cannot retake it because it is no longer `Pending`, and
+ * `FindOrphanedInProgress` will not even report it. The graph sits `In Progress` forever with its
+ * submitting run `Paused` forever, and `IsGraphStalled` reports it healthy because an `In Progress`
+ * node counts as active. Zero diagnostics, anywhere.
+ *
+ * The fix is not "add `PromptID` to the OR" — that restores the coincidence and hands the same
+ * failure to whoever adds the next runner column. It is to say the thing once, here, in the terms
+ * the engine actually means, and have every site ask this module.
+ *
+ * @module @memberjunction/task-graph
+ */
+/** Renders a column reference for the dialect the caller is building. */
+export type ColumnQuoter = (column: string) => string;
+/** For `RunView.ExtraFilter`, which takes bare column names. */
+export declare const BARE_COLUMNS: ColumnQuoter;
+/**
+ * The columns that assign a task to an executor, in the order claim routing tries them.
+ *
+ * Adding a runner means adding its column here and nowhere else — which is the whole point. If a
+ * future runner is assigned by something other than a column on the task, this list stops being
+ * sufficient and the predicate below must change shape rather than grow.
+ */
+export declare const EXECUTOR_COLUMNS: readonly ["AgentID", "ActionID", "PromptID"];
+/** The shape both predicates need. Structural, so `MJTaskEntity` satisfies it as-is. */
+export type TaskAssignment = {
+    AgentID: string | null;
+    ActionID: string | null;
+    PromptID: string | null;
+    StepType: string | null;
+    UserID: string | null;
+};
+/**
+ * SQL for "a dispatcher completes this task".
+ *
+ * Used to SCOPE reclamation: only a task something was supposed to be executing can have been
+ * abandoned by a crash. A human task's `In Progress` — if it ever reaches it — is a person's state
+ * to own, not a claim to reclaim.
+ */
+export declare function MachineTaskSQL(quote?: ColumnQuoter): string;
+/**
+ * SQL for "a person completes this task".
+ *
+ * The `StepType IS NULL` arm is not defensive clutter: `StepType` is nullable and rows predating the
+ * column exist in real databases. A human task written before it would be invisible to a bare
+ * `StepType='Human'` filter — asked, never settled, never expired, dead forever. This is the wide
+ * form the reopen path already used; the settle and expiry paths were narrower, which is B4.
+ */
+export declare function HumanTaskSQL(quote?: ColumnQuoter): string;
+/** True when some runner owns this task. The TypeScript twin of {@link MachineTaskSQL}. */
+export declare function IsMachineTask(task: Pick<TaskAssignment, 'AgentID' | 'ActionID' | 'PromptID'>): boolean;
+/**
+ * True when a person completes this task.
+ *
+ * Deliberately NOT `!IsMachineTask(task)`. A task carrying both an executor column and a `UserID` is
+ * malformed, and the two questions should not silently answer each other for it: routing asks
+ * "is there a runner for this?" and the human lifecycle asks "is somebody expected to act?". A row
+ * that says yes to both is a bug worth seeing rather than a coin flip resolved by operator
+ * precedence.
+ */
+export declare function IsHumanTask(task: Pick<TaskAssignment, 'StepType' | 'UserID'>): boolean;
+//# sourceMappingURL=task-predicates.d.ts.map

package/dist/task-predicates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-predicates.d.ts","sourceRoot":"","sources":["../src/task-predicates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;AAEtD,gEAAgE;AAChE,eAAO,MAAM,YAAY,EAAE,YAAiC,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,8CAA+C,CAAC;AAE7E,wFAAwF;AACxF,MAAM,MAAM,cAAc,GAAG;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,GAAE,YAA2B,GAAG,MAAM,CAEzE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAE,YAA2B,GAAG,MAAM,CAEvE;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC,GAAG,OAAO,CAEtG;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,QAAQ,CAAC,GAAG,OAAO,CAEtF"}

package/dist/task-predicates.js

@@ -0,0 +1,75 @@
+/**
+ * Who completes a task — a dispatcher, or a person.
+ *
+ * **Why this is a module and not three inline predicates.** The distinction is asked in SQL (claim
+ * reclamation, the human settle/expiry sweeps) and in TypeScript (claim routing), by code in two
+ * files, and it has been written down four different ways:
+ *
+ *   `AgentID IS NOT NULL OR ActionID IS NOT NULL`                    — claim reclamation
+ *   `StepType='Human'`                                               — human settle, human expiry
+ *   `StepType='Human' OR (StepType IS NULL AND UserID IS NOT NULL)`  — human reopen
+ *   `if (ActionID) … else if (PromptID) … else if (!AgentID) human`  — claim routing
+ *
+ * Those were co-extensive when they were written and are not any more, and the way that surfaced is
+ * the reason this file exists. The first form predates the `PromptID` column: a Prompt step (and a
+ * ForEach/While with a prompt body) carries `PromptID` with both `AgentID` and `ActionID` null, so a
+ * prompt task whose owner crashed is claimed normally, expires normally, and is then **invisible to
+ * both reclamation statements** — `TryClaim` cannot retake it because it is no longer `Pending`, and
+ * `FindOrphanedInProgress` will not even report it. The graph sits `In Progress` forever with its
+ * submitting run `Paused` forever, and `IsGraphStalled` reports it healthy because an `In Progress`
+ * node counts as active. Zero diagnostics, anywhere.
+ *
+ * The fix is not "add `PromptID` to the OR" — that restores the coincidence and hands the same
+ * failure to whoever adds the next runner column. It is to say the thing once, here, in the terms
+ * the engine actually means, and have every site ask this module.
+ *
+ * @module @memberjunction/task-graph
+ */
+/** For `RunView.ExtraFilter`, which takes bare column names. */
+export const BARE_COLUMNS = (column) => column;
+/**
+ * The columns that assign a task to an executor, in the order claim routing tries them.
+ *
+ * Adding a runner means adding its column here and nowhere else — which is the whole point. If a
+ * future runner is assigned by something other than a column on the task, this list stops being
+ * sufficient and the predicate below must change shape rather than grow.
+ */
+export const EXECUTOR_COLUMNS = ['AgentID', 'ActionID', 'PromptID'];
+/**
+ * SQL for "a dispatcher completes this task".
+ *
+ * Used to SCOPE reclamation: only a task something was supposed to be executing can have been
+ * abandoned by a crash. A human task's `In Progress` — if it ever reaches it — is a person's state
+ * to own, not a claim to reclaim.
+ */
+export function MachineTaskSQL(quote = BARE_COLUMNS) {
+    return `(${EXECUTOR_COLUMNS.map((c) => `${quote(c)} IS NOT NULL`).join(' OR ')})`;
+}
+/**
+ * SQL for "a person completes this task".
+ *
+ * The `StepType IS NULL` arm is not defensive clutter: `StepType` is nullable and rows predating the
+ * column exist in real databases. A human task written before it would be invisible to a bare
+ * `StepType='Human'` filter — asked, never settled, never expired, dead forever. This is the wide
+ * form the reopen path already used; the settle and expiry paths were narrower, which is B4.
+ */
+export function HumanTaskSQL(quote = BARE_COLUMNS) {
+    return `(${quote('StepType')} = 'Human' OR (${quote('StepType')} IS NULL AND ${quote('UserID')} IS NOT NULL))`;
+}
+/** True when some runner owns this task. The TypeScript twin of {@link MachineTaskSQL}. */
+export function IsMachineTask(task) {
+    return !!(task.AgentID || task.ActionID || task.PromptID);
+}
+/**
+ * True when a person completes this task.
+ *
+ * Deliberately NOT `!IsMachineTask(task)`. A task carrying both an executor column and a `UserID` is
+ * malformed, and the two questions should not silently answer each other for it: routing asks
+ * "is there a runner for this?" and the human lifecycle asks "is somebody expected to act?". A row
+ * that says yes to both is a bug worth seeing rather than a coin flip resolved by operator
+ * precedence.
+ */
+export function IsHumanTask(task) {
+    return task.StepType === 'Human' || (task.StepType == null && task.UserID != null);
+}
+//# sourceMappingURL=task-predicates.js.map

package/dist/task-predicates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-predicates.js","sourceRoot":"","sources":["../src/task-predicates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,gEAAgE;AAChE,MAAM,CAAC,MAAM,YAAY,GAAiB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,CAAU,CAAC;AAW7E;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAsB,YAAY;IAC7D,OAAO,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;AACtF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,QAAsB,YAAY;IAC3D,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC,kBAAkB,KAAK,CAAC,UAAU,CAAC,gBAAgB,KAAK,CAAC,QAAQ,CAAC,gBAAgB,CAAC;AACnH,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,aAAa,CAAC,IAA+D;IACzF,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,IAAiD;IACzE,OAAO,IAAI,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC;AACvF,CAAC"}

package/dist/types.d.ts

@@ -19,6 +19,15 @@ import { IMetadataProvider, UserInfo } from '@memberjunction/core';
 export type ProviderFactory = {
     CreateProvider(): Promise<IMetadataProvider>;
 };
+/**
+ * How a runner reports progress inside one task body.
+ *
+ * A plain callback rather than an observer object because a runner should not need to know frames
+ * exist: it says what it is doing, and the dispatcher decides whether anyone is listening, how often
+ * to announce it, and in what shape. MUST NOT throw or block — the dispatcher wraps it, but a
+ * runner's own use should treat it as commentary, never a step of the work.
+ */
+export type TaskRunProgressCallback = (message: string, percent?: number) => void;
 /**
  * Runs one agent for one task node.
  *
@@ -29,6 +38,95 @@ export type ProviderFactory = {
 export type TaskAgentRunner = {
     RunAgentForTask(params: TaskAgentRunParams): Promise<TaskAgentRunResult>;
 };
+/** Everything running one action for one task node needs. */
+export type TaskActionRunParams = {
+    TaskID: string;
+    ActionID: string;
+    /** Structured input from `Task.InputPayload` — for durable entity-action dispatch, the redacted params. */
+    InputPayload: unknown;
+    /** Outputs of this node's satisfied prerequisites, in the same shape agent nodes receive. */
+    DependencyOutputs: Map<string, unknown>;
+    Provider: IMetadataProvider;
+    ContextUser: UserInfo;
+    /** Optional progress sink; the dispatcher turns calls into rate-limited `NodeProgress` frames. */
+    OnProgress?: TaskRunProgressCallback;
+};
+/** The outcome of one action node. */
+export type TaskActionRunResult = {
+    Success: boolean;
+    Output?: unknown;
+    ErrorMessage?: string;
+    /**
+     * The `MJ: Action Execution Logs` row this run produced.
+     *
+     * Carried so the step can record it, which is what lets a workflow's action offer "view the
+     * execution log" the way an ordinary agent run step does. Optional because a runner that
+     * cannot produce one is limited, not broken.
+     */
+    ActionLogID?: string;
+};
+/**
+ * Runs one action for one task node.
+ *
+ * The third execution shape, beside agents and people. Abstracted for the same reason
+ * {@link TaskAgentRunner} is: the dispatcher must stay unit-testable without standing up the action
+ * engine, and this package must not import it — `@memberjunction/actions` depends on the entity
+ * layer this one also builds on, and reaching for it here would make every consumer of durable
+ * execution load the action engine too.
+ *
+ * **A host with no action runner is not broken, it is limited.** Action nodes stay Pending on it,
+ * which is visible in the Tasks UI, rather than being marked failed — a task nobody in this
+ * deployment can run is not the same as a task that ran and did not work.
+ */
+export type TaskActionRunner = {
+    RunActionForTask(params: TaskActionRunParams): Promise<TaskActionRunResult>;
+};
+/** Everything running one prompt for one task node needs. */
+export type TaskPromptRunParams = {
+    TaskID: string;
+    PromptID: string;
+    /** Structured input from `Task.InputPayload`, after the node's input mapping. */
+    InputPayload: unknown;
+    /** Outputs of this node's satisfied prerequisites, in the same shape agent nodes receive. */
+    DependencyOutputs: Map<string, unknown>;
+    /** Template parameters declared on the node's configuration. */
+    TemplateParameters?: Record<string, string>;
+    Provider: IMetadataProvider;
+    ContextUser: UserInfo;
+    /** Optional progress sink; the dispatcher turns calls into rate-limited `NodeProgress` frames. */
+    OnProgress?: TaskRunProgressCallback;
+};
+/** The outcome of one prompt node. */
+export type TaskPromptRunResult = {
+    Success: boolean;
+    /** The parsed JSON response, deep-merged into the payload by the dispatcher. */
+    Output?: unknown;
+    ErrorMessage?: string;
+    /** The `MJ: AI Prompt Runs` row, for provenance. */
+    PromptRunID?: string;
+    /**
+     * Set when the prompt asked to end the workflow and say something to a person.
+     *
+     * A prompt is the one node kind that can decide the workflow is *done* — it is the only one
+     * doing open-ended reasoning. The dispatcher honours it by skipping the remaining tasks and
+     * settling the parent Complete with this message, rather than treating an early finish as an
+     * abandoned graph.
+     */
+    ChatMessage?: string;
+};
+/**
+ * Runs one prompt for one task node.
+ *
+ * The fourth execution shape, and abstracted for the same reason as the others: this package must
+ * stay unit-testable without standing up the AI engine, and must not import it — the prompt runner
+ * lives in MJServer where the engine already does.
+ *
+ * **A host with no prompt runner is limited, not broken.** Prompt nodes stay Pending and visible,
+ * exactly like action nodes without an action runner.
+ */
+export type TaskPromptRunner = {
+    RunPromptForTask(params: TaskPromptRunParams): Promise<TaskPromptRunResult>;
+};
 /** What happened to a task or a graph, as a closed set a consumer can branch on. */
 export type TaskGraphFrameKind = 
 /** A task was claimed by an instance and is about to run. */
@@ -39,10 +137,68 @@ export type TaskGraphFrameKind =
  | 'TaskFailed'
 /** A task was blocked because a prerequisite failed or became unreachable. */
  | 'TaskBlocked'
+/**
+ * A task was NOT TAKEN because another branch of an exclusive fan-out won.
+ *
+ * Distinct from `TaskBlocked` on purpose: blocked means something went wrong upstream and the
+ * viewer should look for a cause; skipped means the workflow chose a different route and there
+ * is nothing to investigate. Rendering them the same would send people hunting for bugs that do
+ * not exist.
+ */
+ | 'TaskSkipped'
 /** A human task became actionable and is waiting on its assignee. */
  | 'TaskAwaitingHuman'
 /** Every node has reached a terminal state; `Status` is the graph's rolled-up outcome. */
- | 'GraphSettled';
+ | 'GraphSettled'
+/**
+ * A gating edge's verdict changed — satisfied, not taken, or held.
+ *
+ * Emitted on CHANGE, not on every poll (the dispatcher re-resolves edges each pass, and an
+ * unqualified emission would repeat every few seconds for as long as the graph is live, exactly
+ * the flood `logUnevaluableConditionOnce` exists to prevent in the log). This frame is what lets
+ * a viewer answer "why did this branch run?" — and what makes a permanent hold visible the
+ * moment it happens instead of after a forensic query.
+ */
+ | 'GateDecision'
+/**
+ * A task's claim changed hands or state — claimed, heartbeat lost, reclaimed.
+ *
+ * The R2-1 defect class ("a crashed worker's task wedges the graph forever with zero
+ * diagnostics") becomes a red badge instead of an invisible fact precisely because this frame
+ * exists.
+ */
+ | 'ClaimChanged'
+/**
+ * One dispatch pass finished for this graph — the engine's heartbeat.
+ *
+ * Carries the pass's counts (eligible / held / claimed / in flight). A run that is stuck is a
+ * strip of these ticking with nothing moving, which is the honest visual of a stall.
+ */
+ | 'PassCompleted'
+/** The graph was paused — by a person or by a breakpoint. Nothing new will be claimed. */
+ | 'GraphPaused'
+/** The graph was resumed; claiming continues normally. */
+ | 'GraphResumed'
+/**
+ * An eligible task carried a breakpoint, so the graph paused BEFORE the task was claimed.
+ * `TaskID` names the task the run is now parked in front of.
+ */
+ | 'BreakpointHit'
+/**
+ * A step allowance could not release anything on this pass — the named work is already running,
+ * or this host has no runner for it. The allowance is NOT spent, and `Reason` says so.
+ *
+ * Exists because the alternative is the worst shape a control can have: the button reports
+ * nothing, the allowance is gone, and the run does not move.
+ */
+ | 'StepRefused'
+/**
+ * A runner reported progress inside one task — message and optional percentage.
+ *
+ * The bridge from node-level execution (an agent run's own progress stream) up to graph-level
+ * observers, rate-limited by the dispatcher so a chatty runner cannot flood the topic.
+ */
+ | 'NodeProgress';
 /**
  * One thing that happened, addressed by the graph it happened in.
  *
@@ -80,6 +236,44 @@ export type TaskGraphFrame = {
     /** How many nodes have reached a terminal state, and out of how many. */
     CompletedCount?: number;
     TotalCount?: number;
+    /** The `MJ: Task Dependencies` row the verdict is about. */
+    EdgeID?: string;
+    /** The edge's origin task. `TaskID` above is the edge's target. */
+    DependsOnTaskID?: string;
+    /** What the gate decided: the edge is open, the branch was not taken, or it cannot be answered yet. */
+    Verdict?: 'satisfied' | 'notTaken' | 'held';
+    /** The condition text, so a viewer can show WHY without loading the row. */
+    ConditionText?: string;
+    /** Human-readable detail: the hold reason, the override applied, or who paused the graph. */
+    Reason?: string;
+    /** What happened to the claim. */
+    ClaimEvent?: 'claimed' | 'heartbeat-lost' | 'reclaimed';
+    /** The dispatcher instance holding (or losing) the claim. */
+    ClaimedBy?: string;
+    /** When the claim lapses unless extended, ISO 8601. */
+    ClaimExpiresAt?: string;
+    /** Monotonic per-instance pass counter, so a viewer can order and gap-detect ticks. */
+    PassNumber?: number;
+    /** Tasks whose prerequisites were satisfied this pass. */
+    EligibleCount?: number;
+    /** Tasks held by an unanswerable condition or undecided fork. */
+    HeldCount?: number;
+    /** Tasks this instance claimed on this pass, for THIS graph. */
+    ClaimedCount?: number;
+    /**
+     * Tasks this INSTANCE is executing right now, across every graph it is working — not this
+     * graph's in-flight count.
+     *
+     * Named for what it measures because the two readings differ and a viewer cannot tell them
+     * apart: it is the dispatcher's own load against `MaxConcurrentTasks`, which is what explains a
+     * graph whose steps are ready but not starting. A per-graph count would answer a different
+     * question (and is visible anyway as the steps rendered running on the canvas).
+     */
+    InstanceInFlightCount?: number;
+    /** What the runner says it is doing. */
+    ProgressMessage?: string;
+    /** 0–100 when the runner can quantify it. */
+    ProgressPercent?: number;
 };
 /**
  * Receives dispatcher lifecycle frames.
@@ -99,6 +293,26 @@ export type TaskGraphObserver = {
 export type TaskAgentRunParams = {
     /** The task row being executed. */
     TaskID: string;
+    /**
+     * The agent run that submitted this graph, when there was one.
+     *
+     * Becomes the spawned run's `ParentRunID`, which is what makes a workflow's total cost a single
+     * indexed sum over `RootParentRunID` instead of a walk. Null for a graph nobody's run submitted
+     * — a schedule, MCP, or a person — and that is a real case, not a missing value.
+     *
+     * Note this is a run→run link: the task graph sits BETWEEN the two conceptually but cannot be
+     * the parent, because the column points at a run. The graph is recovered through
+     * `Task.AgentRunID` and `Task.ParentID`.
+     */
+    SubmittingAgentRunID?: string | null;
+    /**
+     * How many continuation hops led to this run, from the graph's own metadata.
+     *
+     * Carried so the chain is BOUNDED. A flow that dispatches a graph containing itself recurses
+     * forever otherwise: each spawned run starts at depth zero, so `MAX_REINVOKE_DEPTH` compares
+     * against a permanent zero and never fires. The cap exists; this is what feeds it.
+     */
+    ContinuationDepth?: number;
     /** Agent assigned to the task. */
     AgentID: string;
     /** Parsed `Task.InputPayload`, if any. */
@@ -109,6 +323,8 @@ export type TaskAgentRunParams = {
     Provider: IMetadataProvider;
     /** User the work runs as. */
     ContextUser: UserInfo;
+    /** Optional progress sink; the dispatcher turns calls into rate-limited `NodeProgress` frames. */
+    OnProgress?: TaskRunProgressCallback;
 };
 /** Outcome of running one task node. */
 export type TaskAgentRunResult = {
@@ -173,6 +389,13 @@ export type TaskGraphDispatcherConfig = {
      * Identifies this dispatcher instance in `Task.ClaimedBy`. Must be stable for the process
      * lifetime and distinct per instance — it is what lets reconciliation tell "my orphaned work"
      * from "another instance's live work".
+     *
+     * **Distinctness is a correctness requirement, not a nicety** (C2). Every ownership guard in the
+     * claim protocol compares against this value, so two instances sharing one defeats all of them
+     * at once: A's heartbeat renews B's lease, and A's stale terminal write lands over B's live
+     * execution. Host+pid is NOT sufficient — `HOSTNAME` is unexported to child processes under
+     * systemd and pm2, and a containerised process is routinely pid 1 — which is why the server's
+     * default appends real entropy.
      */
     InstanceID: string;
     /**

package/dist/types.d.ts.map

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

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA2NA,wFAAwF;AACxF,MAAM,CAAC,MAAM,yBAAyB,GAAkD;IACpF,eAAe,EAAE,GAAG;IACpB,wBAAwB,EAAE,EAAE;IAC5B,kBAAkB,EAAE,CAAC;IACrB,mBAAmB,EAAE,CAAC;IACtB,6BAA6B,EAAE,GAAG;CACrC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAycA,wFAAwF;AACxF,MAAM,CAAC,MAAM,yBAAyB,GAAkD;IACpF,eAAe,EAAE,GAAG;IACpB,wBAAwB,EAAE,EAAE;IAC5B,kBAAkB,EAAE,CAAC;IACrB,mBAAmB,EAAE,CAAC;IACtB,6BAA6B,EAAE,GAAG;CACrC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/task-graph",
   "type": "module",
-  "version": "6.1.0-edge.1",
+  "version": "6.1.0-edge.3",
   "description": "MemberJunction: Task Graph - producer-agnostic submission and durable execution of dependency-ordered task graphs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,14 +9,18 @@
     "/dist"
   ],
   "author": "MemberJunction.com",
-  "license": "ISC",
+  "license": "BUSL-1.1",
   "dependencies": {
-    "@memberjunction/ai-agents": "6.1.0-edge.1",
-    "@memberjunction/ai-core-plus": "6.1.0-edge.1",
-    "@memberjunction/core": "6.1.0-edge.1",
-    "@memberjunction/core-entities": "6.1.0-edge.1",
-    "@memberjunction/global": "6.1.0-edge.1",
-    "@memberjunction/notifications": "6.1.0-edge.1"
+    "@memberjunction/actions-base": "6.1.0-edge.3",
+    "@memberjunction/ai-agents": "6.1.0-edge.3",
+    "@memberjunction/ai-core-plus": "6.1.0-edge.3",
+    "@memberjunction/ai-prompts": "6.1.0-edge.3",
+    "@memberjunction/aiengine": "6.1.0-edge.3",
+    "@memberjunction/core": "6.1.0-edge.3",
+    "@memberjunction/core-entities": "6.1.0-edge.3",
+    "@memberjunction/global": "6.1.0-edge.3",
+    "@memberjunction/notifications": "6.1.0-edge.3",
+    "@memberjunction/sql-dialect": "6.1.0-edge.3"
   },
   "devDependencies": {
     "@types/node": "24.10.11",