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

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2023 MemberJunction
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/dist/DispatcherConditionEvaluator.d.ts

@@ -0,0 +1,10 @@
+import type { IConditionEvaluator } from '@memberjunction/ai-core-plus';
+export declare class DispatcherConditionEvaluator implements IConditionEvaluator {
+    private readonly evaluator;
+    Evaluate(expression: string, context: Record<string, unknown>): {
+        Success: boolean;
+        Value?: unknown;
+        ErrorMessage?: string;
+    };
+}
+//# sourceMappingURL=DispatcherConditionEvaluator.d.ts.map

package/dist/DispatcherConditionEvaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DispatcherConditionEvaluator.d.ts","sourceRoot":"","sources":["../src/DispatcherConditionEvaluator.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,qBAAa,4BAA6B,YAAW,mBAAmB;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAEpD,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;CAUtI"}

package/dist/DispatcherConditionEvaluator.js

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Condition evaluation for durable graph edges.
+ *
+ * Wraps the same `SafeExpressionEvaluator` the design-time flow executor uses. Sharing the evaluator
+ * is not incidental — it is what makes an edge condition mean the same thing whether it was drawn in
+ * the flow editor or emitted by an agent, which is the premise Save as Workflow (D17) rests on.
+ *
+ * @module @memberjunction/task-graph
+ */
+import { SafeExpressionEvaluator } from '@memberjunction/global';
+export class DispatcherConditionEvaluator {
+    constructor() {
+        this.evaluator = new SafeExpressionEvaluator();
+    }
+    Evaluate(expression, context) {
+        try {
+            const result = this.evaluator.evaluate(expression, context);
+            return result.success
+                ? { Success: true, Value: result.value }
+                : { Success: false, ErrorMessage: String(result.error ?? 'condition evaluation failed') };
+        }
+        catch (e) {
+            return { Success: false, ErrorMessage: e instanceof Error ? e.message : String(e) };
+        }
+    }
+}
+//# sourceMappingURL=DispatcherConditionEvaluator.js.map

package/dist/DispatcherConditionEvaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DispatcherConditionEvaluator.js","sourceRoot":"","sources":["../src/DispatcherConditionEvaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAGjE,MAAM,OAAO,4BAA4B;IAAzC;QACqB,cAAS,GAAG,IAAI,uBAAuB,EAAE,CAAC;IAY/D,CAAC;IAVU,QAAQ,CAAC,UAAkB,EAAE,OAAgC;QAChE,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YAC5D,OAAO,MAAM,CAAC,OAAO;gBACjB,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE;gBACxC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,IAAI,6BAA6B,CAAC,EAAE,CAAC;QAClG,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACxF,CAAC;IACL,CAAC;CACJ"}

