agentic-qe 3.15.8 → 3.15.9

package/dist/coordination/task-dag/dag.d.ts

@@ -5,8 +5,13 @@
  * Directed acyclic graph where nodes are tasks and edges represent
  * "blocked-by" dependencies. Topological sort via Kahn's algorithm,
  * cycle detection via DFS coloring, critical path via longest-path DP.
+ *
+ * Issue #1069: every prerequisite edge carries a typed disposition backed
+ * by an immutable PrerequisiteReceiptV1. A dependent becomes ready only
+ * when every edge is SATISFIED or WAIVED. Removing an unfinished
+ * prerequisite leaves a REMOVED tombstone and keeps dependents blocked.
  */
-import type { DAGTask, AddTaskInput, DAGStats, DAGEventHandler } from './types.js';
+import type { DAGTask, AddTaskInput, DAGStats, DAGSnapshot, DAGEventHandler, CompleteTaskOptions, ObligationSummary, PrerequisiteEdgeState, PrerequisiteReceiptV1, RemovedTaskRecord, RemoveTaskOptions, TaskDAGOptions, WaivePrerequisiteInput } from './types.js';
 /**
  * Directed acyclic graph for task dependency management.
  *
@@ -18,17 +23,30 @@ export declare class TaskDAG {
     private readonly forwardEdges;
     private readonly reverseEdges;
     private readonly eventHandlers;
+    private readonly ledger;
+    private readonly waiverPolicy?;
+    constructor(options?: TaskDAGOptions);
+    /** Stable identity of this graph, stamped on every receipt. */
+    get graphId(): string;
+    /** Monotonically increasing revision; advances on every mutation. */
+    get graphRevision(): number;
     /**
-     * Add a task to the DAG. Status is 'ready' if no incomplete blockers,
-     * otherwise 'blocked'. Reverse edges are computed automatically.
+     * Add a task to the DAG. Status is 'ready' if every prerequisite is
+     * SATISFIED, otherwise 'blocked'. Prerequisites not yet in the graph are
+     * recorded as MISSING until they are added.
      * @throws Error if a task with the same ID already exists
      */
     addTask(input: AddTaskInput): DAGTask;
     /**
-     * Remove a task, clean up edges, and unblock dependents if appropriate.
+     * Remove a task. A lifecycle operation, not an obligation resolution:
+     * dependents keep the edge. An unfinished task's unresolved dependent
+     * edges become REMOVED and dependents stay blocked until it is re-added
+     * and completed, or the edge is waived. SATISFIED edges survive removal,
+     * and the task stays in the obligation denominator as a tombstone.
      * @returns true if removed, false if not found
+     * @throws GraphRevisionConflictError if options.expectedRevision is stale
      */
-    removeTask(taskId: string): boolean;
+    removeTask(taskId: string, options?: RemoveTaskOptions): boolean;
     /** Get a task by ID. */
     getTask(taskId: string): DAGTask | undefined;
     /** Get all tasks with 'ready' status. */
@@ -39,16 +57,48 @@ export declare class TaskDAG {
      */
     start(taskId: string, agentId: string): void;
     /**
-     * Mark a task completed and unblock downstream tasks.
+     * Mark a task completed, record SATISFIED on its dependent edges, and
+     * unblock dependents whose edges are all SATISFIED or WAIVED.
      * @returns Array of newly unblocked task IDs
      * @throws Error if task not found or not 'in_progress'
+     * @throws GraphRevisionConflictError if options.expectedRevision is stale
      */
-    complete(taskId: string, result?: unknown): string[];
+    complete(taskId: string, result?: unknown, options?: CompleteTaskOptions): string[];
     /**
-     * Mark a task failed and cascade cancellation to dependents.
+     * Mark a task failed, record FAILED on its unresolved dependent edges,
+     * and cascade cancellation to dependents.
      * @throws Error if task not found or not in 'in_progress'/'ready'
      */
     fail(taskId: string, error: string): void;
+    /**
+     * Cancel a non-terminal task, record CANCELLED on its unresolved
+     * dependent edges, and cascade cancellation to dependents.
+     * @throws Error if task not found or already terminal
+     */
+    cancel(taskId: string, reason: string): void;
+    /**
+     * Explicitly waive one prerequisite edge. This is the only way a
+     * dependent becomes ready without a SATISFIED receipt. The original edge
+     * is kept and a WAIVED receipt carries actor, reason, authority and time.
+     * @returns The WAIVED receipt
+     * @throws PrerequisiteWaiverError on invalid input, unknown edge,
+     *   already-resolved edge, terminal dependent, or policy rejection
+     * @throws GraphRevisionConflictError if expectedRevision is stale
+     */
+    waivePrerequisite(input: WaivePrerequisiteInput): PrerequisiteReceiptV1;
+    /** Current disposition of every prerequisite edge of a task. */
+    getPrerequisiteDispositions(taskId: string): PrerequisiteEdgeState[];
+    /** Prerequisite edges that currently prevent a task from being ready. */
+    getBlockers(taskId: string): PrerequisiteEdgeState[];
+    /** Append-only receipt log, optionally filtered by dependent or prerequisite. */
+    getReceipts(filter?: {
+        taskId?: string;
+        prerequisiteId?: string;
+    }): PrerequisiteReceiptV1[];
+    /** Tombstones for tasks removed from the graph. */
+    getRemovedTasks(): RemovedTaskRecord[];
+    /** Obligation accounting against the original task denominator. */
+    getObligationSummary(): ObligationSummary;
     /**
      * Topological sort using Kahn's algorithm.
      * @throws Error if cycles exist
@@ -66,28 +116,28 @@ export declare class TaskDAG {
     getCriticalPath(): DAGTask[];
     /** Get aggregate statistics about the DAG. */
     getStats(): DAGStats;
-    /** Remove all tasks from the DAG. */
+    /**
+     * Remove all tasks, receipts and tombstones from the DAG. The graph
+     * revision keeps increasing so stale expectedRevision guards still fail.
+     */
     clear(): void;
-    /** Serialize the DAG for debugging. */
-    toJSON(): {
-        tasks: DAGTask[];
-        edges: Array<{
-            from: string;
-            to: string;
-        }>;
-        stats: DAGStats;
-    };
+    /** Serialize the DAG, its receipt log and tombstones. */
+    toJSON(): DAGSnapshot;
     /**
      * Register a handler to receive DAG events.
      * @returns Unsubscribe function
      */
     onEvent(handler: DAGEventHandler): () => void;
+    private graphView;
     private requireTask;
     private computeStatus;
     private setStatus;
+    /** Commit a failed/cancelled outcome and propagate it to dependent edges. */
+    private terminate;
+    /** Record a disposition on every live dependent edge currently in `from`. */
+    private recordOnDependents;
     private unblockDependents;
     private cascadeCancellation;
-    private dfsCycles;
     private emit;
 }
 //# sourceMappingURL=dag.d.ts.map