ai-foreman 1.7.20 → 1.7.21

package/dist/qaReview.js

@@ -1,4 +1,13 @@
+import { withGraphDerivedAccess } from "./graph/derived.js";
+import { dispatchWithGraphAccess } from "./graph/session.js";
+import { finalQaRoleInstructions, resolveEffectiveQaConfiguration } from "./qaEffectiveConfig.js";
+import { COVERAGE_INSTRUCTIONS, parseContractCoverage, validateContractCoverage } from "./qaContractCoverage.js";
+import { contractDigest, renderVerificationContract } from "./qaVerificationContract.js";
+import { finalReviewContractContext } from "./qaContractDelivery.js";
+import { graphContext, parseGraphRequest, prepareGraphInstruction, sendGraphTurn } from "./graph/turn.js";
+import { BuildControlBoundary } from "./buildInterventions.js";
 import { formatRecoveryCommand } from "./recoveryGuidance.js";
+import { assertBuildAssignmentReconciled, BuildAssignmentRejected, captureBuildSource } from "./buildAssignment.js";
 import { checkQaPrerequisites } from "./qaPrerequisites.js";
 import { boundedQaHistory } from "./qaHandbackHistory.js";
 import { QA_FAILURE_REPORT_END, QA_FAILURE_REPORT_START, parseQaResponseContract, qaFailureReportV1Schema, } from "rafi-spec";
