ai-foreman 1.7.20 → 1.7.21

package/dist/workflowDb.js

@@ -1,3 +1,14 @@
+import { registerQaGraphJournalWriter, ensureQaGraphJournalGuards } from "./qaDeliveryJournal.js";
+import { canonicalJson } from "./qaProtocolV2.js";
+import { resolveEffectiveQaConfiguration } from "./qaEffectiveConfig.js";
+import { registerGraphDerived, graphDerivedAllowed, currentGraphDerivedAccess } from "./graph/derived.js";
+import { parseContractCoverage, validateContractCoverage } from "./qaContractCoverage.js";
+import { QaPreparationStore, migrateQaPreparation, migrateQaPreparationGuards } from "./qaPreparationStore.js";
+import { GraphStore, migrateGraphStore } from "./graph/storage.js";
+import { reconcileWork } from "./buildWorkReconciliation.js";
+import { migrateBuildInterventions, hasQueuedBuilderGuidance, reconcileGuidance, decisionWorkId, queuedControls, completeControl, verifyGuidance, builderVerificationContext, verifyBuilderGuidance, assertFinalizationControls, reserveGuidance, finishGuidance, instruction } from "./buildInterventions.js";
+import { migrateBuildWork } from "./buildWorkMigration.js";
+import { admitWork, admittedWork, assertAdmittedWork } from "./buildWorkAdmission.js";
 import { cleanupReadiness, inspectReadiness, readinessMetadata } from "./readinessCleanup.js";
 import { originalBuildLease, rememberOriginalLease, forgetOriginalLease, registerLaunchChild, acknowledgeLaunchChild, reconcileLaunch, checkBuildOwnershipSchema, canonicalProject, launchDigest, localBuildAuthority, rememberBuildAuthority, forgetBuildAuthority, migrateBuildAdmission, acquireAdmission, readAdmission, assertAdmission, releaseAdmission, reserveLaunch, setLaunchState, claimLaunch, readLaunch } from "./buildAdmission.js";
 import { createHash, randomUUID } from "node:crypto";
