agentic-qe 3.15.8 → 3.15.9

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

@@ -28,14 +28,21 @@
  * 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 { PREREQUISITE_RECEIPT_SCHEMA } from './types.js';
 // ============================================================================
 // Class Exports
 // ============================================================================
 export { TaskDAG } from './dag.js';
 export { DAGScheduler } from './scheduler.js';
+export { GraphRevisionConflictError, PrerequisiteWaiverError, validateWaiverInput, } from './prerequisite-ledger.js';
 // ============================================================================
 // Factory Functions
 // ============================================================================
@@ -44,10 +51,11 @@ import { DAGScheduler } from './scheduler.js';
 /**
  * Create a new empty TaskDAG instance.
  *
+ * @param options - Optional graph identity and waiver policy
  * @returns A fresh TaskDAG with no tasks
  */
-export function createTaskDAG() {
-    return new TaskDAG();
+export function createTaskDAG(options) {
+    return new TaskDAG(options);
 }
 /**
  * Create a new DAGScheduler wrapping a TaskDAG.

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

@@ -0,0 +1,84 @@
+/**
+ * Agentic QE v3 - Prerequisite Ledger
+ * Issue #1069: typed prerequisite dispositions and receipts for TaskDAG
+ *
+ * Holds the graph identity, the monotonically increasing graph revision,
+ * the current disposition of every prerequisite edge, an append-only log
+ * of PrerequisiteReceiptV1 records, and tombstones for removed tasks so the
+ * original obligation denominator survives node removal.
+ */
+import { type DAGTask, type DAGTaskStatus, type ObligationSummary, type PrerequisiteDisposition, type PrerequisiteEdgeState, type PrerequisiteReceiptV1, type PrerequisiteWaiver, type RemovedTaskRecord, type WaivePrerequisiteInput } from './types.js';
+/** Task statuses that end execution */
+export declare const TERMINAL_STATUSES: ReadonlySet<DAGTaskStatus>;
+/** Thrown when an operation's expectedRevision does not match the graph */
+export declare class GraphRevisionConflictError extends Error {
+    readonly expectedRevision: number;
+    readonly actualRevision: number;
+    constructor(expectedRevision: number, actualRevision: number);
+}
+/** Thrown when a waiver request is invalid or rejected by policy */
+export declare class PrerequisiteWaiverError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a waiver request at the API boundary.
+ * @returns The normalized (trimmed) request
+ * @throws PrerequisiteWaiverError on missing or malformed fields
+ */
+export declare function validateWaiverInput(input: WaivePrerequisiteInput): WaivePrerequisiteInput;
+/** Extra fields attached to a receipt */
+interface ReceiptDetails {
+    readonly completionEvidenceRef?: string;
+    readonly waiver?: PrerequisiteWaiver;
+}
+/**
+ * Ledger of prerequisite edge dispositions for one TaskDAG.
+ * Receipts are frozen and never rewritten; the latest receipt per edge
+ * is the edge's current disposition.
+ */
+export declare class PrerequisiteLedger {
+    readonly graphId: string;
+    private revision;
+    private readonly current;
+    private readonly log;
+    private readonly tombstones;
+    private readonly obligations;
+    constructor(graphId: string);
+    /** Current graph revision (0 for a fresh graph) */
+    get graphRevision(): number;
+    /** @throws GraphRevisionConflictError if expected is set and stale */
+    checkRevision(expected?: number): void;
+    /** Advance the revision for a committed mutation. */
+    bump(): number;
+    /** Append a receipt and make it the edge's current disposition. */
+    record(taskId: string, prerequisiteId: string, disposition: PrerequisiteDisposition, details?: ReceiptDetails): PrerequisiteReceiptV1;
+    /** Current disposition of an edge, or undefined if the edge is unknown. */
+    disposition(taskId: string, prerequisiteId: string): PrerequisiteDisposition | undefined;
+    /** True when every listed prerequisite edge is SATISFIED or WAIVED. */
+    allResolved(taskId: string, prerequisiteIds: Iterable<string>): boolean;
+    /** True when any edge of the task has one of the given dispositions. */
+    hasAny(taskId: string, dispositions: readonly PrerequisiteDisposition[]): boolean;
+    /** Current edge states for a dependent, in the given prerequisite order. */
+    edgesOf(taskId: string, prerequisiteIds: Iterable<string>): PrerequisiteEdgeState[];
+    /** Count live edges by disposition across the given dependents. */
+    countEdges(taskIds: Iterable<string>, disposition: PrerequisiteDisposition): number;
+    /** Append-only receipt log, optionally filtered. */
+    receipts(filter?: {
+        taskId?: string;
+        prerequisiteId?: string;
+    }): PrerequisiteReceiptV1[];
+    /** Drop a removed task's own edges from the current projection (log is kept). */
+    dropEdgesOf(taskId: string): void;
+    /** Register a task as an obligation; re-adding clears any tombstone. */
+    addObligation(taskId: string): void;
+    tombstone(taskId: string, statusAtRemoval: DAGTaskStatus): void;
+    isTombstoned(taskId: string): boolean;
+    removedTasks(): RemovedTaskRecord[];
+    get obligationCount(): number;
+    /** Obligation accounting over live tasks plus tombstones. */
+    summarize(liveTasks: Iterable<DAGTask>): ObligationSummary;
+    /** Reset all state except the revision, which stays monotonic. */
+    reset(): void;
+}
+export {};
+//# sourceMappingURL=prerequisite-ledger.d.ts.map

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

@@ -0,0 +1,252 @@
+/**
+ * Agentic QE v3 - Prerequisite Ledger
+ * Issue #1069: typed prerequisite dispositions and receipts for TaskDAG
+ *
+ * Holds the graph identity, the monotonically increasing graph revision,
+ * the current disposition of every prerequisite edge, an append-only log
+ * of PrerequisiteReceiptV1 records, and tombstones for removed tasks so the
+ * original obligation denominator survives node removal.
+ */
+import { PREREQUISITE_RECEIPT_SCHEMA, } from './types.js';
+/** Dispositions that let a dependent become ready */
+const RESOLVING = new Set([
+    'SATISFIED',
+    'WAIVED',
+]);
+/** Task statuses that end execution */
+export const TERMINAL_STATUSES = new Set([
+    'completed',
+    'failed',
+    'cancelled',
+]);
+const MAX_ACTOR_LENGTH = 256;
+const MAX_REASON_LENGTH = 4096;
+const MAX_REF_LENGTH = 1024;
+/** Thrown when an operation's expectedRevision does not match the graph */
+export class GraphRevisionConflictError extends Error {
+    expectedRevision;
+    actualRevision;
+    constructor(expectedRevision, actualRevision) {
+        super(`Graph revision conflict: expected ${expectedRevision}, graph is at ${actualRevision}`);
+        this.expectedRevision = expectedRevision;
+        this.actualRevision = actualRevision;
+        this.name = 'GraphRevisionConflictError';
+    }
+}
+/** Thrown when a waiver request is invalid or rejected by policy */
+export class PrerequisiteWaiverError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PrerequisiteWaiverError';
+    }
+}
+function requireText(value, field, maxLength) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new PrerequisiteWaiverError(`Waiver '${field}' must be a non-empty string`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length > maxLength) {
+        throw new PrerequisiteWaiverError(`Waiver '${field}' exceeds ${maxLength} characters`);
+    }
+    return trimmed;
+}
+/**
+ * Validate a waiver request at the API boundary.
+ * @returns The normalized (trimmed) request
+ * @throws PrerequisiteWaiverError on missing or malformed fields
+ */
+export function validateWaiverInput(input) {
+    if (input === null || typeof input !== 'object') {
+        throw new PrerequisiteWaiverError('Waiver input must be an object');
+    }
+    const authorityRef = input.authorityRef === undefined
+        ? undefined
+        : requireText(input.authorityRef, 'authorityRef', MAX_REF_LENGTH);
+    const expectedRevision = input.expectedRevision;
+    if (expectedRevision !== undefined && !Number.isInteger(expectedRevision)) {
+        throw new PrerequisiteWaiverError(`Waiver 'expectedRevision' must be an integer`);
+    }
+    return {
+        taskId: requireText(input.taskId, 'taskId', MAX_REF_LENGTH),
+        prerequisiteId: requireText(input.prerequisiteId, 'prerequisiteId', MAX_REF_LENGTH),
+        actor: requireText(input.actor, 'actor', MAX_ACTOR_LENGTH),
+        reason: requireText(input.reason, 'reason', MAX_REASON_LENGTH),
+        authorityRef,
+        expectedRevision,
+    };
+}
+/**
+ * Ledger of prerequisite edge dispositions for one TaskDAG.
+ * Receipts are frozen and never rewritten; the latest receipt per edge
+ * is the edge's current disposition.
+ */
+export class PrerequisiteLedger {
+    graphId;
+    revision = 0;
+    current = new Map();
+    log = [];
+    tombstones = new Map();
+    obligations = new Set();
+    constructor(graphId) {
+        this.graphId = graphId;
+    }
+    /** Current graph revision (0 for a fresh graph) */
+    get graphRevision() {
+        return this.revision;
+    }
+    /** @throws GraphRevisionConflictError if expected is set and stale */
+    checkRevision(expected) {
+        if (expected !== undefined && expected !== this.revision) {
+            throw new GraphRevisionConflictError(expected, this.revision);
+        }
+    }
+    /** Advance the revision for a committed mutation. */
+    bump() {
+        return ++this.revision;
+    }
+    /** Append a receipt and make it the edge's current disposition. */
+    record(taskId, prerequisiteId, disposition, details = {}) {
+        const receipt = Object.freeze({
+            schema: PREREQUISITE_RECEIPT_SCHEMA,
+            graphId: this.graphId,
+            graphRevision: this.revision,
+            taskId,
+            prerequisiteId,
+            disposition,
+            ...(details.completionEvidenceRef !== undefined
+                ? { completionEvidenceRef: details.completionEvidenceRef }
+                : {}),
+            ...(details.waiver ? { waiver: Object.freeze({ ...details.waiver }) } : {}),
+            observedAt: new Date().toISOString(),
+        });
+        let edges = this.current.get(taskId);
+        if (!edges) {
+            edges = new Map();
+            this.current.set(taskId, edges);
+        }
+        edges.set(prerequisiteId, receipt);
+        this.log.push(receipt);
+        return receipt;
+    }
+    /** Current disposition of an edge, or undefined if the edge is unknown. */
+    disposition(taskId, prerequisiteId) {
+        return this.current.get(taskId)?.get(prerequisiteId)?.disposition;
+    }
+    /** True when every listed prerequisite edge is SATISFIED or WAIVED. */
+    allResolved(taskId, prerequisiteIds) {
+        for (const id of prerequisiteIds) {
+            const d = this.disposition(taskId, id);
+            if (!d || !RESOLVING.has(d))
+                return false;
+        }
+        return true;
+    }
+    /** True when any edge of the task has one of the given dispositions. */
+    hasAny(taskId, dispositions) {
+        const edges = this.current.get(taskId);
+        if (!edges)
+            return false;
+        for (const receipt of edges.values()) {
+            if (dispositions.includes(receipt.disposition))
+                return true;
+        }
+        return false;
+    }
+    /** Current edge states for a dependent, in the given prerequisite order. */
+    edgesOf(taskId, prerequisiteIds) {
+        const edges = this.current.get(taskId);
+        const states = [];
+        if (!edges)
+            return states;
+        for (const id of prerequisiteIds) {
+            const receipt = edges.get(id);
+            if (receipt)
+                states.push({ prerequisiteId: id, disposition: receipt.disposition, receipt });
+        }
+        return states;
+    }
+    /** Count live edges by disposition across the given dependents. */
+    countEdges(taskIds, disposition) {
+        let count = 0;
+        for (const id of taskIds) {
+            const edges = this.current.get(id);
+            if (!edges)
+                continue;
+            for (const receipt of edges.values()) {
+                if (receipt.disposition === disposition)
+                    count++;
+            }
+        }
+        return count;
+    }
+    /** Append-only receipt log, optionally filtered. */
+    receipts(filter = {}) {
+        return this.log.filter((r) => (filter.taskId === undefined || r.taskId === filter.taskId) &&
+            (filter.prerequisiteId === undefined || r.prerequisiteId === filter.prerequisiteId));
+    }
+    /** Drop a removed task's own edges from the current projection (log is kept). */
+    dropEdgesOf(taskId) {
+        this.current.delete(taskId);
+    }
+    /** Register a task as an obligation; re-adding clears any tombstone. */
+    addObligation(taskId) {
+        this.obligations.add(taskId);
+        this.tombstones.delete(taskId);
+    }
+    tombstone(taskId, statusAtRemoval) {
+        this.tombstones.set(taskId, Object.freeze({
+            taskId,
+            statusAtRemoval,
+            graphRevision: this.revision,
+        }));
+    }
+    isTombstoned(taskId) {
+        return this.tombstones.has(taskId);
+    }
+    removedTasks() {
+        return Array.from(this.tombstones.values());
+    }
+    get obligationCount() {
+        return this.obligations.size;
+    }
+    /** Obligation accounting over live tasks plus tombstones. */
+    summarize(liveTasks) {
+        let completed = 0, failed = 0, cancelled = 0, notRun = 0, removed = 0;
+        const liveIds = [];
+        for (const task of liveTasks) {
+            liveIds.push(task.id);
+            if (task.status === 'completed')
+                completed++;
+            else if (task.status === 'failed')
+                failed++;
+            else if (task.status === 'cancelled')
+                cancelled++;
+            else
+                notRun++;
+        }
+        for (const record of this.tombstones.values()) {
+            if (record.statusAtRemoval === 'completed')
+                completed++;
+            else
+                removed++;
+        }
+        return {
+            graphId: this.graphId,
+            graphRevision: this.revision,
+            originalTotal: this.obligations.size,
+            currentTotal: liveIds.length,
+            completed, failed, cancelled, removed, notRun,
+            waivedEdges: this.countEdges(liveIds, 'WAIVED'),
+            missingEdges: this.countEdges(liveIds, 'MISSING'),
+            removedEdges: this.countEdges(liveIds, 'REMOVED'),
+        };
+    }
+    /** Reset all state except the revision, which stays monotonic. */
+    reset() {
+        this.current.clear();
+        this.log.length = 0;
+        this.tombstones.clear();
+        this.obligations.clear();
+    }
+}
+//# sourceMappingURL=prerequisite-ledger.js.map

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