@@ -127,6 +136,24 @@ function loadDurableQaHistory(db, runId, ticketId) {
     return { reviews, remediations, history };
 }
 export async function runIsolatedQa(opts) {
+    try {
+        return await withGraphDerivedAccess([], () => runIsolatedQaOwned(opts));
+    }
+    catch (error) {
+        if (error instanceof BuildControlBoundary)
+            return { outcome: "needs-human", detail: error.message };
+        throw error;
+    }
+}
+async function runIsolatedQaOwned(opts) {
+    try {
+        assertBuildAssignmentReconciled(opts.recovery.projectDir, opts.recovery.runId);
+    }
+    catch (error) {
+        if (error instanceof BuildAssignmentRejected)
+            return { outcome: "needs-human", detail: error.message };
+        throw error;
+    }
     if (opts.resumedRecovery && (opts.resumedRecovery.manifest.runId !== opts.recovery.runId || opts.resumedRecovery.manifest.ticketId !== opts.ticket.id)) {
         return { outcome: "needs-human", detail: `QA recovery packet ${opts.resumedRecovery.manifest.runId}/${opts.resumedRecovery.manifest.ticketId} does not match requested scope ${opts.recovery.runId}/${opts.ticket.id}; no QA work was dispatched` };
     }
@@ -135,8 +162,10 @@ export async function runIsolatedQa(opts) {
     let history;
     let durableReviews;
     let durableRemediations;
+    let durableRemediationGeneration;
     try {
         scopeDb.ensureRun(opts.recovery.runId);
+        scopeDb.assertAdmittedWork(opts.recovery.runId, opts.ticket.id);
         durablePolicy = scopeDb.autonomyPolicy(opts.recovery.runId) ?? scopeDb.freezeAutonomyPolicy(opts.recovery.runId, resolveAutonomyPolicy(loadProjectAutonomyConfig(opts.recovery.projectDir)));
         const stop = scopeDb.qaRemediationStop(opts.recovery.runId, opts.ticket.id);
         if (stop) {
@@ -183,6 +212,7 @@ export async function runIsolatedQa(opts) {
             scopeDb.updateQaRemediationAttempt(uncertain.attemptId, "uncertain", { detail: "host restarted without a durable Builder completion receipt" });
         durableRemediations = scopeDb.qaRemediationAttempts(opts.recovery.runId, opts.ticket.id);
         ({ history } = loadDurableQaHistory(scopeDb, opts.recovery.runId, opts.ticket.id));
+        durableRemediationGeneration = scopeDb.qaTicketHead(opts.recovery.runId, opts.ticket.id).remediationGeneration;
     }
     finally {
         scopeDb.close();
@@ -197,13 +227,57 @@ export async function runIsolatedQa(opts) {
     const maxBuilderFixes = Math.min(opts.maxCycles, durableLimit);
     let automaticFixes = persistedQaFixCount(opts);
     let reviewAttempt = Math.max(opts.state.reviews, ...durableReviews.map((item) => item.reviewNumber), 0);
-    let remediationGeneration = Math.max(opts.state.remediationGeneration ?? 0, ...durableReviews.map((item) => item.remediationGeneration), ...durableRemediations.map((item) => item.generation), 0);
+    let remediationGeneration = Math.max(opts.state.remediationGeneration ?? 0, durableRemediationGeneration, ...durableReviews.map((item) => item.remediationGeneration), ...durableRemediations.map((item) => item.generation), 0);
     const resumedHeadDb = new WorkflowDb(opts.recovery.projectDir);
+    resumedHeadDb.reconcileInstructionDeliveries(opts.recovery.runId, opts.ticket.id);
+    opts.qaRemediationAuthorization ??= resumedHeadDb.consumeInstructionControls(opts.recovery.runId, opts.ticket.id, "attempts");
     let resumedHead = resumedHeadDb.qaTicketHead(opts.recovery.runId, opts.ticket.id);
     let resumedReport = resumedHead.state === "review-failed"
         ? resumedHeadDb.unresolvedQaReports(opts.recovery.runId, opts.ticket.id).at(-1)
         : undefined;
     resumedHeadDb.close();
+    if (opts.resumeBuilderGuidance && resumedHead.state === "passed") {
+        const controlDb = new WorkflowDb(opts.recovery.projectDir);
+        let waiting = false;
+        try {
+            const preview = controlDb.reserveGuidance(opts.recovery.runId, opts.ticket.id, "builder", randomUUID(), captureBuildSource(opts.builderWorktree).digest, "Builder follow-up", false);
+            waiting = preview.ids.length > 0;
+        }
+        finally {
+            controlDb.close();
+        }
+        if (waiting) {
+            if (automaticFixes >= maxBuilderFixes && !opts.qaRemediationAuthorization) {
+                const detail = `Builder guidance is waiting, but the attempt allowance is exhausted. Authorize one follow-up with /request-attempt ${opts.recovery.runId} ${opts.ticket.id} <reason>, then resume.`;
+                ensureProtocolPausePacket(opts, resumedHead, "builder-guidance-budget", detail);
+                return { outcome: "needs-human", detail };
+            }
+            if (!opts.deliverBuilderFollowup)
+                return { outcome: "needs-human", detail: "Builder guidance is waiting; resume through the build owner with a validated Builder session" };
+            const latest = durableReviews.at(-1);
+            const instruction = `Builder guidance follow-up after explicit resume.\nTicket scope: ${opts.ticket.id}. Do not substitute another ticket.\nPreserve the previously completed work and all mandatory requirements. Apply only the authorized waiting guidance within the approved ticket scope. If broader permission is needed, stop and explain it.\nApproved ticket requirements:\n${JSON.stringify(opts.ticket)}\nReport the instruction IDs you applied with evidence, then finish with STEP_STATUS: done | ticket="${opts.ticket.id}" summary="...".`;
+            const fix = await opts.deliverBuilderFollowup(instruction, { reviewAttemptId: latest.attemptId, requirementsDigest: qaDigest("admitted-requirements", opts.ticket), maximum: maxBuilderFixes, authorizationId: opts.qaRemediationAuthorization });
+            opts.qaRemediationAuthorization = undefined;
+            if (!fix.ok) {
+                const db = new WorkflowDb(opts.recovery.projectDir);
+                try {
+                    ensureProtocolPausePacket(opts, db.qaTicketHead(opts.recovery.runId, opts.ticket.id), "builder-guidance-stopped", fix.detail ?? "Builder follow-up did not complete");
+                }
+                finally {
+                    db.close();
+                }
+                return { outcome: "needs-human", detail: fix.detail ?? "Builder follow-up did not complete; reconcile its outcome before resuming" };
+            }
+            opts.builderSummary = fix.response;
+            opts.state.builderResponseHistory.push({ ticketId: opts.ticket.id, cycle: latest.cycle, kind: "remediation", response: fix.response, summary: boundedBuilderSummary(fix.summary) });
+            automaticFixes = persistedQaFixCount(opts);
+            remediationGeneration += 1;
+            opts.state.remediationGeneration = remediationGeneration;
+            // The assignment transaction invalidated the old certificate. A complete
+            // fresh review now checks the exact post-follow-up source.
+            opts.resumedRecovery = undefined;
+        }
+    }
     if (resumedHead.state === "review-failed") {
         const resumedReviewNumber = resumedReport?.reviewNumber;
         const causing = resumedReviewNumber === undefined ? undefined : durableReviews.find((item) => item.reviewNumber === resumedReviewNumber)?.attemptId;
@@ -230,7 +304,14 @@ export async function runIsolatedQa(opts) {
     }
     if (resumedHead.state === "review-failed" && resumedReport) {
         const durableReport = resumedReport;
-        if (automaticFixes >= maxBuilderFixes)
+        const attemptControlDb = new WorkflowDb(opts.recovery.projectDir);
+        try {
+            opts.qaRemediationAuthorization ??= attemptControlDb.consumeInstructionControls(opts.recovery.runId, opts.ticket.id, "attempts");
+        }
+        finally {
+            attemptControlDb.close();
+        }
+        if (automaticFixes >= maxBuilderFixes && !opts.qaRemediationAuthorization)
             return pauseQaProtocol(opts, "qa-nonconvergence", `QA remediation budget is exhausted with unresolved report ${durableReport.reportDigest}`, "nonconverged");
         const report = durableReport.report;
         const causing = durableReviews.find((item) => item.reviewNumber === durableReport.reviewNumber)?.attemptId;
@@ -239,7 +320,8 @@ export async function runIsolatedQa(opts) {
         const request = {
             kind: "validated-report", report, reportDigest: resumedReport.reportDigest, history: [...history], latestBuilderResult: latestBuilderResponse(opts),
         };
-        const fix = await observedQaFix(opts, "resuming pending QA remediation", request, causing);
+        const fix = await observedQaFix(opts, "resuming pending QA remediation", request, causing, Boolean(opts.qaRemediationAuthorization));
+        opts.qaRemediationAuthorization = undefined;
         if (!fix.ok)
             return pauseQaProtocol(opts, "builder-remediation-failed", fix.detail ?? "Builder QA remediation failed during restart recovery", fix.outcome === "needs-input" ? "needs-human" : "blocked");
         const fixSummary = boundedBuilderSummary(fix.summary ?? fix.response ?? "Builder reported remediation complete");
@@ -292,9 +374,17 @@ export async function runIsolatedQa(opts) {
             return review;
         reviewAttempt = Math.max(reviewAttempt, review.reviewAttempt);
         history.push({ cycle, reviewAttempt: review.reviewAttempt, remediationGeneration, attemptId: review.reviewAttemptId, outcome: "qa_fail", detail: review.detail, reportDigest: review.reportDigest, report: review.report, findingIds: review.report?.findings.map((finding) => finding.id) });
-        if (automaticFixes < maxBuilderFixes) {
+        const controlDb = new WorkflowDb(opts.recovery.projectDir);
+        try {
+            opts.qaRemediationAuthorization ??= controlDb.consumeInstructionControls(opts.recovery.runId, opts.ticket.id, "attempts");
+        }
+        finally {
+            controlDb.close();
+        }
+        if (automaticFixes < maxBuilderFixes || opts.qaRemediationAuthorization) {
             const request = { kind: "validated-report", report: review.report, reportDigest: review.reportDigest, history: [...history], latestBuilderResult: latestBuilderResponse(opts) };
-            const fix = await observedQaFix(opts, "applying QA fixes", request, review.reviewAttemptId);
+            const fix = await observedQaFix(opts, "applying QA fixes", request, review.reviewAttemptId, Boolean(opts.qaRemediationAuthorization));
+            opts.qaRemediationAuthorization = undefined;
             if (!fix.ok)
                 return pauseQaProtocol(opts, "builder-remediation-failed", fix.detail ?? "Builder QA fix failed", fix.outcome === "needs-input" ? "needs-human" : "blocked");
             const fixSummary = boundedBuilderSummary(fix.summary ?? fix.response ?? fix.detail ?? "Builder reported remediation complete");
@@ -326,7 +416,7 @@ export async function runIsolatedQa(opts) {
         if (decision.action === "pause")
             return pauseQaProtocol(opts, "qa-nonconvergence", detail, "nonconverged");
         if (decision.action === "waive") {
-            waiveV2Reports(opts, "Operator explicitly waived unresolved QA findings");
+            waiveV2Reports(opts, "Operator explicitly waived unresolved QA findings", decision.authorizationRef);
             markQaRecoveryResolved(opts);
             return { outcome: "waived", detail: history.at(-1)?.detail ?? detail, summary: "QA explicitly waived by user" };
         }
@@ -610,7 +700,7 @@ async function oneReview(opts, identity) {
         const missingPrerequisites = prerequisiteEvidence.checks.filter(check => check.outcome === "not_run");
         if (missingPrerequisites.length && !prerequisiteEvidence.sourceDefects.length)
             return { outcome: "blocked", detail: `QA verification prerequisites unavailable; required checks were not_run: ${missingPrerequisites.map(check => check.evidence).join("; ")}. Restore the required environment with existing authority, then resume for fresh QA.` };
-        let handoff = buildQaReviewHandoff(opts.ticket, opts.builderSummary, snapshot.manifest.diffDigest, loadTicketSetupConfigWithDefaults(opts.builderWorktree).build.validation_checklist, snapshot.frozenState.changeSummary, opts.qaHistory);
+        let handoff = buildQaReviewHandoff(opts.ticket, opts.builderSummary, snapshot.manifest.diffDigest, (opts.frozenValidationChecklist ??= [...loadTicketSetupConfigWithDefaults(opts.recovery.projectDir).build.validation_checklist]), snapshot.frozenState.changeSummary, opts.qaHistory);
         handoff += `\nHost prerequisite evidence (availability does not prove provider sandbox access): ${JSON.stringify(prerequisiteEvidence)}\nRecord tests prevented from executing as not_run with the actual reason. Never install dependencies, create a lockfile, provision services, or claim an unconditional pass when required verification was not run.`;
         // Every disposable snapshot has a distinct cwd and therefore must have a
         // fresh provider conversation. Cumulative QA state remains in the durable
@@ -633,7 +723,11 @@ async function oneReview(opts, identity) {
                 return { outcome: "retry-modification" };
             return { outcome: "needs-human", detail };
         }
+        let graphReviewContext = graphContext(opts.recovery.projectDir, snapshot.path, "final-qa", handoff, { accessWorkspace: opts.builderWorktree, operationId: `graph-review:${attemptId}`, logicalTaskId: attemptId, sourceRef: snapshot.frozenState.digest, runId: opts.recovery.runId, workId: opts.ticket.id });
+        let graphPrepared = opts.resumedRecovery ? { instruction: handoff, bytes: 0 } : await prepareGraphInstruction(handoff, graphReviewContext, await qa.contextUsage?.());
+        handoff = graphPrepared.instruction;
         const v2Binding = beginV2Review(opts, snapshot.frozenState, snapshot.path, handoff, qaHandle, { attemptId, cycle, remediationGeneration });
+        handoff = v2Binding.reviewInstruction;
         bindQaTurnAdapter(qa, v2Binding);
         reviewAttempt = v2Binding.reviewNumber;
         identity = { ...identity, reviewAttempt };
@@ -780,12 +874,18 @@ async function oneReview(opts, identity) {
             opts.resumedRecovery = undefined;
         }
         if (resumedFullReviewNeedsBinding) {
-            const resumedReviewBinding = beginV2Review(opts, snapshot.frozenState, snapshot.path, handoff, qaHandle, { attemptId: randomUUID(), cycle, remediationGeneration });
+            const resumedAttemptId = randomUUID();
+            graphReviewContext = { ...graphReviewContext, operationId: `graph-review:${resumedAttemptId}`, logicalTaskId: resumedAttemptId };
+            graphPrepared = await prepareGraphInstruction(handoff, graphReviewContext, await qa.contextUsage?.());
+            handoff = graphPrepared.instruction;
+            const resumedReviewBinding = beginV2Review(opts, snapshot.frozenState, snapshot.path, handoff, qaHandle, { attemptId: resumedAttemptId, cycle, remediationGeneration });
             bindQaTurnAdapter(qa, resumedReviewBinding);
             resumedPacket = resumedReviewBinding.recoveryPacket;
             reviewAttempt = resumedReviewBinding.reviewNumber;
         }
-        let turn = preparedTurn ?? await sendDurableQaTurn(qa, handoff, qaEvents, "initial");
+        let graphSubturn = 0;
+        const activeGraphBinding = qaTurnBindings.get(qa);
+        let turn = preparedTurn ?? await sendGraphTurn(qa, handoff, { ...graphReviewContext, reviewBasisRef: activeGraphBinding.reviewBasisDigest }, undefined, (prompt) => sendDurableQaTurn(qa, prompt, qaEvents, graphSubturn++ === 0 ? "initial" : `graph-evidence-${graphSubturn}`), { ...graphPrepared, instruction: activeGraphBinding.reviewInstruction });
         let status = parseStepStatus(turn.text);
         recoveryContext = qaTurnBindings.get(qa)?.recoveryContext;
         try {
@@ -1471,14 +1571,53 @@ const qaTurnBindings = new WeakMap();
 function beginV2Review(opts, source, reviewedSnapshotPath, instruction, handle, attempt) {
     const db = new WorkflowDb(opts.recovery.projectDir);
     try {
+        const verification = db.builderVerificationContext(opts.recovery.runId, opts.ticket.id, source.digest);
+        instruction += verification.text;
         const sourceV2 = {
             version: 2, runId: opts.recovery.runId, ticketId: opts.ticket.id,
             originDigest: source.originDigest, contentDigest: source.contentDigest, digest: source.digest,
             capturedAt: source.capturedAt, paths: source.pathInventory,
         };
-        const checklist = loadTicketSetupConfigWithDefaults(opts.builderWorktree).build.validation_checklist;
+        const checklist = (opts.frozenValidationChecklist ??= [...loadTicketSetupConfigWithDefaults(opts.recovery.projectDir).build.validation_checklist]);
+        if (canonicalJson(checklist) !== canonicalJson(loadTicketSetupConfigWithDefaults(opts.recovery.projectDir).build.validation_checklist))
+            throw new Error("Canonical checklist changed before QA dispatch; contract/input reconciliation required");
+        const preparationStore = db.qaPreparationStore();
+        const admission = db.assertAdmittedWork(opts.recovery.runId, opts.ticket.id);
+        const contractHead = preparationStore.head(opts.recovery.runId, opts.ticket.id, admission.requirementsDigest);
+        const contract = preparationStore.policy(opts.recovery.runId)?.mode === "enforce" && contractHead.state === "ready" && contractHead.digest ? preparationStore.contract(contractHead.digest) : undefined;
+        if (preparationStore.policy(opts.recovery.runId)?.mode === "enforce" && !contract)
+            throw new Error("Final QA requires the retained ready contract; exact QA recovery must not replay preparation");
+        if (contract) {
+            if (qaDigest("admitted-requirements", opts.ticket) !== admission.requirementsDigest)
+                throw new Error("Final QA ticket differs from the frozen admitted scope; renewed approval is required");
+            const identity = handle.sessionIdentity();
+            const priorAssessment = preparationStore.artifact(contract.semanticAssessmentDigest, "semantic-assessment");
+            const involvedSessions = new Set([...contract.preparationEvidence.map(evidence => evidence.sessionId), priorAssessment.sessionId, priorAssessment.authorSessionId, ...preparationStore.receipts(contract.contentDigest).map(receipt => receipt.sessionId)]);
+            if (contract.challengeReceiptDigest)
+                involvedSessions.add(preparationStore.artifact(contract.challengeReceiptDigest, "approach-challenge").sessionId);
+            if (involvedSessions.has(identity.sessionId))
+                throw new Error("Final reviewer must be independent of preparation, assessment, challenge and Builder conversations");
+            const effective = resolveEffectiveQaConfiguration(opts.recovery.projectDir, { make: handle.adapter.agent });
+            if (effective.digest !== contract.inputs.find(input => input.kind === "rules")?.digest || handle.effectiveRoleInstructions !== finalQaRoleInstructions(effective.qaRules) || canonicalJson(handle.skills.map(skill => ({ name: skill.name, path: skill.path, content: skill.content, digest: skill.digest }))) !== canonicalJson(effective.skills.map(skill => ({ name: skill.name, path: skill.path, content: skill.content, digest: sha(skill.content) }))))
+                throw new Error("Actual final QA rules/skills differ from the frozen canonical contract configuration");
+            const expected = contract.inputs.find(input => input.kind === "checklist");
+            if (expected?.digest !== contractDigest("input-checklist", checklist))
+                throw new Error("Final QA checklist differs from delivered contract");
+            const builderClaims = db.operations(opts.recovery.runId).flatMap(operation => {
+                const intent = operation.intent;
+                const result = operation.result;
+                return operation.kind === "builder-coverage" && operation.status === "confirmed" && intent.workId === opts.ticket.id && intent.contractDigest === contract.contentDigest && result?.binding?.sourceDigest === source.digest && result.coverageDigest
+                    ? [{ operationId: operation.idempotencyKey, digest: result.coverageDigest, coverage: preparationStore.artifact(result.coverageDigest, "builder-coverage") }] : [];
+            });
+            instruction += finalReviewContractContext(contract, preparationStore, reviewedSnapshotPath, builderClaims);
+            instruction += `\n${renderVerificationContract(contract)}\n${COVERAGE_INSTRUCTIONS}\nCoverage binding: ${JSON.stringify({ phase: "qa", runId: opts.recovery.runId, workId: opts.ticket.id, contractDigest: contract.contentDigest, revision: contract.revision, sourceDigest: source.digest, attemptId: attempt.attemptId, sessionId: handle.sessionIdentity().sessionId })}`;
+        }
+        const originalInstruction = instruction;
+        const guidance = db.reserveGuidance(opts.recovery.runId, opts.ticket.id, "qa", attempt.attemptId, source.digest, instruction, false);
+        instruction = guidance.text;
         const basisWithoutDigest = {
             version: 2,
+            ...(contract ? { contractBinding: { version: 1, transportVersion: 1, revision: contract.revision, digest: contract.contentDigest, admissionDigest: admission.requirementsDigest, commonConfigDigest: contract.inputs.find(input => input.kind === "rules").digest } } : {}),
             ticketDigest: qaDigest("ticket", opts.ticket),
             instructionDigest: qaDigest("instruction", instruction),
             roleInstructionsDigest: qaDigest("role-instructions", handle.effectiveRoleInstructions),
@@ -1488,6 +1627,8 @@ function beginV2Review(opts, source, reviewedSnapshotPath, instruction, handle,
             confinementDigest: handle.confinement.digest,
         };
         const basis = { ...basisWithoutDigest, digest: qaDigest("review-basis-fields", basisWithoutDigest) };
+        const inputBasisEnvelope = contract ? `\nImmutable input-basis digest: ${basis.digest}. Coverage must bind this inputBasisDigest.` : "";
+        instruction += inputBasisEnvelope;
         let head = db.qaTicketHead(opts.recovery.runId, opts.ticket.id);
         if (head.state === "waived" || head.state === "completed")
             throw new Error(`QA protocol for ${opts.ticket.id} is already terminal`);
@@ -1518,7 +1659,7 @@ function beginV2Review(opts, source, reviewedSnapshotPath, instruction, handle,
         head = db.commitQaReviewReady(sourceV2, basis, identity, handle.confinement, attempt, head.revision);
         if (recoveryPacket)
             recoveryPacket = updateQaRecoveryReviewIdentity(recoveryPacket, head.reviewNumber, attempt.attemptId, attempt.cycle);
-        return { projectDir: opts.recovery.projectDir, runId: opts.recovery.runId, ticketId: opts.ticket.id, reviewNumber: head.reviewNumber, reviewAttemptId: attempt.attemptId, sourceStateDigest: source.digest, reviewBasisDigest: basis.digest, sessionGeneration: identity.generation, sessionRef: identity, reviewedSnapshotPath: identity.cwd, frozenSource: source, recoveryPacket, nextTurn: 0 };
+        return { projectDir: opts.recovery.projectDir, runId: opts.recovery.runId, ticketId: opts.ticket.id, reviewNumber: head.reviewNumber, reviewAttemptId: attempt.attemptId, sourceStateDigest: source.digest, reviewBasisDigest: basis.digest, sessionGeneration: identity.generation, sessionRef: identity, reviewedSnapshotPath: identity.cwd, frozenSource: source, recoveryPacket, nextTurn: 0, originalInstruction, inputBasisEnvelope, reviewInstruction: instruction, guidanceIds: guidance.ids, verificationIds: verification.ids };
     }
     finally {
         db.close();
@@ -1566,6 +1707,14 @@ function bindQaRecoveryContext(adapter, context) {
     binding.recoveryContext = context;
 }
 async function sendDurableQaTurn(adapter, instruction, events, slot) {
+    const binding = qaTurnBindings.get(adapter);
+    if (!binding)
+        throw new Error("QA provider dispatch requires a durable source/review-basis binding");
+    // Repairs and recovery acknowledgements bypass graph navigation, but their
+    // provider history and journal artifacts retain the original access grants.
+    return dispatchWithGraphAccess(binding.projectDir, adapter, instruction, undefined, () => sendDurableQaTurnOwned(adapter, instruction, events, slot));
+}
+async function sendDurableQaTurnOwned(adapter, instruction, events, slot) {
     const binding = qaTurnBindings.get(adapter);
     if (!binding)
         throw new Error("QA provider dispatch requires a durable source/review-basis binding");
@@ -1601,17 +1750,27 @@ async function sendDurableQaTurn(adapter, instruction, events, slot) {
     const providerSession = { version: 2, provider: session.provider, sessionId: session.sessionId, role: "qa", stream: "qa", generation: session.generation, cwd: session.cwd, configRoot: session.configRoot, createdAt: session.createdAt, validatedAt: session.validatedAt ?? intendedAt };
     const db = new WorkflowDb(binding.projectDir);
     try {
-        const instructionDigest = db.putEvidence("qa", Buffer.from(instruction));
-        const intent = { version: 2, operationId, runId: binding.runId, ticketId: binding.ticketId, reviewNumber: binding.reviewNumber, sessionGeneration: binding.sessionGeneration, slot: retrySlot, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest, providerSession, instructionDigest, intendedAt };
-        const head = db.qaTicketHead(binding.runId, binding.ticketId);
-        db.commitQaTurnIntent(intent, head.revision);
+        db.atomic(() => {
+            if (slot === "initial") {
+                const guidance = db.reserveGuidance(binding.runId, binding.ticketId, "qa", operationId, binding.sourceStateDigest, binding.originalInstruction);
+                if (guidance.text + (binding.inputBasisEnvelope ?? "") !== binding.reviewInstruction)
+                    throw new BuildControlBoundary("Manager guidance changed during QA preparation; restart a full review with the current instruction basis");
+                binding.guidanceIds = guidance.ids;
+                instruction = binding.reviewInstruction;
+            }
+            const instructionDigest = db.putEvidence("qa", Buffer.from(instruction));
+            const intent = { version: 2, operationId, runId: binding.runId, ticketId: binding.ticketId, reviewNumber: binding.reviewNumber, sessionGeneration: binding.sessionGeneration, slot: retrySlot, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest, providerSession, instructionDigest, intendedAt };
+            const head = db.qaTicketHead(binding.runId, binding.ticketId);
+            db.commitQaTurnIntent(intent, head.revision);
+        });
     }
     finally {
         db.close();
     }
     let result;
+    const providerStartedAt = Date.now();
     try {
-        result = await adapter.sendTurn(instruction);
+        result = await adapter.sendTurn(instruction, slot === "session-initialization" ? { purpose: "initialization", responseOnly: true } : slot?.includes("acknowledgement") || slot?.includes("correction") ? { purpose: "response-repair", responseOnly: true } : undefined);
     }
     catch (error) {
         const failedDb = new WorkflowDb(binding.projectDir);
@@ -1682,8 +1841,25 @@ async function sendDurableQaTurn(adapter, instruction, events, slot) {
             providerInstructionDigest, rawResponseDigest, cleanedResponseDigest, eventStreamDigest,
             terminalEventObserved, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest, completedAt,
         };
-        receiptDb.finishQaTurn(receipt);
+        receiptDb.atomic(() => {
+            receiptDb.finishQaTurn(receipt);
+            const metricAdmission = receiptDb.admittedWork(binding.runId, binding.ticketId);
+            if (metricAdmission)
+                receiptDb.qaPreparationStore().metric(binding.runId, binding.ticketId, metricAdmission.requirementsDigest, `metric:qa-turn:${operationId}`, slot?.includes("correction") ? "format-repair" : "phase-observation", { phase: slot?.includes("correction") || slot === "session-initialization" ? "repair" : "review", durationMs: Math.max(0, Date.now() - providerStartedAt), costUsd: result.costAuthoritative ? result.costUsd : null, inputTokens: result.inputTokens ?? null, outputTokens: result.outputTokens ?? null });
+            if (slot === "initial")
+                receiptDb.finishGuidance(binding.guidanceIds, "qa", { submitted: terminalEventObserved ? true : undefined, receipt, applied: terminalEventObserved && binding.guidanceIds.every(id => providerInstruction.includes(id)) });
+        });
         binding.lastReceiptDigest = qaDigest("turn-receipt", receipt);
+        let graphRequest = false;
+        try {
+            graphRequest = Boolean(parseGraphRequest(result.cleanedResponse ?? result.text));
+        }
+        catch {
+            graphRequest = true;
+        }
+        if (!slot?.startsWith("session-") && !graphRequest)
+            binding.lastBusinessReceiptDigest = binding.lastReceiptDigest;
+        binding.lastResponse = result.text;
         if (!terminalEventObserved) {
             const head = receiptDb.qaTicketHead(binding.runId, binding.ticketId);
             receiptDb.transitionQa(binding.runId, binding.ticketId, head.revision, { type: "turn-uncertain" });
@@ -1744,29 +1920,55 @@ function finishV2Failure(opts, adapter, reportDigest, report, rawFindingIds, fin
 }
 function finishV2Pass(opts, adapter, detail) {
     const binding = qaTurnBindings.get(adapter);
-    if (!binding?.lastReceiptDigest)
-        throw new Error("QA pass has no completed durable turn receipt");
+    if (!binding?.lastBusinessReceiptDigest)
+        throw new Error("QA pass has no completed business-verdict receipt");
     const db = new WorkflowDb(binding.projectDir);
     try {
-        const head = db.qaTicketHead(binding.runId, binding.ticketId);
-        const certificate = db.commitQaPassAttempt(binding.reviewAttemptId, { runId: binding.runId, ticketId: binding.ticketId, qaRevision: head.revision + 1, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest, turnReceiptDigest: binding.lastReceiptDigest }, detail, head.revision);
-        return { certificateId: certificate.certificateId, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest };
+        return db.atomic(() => {
+            const head = db.qaTicketHead(binding.runId, binding.ticketId);
+            let contractCoverage;
+            if (db.qaPreparationStore().policy(binding.runId)?.mode === "enforce") {
+                const admission = db.assertAdmittedWork(binding.runId, binding.ticketId);
+                const contractHead = db.qaPreparationStore().head(binding.runId, binding.ticketId, admission.requirementsDigest);
+                if (!contractHead.digest || contractHead.state !== "ready")
+                    throw new Error("Final coverage requires the current ready contract");
+                const contract = db.qaPreparationStore().contract(contractHead.digest);
+                const coverage = parseContractCoverage(binding.lastResponse ?? "");
+                const errors = validateContractCoverage(contract, coverage, { phase: "qa", sourceDigest: binding.sourceStateDigest, inputBasisDigest: binding.reviewBasisDigest, attemptId: binding.reviewAttemptId, sessionId: binding.sessionRef.sessionId });
+                if (errors.length)
+                    throw new Error(`Final QA coverage incomplete: ${errors.join("; ")}`);
+                const coverageDigest = db.qaPreparationStore().putArtifact("final-coverage", coverage);
+                contractCoverage = { version: 1, contractDigest: contract.contentDigest, revision: contract.revision, coverageDigest, attemptId: binding.reviewAttemptId, sessionId: binding.sessionRef.sessionId };
+            }
+            const certificate = db.commitQaPassAttempt(binding.reviewAttemptId, { runId: binding.runId, ticketId: binding.ticketId, qaRevision: head.revision + 1, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest, turnReceiptDigest: binding.lastBusinessReceiptDigest, ...(contractCoverage ? { contractCoverage } : {}) }, detail, head.revision);
+            db.verifyGuidance(binding.guidanceIds, certificate, binding.lastResponse ?? "");
+            db.verifyBuilderGuidance(binding.verificationIds, certificate, binding.lastResponse ?? "", binding.lastBusinessReceiptDigest);
+            return { certificateId: certificate.certificateId, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest };
+        });
     }
     finally {
         db.close();
     }
 }
-function waiveV2Reports(opts, reason) {
+function waiveV2Reports(opts, reason, authorizationRef) {
     const db = new WorkflowDb(opts.recovery.projectDir);
     try {
         const head = db.qaTicketHead(opts.recovery.runId, opts.ticket.id);
-        db.commitQaWaiver(opts.recovery.runId, opts.ticket.id, head.revision, reason);
+        db.commitQaWaiver(opts.recovery.runId, opts.ticket.id, head.revision, reason, undefined, authorizationRef);
     }
     finally {
         db.close();
     }
 }
 export async function beginQaFinalization(projectDir, sourceWorktree, runId, ticketId, certificateId, expectedSourceStateDigest, consumer, allowedProjectionPaths = []) {
+    assertBuildAssignmentReconciled(projectDir, runId);
+    const controlDb = new WorkflowDb(projectDir);
+    try {
+        controlDb.assertFinalizationControls(runId, ticketId);
+    }
+    finally {
+        controlDb.close();
+    }
     const invalidatePass = (reason) => {
         const db = new WorkflowDb(projectDir);
         try {
@@ -1808,6 +2010,14 @@ export async function beginQaFinalization(projectDir, sourceWorktree, runId, tic
     }
 }
 export async function verifyPendingQaFinalizationSource(projectDir, sourceWorktree, runId, ticketId, allowProjection = false, projectionOperationId) {
+    assertBuildAssignmentReconciled(projectDir, runId);
+    const controlDb = new WorkflowDb(projectDir);
+    try {
+        controlDb.assertFinalizationControls(runId, ticketId);
+    }
+    finally {
+        controlDb.close();
+    }
     const db = new WorkflowDb(projectDir);
     let step;
     let projectionAuthorized = !projectionOperationId;

package/dist/qaTimeline.d.ts

@@ -0,0 +1,18 @@
+import { type QaEvidenceSnapshot } from "./qaEvidenceReader.js";
+export interface QaTicketTimeline {
+    counters: {
+        failedReviews: number;
+        passedReviews: number;
+        blockedReviews: number;
+        interruptedReviews: number;
+        pendingReviews: number;
+        malformedResponses: number;
+        corrections: number;
+        remediationFailures: number;
+        uncertainRemediations: number;
+    };
+    events: Array<Record<string, unknown>>;
+    gaps: string[];
+}
+/** All counters are scoped rows. A changed digest is never a code-change explanation. */
+export declare function buildQaTimeline(snapshot: QaEvidenceSnapshot, workId: string): QaTicketTimeline;

package/dist/qaTimeline.js

@@ -0,0 +1,123 @@
+import { decisionBelongsToWork } from "./buildInterventions.js";
+import { evidenceRecord } from "./qaEvidenceReader.js";
+import { parseQaResponseContract } from "rafi-spec";
+/** All counters are scoped rows. A changed digest is never a code-change explanation. */
+export function buildQaTimeline(snapshot, workId) {
+    const scoped = (table) => (snapshot.rows[table] ?? []).filter(row => row.ticket_id === workId);
+    const counters = { failedReviews: 0, passedReviews: 0, blockedReviews: 0, interruptedReviews: 0, pendingReviews: 0, malformedResponses: 0, corrections: 0, remediationFailures: 0, uncertainRemediations: 0 };
+    const events = [];
+    for (const row of scoped("qa_review_attempts")) {
+        const record = evidenceRecord(row);
+        const status = String(row.status);
+        if (status === "failed")
+            counters.failedReviews++;
+        else if (status === "passed")
+            counters.passedReviews++;
+        else if (status === "started")
+            counters.pendingReviews++;
+        else if (status === "interrupted")
+            counters.interruptedReviews++;
+        events.push({ kind: "review", id: row.attempt_id, reviewNumber: row.review_number, status, sourceDigest: row.source_digest, detail: record?.detail, asOf: row.updated_at, sequence: Number(row.review_number), order: 0 });
+    }
+    for (const row of scoped("qa_turns")) {
+        const receipt = evidenceRecord(row, "receipt_json");
+        const slot = String(row.retry_slot);
+        if (/correction|repair/.test(slot))
+            counters.corrections++;
+        const bytes = typeof receipt?.cleanedResponseDigest === "string" ? snapshot.blobs.get(receipt.cleanedResponseDigest) : undefined;
+        const contract = bytes ? parseQaResponseContract(bytes.toString("utf8")) : undefined;
+        const classification = contract ? contract.valid ? contract.status : "malformed" : "unavailable";
+        if (slot === "initial" && classification === "malformed")
+            counters.malformedResponses++;
+        if (slot === "initial" && classification === "blocked")
+            counters.blockedReviews++;
+        events.push({ kind: "qa_turn", id: row.operation_id, reviewNumber: row.review_number, slot, status: row.status, classification, responseDigest: receipt?.rawResponseDigest, sequence: Number(row.review_number), order: 1 });
+    }
+    for (const row of scoped("qa_remediation_attempts")) {
+        if (row.status === "failed")
+            counters.remediationFailures++;
+        if (row.status === "uncertain")
+            counters.uncertainRemediations++;
+        const parent = scoped("qa_review_attempts").find(attempt => attempt.attempt_id === row.review_attempt_id);
+        events.push({ kind: "remediation", id: row.attempt_id, reviewAttemptId: row.review_attempt_id, generation: row.generation, status: row.status, requestDigest: row.request_digest, responseDigest: row.response_digest, verification: "requires subsequent source-bound QA", sequence: Number(parent?.review_number ?? -1), order: 3 });
+    }
+    const prior = new Map();
+    for (const row of scoped("qa_reports").sort((a, b) => Number(a.review_number) - Number(b.review_number))) {
+        const report = evidenceRecord(row, "report_json");
+        const findings = Array.isArray(report?.findings) ? report.findings : [];
+        const correlations = findings.map((value, ordinal) => {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return { ordinal, label: "unavailable", confidence: "unestablished", limitation: "Corrupt retained finding; no issue correlation was inferred" };
+            const finding = value;
+            const key = JSON.stringify([finding.requirement, finding.locations, finding.problem, finding.verification]).toLowerCase().replace(/\s+/g, " ");
+            const previous = prior.get(key);
+            prior.set(key, { occurrenceId: row.report_occurrence_id, ordinal, reviewNumber: row.review_number, disposition: row.disposition });
+            const previousAttempt = previous ? scoped("qa_review_attempts").find(attempt => attempt.review_number === previous.reviewNumber) : undefined;
+            const linkedRemediations = previousAttempt ? scoped("qa_remediation_attempts").filter(remediation => remediation.review_attempt_id === previousAttempt.attempt_id).map(remediation => ({ attemptId: remediation.attempt_id, status: remediation.status, responseDigest: remediation.response_digest })) : [];
+            return { ordinal, rawId: finding.id, label: previous ? "possibly_recurring" : "newly_observed", confidence: previous ? "exact_normalized_content" : "unestablished", previous, linkedRemediations, limitation: "Matching content is correlation; review-local IDs and changed source digests do not prove issue identity or exact code changes" };
+        });
+        events.push({ kind: "report", id: row.report_occurrence_id ?? row.report_digest, reviewNumber: row.review_number, reportDigest: row.report_digest, disposition: row.disposition, correlations, sequence: Number(row.review_number), order: 2 });
+    }
+    for (const table of ["qa_transitions", "qa_pass_certificates", "qa_finalization_steps", "qa_recovery_heads"])
+        for (const row of scoped(table)) {
+            events.push({ kind: table, id: row.operation_id ?? row.certificate_id ?? row.sequence ?? row.packet_id, revision: row.to_revision ?? row.qa_revision ?? row.revision, state: row.status ?? row.pending_action, event: row.event_json ? evidenceRecord(row, "event_json") : undefined, certificateId: row.certificate_id, sourceDigest: row.source_state_digest ?? row.reviewed_state_digest, sequence: Number(row.sequence ?? row.qa_revision ?? row.revision), order: 4 });
+        }
+    for (const row of snapshot.rows.human_decisions ?? []) {
+        const decision = evidenceRecord(row, "decision_json");
+        if (!decisionBelongsToWork(decision, snapshot.runId, workId, (snapshot.rows.qa_remediation_stops ?? []).map(stop => ({ runId: String(stop.run_id), workId: String(stop.ticket_id), operationId: String(stop.operation_id), decisionId: evidenceRecord(stop)?.decisionId }))))
+            continue;
+        events.push({ kind: "human_decision", id: row.decision_id, status: row.status, decision, sequence: -1, order: 5 });
+    }
+    for (const row of snapshot.rows.operation_journal ?? []) {
+        const intent = evidenceRecord(row, "intent_json");
+        if (row.kind !== "build-assignment" || intent?.ticketId !== workId)
+            continue;
+        const result = evidenceRecord(row, "result_json");
+        const diffReferences = [];
+        for (const side of ["before", "after"]) {
+            const source = (side === "before" ? intent?.before : result?.after);
+            if (!source)
+                continue;
+            for (const kind of ["staged", "unstaged"])
+                if (source[`${kind}DiffDigest`] || Array.isArray(source[`${kind}DiffChunks`]))
+                    diffReferences.push({ id: `${row.idempotency_key}:${side}:${kind}`, sourceDigest: source.digest, byteLength: source[`${kind}DiffBytes`], digest: source[`${kind}DiffDigest`], chunks: source[`${kind}DiffChunks`] });
+            for (const [index, file] of (source.untracked ?? []).entries())
+                diffReferences.push({ id: `${row.idempotency_key}:${side}:untracked-${index}`, sourceDigest: source.digest, path: file.path, byteLength: file.byteLength, digest: file.evidenceDigest, chunks: file.evidenceChunks });
+        }
+        events.push({ kind: "builder_assignment", id: row.idempotency_key, status: row.status, intent, result, diffReferences, sequence: -1, order: 5 });
+    }
+    for (const row of snapshot.rows.continuity_events ?? []) {
+        const payload = evidenceRecord(row, "payload_json");
+        if (payload?.ticketId !== workId && payload?.ticket !== workId)
+            continue;
+        events.push({ kind: "continuity", id: row.sequence, type: row.kind, payload, sequence: row.sequence, order: 5 });
+    }
+    const occurrences = new Set(scoped("qa_reports").map(row => row.report_occurrence_id));
+    for (const table of ["qa_report_dispositions", "qa_report_chains", "qa_delivery_turns"])
+        for (const row of snapshot.rows[table] ?? []) {
+            if (!occurrences.has(row.report_occurrence_id ?? row.predecessor_occurrence_id))
+                continue;
+            const record = evidenceRecord(row);
+            const parsed = typeof record?.parsedResponseDigest === "string" ? snapshot.blobs.get(record.parsedResponseDigest) : undefined;
+            let reportedFindings;
+            if (parsed)
+                try {
+                    reportedFindings = JSON.parse(parsed.toString("utf8")).findings;
+                }
+                catch { /* snapshot discloses retained corruption */ }
+            events.push({ kind: table, id: row.sequence ?? row.turn_record_id ?? row.successor_occurrence_id, ...row, record, reportedFindings, applicationEvidence: "Builder-reported dispositions; independent source-bound QA establishes verification", providerElapsedMs: record?.providerElapsedMs ?? null, sequence: Number(row.sequence ?? -1), order: 6 });
+        }
+    for (const row of scoped("qa_source_states"))
+        events.push({ kind: "source_basis", id: row.digest, originDigest: row.origin_digest, contentDigest: row.content_digest, paths: evidenceRecord(row, "state_json")?.paths, limitation: "Content changes require retained diff evidence for exact code-change explanations", sequence: -1, order: 6 });
+    for (const row of snapshot.rows.build_instructions ?? [])
+        if (row.work_id === workId)
+            events.push({ kind: "manager_instruction", id: row.instruction_id, record: evidenceRecord(row), deliveries: (snapshot.rows.build_instruction_deliveries ?? []).filter(delivery => delivery.instruction_id === row.instruction_id).map(delivery => evidenceRecord(delivery)), sequence: Number(row.sequence), order: 6 });
+    const committed = (snapshot.rows.build_work_events ?? []).filter(row => row.work_id === workId).sort((a, b) => Number(a.sequence) - Number(b.sequence));
+    if (committed.length) {
+        const ordered = committed.map(row => ({ kind: "committed_work_event", id: row.sequence, commitSequence: row.sequence, table: row.table_name, recordKey: row.record_key, action: row.action, stateAtEvent: evidenceRecord(row), createdAt: row.created_at, ordering: "durable_commit_sequence" }));
+        return { counters, events: [...ordered, ...events.map(event => ({ ...event, ordering: "snapshot_record_or_legacy_history", commitSequence: null }))], gaps: [...snapshot.gaps, "Snapshot records and pre-upgrade history are separately labeled; only indexed events have a proven cross-table commit order. Exact fixes require retained diffs; absent timing evidence leaves duration unknown."] };
+    }
+    // Independent event streams retain their own explicit sequence; timestamps do not establish ownership.
+    events.sort((a, b) => Number(a.sequence) - Number(b.sequence) || Number(a.order) - Number(b.order) || String(a.id).localeCompare(String(b.id)));
+    return { counters, events, gaps: [...snapshot.gaps, "No retained diff is interpreted as proof of the exact fix; durations are unavailable without correlated timing evidence"] };
+}

package/dist/qaVerificationContract.d.ts

@@ -0,0 +1,17 @@
+import type { EquivalentAuthorityResolver } from "./qaAuthorizedDisposition.js";
+import type { QaContractCandidateV1, QaVerificationContractV1, QaSemanticAssessmentV1, QaChallengeReceiptV1, ContractInputRef, RequirementRef } from "rafi-spec";
+import type { TicketDef } from "./tickets/ticketSchema.js";
+export declare function canonicalContractJson(value: unknown): string;
+export declare function contractDigest(domain: string, value: unknown): string;
+export declare function candidatePayload(contract: QaContractCandidateV1 | QaVerificationContractV1): QaContractCandidateV1;
+export declare function draftDigest(candidate: QaContractCandidateV1): string;
+/** Allocate identities from meaning, replacing proposed agent IDs throughout the draft. */
+export declare function allocateStableCheckIds(candidate: QaContractCandidateV1): QaContractCandidateV1;
+export declare function inventoryDigest(requirements: RequirementRef[]): string;
+export declare function authoritativeInventory(ticket: TicketDef, checklist: string[], inputs: ContractInputRef[]): RequirementRef[];
+export declare function parsePreparationArtifact<T>(text: string, tag: string, maximum?: number): T;
+export declare function validateCandidate(candidate: QaContractCandidateV1, inventory: RequirementRef[], resolveEquivalent?: EquivalentAuthorityResolver): string[];
+export declare function validateAssessment(candidate: QaContractCandidateV1, assessment: QaSemanticAssessmentV1, authorSessionId: string): string[];
+export declare function assembleContract(candidate: QaContractCandidateV1, inventory: RequirementRef[], assessment: QaSemanticAssessmentV1, authorSessionId: string, challenge?: QaChallengeReceiptV1, resolveEquivalent?: EquivalentAuthorityResolver): QaVerificationContractV1;
+export declare function verifyContractDigest(contract: QaVerificationContractV1): void;
+export declare function renderVerificationContract(contract: QaVerificationContractV1): string;