agentic-qe 3.15.8 → 3.15.10

package/dist/coordination/task-dag/dag.js

@@ -5,14 +5,16 @@
  * 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.
  */
-/** DFS node coloring for cycle detection */
-var NodeColor;
-(function (NodeColor) {
-    NodeColor[NodeColor["White"] = 0] = "White";
-    NodeColor[NodeColor["Gray"] = 1] = "Gray";
-    NodeColor[NodeColor["Black"] = 2] = "Black";
-})(NodeColor || (NodeColor = {}));
+import { randomUUID } from 'node:crypto';
+import { criticalPath, findCycles, topologicalSort } from './dag-algorithms.js';
+import { PrerequisiteLedger, TERMINAL_STATUSES as TERMINAL, validateWaiverInput } from './prerequisite-ledger.js';
+import { authorizeWaiver, countStatuses, initialDisposition } from './dag-obligations.js';
 /**
  * Directed acyclic graph for task dependency management.
  *
@@ -24,15 +26,31 @@ export class TaskDAG {
     forwardEdges = new Map();
     reverseEdges = new Map();
     eventHandlers = [];
+    ledger;
+    waiverPolicy;
+    constructor(options = {}) {
+        this.ledger = new PrerequisiteLedger(options.graphId ?? `dag-${randomUUID()}`);
+        this.waiverPolicy = options.waiverPolicy;
+    }
+    /** Stable identity of this graph, stamped on every receipt. */
+    get graphId() {
+        return this.ledger.graphId;
+    }
+    /** Monotonically increasing revision; advances on every mutation. */
+    get graphRevision() {
+        return this.ledger.graphRevision;
+    }
     /**
-     * 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) {
         if (this.nodes.has(input.id)) {
             throw new Error(`Task '${input.id}' already exists in the DAG`);
         }
+        this.ledger.bump();
         const blockedBy = input.blockedBy ?? [];
         this.forwardEdges.set(input.id, new Set(blockedBy));
         if (!this.reverseEdges.has(input.id)) {
@@ -44,14 +62,23 @@ export class TaskDAG {
             }
             this.reverseEdges.get(blockerId).add(input.id);
         }
-        // Blocks array: tasks already in graph that depend on this one
+        this.ledger.addObligation(input.id);
+        for (const blockerId of new Set(blockedBy)) {
+            const blocker = this.nodes.get(blockerId);
+            this.ledger.record(input.id, blockerId, initialDisposition(blocker, this.ledger.isTombstoned(blockerId)), {
+                completionEvidenceRef: blocker?.status === 'completed' ? blocker.evidenceRef : undefined,
+            });
+        }
+        // Blocks array: tasks already in graph that depend on this one.
+        // Their MISSING/REMOVED edges are now materialized as UNRESOLVED.
         const blocks = [];
-        const existingDeps = this.reverseEdges.get(input.id);
-        if (existingDeps) {
-            for (const depId of existingDeps)
-                blocks.push(depId);
+        for (const depId of this.reverseEdges.get(input.id) ?? []) {
+            blocks.push(depId);
+            const d = this.ledger.disposition(depId, input.id);
+            if (d === 'MISSING' || d === 'REMOVED')
+                this.ledger.record(depId, input.id, 'UNRESOLVED');
         }
-        const status = this.computeStatus(blockedBy);
+        const status = this.computeStatus(input.id);
         const task = {
             id: input.id,
             name: input.name,
@@ -77,54 +104,43 @@ export class TaskDAG {
         return task;
     }
     /**
-     * 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) {
-        if (!this.nodes.has(taskId))
+    removeTask(taskId, options = {}) {
+        const task = this.nodes.get(taskId);
+        if (!task)
             return false;
-        // Detach from blockers
-        const forward = this.forwardEdges.get(taskId);
-        if (forward) {
-            for (const blockerId of forward) {
-                this.reverseEdges.get(blockerId)?.delete(taskId);
-                const blocker = this.nodes.get(blockerId);
-                if (blocker) {
-                    this.nodes.set(blockerId, {
-                        ...blocker,
-                        blocks: blocker.blocks.filter((id) => id !== taskId),
-                    });
-                }
-            }
-        }
-        // Detach from dependents and check for unblocking
-        const reverse = this.reverseEdges.get(taskId);
-        const unblockedIds = [];
-        if (reverse) {
-            for (const depId of reverse) {
-                this.forwardEdges.get(depId)?.delete(taskId);
-                const dep = this.nodes.get(depId);
-                if (dep) {
-                    this.nodes.set(depId, {
-                        ...dep,
-                        blockedBy: dep.blockedBy.filter((id) => id !== taskId),
-                    });
-                }
-                const updated = this.nodes.get(depId);
-                if (updated && (updated.status === 'blocked' || updated.status === 'pending')) {
-                    if (this.computeStatus(Array.from(this.forwardEdges.get(depId) ?? [])) === 'ready') {
-                        this.setStatus(depId, 'ready');
-                        unblockedIds.push(depId);
-                    }
+        this.ledger.checkRevision(options.expectedRevision);
+        const revision = this.ledger.bump();
+        // Detach the removed node's own edges to its blockers
+        for (const blockerId of this.forwardEdges.get(taskId) ?? []) {
+            this.reverseEdges.get(blockerId)?.delete(taskId);
+            const blocker = this.nodes.get(blockerId);
+            if (blocker)
+                this.nodes.set(blockerId, { ...blocker, blocks: blocker.blocks.filter((id) => id !== taskId) });
+        }
+        this.ledger.dropEdgesOf(taskId);
+        // Fail closed: dependents keep the edge; unfinished work becomes REMOVED
+        const affected = [];
+        if (task.status !== 'completed') {
+            for (const depId of this.reverseEdges.get(taskId) ?? []) {
+                if (this.nodes.has(depId) && this.ledger.disposition(depId, taskId) === 'UNRESOLVED') {
+                    this.ledger.record(depId, taskId, 'REMOVED');
+                    affected.push(depId);
                 }
             }
         }
+        this.ledger.tombstone(taskId, task.status);
         this.forwardEdges.delete(taskId);
-        this.reverseEdges.delete(taskId);
         this.nodes.delete(taskId);
-        if (unblockedIds.length > 0) {
-            this.emit({ type: 'tasks-unblocked', unblockedTaskIds: unblockedIds, timestamp: Date.now() });
-        }
+        // reverseEdges[taskId] is kept so dependents stay linked to the tombstone
+        this.emit({ type: 'task-removed', taskId, affectedTaskIds: affected, graphRevision: revision, timestamp: Date.now() });
         return true;
     }
     /** Get a task by ID. */