@@ -7,7 +7,7 @@
  * by priority level first (p0 > p1 > p2 > p3), then by number of
  * downstream dependents (most blocking tasks first).
  */
-import type { DAGTask, DAGSchedulerConfig } from './types.js';
+import type { CompleteTaskOptions, DAGProgress, DAGTask, DAGSchedulerConfig } from './types.js';
 import type { TaskDAG } from './dag.js';
 /**
  * DAG-aware task scheduler with priority and dependency ordering.
@@ -65,9 +65,10 @@ export declare class DAGScheduler {
      *
      * @param taskId - ID of the completed task
      * @param result - Optional result data from the task
+     * @param options - Optional completion evidence and revision guard
      * @returns Array of newly schedulable tasks
      */
-    onTaskComplete(taskId: string, result?: unknown): DAGTask[];
+    onTaskComplete(taskId: string, result?: unknown, options?: CompleteTaskOptions): DAGTask[];
     /**
      * Handle task failure and cascade cancellations.
      *
@@ -90,22 +91,31 @@ export declare class DAGScheduler {
     /**
      * Get progress information for the DAG execution.
      *
-     * @returns Object with completed count, total count, and percentage
+     * The denominator is the original obligation count: removing a task
+     * does not shrink it, so deleting unfinished work cannot raise the
+     * percentage. Completed tasks that were later removed still count.
+     *
+     * @returns Completed count, original total, percentage and disposition counts
      */
