ai-foreman 1.7.20 → 1.7.21

package/dist/supervisedStart.js

@@ -154,6 +154,7 @@ export async function superviseStart(projectDir, runId, policy, selection) {
     db.ensureRun(runId, "build");
     db.freezeAutonomyPolicy(runId, policy);
     let exitCode = 2;
+    let stopRequestSource;
     const supervisor = new DurableSupervisor({ projectDir, runId, policy, admission: localBuildAuthority(projectDir),
         checkpoint: () => db.getRun(runId)?.checkpoint ?? "preparing",
         spawnWorker: generation => {
@@ -201,8 +202,10 @@ export async function superviseStart(projectDir, runId, policy, selection) {
                 }
                 catch { /* exited */ }
             };
-            const watchdog = setInterval(() => { if (Date.now() - lastHeartbeat > 120_000)
-                stop(); }, 5_000);
+            const watchdog = setInterval(() => { if (Date.now() - lastHeartbeat > 120_000) {
+                stopRequestSource = "heartbeat-timeout";
+                stop();
+            } }, 5_000);
             watchdog.unref();
             child.on("message", message => { if (message && typeof message === "object" && "kind" in message && message.kind === "rafi-worker-heartbeat")
                 lastHeartbeat = Date.now(); });
@@ -237,6 +240,9 @@ export async function superviseStart(projectDir, runId, policy, selection) {
                         clearTimeout(killTimer);
                     exitCode = code ?? 2;
                     try {
+                        const exitState = db.getRun(runId);
+                        if (exitState)
+                            db.transitionSupervisor(runId, generation, { checkpoint: exitState.checkpoint, event: "worker_exit", payload: { code, signal, stopRequested: stopping, source: stopRequestSource ?? "unknown", at: new Date().toISOString(), generation } });
                         // Durable records are authoritative even when the worker never sent IPC.
                         const deadline = Date.now() + 5000;
                         const owned = db.readinessProcesses(runId).filter(row => {
@@ -277,7 +283,10 @@ export async function superviseStart(projectDir, runId, policy, selection) {
                         }
                         else {
                             const state = db.getRun(runId);
-                            if (code === 0 && state?.status !== "completed") {
+                            if (code === 0 && state?.status === "cancelled") {
+                                resolve({ kind: "completed" });
+                            }
+                            else if (code === 0 && state?.status !== "completed") {
                                 exitCode = 2;
                                 resolve({ kind: "waiting_for_human" });
                             }
@@ -294,15 +303,16 @@ export async function superviseStart(projectDir, runId, policy, selection) {
             return { pid: child.pid, result, stop };
         },
     });
-    const stop = () => supervisor.requestStop();
-    process.once("SIGINT", stop);
-    process.once("SIGTERM", stop);
+    const stopInt = () => { stopRequestSource = "parent-SIGINT"; supervisor.requestStop(); };
+    const stopTerm = () => { stopRequestSource = "parent-SIGTERM"; supervisor.requestStop(); };
+    process.once("SIGINT", stopInt);
+    process.once("SIGTERM", stopTerm);
     try {
         await supervisor.run();
     }
     finally {
-        process.off("SIGINT", stop);
-        process.off("SIGTERM", stop);
+        process.off("SIGINT", stopInt);
+        process.off("SIGTERM", stopTerm);
         db.close();
     }
     process.exitCode = exitCode;

package/dist/terminalStyle.d.ts

@@ -0,0 +1,21 @@
+/** Small, dependency-free terminal styling and display sanitization helpers. */
+export type TerminalColorRole = "accent" | "success" | "warning" | "error" | "info";
+export interface TerminalStyleStream {
+    readonly isTTY?: boolean;
+}
+export interface TerminalStyleContext {
+    readonly stream?: TerminalStyleStream;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    /** Declared data output is always plain, including FORCE_COLOR sessions. */
+    readonly machineReadable?: boolean;
+}
+export declare function terminalColorEnabled(context?: TerminalStyleContext): boolean;
+export declare function styleTerminalText(role: TerminalColorRole, text: string, context?: TerminalStyleContext): string;
+export declare function accent(text: string, context?: TerminalStyleContext): string;
+export declare function success(text: string, context?: TerminalStyleContext): string;
+export declare function warning(text: string, context?: TerminalStyleContext): string;
+export declare function error(text: string, context?: TerminalStyleContext): string;
+export declare function info(text: string, context?: TerminalStyleContext): string;
+/** Remove terminal control sequences while retaining intended line breaks. */
+export declare function sanitizeTerminalText(value: string): string;

package/dist/terminalStyle.js

@@ -0,0 +1,50 @@
+/** Small, dependency-free terminal styling and display sanitization helpers. */
+const ANSI = {
+    accent: "\x1b[36m",
+    success: "\x1b[32m",
+    warning: "\x1b[33m",
+    error: "\x1b[31m",
+    info: "\x1b[34m",
+};
+const RESET = "\x1b[39m";
+export function terminalColorEnabled(context = {}) {
+    if (context.machineReadable)
+        return false;
+    const env = context.env ?? process.env;
+    const stream = context.stream ?? process.stdout;
+    if (Object.hasOwn(env, "NO_COLOR"))
+        return false;
+    if (env.TERM?.toLowerCase() === "dumb")
+        return false;
+    if (env.FORCE_COLOR === "0")
+        return false;
+    if (["1", "2", "3"].includes(env.FORCE_COLOR ?? ""))
+        return true;
+    if (!stream.isTTY)
+        return false;
+    // Modern Windows terminals advertise ANSI support. A bare legacy console TTY
+    // is not enough evidence, so leave it readable and unstyled.
+    if ((context.platform ?? process.platform) === "win32") {
+        return Boolean(env.WT_SESSION || env.ANSICON || env.ConEmuANSI === "ON" || env.TERM);
+    }
+    return true;
+}
+export function styleTerminalText(role, text, context = {}) {
+    const safeText = sanitizeTerminalText(text);
+    return terminalColorEnabled(context) ? `${ANSI[role]}${safeText}${RESET}` : safeText;
+}
+export function accent(text, context) { return styleTerminalText("accent", text, context); }
+export function success(text, context) { return styleTerminalText("success", text, context); }
+export function warning(text, context) { return styleTerminalText("warning", text, context); }
+export function error(text, context) { return styleTerminalText("error", text, context); }
+export function info(text, context) { return styleTerminalText("info", text, context); }
+/** Remove terminal control sequences while retaining intended line breaks. */
+export function sanitizeTerminalText(value) {
+    return value
+        // CSI, OSC, DCS/SOS/PM/APC, and two-byte ESC controls.
+        .replace(/\x1b\](?:[^\x07\x1b]|\x1b(?!\\))*(?:\x07|\x1b\\)?/gs, "")
+        .replace(/\x1b(?:[PX^_](?:.|\n)*?\x1b\\|\[[0-?]*[ -/]*[@-~]|[@-_])/g, "")
+        .replace(/\x9d[^\x07]*(?:\x07)?/g, "")
+        .replace(/\x9b[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
+}

package/dist/ticketPopulation.d.ts

@@ -2,6 +2,7 @@ import type { StructuredPlanV1 } from "rafi-spec";
 import type { TicketDef } from "./tickets/ticketSchema.js";
 import { type DeliveryConfig } from "./tickets/delivery.js";
 export interface TicketSliceProposal {
+    qa_preparation?: TicketDef["qa_preparation"];
     slice_ref: string;
     title: string;
     area: string;

package/dist/ticketPopulation.js

@@ -1,3 +1,4 @@
+import { canonicalContractJson } from "./qaVerificationContract.js";
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, copyFileSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
@@ -30,6 +31,9 @@ export function validateTicketPopulationProposal(proposal, plan, existing) {
     const planned = new Set(plan.slices.map((slice) => slice.slice_ref));
     const mapped = new Set();
     for (const ticket of proposal.tickets) {
+        const depth = plan.slices.find(slice => slice.slice_ref === ticket.slice_ref)?.qa_preparation;
+        if (ticket.qa_preparation && (!depth || canonicalContractJson(ticket.qa_preparation) !== canonicalContractJson(depth)))
+            issues.push(`ticket-maker cannot override planner QA depth for ${ticket.slice_ref}`);
         if (!planned.has(ticket.slice_ref))
             issues.push(`unknown slice mapping ${ticket.slice_ref}`);
         if (mapped.has(ticket.slice_ref))
@@ -64,7 +68,7 @@ export function materializeTicketPopulation(proposal, plan, existing) {
     const materialized = proposal.tickets.map((slice, index) => {
         const retained = byPlanSlice.get(`${plan.plan_id}:${slice.slice_ref}`);
         return {
-            ...(retained ?? {}), id: sliceToTicket.get(slice.slice_ref), order: retained?.order ?? nextOrder(existing, index),
+            ...(retained ?? {}), qa_preparation: structuredClone(plan.slices.find(item => item.slice_ref === slice.slice_ref)?.qa_preparation), id: sliceToTicket.get(slice.slice_ref), order: retained?.order ?? nextOrder(existing, index),
             title: slice.title, area: slice.area, priority: slice.priority, size: slice.size, risk: slice.risk,
             depends_on: slice.depends_on.map((ref) => sliceToTicket.get(ref)), summary: slice.summary,
             acceptance: [...slice.acceptance], required_tests: [...slice.required_tests], likely_files: [...slice.likely_files],

package/dist/tickets/commands.js

@@ -259,8 +259,8 @@ export function cmdBlock(projectDir, ticketId, opts) {
             ctx.db.upsertState(ticketId, {
                 status: "blocked",
                 blocked_by_json: JSON.stringify(merged),
-                blocker_type: opts.blockerType ?? "dependency",
-                blocker_notes: opts.unblockCriteria ?? null,
+                blocker_type: opts.blockerType ?? (merged.length ? "dependency" : "external"),
+                blocker_notes: opts.unblockCriteria ?? opts.summary ?? "Resolve the external prerequisite before continuing",
                 first_blocked_at: state?.first_blocked_at ?? now,
                 last_checked_at: now,
                 last_worked_at: now,

package/dist/tickets/queue.js

@@ -31,7 +31,7 @@ export function buildNextQueue(ticketDefs, states, queueLimit) {
             blockedBy: blockedBy.length ? blockedBy.join(", ") : "None",
             size: ticket.size,
             risk: ticket.risk,
-            nextAction: state?.next_action ?? defaultNextAction(ticket, displayStatus, blockedBy),
+            nextAction: state?.next_action ?? (displayStatus === "blocked" && !blockedBy.length ? `Resolve blocker: ${state?.blocker_notes ?? "external prerequisite requires recovery"}` : defaultNextAction(ticket, displayStatus, blockedBy)),
             requiredTests: ticket.required_tests.join("; "),
             evidence: state?.evidence ?? "N/A until implemented.",
             likelyFiles: ticket.likely_files.length ? ticket.likely_files.join(", ") : "unknown",

package/dist/tickets/ticketSchema.d.ts

@@ -1,3 +1,4 @@
+import { type QaPreparationDepthDecisionV1 } from "rafi-spec";
 export type TicketPriority = "P0" | "P1" | "P2" | "P3";
 export type TicketSize = "XS" | "S" | "M" | "L" | "XL";
 export type TicketRisk = "Low" | "Medium" | "High";
@@ -22,6 +23,7 @@ export interface TicketPlanRef {
     slice_ref: string;
 }
 export interface TicketDef {
+    qa_preparation?: QaPreparationDepthDecisionV1;
     id: string;
     order: number;
     title: string;
@@ -47,6 +49,104 @@ export declare const TICKET_JSON_SCHEMA: {
     readonly required: readonly ["id", "order", "title", "area", "priority", "size", "risk", "depends_on", "summary", "acceptance", "required_tests", "likely_files"];
     readonly additionalProperties: true;
     readonly properties: {
+        readonly qa_preparation: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["version", "decisionId", "level", "rationale", "riskFactors", "policyVersion", "plannerOperationId", "plannerIdentity", "timestamp", "minimumLevel", "minimumReasons"];
+            readonly properties: {
+                readonly version: {
+                    readonly const: 1;
+                };
+                readonly decisionId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly level: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 5;
+                };
+                readonly rationale: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly policyVersion: {
+                    readonly const: "qa-preparation-v1";
+                };
+                readonly plannerOperationId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly plannerIdentity: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly timestamp: {
+                    readonly type: "string";
+                    readonly pattern: "^\\d{4}-\\d{2}-\\d{2}T";
+                };
+                readonly minimumLevel: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 5;
+                };
+                readonly minimumReasons: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                };
+                readonly predecessorDecisionId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly lowRisk: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["narrowBehavior", "understoodDependencies", "adequateVerification"];
+                    readonly properties: {
+                        readonly narrowBehavior: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly understoodDependencies: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly adequateVerification: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                    };
+                };
+                readonly riskFactors: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["category", "rationale", "references"];
+                        readonly properties: {
+                            readonly category: {
+                                readonly enum: string[];
+                            };
+                            readonly rationale: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly references: {
+                                readonly type: "array";
+                                readonly minItems: 1;
+                                readonly items: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
         readonly id: {
             readonly type: "string";
             readonly pattern: "^[A-Za-z][A-Za-z0-9-_]*$";
@@ -212,6 +312,104 @@ export declare const TICKETS_FILE_SCHEMA: {
                 readonly required: readonly ["id", "order", "title", "area", "priority", "size", "risk", "depends_on", "summary", "acceptance", "required_tests", "likely_files"];
                 readonly additionalProperties: true;
                 readonly properties: {
+                    readonly qa_preparation: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["version", "decisionId", "level", "rationale", "riskFactors", "policyVersion", "plannerOperationId", "plannerIdentity", "timestamp", "minimumLevel", "minimumReasons"];
+                        readonly properties: {
+                            readonly version: {
+                                readonly const: 1;
+                            };
+                            readonly decisionId: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly level: {
+                                readonly type: "integer";
+                                readonly minimum: 1;
+                                readonly maximum: 5;
+                            };
+                            readonly rationale: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly policyVersion: {
+                                readonly const: "qa-preparation-v1";
+                            };
+                            readonly plannerOperationId: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly plannerIdentity: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly timestamp: {
+                                readonly type: "string";
+                                readonly pattern: "^\\d{4}-\\d{2}-\\d{2}T";
+                            };
+                            readonly minimumLevel: {
+                                readonly type: "integer";
+                                readonly minimum: 1;
+                                readonly maximum: 5;
+                            };
+                            readonly minimumReasons: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                            };
+                            readonly predecessorDecisionId: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly lowRisk: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["narrowBehavior", "understoodDependencies", "adequateVerification"];
+                                readonly properties: {
+                                    readonly narrowBehavior: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                    readonly understoodDependencies: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                    readonly adequateVerification: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                };
+                            };
+                            readonly riskFactors: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "object";
+                                    readonly additionalProperties: false;
+                                    readonly required: readonly ["category", "rationale", "references"];
+                                    readonly properties: {
+                                        readonly category: {
+                                            readonly enum: string[];
+                                        };
+                                        readonly rationale: {
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        };
+                                        readonly references: {
+                                            readonly type: "array";
+                                            readonly minItems: 1;
+                                            readonly items: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
                     readonly id: {
                         readonly type: "string";
                         readonly pattern: "^[A-Za-z][A-Za-z0-9-_]*$";

package/dist/tickets/ticketSchema.js

@@ -1,3 +1,4 @@
+import { qaPreparationDepthDecisionV1Schema } from "rafi-spec";
 export const TICKET_JSON_SCHEMA = {
     type: "object",
     required: [
@@ -6,6 +7,7 @@ export const TICKET_JSON_SCHEMA = {
     ],
     additionalProperties: true,
     properties: {
+        qa_preparation: qaPreparationDepthDecisionV1Schema,
         id: { type: "string", pattern: "^[A-Za-z][A-Za-z0-9-_]*$" },
         order: { type: "number", minimum: 0 },
         title: { type: "string", minLength: 1 },

package/dist/workflowDb.d.ts

@@ -1,7 +1,13 @@
+import { type GraphDerivedAccess } from "./graph/derived.js";
+import { QaPreparationStore } from "./qaPreparationStore.js";
+import { GraphStore } from "./graph/storage.js";
+import { reconcileWork, type BuildOwnershipRepairV1 } from "./buildWorkReconciliation.js";
+import { verifyGuidance, verifyBuilderGuidance, finishGuidance, type InstructionRecipient } from "./buildInterventions.js";
+import { type AdmitWorkInput } from "./buildWorkAdmission.js";
 import { type ReadinessProcess } from "./readinessCleanup.js";
 import { type BuildAdmission, type BuildLaunch } from "./buildAdmission.js";
 import type { BuildRecoveryDecisionReceipt, ContextSample, ContinuityCheckpoint, ContinuityDelta, ContinuityEvent, ContinuityHead, ContinuityHeadState, HandoffLineage, HandoffAcceptanceReceiptV1, HandoffManifestV1, LiveSettingsAcknowledgment, OperationLifecycle, PendingHumanDecision, ProviderSessionRefV1, RecoveryAttemptOutcome, RecoveryAttemptReceipt, ResolvedAutonomyPolicy, ResolvedAgentSettings, SessionUsageSample, StructuredInterruption, SupervisorState, WorkflowIssue } from "rafi-spec";
-import type { QaDeliveryTurnV3, QaDeliveryOutcome, QaDeliveryInvocationV3 } from "./qaDeliveryJournal.js";
+import type { QaDeliveryTurn, QaDeliveryOutcome, QaDeliveryInvocationV3 } from "./qaDeliveryJournal.js";
 import type { BranchResumeSession } from "./branch/resume.js";
 import { type BuilderRemediationReceiptV2, type BuilderRemediationReceiptV3, type FrozenQaSourceStateV2, type HandoffAcceptanceReceiptV2, type QaPassCertificateV2, type QaReducerEventV2, type QaReducerStateV2, type QaReportDisposition, type QaReviewBasisV2, type QaTurnIntentV2, type QaTurnReceiptV2 } from "./qaProtocolV2.js";
 export declare const WORKFLOW_DB_FILE = ".rafi/recovery.sqlite3";
@@ -205,6 +211,7 @@ export declare class WorkflowDb {
     private writerLease?;
     private coordinatorTransition;
     private lineageTransition;
+    private workAuthority;
     constructor(projectDir: string, path?: string, readinessAccess?: {
         probeId: string;
     } | {
@@ -213,6 +220,37 @@ export declare class WorkflowDb {
     /** Connection-local SQL fences: helper/reconciler cannot gain general writer rights. */
     private restrictReadinessConnection;
     close(): void;
+    qaPreparationStore(): QaPreparationStore;
+    graphStore(): GraphStore;
+    admitWork(input: AdmitWorkInput): import("rafi-spec").BuildWorkAdmissionV1;
+    private assertInstructionOwner;
+    reserveGuidance(runId: string, workId: string, recipient: InstructionRecipient, operationId: string, sourceDigest: string, text: string, reserve?: boolean): {
+        text: string;
+        ids: string[];
+    };
+    reconcileInstructionDeliveries(runId: string, workId: string): void;
+    decisionWorkId(decision: PendingHumanDecision): string | undefined;
+    finishGuidance(ids: string[], recipient: InstructionRecipient, result: Parameters<typeof finishGuidance>[3]): void;
+    builderVerificationContext(runId: string, workId: string, sourceDigest: string): {
+        text: string;
+        ids: string[];
+    };
+    verifyBuilderGuidance(ids: string[], certificate: Parameters<typeof verifyBuilderGuidance>[2], response: string, receiptDigest: string): void;
+    verifyGuidance(ids: string[], certificate: Parameters<typeof verifyGuidance>[2], response: string): void;
+    hasQueuedBuilderGuidance(runId: string, workId: string): boolean;
+    instruction(id: string): import("./buildInterventions.js").BuildInstruction | undefined;
+    assertFinalizationControls(runId: string, workId: string): void;
+    consumeInstructionControls(runId: string, workId: string, kind?: "questions" | "attempts"): string | undefined;
+    reconcileWork(request: BuildOwnershipRepairV1, input: Parameters<typeof reconcileWork>[2]): Record<string, unknown>;
+    reconciliation(id: string): Record<string, unknown> | undefined;
+    workDefinitions(runId: string): Array<{
+        workId: string;
+        kind: string;
+        definition: unknown;
+    }>;
+    recordWorkAssignment(runId: string, workId: string, operationId: string, record: unknown): void;
+    admittedWork(runId: string, workId: string): import("rafi-spec").BuildWorkAdmissionV1 | undefined;
+    assertAdmittedWork(runId: string, workId: string): import("rafi-spec").BuildWorkAdmissionV1;
     /** Atomic local changes only; never await provider or filesystem work here. */
     atomic<T>(work: () => T): T;
     buildAdmission(): BuildAdmission | undefined;
@@ -330,6 +368,7 @@ export declare class WorkflowDb {
     }, now?: Date): ContinuityCheckpoint;
     continuityCheckpoints(runId: string, role?: "builder" | "qa"): ContinuityCheckpoint[];
     latestContinuityCheckpoint(runId: string, role: "builder" | "qa"): ContinuityCheckpoint | undefined;
+    private assertGraphContinuityAccess;
     continuityHead(runId: string, role: "builder" | "qa" | "run"): ContinuityHead | undefined;
     setContinuityHeadState(runId: string, role: "builder" | "qa", state: ContinuityHeadState, now?: Date): ContinuityHead | undefined;
     recordSession(runId: string, role: string, stream: string, session: string | ProviderSessionRefV1 | undefined, transition: string, settings: ResolvedAgentSettings, now?: Date): void;
@@ -355,8 +394,12 @@ export declare class WorkflowDb {
         choices: PendingHumanDecision["choices"];
         evidence?: PendingHumanDecision["evidence"];
     }, now?: Date): PendingHumanDecision;
+    cancelPendingHumanDecisions(runId: string, reason: string, now?: Date): void;
+    humanDecisionKey(decisionId: string): string | undefined;
     humanDecision(decisionId: string): PendingHumanDecision | undefined;
     pendingHumanDecisions(runId: string): PendingHumanDecision[];
+    decisionContinuationAvailable(runId: string, decisionId: string): boolean;
+    nextDecisionContinuationKey(runId: string, decisionId: string): string;
     answeredTicketDecisions(runId: string, scopeRevision: string): PendingHumanDecision[];
     /** Unconsumed answers to an older definition must not silently reopen a ticket. */
     staleTicketDecisions(runId: string, scopeRevision: string): PendingHumanDecision[];
@@ -384,6 +427,7 @@ export declare class WorkflowDb {
     operation(idempotencyKey: string): OperationRecord | undefined;
     operations(runId: string): OperationRecord[];
     putEvidence(kind: "handoff" | "diff" | "test" | "qa", value: string | Buffer, now?: Date): string;
+    registerGraphEvidence(value: string | Buffer, access: GraphDerivedAccess | GraphDerivedAccess[]): void;
     getEvidence(digest: string): Buffer | undefined;
     putQaRecoveryHead(input: Omit<QaRecoveryHeadRecord, "updatedAt">, now?: Date): QaRecoveryHeadRecord;
     qaRecoveryHead(runId: string, ticketId?: string): QaRecoveryHeadRecord | undefined;
@@ -398,8 +442,8 @@ export declare class WorkflowDb {
     qaRemediationAttempts(runId: string, ticketId: string): QaRemediationAttemptRecord[];
     qaRemediationAttempt(attemptId: string): QaRemediationAttemptRecord | undefined;
     recordQaDeliveryInvocation(record: QaDeliveryInvocationV3): void;
-    recordQaDeliveryTurn(turn: QaDeliveryTurnV3): void;
-    qaDeliveryTurns(operationId: string): QaDeliveryTurnV3[];
+    recordQaDeliveryTurn(turn: QaDeliveryTurn): void;
+    qaDeliveryTurns(operationId: string): QaDeliveryTurn[];
     /** Attempts, including ambiguous intents, are the common legacy/production ledger. */
     qaAutomaticRemediationCount(runId: string, ticketId: string): number;
     authorizeQaRemediation(runId: string, ticketId: string, reviewAttemptId: string, reason: string): string;
@@ -474,7 +518,8 @@ export declare class WorkflowDb {
     setQaReportDisposition(reportDigest: string, disposition: QaReportDisposition, reason: string, now?: Date): void;
     markQaReportsRecheckRequired(runId: string, ticketId: string, reason: string, now?: Date): void;
     resolveQaReportsAfterPass(runId: string, ticketId: string, now?: Date): void;
-    commitQaWaiver(runId: string, ticketId: string, expectedRevision: number, reason: string, now?: Date): QaReducerStateV2;
+    authorizeContractQaWaiver(runId: string, workId: string, decisionId: string): string;
+    commitQaWaiver(runId: string, ticketId: string, expectedRevision: number, reason: string, now?: Date, authorizationRef?: string): QaReducerStateV2;
     builderRemediationReceipt(operationId: string): BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3 | undefined;
     recordBuilderRemediationReceipt(receipt: BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3): void;
     commitBuilderRemediationSuccess(receipt: BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3, expectedRevision: number, now?: Date): QaReducerStateV2;
@@ -488,12 +533,13 @@ export declare class WorkflowDb {
         receipt?: BuilderRemediationReceiptV2 | BuilderRemediationReceiptV3;
         expectedRevision: number;
     }, now?: Date): QaReducerStateV2;
+    private assertContractCertificate;
     issueQaPassCertificate(input: Omit<QaPassCertificateV2, "version" | "certificateId" | "unresolvedReportCount" | "issuedAt">, now?: Date): QaPassCertificateV2;
     commitQaPass(input: Omit<QaPassCertificateV2, "version" | "certificateId" | "unresolvedReportCount" | "issuedAt">, expectedRevision: number, now?: Date): QaPassCertificateV2;
     /** Accept a passing verdict, its review-attempt outcome, report resolution, certificate, and reducer edge atomically. */
     commitQaPassAttempt(attemptId: string, input: Omit<QaPassCertificateV2, "version" | "certificateId" | "unresolvedReportCount" | "issuedAt">, detail: string, expectedRevision: number, now?: Date): QaPassCertificateV2;
     consumeQaPassCertificate(runId: string, ticketId: string, certificateId: string, consumer: string, now?: Date): QaPassCertificateV2;
-    invalidateUnconsumedQaPassCertificates(runId: string, ticketId: string, reason: string, now?: Date): void;
+    invalidateUnconsumedQaPassCertificates(runId: string, ticketId: string, reason: string, now?: Date, issuedBefore?: string): void;
     invalidateQaPassBeforeFinalization(input: {
         runId: string;
         ticketId: string;