@@ -149,6 +165,7 @@ export class TaskDAG {
         if (task.status !== 'ready') {
             throw new Error(`Cannot start '${taskId}': status '${task.status}', expected 'ready'`);
         }
+        this.ledger.bump();
         this.nodes.set(taskId, {
             ...task,
             status: 'in_progress',
@@ -157,18 +174,27 @@ export class TaskDAG {
         });
     }
     /**
-     * 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, result) {
+    complete(taskId, result, options = {}) {
         const task = this.requireTask(taskId);
         if (task.status !== 'in_progress') {
             throw new Error(`Cannot complete '${taskId}': status '${task.status}', expected 'in_progress'`);
         }
+        const evidenceRef = options.evidenceRef;
+        if (evidenceRef !== undefined && (typeof evidenceRef !== 'string' || evidenceRef.trim() === '')) {
+            throw new Error(`Cannot complete '${taskId}': evidenceRef must be a non-empty string`);
+        }
+        this.ledger.checkRevision(options.expectedRevision);
+        this.ledger.bump();
         const now = Date.now();
-        this.nodes.set(taskId, { ...task, status: 'completed', completedAt: now, result });
+        this.nodes.set(taskId, { ...task, status: 'completed', completedAt: now, result, evidenceRef });
         this.emit({ type: 'task-completed', taskId, timestamp: now });
+        this.recordOnDependents(taskId, 'SATISFIED', ['UNRESOLVED', 'WAIVED'], evidenceRef);
         const unblockedIds = this.unblockDependents(taskId);
         if (unblockedIds.length > 0) {
             this.emit({ type: 'tasks-unblocked', unblockedTaskIds: unblockedIds, timestamp: Date.now() });
@@ -176,7 +202,8 @@ export class TaskDAG {
         return unblockedIds;
     }
     /**
-     * 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, error) {
@@ -184,71 +211,88 @@ export class TaskDAG {
         if (task.status !== 'in_progress' && task.status !== 'ready') {
             throw new Error(`Cannot fail '${taskId}': status '${task.status}', expected 'in_progress' or 'ready'`);
         }
-        const now = Date.now();
-        this.nodes.set(taskId, { ...task, status: 'failed', completedAt: now, error });
-        this.emit({ type: 'task-failed', taskId, timestamp: now });
-        this.cascadeCancellation(taskId);
+        this.terminate(task, 'failed', error);
+    }
+    /**
+     * 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, reason) {
+        const task = this.requireTask(taskId);
+        if (TERMINAL.has(task.status)) {
+            throw new Error(`Cannot cancel '${taskId}': status '${task.status}' is terminal`);
+        }
+        this.terminate(task, 'cancelled', reason);
+    }
+    /**
+     * 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) {
+        const req = validateWaiverInput(input);
+        const task = this.nodes.get(req.taskId);
+        const baseRevision = this.ledger.graphRevision;
+        authorizeWaiver(this.ledger, this.waiverPolicy, req, task, this.forwardEdges.get(req.taskId));
+        // A policy that mutated the graph invalidates the decision it just made
+        this.ledger.checkRevision(baseRevision);
+        const revision = this.ledger.bump();
+        const receipt = this.ledger.record(req.taskId, req.prerequisiteId, 'WAIVED', {
+            waiver: {
+                actor: req.actor,
+                reason: req.reason,
+                ...(req.authorityRef !== undefined ? { authorityRef: req.authorityRef } : {}),
+                issuedAt: new Date().toISOString(),
+            },
+        });
+        const { taskId, prerequisiteId } = req;
+        this.emit({ type: 'prerequisite-waived', taskId, prerequisiteId, graphRevision: revision, timestamp: Date.now() });
+        // Re-read: an event handler may have changed the task (e.g. cancelled it)
+        const latest = this.nodes.get(taskId);
+        if ((latest?.status === 'blocked' || latest?.status === 'pending') && this.computeStatus(taskId) === 'ready') {
+            this.setStatus(taskId, 'ready');
+            this.emit({ type: 'tasks-unblocked', unblockedTaskIds: [taskId], timestamp: Date.now() });
+        }
+        return receipt;
+    }
+    /** Current disposition of every prerequisite edge of a task. */
+    getPrerequisiteDispositions(taskId) {
+        return this.ledger.edgesOf(taskId, this.forwardEdges.get(taskId) ?? []);
+    }
+    /** Prerequisite edges that currently prevent a task from being ready. */
+    getBlockers(taskId) {
+        return this.getPrerequisiteDispositions(taskId).filter((e) => e.disposition !== 'SATISFIED' && e.disposition !== 'WAIVED');
+    }
+    /** Append-only receipt log, optionally filtered by dependent or prerequisite. */
+    getReceipts(filter) {
+        return this.ledger.receipts(filter);
+    }
+    /** Tombstones for tasks removed from the graph. */
+    getRemovedTasks() {
+        return this.ledger.removedTasks();
+    }
+    /** Obligation accounting against the original task denominator. */
+    getObligationSummary() {
+        return this.ledger.summarize(this.nodes.values());
     }
     /**
      * Topological sort using Kahn's algorithm.
      * @throws Error if cycles exist
      */
     topologicalSort() {
-        const inDegree = new Map();
-        for (const nodeId of this.nodes.keys()) {
-            let count = 0;
-            const fwd = this.forwardEdges.get(nodeId);
-            if (fwd) {
-                for (const dep of fwd) {
-                    if (this.nodes.has(dep))
-                        count++;
-                }
-            }
-            inDegree.set(nodeId, count);
-        }
-        const queue = [];
-        for (const [id, deg] of inDegree) {
-            if (deg === 0)
-                queue.push(id);
-        }
-        const sorted = [];
-        while (queue.length > 0) {
-            const nodeId = queue.shift();
-            const task = this.nodes.get(nodeId);
-            if (task)
-                sorted.push(task);
-            const dependents = this.reverseEdges.get(nodeId);
-            if (dependents) {
-                for (const depId of dependents) {
-                    if (!this.nodes.has(depId))
-                        continue;
-                    const newDeg = (inDegree.get(depId) ?? 0) - 1;
-                    inDegree.set(depId, newDeg);
-                    if (newDeg === 0)
-                        queue.push(depId);
-                }
-            }
-        }
-        if (sorted.length !== this.nodes.size) {
-            throw new Error(`Cycle detected: sorted ${sorted.length} of ${this.nodes.size} tasks`);
-        }
-        return sorted;
+        return topologicalSort(this.graphView());
     }
     /**
      * Detect cycles using DFS with white/gray/black coloring.
      * @returns Array of cycles, or null if acyclic
      */
     detectCycles() {
-        const color = new Map();
-        const parent = new Map();
-        const cycles = [];
-        for (const id of this.nodes.keys())
-            color.set(id, NodeColor.White);
-        for (const id of this.nodes.keys()) {
-            if (color.get(id) === NodeColor.White) {
-                this.dfsCycles(id, color, parent, cycles);
-            }
-        }
+        const cycles = findCycles(this.graphView());
         if (cycles.length === 0)
             return null;
         this.emit({ type: 'cycle-detected', cycleNodes: cycles.flat(), timestamp: Date.now() });
@@ -259,98 +303,29 @@ export class TaskDAG {
      * @returns Tasks on the critical path in execution order
      */
     getCriticalPath() {
-        if (this.nodes.size === 0)
-            return [];
-        let sorted;
-        try {
-            sorted = this.topologicalSort();
-        }
-        catch {
-            return [];
-        }
-        const dist = new Map();
-        const pred = new Map();
-        for (const t of sorted) {
-            dist.set(t.id, 1);
-            pred.set(t.id, null);
-        }
-        for (const task of sorted) {
-            const d = dist.get(task.id);
-            const deps = this.reverseEdges.get(task.id);
-            if (deps) {
-                for (const depId of deps) {
-                    if (!this.nodes.has(depId))
-                        continue;
-                    if (d + 1 > (dist.get(depId) ?? 1)) {
-                        dist.set(depId, d + 1);
-                        pred.set(depId, task.id);
-                    }
-                }
-            }
-        }
-        let maxDist = 0;
-        let endNode = null;
-        for (const [id, d] of dist) {
-            if (d > maxDist) {
-                maxDist = d;
-                endNode = id;
-            }
-        }
-        if (!endNode)
-            return [];
-        const path = [];
-        let cur = endNode;
-        while (cur !== null) {
-            const t = this.nodes.get(cur);
-            if (t)
-                path.unshift(t);
-            cur = pred.get(cur) ?? null;
-        }
-        return path;
+        return criticalPath(this.graphView());
     }
     /** Get aggregate statistics about the DAG. */
     getStats() {
-        let pending = 0, ready = 0, inProgress = 0, completed = 0;
-        let failed = 0, blocked = 0, cancelled = 0;
-        for (const task of this.nodes.values()) {
-            switch (task.status) {
-                case 'pending':
-                    pending++;
-                    break;
-                case 'ready':
-                    ready++;
-                    break;
-                case 'in_progress':
-                    inProgress++;
-                    break;
-                case 'completed':
-                    completed++;
-                    break;
-                case 'failed':
-                    failed++;
-                    break;
-                case 'blocked':
-                    blocked++;
-                    break;
-                case 'cancelled':
-                    cancelled++;
-                    break;
-            }
-        }
         return {
             totalTasks: this.nodes.size,
-            pending, ready, inProgress, completed, failed, blocked, cancelled,
+            ...countStatuses(this.nodes.values()),
             longestPath: this.getCriticalPath().length,
             hasCycles: this.detectCycles() !== null,
         };
     }
-    /** 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() {
+        this.ledger.bump();
         this.nodes.clear();
         this.forwardEdges.clear();
         this.reverseEdges.clear();
+        this.ledger.reset();
     }
-    /** Serialize the DAG for debugging. */
+    /** Serialize the DAG, its receipt log and tombstones. */
     toJSON() {
         const tasks = Array.from(this.nodes.values());
         const edges = [];
@@ -358,7 +333,15 @@ export class TaskDAG {
             for (const depId of deps)
                 edges.push({ from: depId, to: taskId });
         }
-        return { tasks, edges, stats: this.getStats() };
+        return {
+            graphId: this.graphId,
+            graphRevision: this.graphRevision,
+            tasks,
+            edges,
+            receipts: this.ledger.receipts(),
+            removedTasks: this.ledger.removedTasks(),
+            stats: this.getStats(),
+        };
     }
     /**
      * Register a handler to receive DAG events.
@@ -373,21 +356,20 @@ export class TaskDAG {
         };
     }
     // --- Internal helpers ---
+    graphView() {
+        return { nodes: this.nodes, forwardEdges: this.forwardEdges, reverseEdges: this.reverseEdges };
+    }
     requireTask(taskId) {
         const task = this.nodes.get(taskId);
         if (!task)
             throw new Error(`Task '${taskId}' not found in the DAG`);
         return task;
     }
-    computeStatus(blockerIds) {
-        if (blockerIds.length === 0)
+    computeStatus(taskId) {
+        const blockers = this.forwardEdges.get(taskId);
+        if (!blockers || blockers.size === 0)
             return 'ready';
-        for (const id of blockerIds) {
-            const b = this.nodes.get(id);
-            if (!b || b.status !== 'completed')
-                return 'blocked';
-        }
-        return 'ready';
+        return this.ledger.allResolved(taskId, blockers) ? 'ready' : 'blocked';
     }
     setStatus(taskId, status) {
         const task = this.nodes.get(taskId);
@@ -398,91 +380,55 @@ export class TaskDAG {
             this.emit({ type: 'task-ready', taskId, timestamp: Date.now() });
         }
     }
+    /** Commit a failed/cancelled outcome and propagate it to dependent edges. */
+    terminate(task, status, error) {
+        this.ledger.bump();
+        const now = Date.now();
+        this.nodes.set(task.id, { ...task, status, completedAt: now, error });
+        this.emit({ type: status === 'failed' ? 'task-failed' : 'task-cancelled', taskId: task.id, timestamp: now });
+        this.recordOnDependents(task.id, status === 'failed' ? 'FAILED' : 'CANCELLED', ['UNRESOLVED']);
+        this.cascadeCancellation(task.id, status);
+    }
+    /** Record a disposition on every live dependent edge currently in `from`. */
+    recordOnDependents(prerequisiteId, disposition, from, completionEvidenceRef) {
+        for (const depId of this.reverseEdges.get(prerequisiteId) ?? []) {
+            if (!this.nodes.has(depId))
+                continue;
+            const current = this.ledger.disposition(depId, prerequisiteId);
+            if (current && from.includes(current)) {
+                this.ledger.record(depId, prerequisiteId, disposition, { completionEvidenceRef });
+            }
+        }
+    }
     unblockDependents(completedId) {
         const unblockedIds = [];
-        const deps = this.reverseEdges.get(completedId);
-        if (!deps)
-            return unblockedIds;
-        for (const depId of deps) {
+        for (const depId of this.reverseEdges.get(completedId) ?? []) {
             const dep = this.nodes.get(depId);
             if (!dep || dep.status !== 'blocked')
                 continue;
-            const fwd = this.forwardEdges.get(depId);
-            if (!fwd)
-                continue;
-            let allDone = true;
-            for (const bId of fwd) {
-                const b = this.nodes.get(bId);
-                if (!b || b.status !== 'completed') {
-                    allDone = false;
-                    break;
-                }
-            }
-            if (allDone) {
+            if (this.computeStatus(depId) === 'ready') {
                 this.setStatus(depId, 'ready');
                 unblockedIds.push(depId);
             }
         }
         return unblockedIds;
     }
-    cascadeCancellation(failedId) {
-        const deps = this.reverseEdges.get(failedId);
-        if (!deps)
-            return;
-        for (const depId of deps) {
+    cascadeCancellation(sourceId, outcome) {
+        for (const depId of this.reverseEdges.get(sourceId) ?? []) {
             const dep = this.nodes.get(depId);
-            if (!dep || dep.status === 'completed' || dep.status === 'failed' || dep.status === 'cancelled') {
+            if (!dep || TERMINAL.has(dep.status))
                 continue;
-            }
-            const fwd = this.forwardEdges.get(depId);
-            if (!fwd)
+            if (!this.ledger.hasAny(depId, ['FAILED', 'CANCELLED']))
                 continue;
-            let unsatisfiable = false;
-            for (const bId of fwd) {
-                const b = this.nodes.get(bId);
-                if (b && (b.status === 'failed' || b.status === 'cancelled')) {
-                    unsatisfiable = true;
-                    break;
-                }
-            }
-            if (unsatisfiable) {
-                this.nodes.set(depId, {
-                    ...dep,
-                    status: 'cancelled',
-                    completedAt: Date.now(),
-                    error: `Cancelled: upstream task '${failedId}' failed`,
-                });
-                this.cascadeCancellation(depId);
-            }
-        }
-    }
-    dfsCycles(nodeId, color, parent, cycles) {
-        color.set(nodeId, NodeColor.Gray);
-        const dependencies = this.forwardEdges.get(nodeId);
-        if (dependencies) {
-            for (const depId of dependencies) {
-                if (!this.nodes.has(depId))
-                    continue;
-                const c = color.get(depId);
-                if (c === NodeColor.White) {
-                    parent.set(depId, nodeId);
-                    this.dfsCycles(depId, color, parent, cycles);
-                }
-                else if (c === NodeColor.Gray) {
-                    const cycle = [depId, nodeId];
-                    let cur = nodeId;
-                    while (cur !== depId) {
-                        const p = parent.get(cur);
-                        if (p === null || p === undefined || p === depId)
-                            break;
-                        cycle.push(p);
-                        cur = p;
-                    }
-                    cycles.push(cycle);
-                }
-            }
+            this.nodes.set(depId, {
+                ...dep,
+                status: 'cancelled',
+                completedAt: Date.now(),
+                error: `Cancelled: upstream task '${sourceId}' ${outcome}`,
+            });
+            this.recordOnDependents(depId, 'CANCELLED', ['UNRESOLVED']);
+            this.cascadeCancellation(depId, 'cancelled');
         }
-        color.set(nodeId, NodeColor.Black);
     }
     emit(event) {
         for (const handler of this.eventHandlers) {

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

@@ -28,21 +28,29 @@
  * const unblocked = scheduler.onTaskComplete('build'); // test may now be ready
  *
  * // Check progress
- * const progress = scheduler.getProgress(); // { completed: 1, total: 4, percentage: 25 }
+ * const progress = scheduler.getProgress(); // { completed: 1, total: 4, percentage: 25, ... }
+ *
+ * // Prerequisites are never resolved by deletion (issue #1069): removing
+ * // unfinished work leaves dependents blocked with a REMOVED receipt.
+ * // An explicit, attributed waiver is the only bypass.
+ * dag.waivePrerequisite({ taskId: 'deploy', prerequisiteId: 'lint', actor: 'release-lead', reason: 'lint gate retired' });
  * ```
  */
-export type { DAGTaskStatus, DAGTask, AddTaskInput, DAGStats, DAGEventType, DAGEvent, DAGSchedulerConfig, DAGEventHandler, } from './types.js';
+export type { DAGTaskStatus, DAGTask, AddTaskInput, DAGStats, DAGEventType, DAGEvent, DAGSchedulerConfig, DAGEventHandler, PrerequisiteDisposition, PrerequisiteWaiver, PrerequisiteReceiptV1, PrerequisiteEdgeState, WaivePrerequisiteInput, WaiverRequest, WaiverPolicy, TaskDAGOptions, CompleteTaskOptions, RemoveTaskOptions, RemovedTaskRecord, ObligationSummary, DAGProgress, } from './types.js';
+export { PREREQUISITE_RECEIPT_SCHEMA } from './types.js';
 export { TaskDAG } from './dag.js';
 export { DAGScheduler } from './scheduler.js';
+export { GraphRevisionConflictError, PrerequisiteWaiverError, validateWaiverInput, } from './prerequisite-ledger.js';
 import { TaskDAG } from './dag.js';
 import { DAGScheduler } from './scheduler.js';
-import type { DAGSchedulerConfig } from './types.js';
+import type { DAGSchedulerConfig, TaskDAGOptions } from './types.js';
 /**
  * Create a new empty TaskDAG instance.
  *
+ * @param options - Optional graph identity and waiver policy
  * @returns A fresh TaskDAG with no tasks
  */
-export declare function createTaskDAG(): TaskDAG;
+export declare function createTaskDAG(options?: TaskDAGOptions): TaskDAG;
 /**
  * Create a new DAGScheduler wrapping a TaskDAG.
  *