-    getProgress(): {
-        completed: number;
-        total: number;
-        percentage: number;
-    };
+    getProgress(): DAGProgress;
     /**
      * Check whether all tasks have reached a terminal state.
      *
      * A DAG execution is complete when every task is either
-     * 'completed', 'failed', or 'cancelled'.
+     * 'completed', 'failed', or 'cancelled'. This is an operational
+     * signal only; use isSatisfied() to ask whether the objective was met.
      *
      * @returns true if all tasks are in a terminal state
      */
     isComplete(): boolean;
+    /**
+     * Check whether every original obligation completed. Failed, cancelled
+     * and removed-before-completion tasks make this false even when
+     * isComplete() is true.
+     *
+     * @returns true if every task ever added has completed
+     */
+    isSatisfied(): boolean;
     /**
      * Sort tasks by priority (highest first) then by downstream
      * dependent count (most blocking first).

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

@@ -110,10 +110,11 @@ export class DAGScheduler {
      *
      * @param taskId - ID of the completed task
      * @param result - Optional result data from the task
+     * @param options - Optional completion evidence and revision guard
      * @returns Array of newly schedulable tasks
      */
-    onTaskComplete(taskId, result) {
-        const unblockedIds = this.dag.complete(taskId, result);
+    onTaskComplete(taskId, result, options) {
+        const unblockedIds = this.dag.complete(taskId, result, options);
         const tasks = [];
         for (const id of unblockedIds) {
             const task = this.dag.getTask(id);
@@ -164,23 +165,35 @@ export class DAGScheduler {
     /**
      * Get progress information for the DAG execution.
      *
-     * @returns Object with completed count, total count, and percentage
+     * The denominator is the original obligation count: removing a task
+     * does not shrink it, so deleting unfinished work cannot raise the
+     * percentage. Completed tasks that were later removed still count.
+     *
+     * @returns Completed count, original total, percentage and disposition counts
      */
     getProgress() {
-        const stats = this.dag.getStats();
-        const total = stats.totalTasks;
-        if (total === 0) {
-            return { completed: 0, total: 0, percentage: 100 };
-        }
-        const completed = stats.completed;
-        const percentage = Math.round((completed / total) * 100);
-        return { completed, total, percentage };
+        const s = this.dag.getObligationSummary();
+        const total = s.originalTotal;
+        const percentage = total === 0 ? 100 : Math.round((s.completed / total) * 100);
+        return {
+            completed: s.completed,
+            total,
+            percentage,
+            currentTotal: s.currentTotal,
+            failed: s.failed,
+            cancelled: s.cancelled,
+            removed: s.removed,
+            notRun: s.notRun,
+            waivedEdges: s.waivedEdges,
+            graphRevision: s.graphRevision,
+        };
     }
     /**
      * Check whether all tasks have reached a terminal state.
      *
      * A DAG execution is complete when every task is either
-     * 'completed', 'failed', or 'cancelled'.
+     * 'completed', 'failed', or 'cancelled'. This is an operational
+     * signal only; use isSatisfied() to ask whether the objective was met.
      *
      * @returns true if all tasks are in a terminal state
      */
@@ -192,6 +205,17 @@ export class DAGScheduler {
         const terminal = stats.completed + stats.failed + stats.cancelled;
         return terminal === stats.totalTasks;
     }
+    /**
+     * Check whether every original obligation completed. Failed, cancelled
+     * and removed-before-completion tasks make this false even when
+     * isComplete() is true.
+     *
+     * @returns true if every task ever added has completed
+     */
+    isSatisfied() {
+        const s = this.dag.getObligationSummary();
+        return s.completed === s.originalTotal;
+    }
     // --------------------------------------------------------------------------
     // Internal Helpers
     // --------------------------------------------------------------------------