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

package/LICENSE

@@ -1,7 +1,183 @@
-ISC License
+Business Source License 1.1
 
-Copyright (c) 2023 MemberJunction
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.
 
-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.
+Parameters
+
+Licensor:             Blue Cypress, Inc.
+
+Licensed Work:        MemberJunction.
+                      The Licensed Work is (c) 2023-2026 Blue Cypress, Inc.
+
+Additional Use Grant: Subject to the terms of this License, Licensor grants
+                      you the following additional rights to make Production
+                      Use of the Licensed Work.
+
+                      1. Internal Use
+
+                      You may make production use of the Licensed Work for
+                      your own internal business or organizational operations.
+
+                      2. Nonprofit Use
+
+                      If you are a Nonprofit, you may make production use of
+                      the Licensed Work for the operations and activities of
+                      your Organizational Family.
+
+                      3. MemberJunction Certified Program Use
+
+                      If you are authorized by Licensor under the
+                      MemberJunction Certified Program to provide professional
+                      services using the Licensed Work, you may make
+                      production use of the Licensed Work in providing such
+                      professional services to a client, provided that:
+
+                      (a) the Licensed Work is deployed in, and the applicable
+                      production use occurs within, an environment owned,
+                      leased, licensed, subscribed to, or otherwise controlled
+                      by that client; and
+
+                      (b) the production use is for that client's own internal
+                      business or organizational operations or is otherwise
+                      independently permitted to that client under this
+                      Additional Use Grant.
+
+                      4. Definitions Applicable to the Additional Use Grant
+
+                      "Affiliate" means, with respect to a specified Person,
+                      any other Person that directly or indirectly Controls,
+                      is Controlled by, or is under common Control with such
+                      specified Person.
+
+                      "Control" (including the terms "Controls," "Controlled
+                      by," and "under common Control with") means the direct
+                      or indirect possession of the power to direct or cause
+                      the direction of the management and policies of a
+                      Person, whether through ownership of voting interests,
+                      by contract, or otherwise.
+
+                      "Organizational Family" means, with respect to a Person,
+                      (a) such Person and its Affiliates, and (b) any
+                      nonprofit organization, governmental entity, chapter,
+                      division, local affiliate, regional affiliate, state
+                      affiliate, national affiliate, or other entity that is
+                      formally affiliated with such Person through governing
+                      documents, a charter, bylaws, a membership agreement, or
+                      another written organizational instrument, and is
+                      recognized under such documents as part of the same
+                      organizational structure.
+
+                      "Nonprofit" means a Person recognized by the Internal
+                      Revenue Service as exempt from federal income taxation
+                      under Section 501(c)(3), 501(c)(4), 501(c)(5), or
+                      501(c)(6) of the Internal Revenue Code, or a foreign
+                      organization recognized under substantially equivalent
+                      laws.
+
+                      A Person claiming eligibility as a Nonprofit shall, upon
+                      Licensor's reasonable request, provide documentation
+                      reasonably sufficient to demonstrate that it qualifies
+                      as a Nonprofit. If such Person materially misrepresents,
+                      or is unable to demonstrate, its qualification as a
+                      Nonprofit, the rights granted to such Person under
+                      Section 2 of this Additional Use Grant shall terminate.
+
+                      "MemberJunction Certified Program" means Licensor's
+                      then-current program for certifying and authorizing a
+                      Person to provide professional services using the
+                      Licensed Work.
+
+                      "Person" means any individual, corporation, limited
+                      liability company, partnership, association, nonprofit
+                      organization, governmental entity, or other legal or
+                      organizational entity.
+
+Change Date:          Four (4) years from the date the Licensed Work is first
+                      made available.
+
+Change License:       MIT License.
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Blue Cypress, Inc.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/README.md

@@ -5,7 +5,8 @@ that turn a node into work.
 
 > **New to workflows?** Start with the [Workflows and Task Graphs
 > Guide](../../guides/WORKFLOW_AND_TASK_GRAPH_GUIDE.md), which covers what a workflow is, when to
-> use one, and every rule that decides what happens next. This README is the package tour.
+> use one, and every rule that decides what happens next. To **step a live run**, see the
+> [Workflow Debugger Guide](../../guides/WORKFLOW_DEBUGGER_GUIDE.md). This README is the package tour.
 
 ---
 
@@ -72,6 +73,8 @@ without standing up the agent framework.
 | `DispatcherConditionEvaluator.ts` | Edge conditions, over the superset context both dialects can read. |
 | `TaskGraphSubmitterImpl.ts` | Registers the durable submitter under the `ClassFactory` seam. |
 | `operations/` | The `TaskGraph.*` remote operations. |
+| `debug-state.ts` | Durable `$.debug` bag — pause, breakpoints, step allowance, `skipBreakpointTaskID`, edge overrides. Pure claim-gate. |
+| `task-graph-kick.ts` | Process-local kick set. `Start()` registers; `Submit` pokes every running dispatcher so the first pass is immediate. |
 
 ---
 
@@ -146,6 +149,30 @@ await dispatcher.Start();
 Without `LoadTaskGraphOperations()` nothing registers the submitter, and
 `GetTaskGraphSubmitter()` returns `null` — which callers must report rather than swallow.
 
+`Start()` registers a kick and fires one immediately. Do not wait for the first `setInterval`
+tick — that is a 5s dead pause after Debug/Run. Submit cannot import the dispatcher instance
+(submit and execute are separate halves), so it calls `KickTaskGraphDispatchers()` instead.
+
+---
+
+## Debugging a live graph
+
+Every control is a **gate on claiming**, never on running. State lives under `$.debug` on the
+parent task's `InputPayload`. The debugger UI and the dispatcher never talk directly — they
+rendezvous on the row. See [`debug-state.ts`](src/debug-state.ts) and the
+[Workflow Debugger Guide](../../guides/WORKFLOW_DEBUGGER_GUIDE.md).
+
+- **Start-paused.** Submit writes `paused: true` before any dispatcher has seen the graph.
+- **Breakpoints.** The claim gate treats an armed, eligible task like a hold. Resume from a
+  breakpoint stamps `skipBreakpointTaskID` so that one claim is allowed through; without it the
+  next poll re-hits the same Pending row. `ForEach` is one task — one Continue runs the loop.
+- **Edge overrides.** Authored `'true'` / `'false'` on a `TaskDependency` id, honored by every
+  instance, survive a restart.
+- **Kick.** After Submit (and on `Start()`), `KickTaskGraphDispatchers()` runs a pass now.
+
+The Angular drop-in is `<mj-task-graph-debugger>` in
+[`@memberjunction/ng-task-graph-editor`](../Angular/Generic/task-graph-editor/README.md).
+
 ---
 
 ## Cost rollup
@@ -179,6 +206,8 @@ real rollup.
 ## Related
 
 - [Workflows and Task Graphs Guide](../../guides/WORKFLOW_AND_TASK_GRAPH_GUIDE.md) — start here
+- [Workflow Debugger Guide](../../guides/WORKFLOW_DEBUGGER_GUIDE.md) — step a live run
+- [`@memberjunction/ng-task-graph-editor`](../Angular/Generic/task-graph-editor/README.md) — canvas and drop-in debugger
 - [`@memberjunction/ai-core-plus`](../AI/CorePlus) — the spec, validator, compiler, pure algorithms,
   payload mapping and layout
 - [`@memberjunction/ai-agents`](../AI/Agents) — the agent framework and `FlowAgentType`

package/dist/TaskClaimStore.d.ts

@@ -22,7 +22,44 @@
  * @module @memberjunction/task-graph
  */
 import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { type TerminalTaskGraphStatus } from '@memberjunction/ai-core-plus';
 import { ReconciliationEvent } from './types.js';
+/**
+ * A value one debug-bag field is being set to.
+ *
+ * Discriminated so the statement renders each with the right JSON type — a boolean stored as the
+ * string `"true"` reads back as truthy-but-wrong, and an object stored as a string reads back as a
+ * string. `null` deletes the key.
+ */
+export type TaskGraphDebugFieldValue = {
+    Kind: 'null';
+} | {
+    Kind: 'bool';
+    Value: boolean;
+} | {
+    Kind: 'string';
+    Value: string;
+}
+/** Pre-serialized JSON for an object or array. */
+ | {
+    Kind: 'json';
+    Value: string;
+};
+/** One field of the debug bag, addressed by its JSON path. */
+export type TaskGraphDebugFieldWrite = {
+    Path: string;
+    Value: TaskGraphDebugFieldValue;
+};
+/**
+ * Every object path that must exist for a JSON path to be writable — i.e. its proper prefixes,
+ * excluding the root and the leaf itself.
+ *
+ * `$.debug.edgeOverrides."abc"` → `['$.debug', '$.debug.edgeOverrides']`.
+ *
+ * Exported and pure because the rule ("JSON_MODIFY does not create intermediate objects") is the
+ * kind of database behaviour that is easy to assume wrongly and cheap to pin with a test.
+ */
+export declare function ContainingPaths(path: string): string[];
 /** Fields the claim protocol needs from a candidate task. */
 export type ClaimableTask = {
     ID: string;
@@ -40,6 +77,29 @@ export type ClaimableTask = {
  * changed underneath it, which is precisely the race being defended against. Every method here is a
  * single statement; nothing reads-then-writes.
  */
+/**
+ * Statuses a graph parent has stopped moving from — the single source of truth.
+ *
+ * `Blocked` is INCLUDED: `ComputeParentRollup` returns it as settled, so a
+ * failure-blocked graph is as settled as a completed one. Leaving it out left a Blocked settlement
+ * unprotected from overwrite AND invisible to the rescue sweep — a stranded run with extra steps.
+ *
+ * Exported because the dispatcher's sweep filters on the same set. Two lists that must agree is how
+ * a graph becomes invisible to the machinery meant to rescue it.
+ */
+export declare const TERMINAL_PARENT_STATUSES: readonly ["Complete", "Failed", "Cancelled", "Skipped", "Blocked"];
+export type TerminalParentStatus = TerminalTaskGraphStatus;
+/**
+ * The only status a *progress* write may set.
+ *
+ * Typed rather than left as a string so the split between the two parent writes is enforced instead
+ * of remembered: settling is a once-only guarded transition with a completion timestamp, and it goes
+ * through {@link TaskClaimStore.TrySettleParent}. Handing a terminal status to the progress method
+ * is now a compile error rather than a graph that settles without a `CompletedAt`.
+ */
+export type NonTerminalParentStatus = 'In Progress';
+/** The same set as a SQL literal list, so the guards and the sweep cannot drift. */
+export declare const TERMINAL_PARENT_STATUS_SQL: string;
 export declare class TaskClaimStore {
     private readonly instanceID;
     private readonly claimTTLSeconds;
@@ -47,6 +107,30 @@ export declare class TaskClaimStore {
     private sql;
     /** Schema-qualified `Task` table for the provider's configured core schema. */
     private taskTable;
+    private agentRunTable;
+    /**
+     * Writes a graph's cost rollup onto the submitting run, those four columns and no others.
+     *
+     * **The full-row `Save()` this replaces could revert a peer's settle** (C4). Two instances
+     * entering the settled branch for one graph is by design, so instance B's rollup — loaded before
+     * A settled the run — would write back `Paused` over A's `Completed`, along with every other
+     * column it had read. And a crash between this write and the same pass's lifecycle write left
+     * the run `Paused` under a claimed marker, which no sweep re-enters.
+     */
+    TrySetRunCostRollup(provider: IMetadataProvider, runID: string, totals: {
+        Cost: number | null;
+        Tokens: number | null;
+        PromptTokens: number | null;
+        CompletionTokens: number | null;
+    }, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Settles a parked agent run, guarded on it still being parked.
+     *
+     * Same reasoning as the rollup above and as every parent write since Round 1: a full-row save
+     * carries a whole stale snapshot, and the `Paused` predicate makes the transition once-only
+     * across instances rather than last-write-wins.
+     */
+    TrySettleRun(provider: IMetadataProvider, runID: string, succeeded: boolean, errorMessage: string | null, contextUser: UserInfo): Promise<boolean>;
     /**
      * Attempts to claim one task.
      *
@@ -98,10 +182,15 @@ export declare class TaskClaimStore {
      * 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.
+     * **Scoped to tasks a dispatcher executes**, via the one shared predicate — see `task-predicates`.
+     * Expressed that way rather than as a list of the runner columns that happened to exist when this
+     * was written: the earlier form named `AgentID` and `ActionID` only, and the day `PromptID`
+     * arrived, a crashed prompt task became unrecoverable and undiagnosable in the same stroke.
+     *
+     * **Tasks a person completes are exempt.** One 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.
@@ -116,6 +205,289 @@ export declare class TaskClaimStore {
      * excluded because for them this shape is legitimate, not anomalous.
      */
     FindOrphanedInProgress(provider: IMetadataProvider, contextUser: UserInfo): Promise<ReconciliationEvent[]>;
+    /**
+     * Writes a graph parent's terminal status, and only if it is not already terminal.
+     *
+     * **Why this is not `parent.Save()`.** `GenerateSaveSQL` sends every updateable column on every
+     * save, not just the dirty ones — so a full-row save carries the whole in-memory snapshot,
+     * including `InputPayload`. Two instances polling the same settling graph both compute the
+     * terminal rollup; if one claims the continuation marker (written into that JSON bag) and the
+     * other then saves its pre-marker snapshot, **the marker is erased** and the settlement is
+     * delivered a second time. For `reinvoke` that is a second billed agent turn for one settlement
+     * — precisely the failure P4 exists to prevent, reintroduced through a column nobody thought
+     * they were writing.
+     *
+     * Column-scoped and guarded, per the doctrine every task transition already follows: touch
+     * `Status`/`PercentComplete`/`CompletedAt` and nothing else, and only from a non-terminal state.
+     * The second instance's write becomes a no-op instead of a rewind.
+     *
+     * @returns true when this call moved the parent to terminal; false when it was already terminal
+     *          (someone else settled it) or the write failed
+     */
+    TrySettleParent(provider: IMetadataProvider, parentTaskID: string, status: TerminalParentStatus, percentComplete: number, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Updates a graph parent's in-flight progress — column-scoped, and refused once it is terminal.
+     *
+     * **The race this closes needs no exotic timing.** Instance A loads the graph while a child is
+     * still In Progress and computes a non-terminal rollup. Instance B loads after that child
+     * finishes, settles the parent and claims the continuation. A's full-row progress `Save()` then
+     * lands: `Status` reverts to non-terminal *and* A's pre-marker `InputPayload` snapshot erases
+     * the marker. The next pass finds a non-terminal parent with a terminal rollup and an absent
+     * marker — so it settles again and delivers again. That is the duplicate `reinvoke` P4 exists to
+     * prevent, arriving through the last unguarded window.
+     *
+     * "These writes happen before settlement" is true per instance and false across instances, which
+     * is exactly the kind of timing argument a guard replaces with a structural one.
+     */
+    TryUpdateParentProgress(provider: IMetadataProvider, parentTaskID: string, status: NonTerminalParentStatus, percentComplete: number, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Stamps a graph parent's start time, once, without touching anything else.
+     *
+     * Same reason as {@link TrySettleParent}: a full-row `Save()` here would carry the whole
+     * in-memory snapshot including `InputPayload`, so stamping a start time could erase a
+     * continuation marker another instance had just claimed. Guarded on `StartedAt IS NULL` so it is
+     * naturally once-only and safe to call on every pass.
+     */
+    TryStampParentStart(provider: IMetadataProvider, parentTaskID: string, startedAt: Date, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Claims the right to deliver a graph's continuation — exactly once, across every instance.
+     *
+     * **What this replaces.** `claimContinuation` was Load → check the marker → `BaseEntity.Save()`:
+     * an unconditional last-write-wins UPDATE. Two dispatchers polling the same settled graph inside
+     * one interval both read "no marker", both saved, and both delivered. The comments called it a
+     * compare-and-swap; it was read-check-write. Every *task* transition in this store is a guarded
+     * single statement for exactly this reason — the continuation marker was the one transition that
+     * was not.
+     *
+     * The marker lives inside the parent's `InputPayload` JSON bag rather than a column, so the
+     * guard is a JSON predicate. That keeps one representation for writer and reader: this statement
+     * writes it, `ParseTaskGraphParentMetadata` reads it, and a graph settled before this existed is
+     * decided by the same parser as one settled after — which a new column plus a backfill could not
+     * promise.
+     *
+     * Timestamps are ISO 8601 UTC because the TS reader parses them; `JSON_MODIFY` on a row whose
+     * payload is absent or unparseable writes nothing and the rowcount says so, which is the honest
+     * outcome — a graph we cannot read metadata for is one we must not deliver for.
+     *
+     * `workflowTaskTypeID` is REQUIRED rather than optional because this statement injects keys into
+     * a row's `InputPayload`. `MJ: Tasks` holds conversation tasks and users' own to-dos as well as
+     * workflow graphs; a mis-targeted claim would silently edit somebody's payload. Passing the
+     * discriminator is not a filter the caller may forget — it is the caller stating which family of
+     * task it believes it is writing to, and the statement refusing if it is wrong.
+     *
+     * @param deliveredAs how the settlement is being delivered, recorded alongside the marker so an
+     *                    expired settlement is distinguishable from a delivered one after the fact
+     * @returns true when this instance won the right to deliver
+     */
+    TryClaimContinuation(provider: IMetadataProvider, parentTaskID: string, deliveredAs: 'delivered' | 'expired' | 'cancelled', workflowTaskTypeID: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Skips one task, refusing if anything has taken it since the caller looked.
+     *
+     * **Why this cannot be a `Save()`** — and R3-1 is the proof that the earlier reasoning was wrong.
+     * The early-finish path skipped siblings with a full-row `BaseEntity.Save()` against a snapshot
+     * taken before the loop began, justified by "the siblings are Pending and unclaimed until the
+     * skip lands". They are not: `executeClaimed` is not awaited, so this instance's own next poll
+     * tick runs concurrently with the loop, and a sibling can be claimed and STARTED between the
+     * snapshot and its own write. The full-row save then overwrote `In Progress` back to `Skipped`
+     * and cleared `ClaimedBy` mid-execution — the agent's real side effects had already fired, its
+     * completion was refused by the claim guard, and its output was discarded. The graph settled
+     * `Complete` with no record anywhere that the step ran.
+     *
+     * **The status predicate is `Status='Pending'` alone, deliberately.** `TryClaim` moves a task
+     * to `In Progress` in the same statement that stamps `ClaimedBy`, so a task an executor holds is
+     * never `Pending` — the status IS the claim test. Adding `ClaimedBy IS NULL` would look like
+     * defence in depth and would instead break a real case: a notified human task carries a marker
+     * in `ClaimedBy` while still `Pending`, and those must stay skippable.
+     *
+     * **Type-scoped, like every other write in this store that a caller-supplied ID can reach.**
+     * `MJ: Tasks` also holds conversation tasks and users' personal to-dos; without the
+     * discriminator an operator verb pointed at a mis-derived (or hostile) ID could write `Skipped`
+     * onto somebody's to-do. The engine-internal caller (`endGraphEarly`) derives its IDs from a
+     * workflow parent's own children, but it pays the same predicate — one statement, one contract.
+     *
+     * @returns true when this call is the one that skipped it; false means something else got there
+     */
+    TrySkipPending(provider: IMetadataProvider, taskID: string, workflowTaskTypeID: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Stamps the human-notified marker, once, without touching anything else.
+     *
+     * The marker lives in `ClaimedBy` because a human task has no executor claim, and it exists to
+     * stop the notify path re-raising on every poll. It was written with a full-row `Save()` against
+     * a snapshot — so it could revert a status the row had reached since, and two instances could
+     * both write it after both having seen it absent. Guarded on the marker being unset, it is
+     * naturally once-only and the rowcount says which instance did it.
+     */
+    TryMarkHumanNotified(provider: IMetadataProvider, taskID: string, marker: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Cancels one task, refusing if it settled while the caller was looking elsewhere.
+     *
+     * **The terminal check has to be IN the statement.** `Cancel` loaded every child, tested the
+     * terminal set against that in-memory snapshot, and wrote `Status='Cancelled'` with a full-row
+     * `BaseEntity.Save()` — an unconditional UPDATE sending every updateable column against a
+     * PK-only predicate. A child whose executor's guarded `CompleteClaimed` landed between the load
+     * and its save had its entire outcome overwritten: `Complete` back to `Cancelled`,
+     * `OutputPayload` to NULL (the null-clear companions make those explicit clears),
+     * `AgentRunID`/`CompletedAt`/runtime `Configuration` reverted, and stale claim columns
+     * re-instated on a terminal row.
+     *
+     * The moment users cancel is exactly the moment tasks are running, so this is not a narrow
+     * window. The reverse ordering was always safe — `CompleteClaimed`'s own predicate refuses a
+     * cancelled row — so the hazard lived entirely in this write.
+     *
+     * @returns true when this call cancelled it; false means it had already settled
+     */
+    TryCancelTask(provider: IMetadataProvider, taskID: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Records, durably and once, that a graph is finishing early.
+     *
+     * **The declaration has to outlive the deciding instance's memory.** An early finish is decided
+     * by one task's result (`result.ChatMessage`) and nothing else in the system knows: skip seeds
+     * are derived from durable condition and exclusive-group state, so no claim filter on any
+     * instance — including the deciding one, whose poll loop runs concurrently — can tell that the
+     * remaining steps are about to be skipped. Writing it here first is what lets
+     * `loadGraphState` fold those steps into the claim filter, closing the window for everyone
+     * rather than narrowing it for one.
+     *
+     * Guarded and once-only for the same reason the continuation marker is: two tasks can end the
+     * same flow, and the first declaration is the one that counts. Type-scoped like every other
+     * statement here that writes into a payload column.
+     *
+     * @returns true when this call is the one that declared it
+     */
+    TryDeclareEarlyFinish(provider: IMetadataProvider, parentTaskID: string, workflowTaskTypeID: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Records why a graph ended early, writing that column and no other.
+     *
+     * The hazard is the one {@link TrySettleParent} exists for, reached by a different route. A task
+     * that ends the flow early skips its siblings, which makes the graph fully terminal — so another
+     * instance's very next poll can settle it and claim the continuation marker. The old code had
+     * already loaded the parent by then and finished with a full-row `Save()`, which would write back
+     * the pre-settle snapshot: status reverted to `In Progress`, marker gone, graph delivered twice.
+     *
+     * No status predicate here, unlike the other writes: the early-finish message is the truthful
+     * summary whether or not the graph has settled since, and two tasks ending the same flow both
+     * describe it correctly. The bug was never the value — it was the other columns riding along.
+     *
+     * Type-scoped for the same reason the claim is: every statement in this store that writes into a
+     * payload column states which family of task it means, so a mis-derived parent ID cannot edit a
+     * conversation task or somebody's to-do.
+     */
+    TrySetParentOutput(provider: IMetadataProvider, parentTaskID: string, outputPayload: string, workflowTaskTypeID: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Clears a graph's debug state entirely — the "stop debugging this run" write.
+     *
+     * Whole-bag, and safe to be: deleting `$.debug` is the one operation that genuinely owns every
+     * field in it. Every PARTIAL change goes through {@link TryWriteDebugFields}, because a
+     * read-merge-write of the whole bag puts back whatever the fields a verb does not own held at
+     * read time — most sharply resurrecting a step allowance the dispatcher consumed in between.
+     */
+    TryClearDebugState(provider: IMetadataProvider, parentTaskID: string, workflowTaskTypeID: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * One field of the debug bag, as a value the statement can write.
+     *
+     * Typed rather than a raw SQL fragment so a caller cannot inject one: the shape decides how the
+     * value is rendered, and every string goes through {@link escape}.
+     */
+    static DebugField(path: string, value: TaskGraphDebugFieldValue): TaskGraphDebugFieldWrite;
+    /**
+     * Writes named fields of a graph's debug bag, leaving every other field alone.
+     *
+     * **Why field-scoped rather than rewriting `$.debug`.** A read-merge-write of the whole bag is
+     * the same stale-snapshot hazard as a full-row save, one level down: a verb that reads the bag,
+     * merges its own change, and writes the result puts back whatever the fields it does NOT own
+     * held at read time. The sharp case is the step allowance — if the dispatcher consumes it
+     * between a `SetBreakpoints` read and its write, the rewrite *resurrects* the consumed
+     * allowance and one press of Step releases two waves, straight through the CAS that exists to
+     * prevent exactly that. Writing only the paths a verb owns removes the class rather than
+     * narrowing the window.
+     *
+     * Paths are nested `JSON_MODIFY` calls, so the whole set lands in one statement.
+     */
+    TryWriteDebugFields(provider: IMetadataProvider, parentTaskID: string, fields: readonly TaskGraphDebugFieldWrite[], workflowTaskTypeID: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Wraps a payload expression so every object CONTAINING one of these paths exists.
+     *
+     * `JSON_MODIFY` does not create intermediate objects: writing `$.debug.paused` into a payload
+     * with no `debug` key, or `$.debug.edgeOverrides."<id>"` with no override map yet, silently
+     * changes nothing — which for a control verb means the write reports success (rowcount 1, the
+     * row WAS updated, just not the way anyone meant) and the workflow never pauses. A graph only
+     * acquires a `debug` key the first time somebody debugs it, so this is the NORMAL first call,
+     * not an edge case.
+     *
+     * This hazard arrived WITH field-scoped writes and is the price of them: the whole-bag write
+     * they replaced targeted `$.debug`, one level down from a root that always exists, so it
+     * created the containing object as a side effect of every verb. Field-scoping is still the
+     * right trade — it removes the step-resurrection class outright — but it moves the
+     * container's existence from implicit to something this method has to guarantee.
+     *
+     * Each containing object is created only when absent, shallowest first, so an existing bag is
+     * never replaced.
+     */
+    private ensureObjects;
+    /** Renders one debug value as a SQL literal `JSON_MODIFY` will store with the right JSON type. */
+    private renderDebugValue;
+    /**
+     * Consumes a paused graph's one-shot step allowance — exactly once, across every instance.
+     *
+     * The predicate `$.debug.step IS NOT NULL` is the whole contract: two dispatchers polling the
+     * same paused graph inside one interval both see the allowance, but only one statement clears it
+     * and sees rowcount 1. The loser claims nothing and waits for the next allowance, so "step" can
+     * never release two waves.
+     */
+    TryConsumeStepMarker(provider: IMetadataProvider, parentTaskID: string, workflowTaskTypeID: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Pauses a graph because an eligible task hit a breakpoint — once, whichever instance sees it
+     * first.
+     *
+     * Guarded on "not already paused" so two instances arriving at the same breakpoint in the same
+     * interval produce one `BreakpointHit` announcement, not two. The graph's existing breakpoint
+     * list and edge overrides are untouched — only the pause fields are written.
+     *
+     * The `$.debug` object is created when absent, for the same reason the field-scoped writes need
+     * it: `JSON_MODIFY` will not create a missing container, so without this the pause would report
+     * success and the workflow would run straight through its breakpoint. Reachable here only since
+     * the writes became field-scoped — the whole-bag write this replaced created `$.debug` on the
+     * way past, so a breakpoint could not exist without its container already being there.
+     */
+    TryPauseAtBreakpoint(provider: IMetadataProvider, parentTaskID: string, breakpointTaskID: string, workflowTaskTypeID: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Replaces a task's input, guarded on the status the caller believes it is in.
+     *
+     * **Why this is a guarded statement and not `task.Save()`.** The obvious shape — load, check
+     * `Status === 'Pending'` in memory, save — is an unconditional full-row UPDATE carrying the
+     * whole loaded snapshot. A task claimed between the load and the save has its `Status`,
+     * `ClaimedBy` and `ClaimExpiresAt` reverted to that snapshot *while its body executes*, after
+     * which a second instance claims it again and the step runs twice. That is the stale-snapshot
+     * class this file's header exists to prevent, and it does not become safe because the window is
+     * small — the dispatcher polls every few seconds.
+     *
+     * `expectedStatus` is a parameter because two verbs need it: editing the brief of a step that
+     * has not started (`Pending`) and correcting the brief of one that failed, on the way into a
+     * retry (`Failed`).
+     */
+    TryUpdateInputPayload(provider: IMetadataProvider, taskID: string, inputPayload: string | null, expectedStatus: 'Pending' | 'Failed', workflowTaskTypeID: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Marks a task Complete with an operator-supplied output — the escape hatch for a wedged or
+     * externally-resolved step.
+     *
+     * The guard is deliberately narrow: `Pending`, `Failed`, `Blocked`, or `In Progress` **with a
+     * lapsed claim**. A live claim means an executor is genuinely working, and force-completing
+     * underneath it would hand dependents an output the still-running body is about to contradict —
+     * that case must go through Cancel or wait for the claim to lapse. Downstream edges evaluate
+     * against the supplied output exactly as they would a runner's.
+     *
+     * **The lapsed-claim test uses the DATABASE clock, not this process's.** With app/DB skew — or
+     * skew between two app servers — a claim that is live on the clock that wrote it can read as
+     * expired on the clock that judges it, and this verb would then complete a task underneath a
+     * running executor. That interleaving is the entire reason the gate is narrow, so the gate must
+     * not be the thing that gets it wrong. The database is the one reference every instance shares.
+     * (This verb once carried a residual asymmetry — it *judged* on the database clock while
+     * `TryClaim` still *wrote* the lease from the claiming process's clock, trading app-vs-app skew
+     * for app-vs-DB skew. The claim protocol has since moved its write to `SYSUTCDATETIME()` as
+     * well, so both ends of the comparison now come from the one shared clock and the window is
+     * closed rather than relocated.)
+     */
+    TryForceComplete(provider: IMetadataProvider, taskID: string, outputPayload: string | null, workflowTaskTypeID: string, contextUser: UserInfo): Promise<boolean>;
     /** Runs the affected-rows statement, returning 0 on error rather than throwing into the loop. */
     private affectedRows;
     private literalOrNull;