@@ -5,6 +16,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statS
 import { hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import Database from "better-sqlite3";
+import { validateQaFailureReport } from "rafi-spec";
 import { migrateQaHandback, registerHandbackWriter, reportOccurrenceId } from "./qaHandbackMigration.js";
 import { providerSessionKey } from "./sessionIdentity.js";
 import { taggedProcesses, classifyProcess, processStartIdentity } from "./processIdentity.js";
@@ -60,6 +72,7 @@ export class WorkflowDb {
     writerLease;
     coordinatorTransition = 0;
     lineageTransition = 0;
+    workAuthority = 0;
     constructor(projectDir, path = join(resolve(projectDir), WORKFLOW_DB_FILE), readinessAccess) {
         this.projectDir = projectDir;
         this.readinessAccess = readinessAccess;
@@ -85,7 +98,9 @@ export class WorkflowDb {
         this.db.function("rafi_build_lease_generation", () => this.writerLease?.generation ?? -1);
         this.db.function("rafi_build_writer_token", () => this.writerAuthority?.token ?? "");
         this.db.function("rafi_build_writer_run", () => this.writerAuthority?.runId ?? "");
+        this.db.function("rafi_work_authority", () => this.workAuthority);
         registerHandbackWriter(this.db);
+        registerQaGraphJournalWriter(this.db);
         if (!readinessAccess)
             this.db.pragma("journal_mode = WAL");
         this.db.pragma("synchronous = FULL");
@@ -95,8 +110,12 @@ export class WorkflowDb {
                 this.restrictReadinessConnection(readinessAccess);
             else {
                 this.migrate();
+                migrateQaPreparation(this.db);
                 migrateBuildAdmission(this.db);
                 this.importLegacyOnce();
+                migrateBuildWork(this.db, projectDir);
+                migrateBuildInterventions(this.db);
+                migrateQaPreparationGuards(this.db);
             }
         }
         catch (error) {
@@ -119,6 +138,155 @@ export class WorkflowDb {
         }
     }
     close() { this.db.close(); }
+    qaPreparationStore() { return new QaPreparationStore(this.db, runId => this.assertInstructionOwner(runId), this.projectDir); }
+    graphStore() { migrateGraphStore(this.db); return new GraphStore(this.db); }
+    admitWork(input) {
+        this.assertInstructionOwner(input.runId);
+        this.workAuthority++;
+        try {
+            const result = admitWork(this.db, input);
+            this.qaPreparationStore().metric(input.runId, result.workId, result.requirementsDigest, `metric:approved:${input.runId}:${result.workId}:${result.requirementsDigest}`, "approved");
+            return result;
+        }
+        finally {
+            this.workAuthority--;
+        }
+    }
+    assertInstructionOwner(runId) {
+        if (this.writerAuthority) {
+            assertAdmission(this.db, this.writerAuthority);
+            if (this.writerAuthority.runId !== runId && !this.db.prepare("SELECT 1 FROM build_child_runs WHERE child=? AND parent=?").get(runId, this.writerAuthority.runId))
+                throw new Error("Instruction execution authority belongs to another run");
+            return;
+        }
+        if (this.buildAdmission())
+            throw new Error("Instruction consumption requires the original build owner");
+        if (this.db.prepare("SELECT 1 FROM build_runtime_runs WHERE run_id=?").get(runId)) {
+            const held = this.currentLease();
+            if (!held || !this.writerLease || held.owner !== this.writerLease.owner || held.generation !== this.writerLease.generation || held.runId !== runId)
+                throw new Error("Instruction execution requires the original workflow lease");
+        }
+    }
+    reserveGuidance(runId, workId, recipient, operationId, sourceDigest, text, reserve = true) {
+        this.assertInstructionOwner(runId);
+        return reserveGuidance(this.db, runId, workId, recipient, operationId, sourceDigest, text, reserve);
+    }
+    reconcileInstructionDeliveries(runId, workId) { this.assertInstructionOwner(runId); this.atomic(() => reconcileGuidance(this.db, runId, workId)); }
+    decisionWorkId(decision) { return decisionWorkId(this.db, decision); }
+    finishGuidance(ids, recipient, result) { for (const id of ids)
+        this.assertInstructionOwner(instruction(this.db, id).request.runId); finishGuidance(this.db, ids, recipient, result); }
+    builderVerificationContext(runId, workId, sourceDigest) { return builderVerificationContext(this.db, runId, workId, sourceDigest); }
+    verifyBuilderGuidance(ids, certificate, response, receiptDigest) { for (const id of ids)
+        this.assertInstructionOwner(instruction(this.db, id).request.runId); return this.atomic(() => verifyBuilderGuidance(this.db, ids, certificate, response, receiptDigest)); }
+    verifyGuidance(ids, certificate, response) { for (const id of ids)
+        this.assertInstructionOwner(instruction(this.db, id).request.runId); return this.atomic(() => verifyGuidance(this.db, ids, certificate, response)); }
+    hasQueuedBuilderGuidance(runId, workId) { return hasQueuedBuilderGuidance(this.db, runId, workId); }
+    instruction(id) { return instruction(this.db, id); }
+    assertFinalizationControls(runId, workId) { assertFinalizationControls(this.db, runId, workId); }
+    consumeInstructionControls(runId, workId, kind = "questions") {
+        return this.atomic(() => {
+            this.assertInstructionOwner(runId);
+            const admission = this.assertAdmittedWork(runId, workId);
+            const latestReview = this.qaReviewAttempts(runId, workId).at(-1);
+            let authorization = kind === "attempts" && latestReview && ["failed", "passed"].includes(latestReview.status) ? this.db.prepare("SELECT a.authorization_id FROM qa_remediation_authorizations a JOIN build_instruction_deliveries d ON json_extract(d.record_json,'$.receipt.authorizationId')=a.authorization_id JOIN build_instructions i USING(instruction_id) WHERE a.run_id=? AND a.ticket_id=? AND a.review_attempt_id=? AND a.consumed_by IS NULL AND d.state='applied' AND json_extract(i.record_json,'$.requirementsDigest')=? AND json_extract(i.record_json,'$.basis.assignmentId')=? AND json_extract(i.record_json,'$.basis.scopeRevision')=? ORDER BY i.sequence LIMIT 1").get(runId, workId, latestReview.attemptId, admission.requirementsDigest, admission.assignmentId, admission.scopeRevision)?.authorization_id : undefined;
+            if (authorization) {
+                const head = this.qaTicketHead(runId, workId);
+                const eligible = latestReview?.status === "passed"
+                    ? head.state === "passed" && this.hasQueuedBuilderGuidance(runId, workId)
+                    : head.state === "review-failed" && this.unresolvedQaReports(runId, workId).some(report => report.reviewNumber === latestReview.reviewNumber && report.reportDigest === latestReview.reportDigest);
+                if (!eligible)
+                    authorization = undefined;
+            }
+            for (const record of queuedControls(this.db, runId, workId).filter(record => kind === "questions" ? record.request.action === "answer_question" : record.request.action === "request_attempt")) {
+                const priorAuthorization = authorization;
+                try {
+                    this.atomic(() => {
+                        if (record.requirementsDigest !== admission.requirementsDigest)
+                            throw new Error("Instruction requirements are stale");
+                        if (record.request.action === "answer_question") {
+                            const decision = this.humanDecision(record.request.decisionId);
+                            if (!decision || decision.runId !== runId || this.decisionWorkId(decision) !== workId || createHash("sha256").update(json(decision)).digest("hex") !== record.request.decisionRevision)
+                                throw new Error("Pending question identity or revision changed");
+                            const choice = decision.choices.find(choice => choice.id === record.request.text || choice.label === record.request.text) ?? decision.choices.find(choice => choice.id === "custom" || choice.id === "answer");
+                            if (!choice)
+                                throw new Error("Answer must name an offered choice or use a question accepting custom text");
+                            const answer = this.answerHumanDecision(runId, decision.decisionId, choice.id, new Date(), choice.id === "custom" || choice.id === "answer" ? record.request.text : undefined);
+                            completeControl(this.db, record.instructionId, { decisionId: answer.decisionId, status: answer.status });
+                        }
+                        else {
+                            const latest = this.qaReviewAttempts(runId, workId).at(-1);
+                            if (!latest || !["failed", "passed"].includes(latest.status) || latest.attemptId !== record.basis.reviewAttemptId || authorization)
+                                throw new Error("One extra attempt requires the current eligible review; another authorization is already available");
+                            if (record.basis.assignmentId !== admission.assignmentId || record.basis.scopeRevision !== admission.scopeRevision)
+                                throw new Error("Attempt authorization scope changed");
+                            const head = this.qaTicketHead(runId, workId);
+                            if (latest.status === "passed") {
+                                if (head.state !== "passed" || !this.hasQueuedBuilderGuidance(runId, workId))
+                                    throw new Error("Follow-up authorization requires waiting Builder guidance on the current unfinalized pass");
+                                authorization = this.authorizeQaRemediation(runId, workId, latest.attemptId, record.request.text);
+                                completeControl(this.db, record.instructionId, { authorizationId: authorization, reviewAttemptId: latest.attemptId, consumed: false, kind: "builder-guidance-followup" });
+                                return;
+                            }
+                            const report = this.unresolvedQaReports(runId, workId).find(report => report.reviewNumber === latest.reviewNumber && report.reportDigest === latest.reportDigest && report.sourceStateDigest === latest.sourceDigest && report.reviewBasisDigest === head.reviewBasisDigest);
+                            if (!report || !validateQaFailureReport(report.report).valid || head.reviewNumber !== latest.reviewNumber || head.sourceStateDigest !== latest.sourceDigest || !["review-failed", "operator-menu"].includes(head.state) || this.qaRemediationAttempts(runId, workId).some(attempt => attempt.reviewAttemptId === latest.attemptId))
+                                throw new Error("Extra attempt requires an unconsumed validated failed-review basis; reconcile uncertain execution separately");
+                            const decisions = this.db.prepare("SELECT decision_id,status,decision_json FROM human_decisions WHERE run_id=? AND decision_key LIKE ?").all(runId, `${runId}:qa-nonconvergence:%`).filter(row => this.decisionWorkId(parseJson(row.decision_json)) === workId && parseJson(row.decision_json).createdAt >= latest.createdAt);
+                            if (decisions.some(row => row.status === "answered"))
+                                throw new Error("The nonconvergence decision was already answered; resume that decision before requesting another attempt");
+                            authorization = this.authorizeQaRemediation(runId, workId, latest.attemptId, record.request.text);
+                            for (const row of decisions.filter(row => row.status === "pending")) {
+                                const decision = parseJson(row.decision_json);
+                                const at = new Date().toISOString();
+                                this.db.prepare("UPDATE human_decisions SET status='cancelled',decision_json=?,updated_at=? WHERE decision_id=? AND status='pending'").run(json({ ...decision, status: "cancelled", cancellationReason: `Superseded by scoped attempt instruction ${record.instructionId}`, cancelledAt: at }), at, row.decision_id);
+                                this.insertEvent(runId, "human_decision_cancelled", "attempt-authorized", { decisionId: row.decision_id, instructionId: record.instructionId }, at);
+                            }
+                            if (head.state === "operator-menu")
+                                this.transitionQa(runId, workId, head.revision, { type: "failed-review-restored", reviewNumber: latest.reviewNumber, sourceStateDigest: latest.sourceDigest, reportDigest: report.reportDigest });
+                            completeControl(this.db, record.instructionId, { authorizationId: authorization, reviewAttemptId: latest.attemptId, consumed: false });
+                        }
+                    });
+                }
+                catch (error) {
+                    authorization = priorAuthorization;
+                    completeControl(this.db, record.instructionId, undefined, String(error));
+                }
+            }
+            return authorization;
+        });
+    }
+    reconcileWork(request, input) {
+        this.assertInstructionOwner(request.runId);
+        if (this.writerAuthority)
+            assertAdmission(this.db, this.writerAuthority);
+        this.workAuthority++;
+        try {
+            return this.atomic(() => reconcileWork(this.db, request, input));
+        }
+        finally {
+            this.workAuthority--;
+        }
+    }
+    reconciliation(id) {
+        const row = this.db.prepare("SELECT record_json FROM build_reconciliations WHERE reconciliation_id=?").get(id);
+        return row ? JSON.parse(row.record_json) : undefined;
+    }
+    workDefinitions(runId) {
+        return this.db.prepare("SELECT work_id,kind,definition_json FROM build_work_scope WHERE run_id=? AND state='admitted' ORDER BY rowid").all(runId).map(row => ({ workId: row.work_id, kind: row.kind, definition: JSON.parse(row.definition_json) }));
+    }
+    recordWorkAssignment(runId, workId, operationId, record) {
+        this.assertInstructionOwner(runId);
+        const admission = this.assertAdmittedWork(runId, workId);
+        this.qaPreparationStore().metric(runId, workId, admission.requirementsDigest, `metric:started:${runId}:${workId}:${admission.requirementsDigest}`, "implementation-started");
+        this.workAuthority++;
+        try {
+            this.db.prepare("INSERT INTO build_assignments VALUES(?,?,?,?,?)").run(operationId, runId, workId, operationId, json(record));
+        }
+        finally {
+            this.workAuthority--;
+        }
+    }
+    admittedWork(runId, workId) { return admittedWork(this.db, runId, workId); }
+    assertAdmittedWork(runId, workId) { return assertAdmittedWork(this.db, runId, workId); }
     /** Atomic local changes only; never await provider or filesystem work here. */
     atomic(work) { return this.db.transaction(work).immediate(); }
     buildAdmission() { return readAdmission(this.db); }
@@ -685,6 +853,9 @@ export class WorkflowDb {
         this.ensureRun(input.runId, "build", now);
         const at = now.toISOString();
         const safePayload = sanitizeContinuityValue(input.payload);
+        const graphAccess = currentGraphDerivedAccess();
+        if (graphAccess)
+            registerGraphDerived(this.db, json(safePayload), graphAccess);
         const session = sessionParts(input.sessionRef, undefined, input.sessionKey);
         const digest = digestJson({ runId: input.runId, role: input.role, kind: input.kind, payload: safePayload, authoritativeStateRevision: input.authoritativeStateRevision, sessionKey: session.key, at });
         const result = this.db.prepare(`INSERT INTO continuity_events(run_id,role,kind,payload_json,digest,authoritative_state_revision,session_key,session_ref_json,created_at)
@@ -693,6 +864,8 @@ export class WorkflowDb {
     }
     continuityEvents(runId, afterSequence = 0) {
         const rows = this.db.prepare("SELECT * FROM continuity_events WHERE run_id=? AND sequence>? ORDER BY sequence").all(runId, afterSequence);
+        for (const row of rows)
+            this.assertGraphContinuityAccess(row.payload_json);
         return rows.map(continuityEventFromRow);
     }
     publishContinuityCheckpoint(input, now = new Date()) {
@@ -702,6 +875,9 @@ export class WorkflowDb {
             const previous = this.continuityHead(input.runId, input.role);
             const latestEvent = this.db.prepare("SELECT COALESCE(MAX(sequence),0) AS sequence FROM continuity_events WHERE run_id=?").get(input.runId);
             const safeDelta = sanitizeContinuityValue(input.delta);
+            const graphAccess = currentGraphDerivedAccess();
+            if (graphAccess)
+                registerGraphDerived(this.db, json(safeDelta), graphAccess);
             const session = sessionParts(input.sessionRef, undefined, input.sessionKey);
             const digest = digestJson({ runId: input.runId, role: input.role, sequence: latestEvent.sequence, predecessorDigest: previous?.digest, delta: safeDelta, authoritativeStateRevision: input.authoritativeStateRevision, sessionKey: session.key });
             const result = this.db.prepare(`INSERT INTO continuity_checkpoints(run_id,role,event_sequence,state,delta_json,digest,predecessor_digest,authoritative_state_revision,session_key,session_ref_json,created_at)
@@ -723,12 +899,21 @@ export class WorkflowDb {
         const rows = role
             ? this.db.prepare("SELECT * FROM continuity_checkpoints WHERE run_id=? AND role=? ORDER BY checkpoint_id").all(runId, role)
             : this.db.prepare("SELECT * FROM continuity_checkpoints WHERE run_id=? ORDER BY checkpoint_id").all(runId);
+        for (const row of rows)
+            this.assertGraphContinuityAccess(row.delta_json);
         return rows.map(continuityCheckpointFromRow);
     }
     latestContinuityCheckpoint(runId, role) {
         const row = this.db.prepare("SELECT * FROM continuity_checkpoints WHERE run_id=? AND role=? ORDER BY checkpoint_id DESC LIMIT 1").get(runId, role);
+        if (row)
+            this.assertGraphContinuityAccess(row.delta_json);
         return row ? continuityCheckpointFromRow(row) : undefined;
     }
+    assertGraphContinuityAccess(value) {
+        const digest = createHash("sha256").update(value).digest("hex");
+        if (!graphDerivedAllowed(this.db, this.projectDir, digest))
+            throw new Error("Continuity contains revoked graph-derived evidence; explicit source-based recovery is required");
+    }
     continuityHead(runId, role) {
         const row = this.db.prepare("SELECT * FROM continuity_heads WHERE run_id=? AND role=?").get(runId, role);
         return row ? continuityHeadFromRow(row) : undefined;
@@ -858,6 +1043,18 @@ export class WorkflowDb {
         })();
         return decision;
     }
+    cancelPendingHumanDecisions(runId, reason, now = new Date()) {
+        this.atomic(() => {
+            for (const decision of this.pendingHumanDecisions(runId)) {
+                const next = { ...decision, status: "cancelled", cancellationReason: reason, cancelledAt: now.toISOString() };
+                this.db.prepare("UPDATE human_decisions SET status='cancelled',decision_json=?,updated_at=? WHERE decision_id=? AND status='pending'").run(json(next), now.toISOString(), decision.decisionId);
+                this.insertEvent(runId, "human_decision_cancelled", "cancelled", { decisionId: decision.decisionId, reason }, now.toISOString());
+            }
+        });
+    }
+    humanDecisionKey(decisionId) {
+        return this.db.prepare("SELECT decision_key FROM human_decisions WHERE decision_id=?").get(decisionId)?.decision_key;
+    }
     humanDecision(decisionId) {
         const row = this.db.prepare("SELECT decision_json FROM human_decisions WHERE decision_id=?").get(decisionId);
         return row ? parseJson(row.decision_json) : undefined;
@@ -866,21 +1063,39 @@ export class WorkflowDb {
         return this.db.prepare("SELECT decision_json FROM human_decisions WHERE run_id=? AND status='pending' ORDER BY created_at").all(runId)
             .map((row) => parseJson(row.decision_json));
     }
+    decisionContinuationAvailable(runId, decisionId) {
+        const prior = this.operations(runId).filter(op => op.kind === "decision-continuation" && op.intent.decisionId === decisionId);
+        return prior.every(op => op.status === "failed" && op.result?.dispatchState === "not-sent");
+    }
+    nextDecisionContinuationKey(runId, decisionId) {
+        if (!this.decisionContinuationAvailable(runId, decisionId))
+            throw new Error("Decision continuation requires reconciliation before replay");
+        const count = this.operations(runId).filter(op => op.kind === "decision-continuation" && op.intent.decisionId === decisionId).length;
+        return `decision-continuation:${decisionId}${count ? `:retry-${count}` : ""}`;
+    }
     answeredTicketDecisions(runId, scopeRevision) {
         return this.db.prepare("SELECT decision_key,decision_json FROM human_decisions WHERE run_id=? AND status='answered'").all(runId)
             .filter(row => row.decision_key.includes(`:${scopeRevision}:`))
             .map(row => parseJson(row.decision_json))
-            .filter(decision => decision.interruptionId.startsWith("ticket:") && !this.operation(`decision-continuation:${decision.decisionId}`) && !this.operation(`decision-supersession:${decision.decisionId}`));
+            .filter(decision => decision.interruptionId.startsWith("ticket:") && this.decisionContinuationAvailable(runId, decision.decisionId) && !this.operation(`decision-supersession:${decision.decisionId}`));
     }
     /** Unconsumed answers to an older definition must not silently reopen a ticket. */
     staleTicketDecisions(runId, scopeRevision) {
         return this.db.prepare("SELECT decision_key,decision_json FROM human_decisions WHERE run_id=? AND status='answered'").all(runId)
             .filter(row => !row.decision_key.includes(`:${scopeRevision}:`))
             .map(row => parseJson(row.decision_json))
-            .filter(decision => decision.interruptionId.startsWith("ticket:") && !this.operation(`decision-continuation:${decision.decisionId}`) && !this.operation(`decision-supersession:${decision.decisionId}`));
+            .filter(decision => decision.interruptionId.startsWith("ticket:") && this.decisionContinuationAvailable(runId, decision.decisionId) && !this.operation(`decision-supersession:${decision.decisionId}`));
     }
     refreshStaleTicketDecisions(runId, scopeRevision, tickets) {
         this.atomic(() => {
+            for (const prior of this.pendingHumanDecisions(runId)) {
+                const key = this.humanDecisionKey(prior.decisionId) ?? "";
+                if (!prior.interruptionId.startsWith("ticket:") || tickets && !tickets.includes(prior.interruptionId.slice(7)) || key.includes(`:${scopeRevision}:`) || !(key.startsWith(`${runId}:builder:`) || key.startsWith(`${runId}:ticket-question:`)))
+                    continue;
+                this.ensureHumanDecision({ runId, decisionKey: `${runId}:ticket-question:${scopeRevision}:supersedes:${prior.decisionId}`, interruptionId: prior.interruptionId, prompt: prior.prompt, choices: prior.choices, evidence: prior.evidence });
+                this.db.prepare("UPDATE human_decisions SET status='cancelled',decision_json=?,updated_at=? WHERE decision_id=? AND status='pending'").run(json({ ...prior, status: "cancelled", cancellationReason: "ticket scope changed before the question was answered" }), new Date().toISOString(), prior.decisionId);
+                this.insertEvent(runId, "human_decision_superseded", "question-revised", { decisionId: prior.decisionId, scopeRevision }, new Date().toISOString());
+            }
             for (const prior of this.staleTicketDecisions(runId, scopeRevision)) {
                 if (tickets && !tickets.includes(prior.interruptionId.slice(7)))
                     continue;
@@ -962,6 +1177,12 @@ export class WorkflowDb {
         this.db.transaction(() => {
             this.db.prepare("UPDATE operation_journal SET status=?,result_json=?,external_id=?,error=?,updated_at=? WHERE idempotency_key=?")
                 .run(status, details.result === undefined ? null : json(details.result), details.externalId ?? null, details.error ?? null, at, idempotencyKey);
+            if (status === "confirmed" && ["ticket-complete", "synthetic-completion"].includes(prior.kind)) {
+                const workId = prior.intent.workId ?? prior.intent.ticket ?? prior.intent.ticketId;
+                const admission = workId && this.admittedWork(prior.runId, workId);
+                if (admission)
+                    this.qaPreparationStore().metric(prior.runId, workId, admission.requirementsDigest, `metric:completed:${prior.runId}:${workId}`, "completed", { status: this.getRun(prior.runId)?.state?.qaEnabled === false ? "disabled" : undefined, at });
+            }
             this.appendContinuityEvent({ runId: prior.runId, role: "host", kind: "operation_receipt", payload: { idempotencyKey, kind: prior.kind, status, externalId: details.externalId, error: details.error }, authoritativeStateRevision: this.continuityHead(prior.runId, "run")?.authoritativeStateRevision ?? 0 }, now);
         })();
         return this.operation(idempotencyKey);
@@ -995,9 +1216,15 @@ export class WorkflowDb {
             throw new Error(`${kind} evidence exceeds the durable ${maximum}-byte item limit`);
         const digest = createHash("sha256").update(bytes).digest("hex");
         this.db.prepare("INSERT OR IGNORE INTO content_refs(digest,kind,content,created_at) VALUES(?,?,?,?)").run(digest, kind, bytes, now.toISOString());
+        const graphAccess = currentGraphDerivedAccess();
+        if (graphAccess && (kind === "qa" || kind === "handoff"))
+            registerGraphDerived(this.db, bytes, graphAccess);
         return digest;
     }
+    registerGraphEvidence(value, access) { registerGraphDerived(this.db, value, access); }
     getEvidence(digest) {
+        if (!graphDerivedAllowed(this.db, this.projectDir, digest))
+            return undefined;
         const row = this.db.prepare("SELECT content FROM content_refs WHERE digest=?").get(digest);
         return row?.content;
     }
@@ -1052,6 +1279,11 @@ export class WorkflowDb {
         const next = { ...prior, ...patch, updatedAt: now.toISOString() };
         this.db.prepare("UPDATE qa_review_attempts SET status=?,report_digest=?,record_json=?,updated_at=? WHERE attempt_id=?")
             .run(next.status, next.reportDigest ?? null, json({ findingIds: next.findingIds, namespacedFindingIds: next.namespacedFindingIds, detail: next.detail }), next.updatedAt, attemptId);
+        const admission = this.admittedWork(next.runId, next.ticketId);
+        const turns = this.db.prepare("SELECT receipt_json FROM qa_turns WHERE run_id=? AND ticket_id=? AND review_number=? AND status='completed'").all(next.runId, next.ticketId, next.reviewNumber);
+        const terminalBlock = turns.some(row => { const receipt = parseJson(row.receipt_json); const response = receipt.cleanedResponseDigest && this.getEvidence(receipt.cleanedResponseDigest); return receipt.terminalEventObserved && response && /STEP_STATUS:\s*(blocked|needs_input)\b/.test(response.toString()); });
+        if (admission && (next.status === "passed" || next.status === "failed" || terminalBlock))
+            this.qaPreparationStore().metric(next.runId, next.ticketId, admission.requirementsDigest, `metric:review:${attemptId}`, "substantive-review", { status: next.status === "passed" ? "passed" : next.status === "failed" ? "failed" : "blocked", at: now.toISOString(), evidenceRefs: next.reportDigest ? [next.reportDigest] : [] });
         return next;
     }
     qaReviewAttempts(runId, ticketId) {
@@ -1107,6 +1339,8 @@ export class WorkflowDb {
             .run(record.invocationId, record.runId, record.ticketId, qaDigest("handback-invocation", intent), json(intent), record.status, json(record), record.startedAt, record.completedAt ?? new Date().toISOString());
     }
     recordQaDeliveryTurn(turn) {
+        if (turn.version === 4)
+            ensureQaGraphJournalGuards(this.db);
         const prior = this.qaDeliveryTurns(turn.operationId).find(t => t.turnRecordId === turn.turnRecordId);
         if (prior) {
             if (prior.status !== "intended") {
@@ -1146,7 +1380,8 @@ export class WorkflowDb {
         if (linked.size !== recoveries.length)
             throw new Error("QA remediation budget requires legacy attempt reconciliation");
         const authorized = new Set(this.db.prepare("SELECT consumed_by FROM qa_remediation_authorizations WHERE run_id=? AND ticket_id=? AND consumed_by IS NOT NULL").all(runId, ticketId).map(r => r.consumed_by));
-        return attempts.filter(a => !authorized.has(a.attemptId)).length;
+        const followups = this.operations(runId).filter(operation => operation.kind === "build-assignment" && operation.intent.ticketId === ticketId && operation.intent.managerFollowup);
+        return attempts.filter(a => !authorized.has(a.attemptId)).length + followups.filter(operation => !authorized.has(operation.idempotencyKey)).length;
     }
     authorizeQaRemediation(runId, ticketId, reviewAttemptId, reason) {
         const authorizationId = randomUUID();
@@ -1397,6 +1632,12 @@ export class WorkflowDb {
         return this.db.transaction(() => {
             const predecessors = this.unresolvedQaReports(input.runId, input.ticketId);
             const current = this.recordQaReport(input, findingIds, now);
+            const admission = this.admittedWork(input.runId, input.ticketId), preparation = this.qaPreparationStore();
+            if (admission && preparation.policy(input.runId)) {
+                const evidence = preparation.putArtifact("finding-classification-input", { report: input, contractHead: preparation.head(input.runId, input.ticketId, admission.requirementsDigest), evidenceDisposition: "Cause remains unknown until supported assessment" });
+                for (const findingId of findingIds)
+                    preparation.metric(input.runId, input.ticketId, admission.requirementsDigest, `metric:finding-unknown:${current.reportOccurrenceId}:${findingId}`, "finding-classification", { findingId, classifier: "host-evidence-boundary", cause: "unknown", confidence: "unknown", evidenceRefs: [evidence], at: now.toISOString() });
+            }
             for (const predecessor of predecessors) {
                 if (predecessor.reportOccurrenceId === current.reportOccurrenceId)
                     continue;
@@ -1468,13 +1709,38 @@ export class WorkflowDb {
         for (const report of this.unresolvedQaReports(runId, ticketId))
             this.setQaReportDisposition(report.reportOccurrenceId, "verified-fixed", "subsequent bound QA review passed", now);
     }
-    commitQaWaiver(runId, ticketId, expectedRevision, reason, now = new Date()) {
+    authorizeContractQaWaiver(runId, workId, decisionId) {
+        this.assertInstructionOwner(runId);
+        const decision = this.humanDecision(decisionId);
+        if (!decision || decision.runId !== runId || decision.status !== "answered" || decision.selectedChoiceId !== "yes" || decision.interruptionId !== `ticket:${workId}` || !this.humanDecisionKey(decisionId)?.startsWith(`${runId}:qa-nonconvergence:`) || !decision.prompt.includes("QA waiver confirmation"))
+            throw new Error("Whole-work waiver requires the actual answered operator confirmation");
+        const admission = this.assertAdmittedWork(runId, workId), store = this.qaPreparationStore(), head = store.head(runId, workId, admission.requirementsDigest), qa = this.qaTicketHead(runId, workId);
+        if (head.state !== "ready" || !head.digest)
+            throw new Error("Whole-work waiver requires a current ready contract");
+        return store.putArtifact("waiver-authorization", { decisionId, runId, workId, admissionDigest: admission.requirementsDigest, contractDigest: head.digest, qaRevision: qa.revision, sourceDigest: qa.sourceStateDigest, reviewBasisDigest: qa.reviewBasisDigest, authorizedAt: decision.answeredAt });
+    }
+    commitQaWaiver(runId, ticketId, expectedRevision, reason, now = new Date(), authorizationRef) {
         return this.db.transaction(() => {
             const head = this.qaTicketHead(runId, ticketId);
             if (head.revision !== expectedRevision)
                 throw new Error(`QA waiver raced for ${runId}/${ticketId}`);
+            const store = this.qaPreparationStore();
+            if (store.policy(runId)?.mode === "enforce") {
+                const admission = this.assertAdmittedWork(runId, ticketId), contractHead = store.head(runId, ticketId, admission.requirementsDigest);
+                if (contractHead.state !== "ready" || !contractHead.digest || !reason.trim())
+                    throw new Error("Whole-work waiver requires exact contract scope and operator reason");
+                const authority = authorizationRef ? store.artifact(authorizationRef, "waiver-authorization") : undefined;
+                const decision = authority && this.humanDecision(authority.decisionId);
+                if (!authority || authority.runId !== runId || authority.workId !== ticketId || authority.admissionDigest !== admission.requirementsDigest || authority.contractDigest !== contractHead.digest || authority.qaRevision !== expectedRevision || authority.sourceDigest !== head.sourceStateDigest || authority.reviewBasisDigest !== head.reviewBasisDigest || decision?.status !== "answered" || decision.selectedChoiceId !== "yes")
+                    throw new Error("Missing or stale whole-work waiver authorization");
+                const contract = store.contract(contractHead.digest), review = this.qaReviewAttempts(runId, ticketId).at(-1);
+                store.event(runId, ticketId, `whole-work-waiver:${runId}:${ticketId}:${head.revision}`, "whole-work-waiver", { version: 1, runId, workId: ticketId, admissionDigest: admission.requirementsDigest, contractDigest: contract.contentDigest, revision: contract.revision, sourceDigest: review?.sourceDigest ?? null, reviewBasisDigest: head.reviewBasisDigest ?? null, mandatoryCheckIds: contract.checks.filter(check => check.obligation === "mandatory").map(check => check.id), unresolvedReports: this.unresolvedQaReports(runId, ticketId).map(report => report.reportOccurrenceId), reason, actor: "operator", authorizationRef, decisionId: authority.decisionId, mechanism: "existing-qa-nonconvergence-decision", at: now.toISOString(), completion: "waived" });
+            }
             for (const report of this.unresolvedQaReports(runId, ticketId))
                 this.setQaReportDisposition(report.reportOccurrenceId, "waived", reason, now);
+            const admission = this.admittedWork(runId, ticketId);
+            if (admission)
+                store.metric(runId, ticketId, admission.requirementsDigest, `metric:waiver:${runId}:${ticketId}:${head.revision}`, "waived", { at: now.toISOString() });
             return this.transitionQa(runId, ticketId, head.revision, { type: "waived" }, now);
         })();
     }
@@ -1499,6 +1765,11 @@ export class WorkflowDb {
         return this.db.transaction(() => {
             this.recordBuilderRemediationReceipt(receipt);
             this.markQaReportsRecheckRequired(receipt.runId, receipt.ticketId, "Builder remediation received; QA recheck required", now);
+            const admission = this.admittedWork(receipt.runId, receipt.ticketId);
+            const remediation = this.qaRemediationAttempt(receipt.operationId);
+            const review = remediation ? this.qaReviewAttempt(remediation.reviewAttemptId) : undefined;
+            if (admission)
+                this.qaPreparationStore().metric(receipt.runId, receipt.ticketId, admission.requirementsDigest, `metric:remediation:${receipt.operationId}`, "remediation", { phase: "remediation", findingIds: review?.namespacedFindingIds ?? [], at: now.toISOString() });
             return this.transitionQa(receipt.runId, receipt.ticketId, expectedRevision, { type: "remediation-received" }, now);
         })();
     }
@@ -1520,7 +1791,60 @@ export class WorkflowDb {
             return this.transitionQa(remediation.runId, remediation.ticketId, head.revision, { type: input.outcome === "uncertain" ? "remediation-uncertain" : "remediation-failed" }, now);
         })();
     }
+    assertContractCertificate(input) {
+        const store = this.qaPreparationStore();
+        if (store.policy(input.runId)?.mode !== "enforce")
+            return;
+        const binding = input.contractCoverage;
+        if (!binding || binding.version !== 1)
+            throw new Error("Enforcing pass requires tagged contract coverage authority");
+        const admission = this.assertAdmittedWork(input.runId, input.ticketId);
+        const head = store.head(input.runId, input.ticketId, admission.requirementsDigest);
+        if (head.state !== "ready" || head.digest !== binding.contractDigest)
+            throw new Error("Pass contract is stale or incomplete");
+        const contract = store.contract(binding.contractDigest);
+        if (contract.revision !== binding.revision)
+            throw new Error("Pass revision mismatch");
+        const basisRow = this.db.prepare("SELECT basis_json FROM qa_review_bases WHERE digest=? AND run_id=? AND ticket_id=?").get(input.reviewBasisDigest, input.runId, input.ticketId);
+        if (!basisRow)
+            throw new Error("Pass lacks immutable input basis");
+        const basis = parseJson(basisRow.basis_json);
+        const definition = this.workDefinitions(input.runId).find(work => work.workId === input.ticketId)?.definition;
+        if (!definition || basis.ticketDigest !== qaDigest("ticket", definition))
+            throw new Error("Pass ticket basis differs from frozen admitted scope");
+        const { digest, ...fields } = basis;
+        if (digest !== qaDigest("review-basis-fields", fields) || basis.contractBinding?.digest !== contract.contentDigest || basis.contractBinding.admissionDigest !== admission.requirementsDigest)
+            throw new Error("Pass basis/contract binding mismatch");
+        const configuredMake = this.getRun(input.runId)?.state?.qa?.settings?.make;
+        if (configuredMake && resolveEffectiveQaConfiguration(this.projectDir, { make: configuredMake }).digest !== basis.contractBinding.commonConfigDigest)
+            throw new Error("Effective QA configuration changed before pass authority; reconcile contract");
+        const attempt = this.qaReviewAttempt(binding.attemptId);
+        if (!attempt || attempt.runId !== input.runId || attempt.ticketId !== input.ticketId || attempt.sourceDigest !== input.sourceStateDigest || attempt.reviewNumber !== this.qaTicketHead(input.runId, input.ticketId).reviewNumber)
+            throw new Error("Coverage review attempt is stale or foreign");
+        const coverage = store.artifact(binding.coverageDigest, "final-coverage");
+        for (const check of contract.checks)
+            for (const method of check.verification)
+                if (method.equivalentAuthorityId && !store.equivalentResolver()(method.equivalentAuthorityId, contract, check, method, input.sourceStateDigest))
+                    throw new Error("Equivalent verification authority is stale or foreign");
+        const errors = validateContractCoverage(contract, coverage, { phase: "qa", sourceDigest: input.sourceStateDigest, inputBasisDigest: input.reviewBasisDigest, attemptId: binding.attemptId, sessionId: binding.sessionId });
+        if (errors.length)
+            throw new Error(errors.join("; "));
+        const initialTurns = this.db.prepare("SELECT intent_json FROM qa_turns WHERE run_id=? AND ticket_id=? AND review_number=? AND source_state_digest=? AND review_basis_digest=?").all(input.runId, input.ticketId, attempt.reviewNumber, input.sourceStateDigest, input.reviewBasisDigest);
+        const initial = initialTurns.map(row => parseJson(row.intent_json)).find(turn => turn.slot === "initial");
+        if (!initial || initial.providerSession.sessionId !== binding.sessionId)
+            throw new Error("Coverage lacks the actual fresh review dispatch identity");
+        const dispatchedInstruction = this.getEvidence(initial.instructionDigest)?.toString();
+        const envelope = `\nImmutable input-basis digest: ${basis.digest}. Coverage must bind this inputBasisDigest.`;
+        if (basis.contractBinding.transportVersion !== 1 || !dispatchedInstruction?.endsWith(envelope) || qaDigest("instruction", dispatchedInstruction.slice(0, -envelope.length)) !== basis.instructionDigest)
+            throw new Error("Actual review dispatch differs from frozen base instruction and tagged input-basis envelope");
+        const receipts = this.db.prepare("SELECT receipt_json FROM qa_turns WHERE run_id=? AND ticket_id=? AND source_state_digest=? AND review_basis_digest=? AND status='completed'").all(input.runId, input.ticketId, input.sourceStateDigest, input.reviewBasisDigest);
+        const receipt = receipts.map(row => parseJson(row.receipt_json)).find(row => qaDigest("turn-receipt", row) === input.turnReceiptDigest && row.terminalEventObserved);
+        const response = receipt?.cleanedResponseDigest ? this.getEvidence(receipt.cleanedResponseDigest) : undefined;
+        if (!receipt || !response || canonicalJson(parseContractCoverage(response.toString())) !== canonicalJson(coverage))
+            throw new Error("Coverage is not bound to the retained terminal review receipt");
+    }
     issueQaPassCertificate(input, now = new Date()) {
+        this.assertContractCertificate(input);
         if (this.unresolvedQaReports(input.runId, input.ticketId).length)
             throw new Error("cannot issue QA pass certificate while reports remain unresolved");
         const certificate = { version: 2, certificateId: qaDigest("pass-certificate", { ...input, issuedAt: now.toISOString() }), ...input, unresolvedReportCount: 0, issuedAt: now.toISOString() };
@@ -1545,6 +1869,7 @@ export class WorkflowDb {
                 || attempt.sourceDigest !== input.sourceStateDigest || attempt.status !== "started") {
                 throw new Error(`QA pass attempt binding mismatch: ${attemptId}`);
             }
+            this.assertContractCertificate(input);
             this.finishQaReviewAttempt(attemptId, { status: "passed", detail }, now);
             return this.commitQaPass(input, expectedRevision, now);
         })();
@@ -1556,6 +1881,7 @@ export class WorkflowDb {
                 throw new Error("QA pass certificate is missing or scoped to another run/ticket");
             if (row.consumed_at)
                 throw new Error("QA pass certificate has already been consumed");
+            this.assertContractCertificate(parseJson(row.certificate_json));
             if (this.unresolvedQaReports(runId, ticketId).length)
                 throw new Error("QA pass certificate cannot be consumed with unresolved reports");
             const at = now.toISOString();
@@ -1566,9 +1892,9 @@ export class WorkflowDb {
             return certificate;
         })();
     }
-    invalidateUnconsumedQaPassCertificates(runId, ticketId, reason, now = new Date()) {
+    invalidateUnconsumedQaPassCertificates(runId, ticketId, reason, now = new Date(), issuedBefore) {
         const at = now.toISOString();
-        this.db.prepare("UPDATE qa_pass_certificates SET consumed_at=?,consumed_by=? WHERE run_id=? AND ticket_id=? AND consumed_at IS NULL").run(at, `invalidated:${reason}`, runId, ticketId);
+        this.db.prepare("UPDATE qa_pass_certificates SET consumed_at=?,consumed_by=? WHERE run_id=? AND ticket_id=? AND consumed_at IS NULL AND (? IS NULL OR issued_at<=?)").run(at, `invalidated:${reason}`, runId, ticketId, issuedBefore ?? null, issuedBefore ?? null);
     }
     invalidateQaPassBeforeFinalization(input, now = new Date()) {
         return this.db.transaction(() => {
@@ -1584,6 +1910,7 @@ export class WorkflowDb {
     }
     beginQaFinalization(input, now = new Date()) {
         return this.db.transaction(() => {
+            this.assertFinalizationControls(input.runId, input.ticketId);
             const head = this.qaTicketHead(input.runId, input.ticketId);
             if (head.revision !== input.expectedRevision || head.state !== "passed")
                 throw new Error(`QA finalization start raced for ${input.runId}/${input.ticketId}`);
@@ -1660,10 +1987,14 @@ export class WorkflowDb {
     }
     completeQaFinalization(runId, ticketId, expectedRevision, receipt, now = new Date()) {
         return this.db.transaction(() => {
+            this.assertFinalizationControls(runId, ticketId);
             const head = this.qaTicketHead(runId, ticketId);
             if (head.revision !== expectedRevision || head.state !== "finalizing")
                 throw new Error(`QA finalization completion raced for ${runId}/${ticketId}`);
             this.finishPendingQaFinalizationSteps(runId, ticketId, receipt, now);
+            const admission = this.admittedWork(runId, ticketId);
+            if (admission)
+                this.qaPreparationStore().metric(runId, ticketId, admission.requirementsDigest, `metric:completed:${runId}:${ticketId}`, "completed", { at: now.toISOString() });
             return this.transitionQa(runId, ticketId, head.revision, { type: "completed" }, now);
         })();
     }
@@ -2272,7 +2603,7 @@ function leaseVerifiedLive(lease, now, staleMs) {
 function ensureRecoveryGitignore(projectDir) {
     const localExclude = join(projectDir, ".git", "info", "exclude");
     const path = existsSync(localExclude) ? localExclude : join(projectDir, ".gitignore");
-    const entries = [WORKFLOW_DB_FILE, `${WORKFLOW_DB_FILE}-wal`, `${WORKFLOW_DB_FILE}-shm`, ".rafi/cache/handoffs/"];
+    const entries = [WORKFLOW_DB_FILE, `${WORKFLOW_DB_FILE}-wal`, `${WORKFLOW_DB_FILE}-shm`, ".rafi/cache/handoffs/", ".rafi/backups/work-admission-v4/"];
     const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
     const missing = entries.filter((entry) => !existing.split(/\r?\n/).includes(entry));
     if (missing.length)