package/dist/TaskClaimStore.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview The compare-and-swap claim protocol for durable task execution.
+ *
+ * This is the mechanism that lets more than one dispatcher instance work the same task table
+ * without two of them running the same task, and that lets a crashed instance's work be picked up
+ * rather than stranded. It is deliberately a small, self-contained unit: every state transition is
+ * a guarded `UPDATE ... WHERE <expected state>` whose rowcount is the answer, so correctness rests
+ * on the database's own atomicity rather than on a distributed lock manager.
+ *
+ * **Why rowcount and not read-then-write.** Reading a task, deciding it is claimable, then writing
+ * the claim is a textbook race: two instances can both read `Pending`. The single-statement form —
+ * `UPDATE Task SET ClaimedBy=@me WHERE ID=@id AND Status='Pending'` — makes the check and the write
+ * one atomic operation, so exactly one instance sees rowcount 1 and the other sees 0 and moves on.
+ *
+ * **Why every transition is guarded, not just the initial claim.** Per D20 the Task table stays
+ * user-writable: entity forms, Data Explorer, GraphQL, and any agent holding an update-record action
+ * can change `Status` or clear `ClaimedBy` underneath a running executor. A completion write that
+ * only said "set this task Complete" would happily overwrite a task someone had reassigned. Guarding
+ * on `ClaimedBy=@me` means a stale executor's write fails cleanly (rowcount 0) instead of
+ * double-completing, and the dispatcher can defer to the sweep.
+ *
+ * @module @memberjunction/task-graph
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { ReconciliationEvent } from './types.js';
+/** Fields the claim protocol needs from a candidate task. */
+export type ClaimableTask = {
+    ID: string;
+    Name: string;
+    AgentID: string | null;
+    UserID: string | null;
+    InputPayload: string | null;
+};
+/**
+ * Guarded reads and writes over the `Task` claim columns.
+ *
+ * Uses direct SQL rather than `BaseEntity.Save()` on purpose, and this is the one place in the
+ * program where that is correct: the entire point is a *conditional* write whose rowcount is the
+ * return value. `Save()` issues an unconditional update and reports success for a row whose state
+ * changed underneath it, which is precisely the race being defended against. Every method here is a
+ * single statement; nothing reads-then-writes.
+ */
+export declare class TaskClaimStore {
+    private readonly instanceID;
+    private readonly claimTTLSeconds;
+    constructor(instanceID: string, claimTTLSeconds: number);
+    private sql;
+    /** Schema-qualified `Task` table for the provider's configured core schema. */
+    private taskTable;
+    /**
+     * Attempts to claim one task.
+     *
+     * The `Status='Pending'` predicate is the whole contract: a task another instance already moved
+     * to `In Progress` fails the predicate and yields rowcount 0. `ClaimedBy IS NULL OR
+     * ClaimExpiresAt < now` additionally lets an expired claim be taken over without a separate
+     * reconciliation pass having to run first.
+     *
+     * @returns true when this instance now owns the task
+     */
+    TryClaim(provider: IMetadataProvider, taskID: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Extends this instance's claim on a task it is actively running.
+     *
+     * Guarded on `ClaimedBy=@me` so a heartbeat can never resurrect a claim that reconciliation
+     * already released — if the sweep took the task back, the heartbeat fails and the executor
+     * learns its work is no longer owned.
+     *
+     * @returns true when the claim was extended; false means this instance no longer owns the task
+     */
+    Heartbeat(provider: IMetadataProvider, taskID: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Records a terminal outcome and releases the claim in one guarded statement.
+     *
+     * Guarded on both `Status='In Progress'` and `ClaimedBy=@me`: a task that was cancelled or
+     * reassigned while running fails the predicate, so a stale executor cannot overwrite the newer
+     * decision. The caller treats rowcount 0 as "someone else owns this now" rather than an error.
+     *
+     * @returns true when this instance's outcome was recorded
+     */
+    CompleteClaimed(provider: IMetadataProvider, taskID: string, outcome: {
+        Status: 'Complete' | 'Failed';
+        OutputPayload?: string | null;
+        ErrorMessage?: string | null;
+        AgentRunID?: string | null;
+    }, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Reclaims tasks whose claims have lapsed, returning them to `Pending` so any instance can pick
+     * them up.
+     *
+     * **Human tasks are exempt** (review round 2). A task assigned to a person (`UserID` set) never
+     * carries a claim, so `In Progress` with no claim is its *legitimate* parked shape — an approval
+     * waiting on someone. Normalizing it would reset that approval out from under the user. Their
+     * lifecycle is driven by `DueAt` notification and escalation, never by claim expiry.
+     *
+     * Only expired claims are reclaimed; a live claim is left strictly alone, which is what keeps a
+     * slow-but-healthy task from being executed twice.
+     */
+    ReleaseExpiredClaims(provider: IMetadataProvider, contextUser: UserInfo): Promise<ReconciliationEvent[]>;
+    /**
+     * Returns *agent* tasks sitting `In Progress` with no claim at all.
+     *
+     * This is the anomalous shape D20 anticipates from a human or an agent writing `Status`
+     * directly. It is reported rather than silently corrected: the row is evidence of tampering or
+     * of a bug, and Record Changes already carries the audit trail. Human-assigned tasks are
+     * excluded because for them this shape is legitimate, not anomalous.
+     */
+    FindOrphanedInProgress(provider: IMetadataProvider, contextUser: UserInfo): Promise<ReconciliationEvent[]>;
+    /** Runs the affected-rows statement, returning 0 on error rather than throwing into the loop. */
+    private affectedRows;
+    private literalOrNull;
+    /** Single-quote escaping. Inputs here are UUIDs and JSON the dispatcher itself produced. */
+    private escape;
+}
+//# sourceMappingURL=TaskClaimStore.d.ts.map

package/dist/TaskClaimStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskClaimStore.d.ts","sourceRoot":"","sources":["../src/TaskClaimStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,iBAAiB,EAA6C,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC9G,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF;;;;;;;;GAQG;AACH,qBAAa,cAAc;IAEnB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe;gBADf,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM;IAG5C,OAAO,CAAC,GAAG;IAIX,+EAA+E;IAC/E,OAAO,CAAC,SAAS;IAKjB;;;;;;;;;OASG;IACU,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAiB3G;;;;;;;;OAQG;IACU,SAAS,CAAC,QAAQ,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAY5G;;;;;;;;OAQG;IACU,eAAe,CACxB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;QAAE,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EACnI,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC,OAAO,CAAC;IAwBnB;;;;;;;;;;;OAWG;IACU,oBAAoB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IA2CrH;;;;;;;OAOG;IACU,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAqBvH,iGAAiG;YACnF,YAAY;IAe1B,OAAO,CAAC,aAAa;IAIrB,4FAA4F;IAC5F,OAAO,CAAC,MAAM;CAGjB"}

package/dist/TaskClaimStore.js

@@ -0,0 +1,218 @@
+/**
+ * @fileoverview The compare-and-swap claim protocol for durable task execution.
+ *
+ * This is the mechanism that lets more than one dispatcher instance work the same task table
+ * without two of them running the same task, and that lets a crashed instance's work be picked up
+ * rather than stranded. It is deliberately a small, self-contained unit: every state transition is
+ * a guarded `UPDATE ... WHERE <expected state>` whose rowcount is the answer, so correctness rests
+ * on the database's own atomicity rather than on a distributed lock manager.
+ *
+ * **Why rowcount and not read-then-write.** Reading a task, deciding it is claimable, then writing
+ * the claim is a textbook race: two instances can both read `Pending`. The single-statement form —
+ * `UPDATE Task SET ClaimedBy=@me WHERE ID=@id AND Status='Pending'` — makes the check and the write
+ * one atomic operation, so exactly one instance sees rowcount 1 and the other sees 0 and moves on.
+ *
+ * **Why every transition is guarded, not just the initial claim.** Per D20 the Task table stays
+ * user-writable: entity forms, Data Explorer, GraphQL, and any agent holding an update-record action
+ * can change `Status` or clear `ClaimedBy` underneath a running executor. A completion write that
+ * only said "set this task Complete" would happily overwrite a task someone had reassigned. Guarding
+ * on `ClaimedBy=@me` means a stale executor's write fails cleanly (rowcount 0) instead of
+ * double-completing, and the dispatcher can defer to the sweep.
+ *
+ * @module @memberjunction/task-graph
+ */
+import { LogError, LogStatus } from '@memberjunction/core';
+/**
+ * Guarded reads and writes over the `Task` claim columns.
+ *
+ * Uses direct SQL rather than `BaseEntity.Save()` on purpose, and this is the one place in the
+ * program where that is correct: the entire point is a *conditional* write whose rowcount is the
+ * return value. `Save()` issues an unconditional update and reports success for a row whose state
+ * changed underneath it, which is precisely the race being defended against. Every method here is a
+ * single statement; nothing reads-then-writes.
+ */
+export class TaskClaimStore {
+    constructor(instanceID, claimTTLSeconds) {
+        this.instanceID = instanceID;
+        this.claimTTLSeconds = claimTTLSeconds;
+    }
+    sql(provider) {
+        return provider;
+    }
+    /** Schema-qualified `Task` table for the provider's configured core schema. */
+    taskTable(provider) {
+        const db = this.sql(provider);
+        return `${db.QuoteIdentifier(db.MJCoreSchemaName)}.${db.QuoteIdentifier('Task')}`;
+    }
+    /**
+     * Attempts to claim one task.
+     *
+     * The `Status='Pending'` predicate is the whole contract: a task another instance already moved
+     * to `In Progress` fails the predicate and yields rowcount 0. `ClaimedBy IS NULL OR
+     * ClaimExpiresAt < now` additionally lets an expired claim be taken over without a separate
+     * reconciliation pass having to run first.
+     *
+     * @returns true when this instance now owns the task
+     */
+    async TryClaim(provider, taskID, contextUser) {
+        const db = this.sql(provider);
+        const expires = new Date(Date.now() + this.claimTTLSeconds * 1000);
+        const sql = `
+            UPDATE ${this.taskTable(provider)}
+            SET ${db.QuoteIdentifier('Status')} = 'In Progress',
+                ${db.QuoteIdentifier('ClaimedBy')} = '${this.escape(this.instanceID)}',
+                ${db.QuoteIdentifier('ClaimExpiresAt')} = '${expires.toISOString()}',
+                ${db.QuoteIdentifier('StartedAt')} = '${new Date().toISOString()}'
+            WHERE ${db.QuoteIdentifier('ID')} = '${this.escape(taskID)}'
+              AND ${db.QuoteIdentifier('Status')} = 'Pending'
+              AND (${db.QuoteIdentifier('ClaimedBy')} IS NULL
+                   OR ${db.QuoteIdentifier('ClaimExpiresAt')} IS NULL
+                   OR ${db.QuoteIdentifier('ClaimExpiresAt')} < '${new Date().toISOString()}')`;
+        return (await this.affectedRows(db, sql, contextUser)) === 1;
+    }
+    /**
+     * Extends this instance's claim on a task it is actively running.
+     *
+     * Guarded on `ClaimedBy=@me` so a heartbeat can never resurrect a claim that reconciliation
+     * already released — if the sweep took the task back, the heartbeat fails and the executor
+     * learns its work is no longer owned.
+     *
+     * @returns true when the claim was extended; false means this instance no longer owns the task
+     */
+    async Heartbeat(provider, taskID, contextUser) {
+        const db = this.sql(provider);
+        const expires = new Date(Date.now() + this.claimTTLSeconds * 1000);
+        const sql = `
+            UPDATE ${this.taskTable(provider)}
+            SET ${db.QuoteIdentifier('ClaimExpiresAt')} = '${expires.toISOString()}'
+            WHERE ${db.QuoteIdentifier('ID')} = '${this.escape(taskID)}'
+              AND ${db.QuoteIdentifier('ClaimedBy')} = '${this.escape(this.instanceID)}'
+              AND ${db.QuoteIdentifier('Status')} = 'In Progress'`;
+        return (await this.affectedRows(db, sql, contextUser)) === 1;
+    }
+    /**
+     * Records a terminal outcome and releases the claim in one guarded statement.
+     *
+     * Guarded on both `Status='In Progress'` and `ClaimedBy=@me`: a task that was cancelled or
+     * reassigned while running fails the predicate, so a stale executor cannot overwrite the newer
+     * decision. The caller treats rowcount 0 as "someone else owns this now" rather than an error.
+     *
+     * @returns true when this instance's outcome was recorded
+     */
+    async CompleteClaimed(provider, taskID, outcome, contextUser) {
+        const db = this.sql(provider);
+        const sets = [
+            `${db.QuoteIdentifier('Status')} = '${outcome.Status}'`,
+            `${db.QuoteIdentifier('CompletedAt')} = '${new Date().toISOString()}'`,
+            `${db.QuoteIdentifier('PercentComplete')} = ${outcome.Status === 'Complete' ? 100 : 0}`,
+            // Release the claim as part of the same atomic write — a separate release could be
+            // interrupted, leaving a terminal task holding a claim that the sweep would then flag.
+            `${db.QuoteIdentifier('ClaimedBy')} = NULL`,
+            `${db.QuoteIdentifier('ClaimExpiresAt')} = NULL`,
+        ];
+        sets.push(`${db.QuoteIdentifier('OutputPayload')} = ${this.literalOrNull(outcome.OutputPayload)}`);
+        sets.push(`${db.QuoteIdentifier('ErrorMessage')} = ${this.literalOrNull(outcome.ErrorMessage)}`);
+        sets.push(`${db.QuoteIdentifier('AgentRunID')} = ${outcome.AgentRunID ? `'${this.escape(outcome.AgentRunID)}'` : 'NULL'}`);
+        const sql = `
+            UPDATE ${this.taskTable(provider)}
+            SET ${sets.join(', ')}
+            WHERE ${db.QuoteIdentifier('ID')} = '${this.escape(taskID)}'
+              AND ${db.QuoteIdentifier('Status')} = 'In Progress'
+              AND ${db.QuoteIdentifier('ClaimedBy')} = '${this.escape(this.instanceID)}'`;
+        return (await this.affectedRows(db, sql, contextUser)) === 1;
+    }
+    /**
+     * Reclaims tasks whose claims have lapsed, returning them to `Pending` so any instance can pick
+     * them up.
+     *
+     * **Human tasks are exempt** (review round 2). A task assigned to a person (`UserID` set) never
+     * carries a claim, so `In Progress` with no claim is its *legitimate* parked shape — an approval
+     * waiting on someone. Normalizing it would reset that approval out from under the user. Their
+     * lifecycle is driven by `DueAt` notification and escalation, never by claim expiry.
+     *
+     * Only expired claims are reclaimed; a live claim is left strictly alone, which is what keeps a
+     * slow-but-healthy task from being executed twice.
+     */
+    async ReleaseExpiredClaims(provider, contextUser) {
+        const db = this.sql(provider);
+        const now = new Date().toISOString();
+        // Capture what will be reclaimed BEFORE reclaiming, so the log names the tasks. The
+        // subsequent UPDATE re-states the same predicate, so a task whose claim was refreshed in
+        // between is correctly skipped rather than reclaimed on stale information.
+        const candidates = await db.ExecuteSQL(`SELECT ${db.QuoteIdentifier('ID')}, ${db.QuoteIdentifier('Name')}, ${db.QuoteIdentifier('ClaimedBy')}
+             FROM ${this.taskTable(provider)}
+             WHERE ${db.QuoteIdentifier('Status')} = 'In Progress'
+               AND ${db.QuoteIdentifier('AgentID')} IS NOT NULL
+               AND ${db.QuoteIdentifier('ClaimedBy')} IS NOT NULL
+               AND ${db.QuoteIdentifier('ClaimExpiresAt')} IS NOT NULL
+               AND ${db.QuoteIdentifier('ClaimExpiresAt')} < '${now}'`, undefined, undefined, contextUser);
+        if (!candidates || candidates.length === 0)
+            return [];
+        const sql = `
+            UPDATE ${this.taskTable(provider)}
+            SET ${db.QuoteIdentifier('Status')} = 'Pending',
+                ${db.QuoteIdentifier('ClaimedBy')} = NULL,
+                ${db.QuoteIdentifier('ClaimExpiresAt')} = NULL
+            WHERE ${db.QuoteIdentifier('Status')} = 'In Progress'
+              AND ${db.QuoteIdentifier('AgentID')} IS NOT NULL
+              AND ${db.QuoteIdentifier('ClaimedBy')} IS NOT NULL
+              AND ${db.QuoteIdentifier('ClaimExpiresAt')} IS NOT NULL
+              AND ${db.QuoteIdentifier('ClaimExpiresAt')} < '${now}'`;
+        const released = await this.affectedRows(db, sql, contextUser);
+        const events = candidates.slice(0, released).map((c) => ({
+            TaskID: c.ID,
+            Action: 'ExpiredClaimReleased',
+            Detail: `Claim held by '${c.ClaimedBy}' expired; task '${c.Name}' returned to Pending.`,
+        }));
+        for (const e of events) {
+            LogStatus(`[TaskGraph reconciliation] ${e.Action}: ${e.Detail}`);
+        }
+        return events;
+    }
+    /**
+     * Returns *agent* tasks sitting `In Progress` with no claim at all.
+     *
+     * This is the anomalous shape D20 anticipates from a human or an agent writing `Status`
+     * directly. It is reported rather than silently corrected: the row is evidence of tampering or
+     * of a bug, and Record Changes already carries the audit trail. Human-assigned tasks are
+     * excluded because for them this shape is legitimate, not anomalous.
+     */
+    async FindOrphanedInProgress(provider, contextUser) {
+        const db = this.sql(provider);
+        const rows = await db.ExecuteSQL(`SELECT ${db.QuoteIdentifier('ID')}, ${db.QuoteIdentifier('Name')}
+             FROM ${this.taskTable(provider)}
+             WHERE ${db.QuoteIdentifier('Status')} = 'In Progress'
+               AND ${db.QuoteIdentifier('AgentID')} IS NOT NULL
+               AND ${db.QuoteIdentifier('ClaimedBy')} IS NULL`, undefined, undefined, contextUser);
+        const events = (rows ?? []).map((r) => ({
+            TaskID: r.ID,
+            Action: 'OrphanedInProgressReleased',
+            Detail: `Agent task '${r.Name}' is In Progress with no claim — no dispatcher owns it.`,
+        }));
+        for (const e of events) {
+            LogError(`[TaskGraph reconciliation] ${e.Action}: ${e.Detail}`);
+        }
+        return events;
+    }
+    /** Runs the affected-rows statement, returning 0 on error rather than throwing into the loop. */
+    async affectedRows(db, sql, contextUser) {
+        try {
+            // Trailing SELECT is how the row count comes back as data across both dialects, rather
+            // than depending on a driver-specific rowsAffected field.
+            const rows = await db.ExecuteSQL(`${sql};\nSELECT @@ROWCOUNT AS ${db.QuoteIdentifier('AffectedRows')}`, undefined, undefined, contextUser);
+            return Number(rows?.[0]?.AffectedRows ?? 0);
+        }
+        catch (e) {
+            LogError(`[TaskGraph] guarded write failed: ${e instanceof Error ? e.message : String(e)}`);
+            return 0;
+        }
+    }
+    literalOrNull(value) {
+        return value == null ? 'NULL' : `'${this.escape(value)}'`;
+    }
+    /** Single-quote escaping. Inputs here are UUIDs and JSON the dispatcher itself produced. */
+    escape(value) {
+        return value.replace(/'/g, "''");
+    }
+}
+//# sourceMappingURL=TaskClaimStore.js.map

package/dist/TaskClaimStore.js.map

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

package/dist/TaskGraphDispatcher.d.ts

@@ -0,0 +1,186 @@
+import { UserInfo } from '@memberjunction/core';
+import { IShutdownable } from '@memberjunction/global';
+import { ProviderFactory, TaskAgentRunner, 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?;
+    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;
+    /** 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);
+    /**
+     * 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;
+    /**
+     * 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;
+    /** 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;
+    /** Parsed `OutputPayload` of each completed dependency, keyed by that task's ID. */
+    private loadDependencyOutputs;
+}
+//# 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":"AA6BA,OAAO,EAAmD,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACjG,OAAO,EAAE,aAAa,EAAoB,MAAM,wBAAwB,CAAC;AAkBzE,OAAO,EAEH,eAAe,EACf,eAAe,EACf,yBAAyB,EACzB,KAAK,yBAAyB,EAG9B,KAAK,iBAAiB,EACzB,MAAM,SAAS,CAAC;AAcjB,qBAAa,mBAAoB,YAAW,aAAa;IAiBjD,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAE5B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC;IACvC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IA9B9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA+B;IAElE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,cAAc,CAA+C;IACrE,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,4DAA4D;IAC5D,OAAO,CAAC,OAAO,CAAS;IAExB,kHAAkH;IAClH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;gBAG/C,eAAe,EAAE,eAAe,EAChC,WAAW,EAAE,eAAe,EAC5B,WAAW,EAAE,QAAQ,EACtC,MAAM,EAAE,OAAO,CAAC,yBAAyB,CAAC,GAAG,IAAI,CAAC,yBAAyB,EAAE,YAAY,CAAC;IAC1F;;;;OAIG;IACc,qBAAqB,CAAC,EAAE,yBAAyB;IAClE;;;OAGG;IACc,QAAQ,CAAC,EAAE,iBAAiB;IAOjD;;;;;;OAMG;IACH,OAAO,CAAC,IAAI;IASZ;;;;;;;;;;;OAWG;YACW,YAAY;IAmB1B;;;;;;OAMG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBnC;;;;;;OAMG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAelC,4CAA4C;IAC5C,SAAgB,YAAY,yBAAyB;IAErD,6EAA6E;IAChE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC;;;;;;OAMG;IACU,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBvC;;;;;OAKG;YACW,QAAQ;IA+BtB;;;;;OAKG;YACW,cAAc;IAsF5B;;;;;OAKG;YACW,kBAAkB;IA8DhC;;;;;;;;;;;;;OAaG;YACW,mBAAmB;IAgEjC,kFAAkF;IAClF,OAAO,CAAC,kBAAkB;IAI1B;;;;;OAKG;YACW,iBAAiB;IAmB/B,4FAA4F;IAC5F,OAAO,CAAC,wBAAwB;IAOhC;;;;;;;;;;;;OAYG;YACW,oBAAoB;IAsClC;;;;;;;;;;OAUG;YACW,kBAAkB;IA2ChC;;;;;;OAMG;YACW,kBAAkB;IA4BhC,8FAA8F;YAChF,cAAc;IA8D5B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAgC7B,oFAAoF;YACtE,qBAAqB;CAkBtC"}