ai-foreman 1.7.29 → 2.0.1

package/dist/qaFailureDelivery.js

@@ -1,15 +1,22 @@
+import { BoundedTurnEvents, boundedUtf8 as boundedEvidenceUtf8, receiptFingerprint, rawFingerprint } from "./boundedTurnEvidence.js";
+import { providerWireContract, remediationOutput } from "rafi-spec";
+import { journalStructuredDispatch, operationInstruction, operationResponse, nativePolicy } from "./structuredOperation.js";
+import { durableOwnerDispatch } from "./structuredDispatchAuthority.js";
+import { remediationStructuredResponse } from "./qaStructuredResponse.js";
 import { dispatchWithGraphAccess } from "./graph/session.js";
 import { currentGraphDerivedAccess, inheritGraphDerivedAccess, withGraphDerivedAccess } from "./graph/derived.js";
 import { collectBuilderContractCoverage, assertBuilderContractCoverage } from "./qaBuilderCoverage.js";
+import { observeHostBuilderTests } from "./qaBuilderEvidence.js";
+import { captureBuildSource } from "./buildAssignment.js";
 import { queueGraphMaintenance, maintainGraphTask } from "./graph/boundary.js";
 import { ensureBuilderContract } from "./qaBuildGate.js";
 import { actualContractSession, assertContractReceipt } from "./qaContractDelivery.js";
-import { graphContext, parseGraphRequest, prepareGraphInstruction, sendGraphTurn } from "./graph/turn.js";
+import { graphContext, prepareGraphInstruction, sendGraphTurn } from "./graph/turn.js";
 import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { reportOccurrenceId } from "./qaHandbackMigration.js";
 import { boundedQaHistory, evidenceDigest, utf8Prefix } from "./qaHandbackHistory.js";
-import { BUILDER_QA_REMEDIATION_END, BUILDER_QA_REMEDIATION_START, builderQaRemediationReportV3Schema, parseBuilderQaRemediationContract, } from "rafi-spec";
+import { builderQaRemediationReportV3Schema, } from "rafi-spec";
 import { withActivityPhase } from "./activity.js";
 import { captureFrozenQaSourceAsync } from "./qaSnapshot.js";
 import { canonicalJson, createQaFindingRefs, qaDigest } from "./qaProtocolV2.js";
@@ -92,7 +99,7 @@ export class QaFailureDeliveryService {
         try {
             let prior = read.qaFailureHandoff(handoffId);
             if (prior?.state === "delivery-intended" && read.qaRemediationAttempt(prior.operationId)?.status === "succeeded") {
-                const historical = read.builderRemediationReceipt(prior.operationId);
+                const historical = read.verifiedBuilderRemediationReceipt(prior.operationId);
                 if (!historical || historical.runId !== input.runId || historical.ticketId !== input.ticket.id || historical.reportDigest !== input.reportDigest || !read.getEvidence(historical.responseDigest))
                     throw new Error("Partial historical handback needs receipt reconciliation; no redispatch permitted");
                 const receiptDigest = read.putEvidence("handoff", Buffer.from(canonicalEvidence({ version: 3, outcome: "remediation-reported", legacyEvidenceIncomplete: true, historicalReceipt: historical, reconciledAt: new Date().toISOString(), qaApproved: false })));
@@ -103,6 +110,13 @@ export class QaFailureDeliveryService {
                 const raw = prior.receiptDigest ? read.getEvidence(prior.receiptDigest) : undefined;
                 const receipt = raw ? JSON.parse(raw.toString()) : undefined;
                 const accepted = prior.state === "recheck-required" && read.qaRemediationAttempt(prior.operationId)?.status === "succeeded";
+                if (accepted) {
+                    const verified = read.verifiedBuilderRemediationReceipt(prior.operationId);
+                    if (!verified || verified.runId !== prior.runId || verified.ticketId !== prior.ticketId
+                        || verified.reportDigest !== prior.reportDigest || verified.responseDigest !== prior.responseDigest
+                        || verified.providerTurnId !== prior.providerTurnId)
+                        throw new Error("Replayed QA remediation handoff lacks its verified native receipt");
+                }
                 return { ok: accepted, outcome: receipt?.outcome ?? (accepted ? "remediation-reported" : "delivery-uncertain"), detail: prior.detail ?? "Operation already dispatched; reconcile its durable evidence before further work", handoffId, operationId: prior.operationId,
                     turnRecordId: receipt?.turnRecordId, response: prior.responseDigest ? read.getEvidence(prior.responseDigest)?.toString() : undefined,
                     summary: accepted ? "Previously reported remediation; independent QA required" : undefined, providerTurnId: prior.providerTurnId };
@@ -175,7 +189,7 @@ export class QaFailureDeliveryService {
         // Byte counts are not token counts. This deliberately conservative bound also
         // reserves wrapper instructions, response and continuity against known capacity.
         const graphDeliveryContext = graphContext(input.projectDir, input.builderWorktree, "remediation", instruction, { operationId: `graph-delivery:${operationId}`, logicalTaskId: operationId, sourceRef: preDispatch.digest, runId: input.runId, workId: input.ticket.id, qualifies: input.report.findings.some(f => f.locations.length > 1) });
-        let graphPrepared = await prepareGraphInstruction(instruction, graphDeliveryContext);
+        let graphPrepared = await prepareGraphInstruction(instruction, graphDeliveryContext, undefined, remediationOutput);
         const usage = await builder.contextUsage?.();
         if (usage?.maximum && Buffer.byteLength(graphPrepared.instruction) + 16_384 > usage.maximum - usage.used)
             graphPrepared = { instruction, bytes: 0 };
@@ -212,28 +226,37 @@ export class QaFailureDeliveryService {
         this.faults.afterIntent?.();
         let response;
         let graphSequence = 0;
-        const exchangeResult = await phase("initial-work-and-validation", () => sendGraphTurn(builder, instruction, graphDeliveryContext, { handback: true, logicalActionId: operationId }, async (prompt) => {
-            if (graphSequence > 0) {
-                const nextDb = new WorkflowDb(input.projectDir);
-                try {
-                    const head = nextDb.qaTicketHead(input.runId, input.ticket.id);
-                    const active = nextDb.qaRemediationAttempt(operationId);
-                    if (head.revision !== intent.expectedRevision || head.state !== "remediation-intended" || active?.status !== "started" || active.reviewAttemptId !== input.reviewAttemptId)
-                        throw new Error("Graph continuation lost its remediation authority");
-                    record = this.turnIntent(nextDb, operationId, occurrence, session, prompt, graphSequence, "graph-continuation");
-                }
-                finally {
-                    nextDb.close();
+        const hostToolObservations = [];
+        const initialSourceDigest = captureBuildSource(input.builderWorktree).digest;
+        const stopHostObservation = observeHostBuilderTests(builder, input.builderWorktree, hostToolObservations);
+        let exchangeResult;
+        try {
+            exchangeResult = await phase("initial-work-and-validation", () => sendGraphTurn(builder, instruction, graphDeliveryContext, nativePolicy(remediationOutput, { handback: true, logicalActionId: operationId, journalRunId: input.runId }), durableOwnerDispatch(input.projectDir, remediationOutput, { runId: input.runId, actionId: operationId }, async (prompt) => {
+                if (graphSequence > 0) {
+                    const nextDb = new WorkflowDb(input.projectDir);
+                    try {
+                        const head = nextDb.qaTicketHead(input.runId, input.ticket.id);
+                        const active = nextDb.qaRemediationAttempt(operationId);
+                        if (head.revision !== intent.expectedRevision || head.state !== "remediation-intended" || active?.status !== "started" || active.reviewAttemptId !== input.reviewAttemptId)
+                            throw new Error("Graph continuation lost its remediation authority");
+                        record = this.turnIntent(nextDb, operationId, occurrence, session, prompt, graphSequence, "graph-continuation");
+                    }
+                    finally {
+                        nextDb.close();
+                    }
                 }
-            }
-            graphSequence++;
-            response = await this.dispatch(input, builder, record, prompt);
-            if (!response.turn)
-                return { text: response.detail ?? "Remediation dispatch uncertain", isError: true, costUsd: 0, numTurns: 0 };
-            if (response.record.validationErrors?.length)
-                return { ...response.turn, isError: true };
-            return response.turn;
-        }, { ...graphPrepared, instruction }));
+                graphSequence++;
+                response = await this.dispatch(input, builder, record, prompt);
+                if (!response.turn)
+                    return { text: response.detail ?? "Remediation dispatch uncertain", isError: true, costUsd: 0, numTurns: 0 };
+                if (response.record.validationErrors?.length)
+                    return { ...response.turn, isError: true };
+                return response.turn;
+            }), { ...graphPrepared, instruction }));
+        }
+        finally {
+            stopHostObservation();
+        }
         const guidanceDb = new WorkflowDb(input.projectDir);
         try {
             guidanceDb.finishGuidance(guidanceIds, "builder", { submitted: response.record.status === "completed" && response.record.providerTurnId ? true : undefined, receipt: response.record.providerTurnId ? response.record : undefined });
@@ -241,33 +264,16 @@ export class QaFailureDeliveryService {
         finally {
             guidanceDb.close();
         }
-        let outcome = exchangeResult.isError ? "delivery-uncertain" : this.classify(response);
-        if (exchangeResult.isError)
+        let outcome = this.classify(response);
+        if (exchangeResult.isError && outcome !== "response-invalid") {
+            outcome = "delivery-uncertain";
             response.detail = exchangeResult.text;
-        if (outcome === "response-invalid" && response.record.sourceCapture === "captured") {
-            const correction = [
-                "Builder QA remediation response correction only. Do not inspect files, run tools, edit source, or perform additional remediation.",
-                "Preserve the original substantive result: do not invent changes, evidence, verification, answers, or turn a blocker into done.",
-                `Actual validation errors: ${JSON.stringify(response.record.parserErrors)}`,
-                `Original raw response evidence: ${response.record.rawResponseDigest}. The original turn remains in this same conversation.`,
-                `Post-remediation source digest: ${response.record.postSourceDigest}`,
-                responseInstructions(handoff),
-            ].join("\n\n");
-            enforceMandatoryPromptLimit(Buffer.from(correction));
-            const repairDb = new WorkflowDb(input.projectDir);
-            try {
-                record = this.turnIntent(repairDb, operationId, occurrence, session, correction, graphSequence, "response-repair");
-            }
-            finally {
-                repairDb.close();
-            }
-            const before = response.record.postSourceDigest;
-            response = await phase("response-repair-and-validation", () => this.dispatch(input, builder, record, correction, before));
-            outcome = this.classify(response);
         }
+        // Native malformed results retain completed side effects and stop at the
+        // operation boundary. A second model turn cannot prove content equivalence.
         if (outcome === "remediation-reported" && response.turn) {
             try {
-                await collectBuilderContractCoverage(input.projectDir, input.runId, input.ticket.id, input.builderWorktree, builder, operationId, instruction, response.turn);
+                await collectBuilderContractCoverage(input.projectDir, input.runId, input.ticket.id, input.builderWorktree, builder, operationId, instruction, response.turn, hostToolObservations, initialSourceDigest);
             }
             catch (error) {
                 outcome = "response-invalid";
@@ -326,7 +332,7 @@ export class QaFailureDeliveryService {
         }
         if (outcome === "remediation-reported" && response.turn) {
             try {
-                queueGraphMaintenance(input.projectDir, input.builderWorktree, operationId, response.turn.text, response.record.postSourceDigest !== preDispatch.digest);
+                queueGraphMaintenance(input.projectDir, input.builderWorktree, operationId, operationResponse(response.turn, remediationOutput).result.payload?.graphMaintenance === "meaningful-indexed-change", response.record.postSourceDigest !== preDispatch.digest);
                 await maintainGraphTask(input.projectDir, input.builderWorktree, operationId, builder);
             }
             catch (error) {
@@ -335,23 +341,23 @@ export class QaFailureDeliveryService {
         }
         return { ok: outcome === "remediation-reported", outcome, detail, response: response.turn?.text, summary: response.contract?.report?.summary, providerTurnId: response.record.providerTurnId, handoffId, operationId, turnRecordId: response.record.turnRecordId };
     }
-    turnIntent(db, operationId, occurrence, session, prompt, index, kind = index ? "response-repair" : "remediation") {
+    turnIntent(db, operationId, occurrence, session, prompt, index, kind = "remediation") {
         const turn = { version: 4, turnRecordId: qaDigest("qa-delivery-turn-v4", { operationId, index }), operationId, reportOccurrenceId: occurrence, turnIndex: index, kind, ...(index ? { parentTurnRecordId: qaDigest("qa-delivery-turn-v4", { operationId, index: 0 }) } : {}), status: "intended", intendedSession: session, hostInstructionDigest: db.putEvidence("handoff", Buffer.from(prompt)), hostInstructionBytes: Buffer.byteLength(prompt), providerInstructionAvailability: "unavailable", sourceCapture: "pending", startedAt: new Date().toISOString() };
         if (db.qaDeliveryTurns(operationId).some(t => t.turnIndex === index))
             throw new Error("Delivery turn already intended; reconcile without redispatch");
         db.recordQaDeliveryTurn(turn);
         return turn;
     }
-    async dispatch(input, builder, record, prompt, responseOnlySourceDigest) {
+    async dispatch(input, builder, record, prompt) {
         let result;
         await dispatchWithGraphAccess(input.projectDir, builder, prompt, undefined, async () => {
-            result = await this.dispatchOwned(input, builder, record, prompt, responseOnlySourceDigest);
+            result = await this.dispatchOwned(input, builder, record, prompt);
             return result.turn ?? { text: result.detail ?? "Dispatch failed", isError: true, costUsd: 0, numTurns: 0 };
         });
         return result;
     }
-    async dispatchOwned(input, builder, record, prompt, responseOnlySourceDigest) {
-        const events = [];
+    async dispatchOwned(input, builder, record, prompt) {
+        const events = new BoundedTurnEvents(providerWireContract(remediationOutput, builder.agent).maximumResponseBytes);
         let unsubscribe;
         let turn, error;
         const began = performance.now();
@@ -361,10 +367,14 @@ export class QaFailureDeliveryService {
             if (stableBuilderSessionIdentity(validateBuilderSession(builder, input)) !== stableBuilderSessionIdentity(record.intendedSession))
                 throw new Error("Builder session identity changed before dispatch");
             unsubscribe = builder.observeEvents(event => { events.push(event); });
-            turn = await withActivityPhase(record.kind === "response-repair" ? "correcting Builder QA remediation response" : "delivering source-bound QA failure handoff to Builder", () => builder.sendTurn(prompt, { handback: true, responseOnly: record.kind === "response-repair" }));
+            // The QA record is the domain owner, while the common gateway owns the
+            // immutable transport tuple.  Calling it here (rather than relying on
+            // the graph wrapper) gives QA the same prepare/seal-before-send boundary
+            // as every other structured dispatch without creating a second tuple.
+            turn = await withActivityPhase("delivering source-bound QA failure handoff to Builder", () => journalStructuredDispatch(input.projectDir, builder, `${prompt}\n\n${operationInstruction(remediationOutput)}`, nativePolicy(remediationOutput, { dispatchId: record.turnRecordId, logicalActionId: record.operationId, journalRunId: input.runId, handback: true }), (text, policy) => builder.sendTurn(text, policy)));
         }
         catch (caught) {
-            error = `Builder ${record.kind === "response-repair" ? "correction " : ""}dispatch uncertain: ${String(caught)}`;
+            error = `Builder dispatch uncertain: ${String(caught)}`;
         }
         finally {
             unsubscribe?.();
@@ -374,18 +384,29 @@ export class QaFailureDeliveryService {
         try {
             // Preserve returned bytes before identity/source inspection can fail.
             if (turn) {
+                record.sealedDispatch = db.structuredOwnerDispatch(record.turnRecordId);
                 const raw = turn.rawResponse ?? turn.text, cleaned = turn.cleanedResponse ?? turn.text;
-                Object.assign(record, { rawResponseDigest: db.putEvidence("qa", Buffer.from(raw)), rawResponseBytes: Buffer.byteLength(raw), cleanedResponseDigest: db.putEvidence("qa", Buffer.from(cleaned)), cleanedResponseBytes: Buffer.byteLength(cleaned), providerTurnId: turn.turnId, providerReturnedError: turn.isError, providerMetadata: turn.providerMetadata, failure: turn.failure });
+                record.structuredResponseDigest = db.operation(record.turnRecordId)?.result?.responseDigest;
+                Object.assign(record, { rawResponseDigest: (db.operation(record.turnRecordId)?.result).rawDigest, rawResponseBytes: Buffer.byteLength(raw), cleanedResponseDigest: db.putEvidence("qa", boundedEvidenceUtf8(cleaned, events.maximumBytes)), cleanedResponseBytes: Buffer.byteLength(cleaned), providerTurnId: turn.turnId, providerReturnedError: turn.isError, providerMetadata: turn.providerMetadata, failure: turn.failure && { ...turn.failure, diagnostics: boundedEvidenceUtf8(turn.failure.diagnostics, 4096).toString() } });
                 if (turn.providerInstruction !== undefined)
                     Object.assign(record, { providerInstructionDigest: db.putEvidence("handoff", Buffer.from(turn.providerInstruction)), providerInstructionBytes: Buffer.byteLength(turn.providerInstruction), providerInstructionAvailability: "captured" });
             }
-            record.eventEvidenceDigest = db.putEvidence("qa", Buffer.from(canonicalEvidence(events)));
-            record.toolCount = events.filter(e => e.kind === "tool" || e.kind === "provider-item" && !["text", "agentMessage", "reasoning", "userMessage", "contextCompaction"].includes(e.itemType)).length;
-            record.terminalCount = events.filter(e => e.kind === "turn-complete").length;
+            record.eventEvidenceDigest = db.putEvidence("qa", Buffer.from(canonicalEvidence(events.metadata())));
+            db.recordCommunicationEvidenceRefs(record.turnRecordId, [record.rawResponseDigest, record.cleanedResponseDigest, record.eventEvidenceDigest].filter((digest) => Boolean(digest)));
+            record.toolCount = events.toolCount;
+            record.terminalCount = events.terminalCount;
             db.recordQaDeliveryTurn(record);
             this.faults.afterResponseStored?.();
             const validationStarted = performance.now();
             const errors = error ? [error] : [];
+            if (turn && !turn.isError && !turn.failure) {
+                try {
+                    db.replayStructuredDispatch(record.turnRecordId, remediationOutput);
+                }
+                catch (caught) {
+                    errors.push(`Persisted remediation receipt rejected: ${String(caught)}`);
+                }
+            }
             try {
                 record.observedSession = validateBuilderSession(builder, input);
                 if (stableBuilderSessionIdentity(record.observedSession) !== stableBuilderSessionIdentity(record.intendedSession))
@@ -395,10 +416,13 @@ export class QaFailureDeliveryService {
                 errors.push(String(caught));
             }
             if (turn) {
-                if (turn.isError || turn.failure)
+                if (turn.failure || turn.isError && turn.structured?.state !== "rejected")
                     errors.push("Builder provider returned an error or failure metadata");
                 if (!turn.turnId)
                     errors.push("Builder completed without a provider turn identity");
+                const expectedWire = providerWireContract(remediationOutput, record.intendedSession.provider);
+                if (turn.structured?.state === "candidate" && (turn.structured.dispatchId !== record.turnRecordId || turn.structured.sessionId !== record.intendedSession.sessionId || turn.structured.profile !== expectedWire.profile || turn.structured.wireContractDigest !== expectedWire.descriptorDigest || turn.structured.wireSchemaDigest !== expectedWire.wireSchemaDigest || turn.structured.wireVariant !== expectedWire.variant))
+                    errors.push("Native remediation receipt has a foreign dispatch or provider session");
                 const meta = turn.providerMetadata;
                 try {
                     if (!meta?.sessionRef || meta.provider !== record.intendedSession.provider || meta.sessionId !== record.intendedSession.sessionId || stableBuilderSessionIdentity(meta.sessionRef) !== stableBuilderSessionIdentity(record.intendedSession))
@@ -416,7 +440,7 @@ export class QaFailureDeliveryService {
                 catch (caught) {
                     errors.push(`Terminal event scope is inaccessible: ${String(caught)}`);
                 }
-                if (terminal.length !== 1 || terminal[0]?.turnId !== turn.turnId || terminal[0]?.result.turnId !== turn.turnId || terminal[0]?.result.isError || terminal[0]?.result.failure || (terminal[0]?.result.rawResponse ?? terminal[0]?.result.text) !== (turn.rawResponse ?? turn.text))
+                if (events.terminalOverflow || events.terminalCount !== 1 || terminal.length !== 1 || terminal[0]?.turnId !== turn.turnId || terminal[0]?.result.turnId !== turn.turnId || terminal[0]?.result.isError || terminal[0]?.result.failure || (!terminal[0] || receiptFingerprint(terminal[0].result) !== receiptFingerprint(turn)) || (!terminal[0] || rawFingerprint(terminal[0].result) !== rawFingerprint(turn)))
                     errors.push("Builder completion is missing, duplicated, or uncorrelated");
             }
             const captureStart = performance.now();
@@ -426,33 +450,28 @@ export class QaFailureDeliveryService {
             }
             catch (caught) {
                 record.sourceCapture = "unavailable";
-                record.sourceCaptureError = String(caught);
+                record.sourceCaptureError = boundedEvidenceUtf8(String(caught), 4096).toString();
                 errors.push(`Post-dispatch source capture failed: ${String(caught)}`);
             }
             record.captureElapsedMs = performance.now() - captureStart;
-            if (record.kind === "response-repair") {
-                record.responseOnlyViolations = record.toolCount ? ["Builder used tools during response correction"] : [];
-                record.responseOnlySourceChanged = Boolean(record.postSourceDigest && record.postSourceDigest !== responseOnlySourceDigest);
-                if (record.responseOnlySourceChanged)
-                    record.responseOnlyViolations.push(`source changed during response correction (${responseOnlySourceDigest} -> ${record.postSourceDigest})`);
-            }
             let graphRequest = false;
+            const parserErrors = [];
             try {
-                graphRequest = Boolean(turn && parseGraphRequest(turn.cleanedResponse ?? turn.text));
+                graphRequest = Boolean(turn && operationResponse(turn, remediationOutput).result.kind === "graph-request");
             }
             catch (caught) {
-                errors.push(String(caught));
+                parserErrors.push(String(caught));
             }
-            const contract = turn && !graphRequest ? parseBuilderQaRemediationContract(turn.cleanedResponse ?? turn.text, { handoffId: qaDigest("qa-failure-handoff", { runId: input.runId, ticketId: input.ticket.id, reviewAttemptId: input.reviewAttemptId, reportDigest: input.reportDigest, remediationGeneration: input.remediationGeneration + 1 }), findings: createQaFindingRefs({ runId: input.runId, ticketId: input.ticket.id, reviewAttemptId: input.reviewAttemptId, reportDigest: input.reportDigest, rawFindingIds: selectRemediationChunk(input) }) }) : undefined;
-            record.parserErrors = [...(contract?.errors ?? []), ...(turn?.continuityErrors ?? [])];
-            record.validationErrors = errors;
+            const contract = turn && !graphRequest ? remediationStructuredResponse(turn, { handoffId: qaDigest("qa-failure-handoff", { runId: input.runId, ticketId: input.ticket.id, reviewAttemptId: input.reviewAttemptId, reportDigest: input.reportDigest, remediationGeneration: input.remediationGeneration + 1 }), findings: createQaFindingRefs({ runId: input.runId, ticketId: input.ticket.id, reviewAttemptId: input.reviewAttemptId, reportDigest: input.reportDigest, rawFindingIds: selectRemediationChunk(input) }) }) : undefined;
+            record.parserErrors = [...parserErrors, ...(contract?.errors ?? []), ...(turn?.continuityErrors ?? [])].slice(0, 32).map(detail => boundedEvidenceUtf8(detail, 1024).toString());
+            record.validationErrors = errors.slice(0, 32).map(detail => boundedEvidenceUtf8(detail, 1024).toString());
             if (contract?.report)
                 record.parsedResponseDigest = db.putEvidence("qa", Buffer.from(canonicalEvidence(contract.report)));
-            record.status = errors.length ? "delivery-uncertain" : "completed";
+            record.status = errors.length || !turn || turn.isError || turn.failure ? "delivery-uncertain" : "completed";
             record.completedAt = new Date().toISOString();
             record.validationElapsedMs = Math.max(0, performance.now() - validationStarted - record.captureElapsedMs);
             db.recordQaDeliveryTurn(record);
-            return { turn, record, contract, detail: errors.length ? errors.join("; ") : record.responseOnlyViolations?.length ? record.responseOnlyViolations.join("; ") : undefined };
+            return { turn, record, contract, detail: errors.length ? boundedEvidenceUtf8(errors.join("; "), 4096).toString() : undefined };
         }
         finally {
             db.close();
@@ -461,10 +480,6 @@ export class QaFailureDeliveryService {
     classify(result) {
         if (result.record.validationErrors?.length)
             return "delivery-uncertain";
-        if (result.record.responseOnlySourceChanged)
-            return "source-drift";
-        if (result.record.responseOnlyViolations?.length)
-            return "response-invalid";
         if (result.contract?.valid && result.contract.status === "blocked")
             return "blocked";
         if (result.contract?.valid && result.contract.status === "needs_input")
@@ -654,11 +669,8 @@ function responseInstructions(handoff) {
         `Required finding identities for this remediation chunk: ${JSON.stringify(handoff.report.findingRefs.map(f => ({ finding_key: f.findingKey, raw_id: f.rawId })))}`,
         "Address, dispute with evidence, or mark blocked every finding in this remediation chunk. Do not address findings outside the chunk. A Builder claim never approves QA findings.",
         "This is only a bounded remediation chunk. It does not approve the ticket. Any source change invalidates this chunk's source binding, and Rafi must perform a fresh full independent QA review afterward.",
-        "The envelope must be the first non-empty content of the cleaned response. STEP_STATUS must be the final non-empty line. No prologue, trailing prose, duplicate keys, unknown or missing findings.",
-        "In raw output, put the required RAFI_CONTINUITY_DELTA record between the envelope end and STEP_STATUS. The continuity wrapper removes only that record before contract validation.",
-        `${BUILDER_QA_REMEDIATION_START}\n${JSON.stringify({ version: 3, handoff_id: handoff.handoffId, summary: "Truthful result", findings: handoff.report.findingRefs.map(f => ({ finding_key: f.findingKey, raw_id: f.rawId, disposition: "disputed", changes: ["Explain actual changes or why none were needed"], evidence: "Actual evidence", verification: [{ check: "Actual verification", outcome: "not_run", evidence: "Actual reason" }] })), observations: [] })}\n${BUILDER_QA_REMEDIATION_END}\nSTEP_STATUS: done | summary="short truthful summary"`,
-        'If blocked, use STEP_STATUS: blocked | reason="actual blocker and recovery needed". A V3 envelope with complete partial fixed/disputed/blocked coverage is allowed; blocked findings require category, reason, recovery, capability, evidence. Without partial results, the blocked status alone is valid.',
-        'If a decision is required, use STEP_STATUS: needs_input | question="actual unanswered question" without fabricating an envelope or answer.',
+        "Return one native builder-remediation response. The completed payload contains status done or blocked, a reason (null for done), the complete V3 report, and available coverage claims. Keep continuity in the same response object.",
+        "A report must cover every finding exactly once. Partial fixed/disputed/blocked coverage is valid only with status blocked, a truthful reason, and a structured blocker on each blocked finding. If no partial report is available, use the outer blocked result. Questions use the needs-input alternative.",
         `Authoritative V3 schema: ${JSON.stringify(builderQaRemediationReportV3Schema)}`,
     ].join("\n\n");
 }

package/dist/qaHostTransformation.d.ts

@@ -0,0 +1,26 @@
+export type QaHostTransformationRule = "assessment-host-bindings-v1" | "depth-host-bindings-v1" | "draft-host-bindings-v1";
+export interface QaHostTransformationV1 {
+    version: 1;
+    ruleVersion: QaHostTransformationRule;
+    operation: string;
+    tupleDigest: string;
+    inputDigest: string;
+    outputDigest: string;
+    authorityClass: "host-binding-and-observation";
+    justification: string;
+    effects: Array<{
+        path: string;
+        beforeDigest: string;
+        afterDigest: string;
+    }>;
+}
+/** Records only approved host effects; provider/user requirements remain immutable. */
+export declare function qaHostTransformation(input: {
+    rule: QaHostTransformationRule;
+    operation: string;
+    tupleDigest: string;
+    before: unknown;
+    after: unknown;
+    workspacePaths?: Record<string, string>;
+}): QaHostTransformationV1;
+export declare function verifyQaHostTransformation(record: QaHostTransformationV1, before: unknown, after: unknown, workspacePaths?: Record<string, string>): void;

package/dist/qaHostTransformation.js

@@ -0,0 +1,100 @@
+import { canonicalJson, structuredDigest } from "rafi-spec";
+const hashValue = (value, present) => structuredDigest({ present, ...(present ? { value } : {}) });
+/** Records only approved host effects; provider/user requirements remain immutable. */
+export function qaHostTransformation(input) {
+    if (!["assessment-host-bindings-v1", "depth-host-bindings-v1", "draft-host-bindings-v1"].includes(input.rule))
+        throw new Error("Unknown QA host transformation rule");
+    if (!/^[a-f0-9]{64}$/.test(input.tupleDigest) || !input.operation)
+        throw new Error("QA transformation requires native tuple provenance");
+    const effects = [];
+    const original = input.before, transformed = input.after;
+    const ids = new Map();
+    if (input.rule === "draft-host-bindings-v1") {
+        if (transformed.checks.length < original.checks.length)
+            throw new Error("QA transformation cannot remove provider checks");
+        original.checks.forEach((check, index) => ids.set(check.id, transformed.checks[index].id));
+    }
+    const labelIds = [...ids.keys()].filter(id => id.startsWith("check-")).sort((a, b) => b.length - a.length);
+    const labelPattern = labelIds.length ? new RegExp(`(^|[^A-Za-z0-9_-])(${labelIds.map(id => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})(?![A-Za-z0-9_-])`, "g") : undefined;
+    const relabel = (value) => typeof value === "string" && labelPattern
+        ? value.replace(labelPattern, (_match, prefix, id) => `${prefix}${ids.get(id)}`) : value;
+    const walk = (before, after, path, beforePresent = true, afterPresent = true) => {
+        if (beforePresent === afterPresent && canonicalJson(before ?? null) === canonicalJson(after ?? null))
+            return;
+        if (input.rule === "draft-host-bindings-v1" && path === "baseline" && Array.isArray(before) && Array.isArray(after)) {
+            for (const prior of before)
+                if (!after.some(row => row.id === prior.id))
+                    throw new Error("QA transformation cannot remove provider observations");
+            for (const [index, row] of after.entries()) {
+                const prior = before.find(item => item.id === row.id);
+                walk(prior, row, `baseline.${index}`, prior !== undefined, true);
+            }
+            return;
+        }
+        if (before && after && typeof before === "object" && typeof after === "object" && Array.isArray(before) === Array.isArray(after)) {
+            for (const key of [...new Set([...Object.keys(before), ...Object.keys(after)])].sort())
+                walk(before[key], after[key], path ? `${path}.${key}` : key, Object.hasOwn(before, key), Object.hasOwn(after, key));
+            return;
+        }
+        const assessment = /^(draftPayloadDigest|inventoryDigest|policyVersion|authorSessionId|sessionId|operationId)$/.test(path);
+        const depth = /^(plannerOperationId|plannerIdentity|minimumReasons(?:\.\d+)?)$/.test(path);
+        let draft = false;
+        if (input.rule === "draft-host-bindings-v1") {
+            const check = /^checks\.(\d+)\.(.+)$/.exec(path);
+            const originalCheck = check && original.checks[Number(check[1])];
+            const idReference = /^(checks\.\d+\.(id|dependsOnChecks\.\d+)|coverage\.\d+\.checkIds\.\d+|unresolved\.\d+\.checkIds\.\d+)$/.test(path);
+            draft = idReference && ids.get(before) === after;
+            if (check?.[2] === "obligation" && originalCheck && after === "mandatory") {
+                draft = original.requirements.some((requirement) => requirement.obligation === "mandatory" &&
+                    original.coverage.some((row) => row.requirementId === requirement.id && row.checkIds.includes(originalCheck.id)));
+            }
+            if (check && /^requirementRefs\.\d+$/.test(check[2]) && !beforePresent && originalCheck) {
+                draft = original.coverage.some((row) => row.requirementId === after && row.checkIds.includes(originalCheck.id));
+            }
+            if (/^checks\.\d+\.hostKind$/.test(path) && !beforePresent)
+                draft = after === "source-scope" || after === "graph-maintenance";
+            if (/^checks\.\d+$/.test(path) && !beforePresent)
+                draft = after && (after.hostKind === "source-scope" || after.hostKind === "graph-maintenance") &&
+                    after.origin === "invariant" && after.obligation === "mandatory" && after.requirementRefs.every((id) => original.requirements.some((requirement) => requirement.id === id));
+            if (/^baseline\.\d+$/.test(path) && !beforePresent)
+                draft = after && /^[a-f0-9]{64}$/.test(after.evidenceDigest) && typeof after.observedAt === "string";
+            if (/^baseline\.\d+\.(sourceDigest|observedAt|phase|evidenceDigest)$/.test(path))
+                draft = true;
+            if (/^baseline\.\d+\.checkId$/.test(path)) {
+                const row = transformed.baseline[Number(path.split(".")[1])];
+                const checks = transformed.checks.filter((item) => item.prerequisiteRefs.includes(row.id));
+                draft = ids.get(before) === after || checks.length === 1 && checks[0].id === after;
+            }
+            if (/^preparationEvidence\.\d+\.(operationId|sessionId|graphReceiptRefs(?:\.\d+)?|evidenceDigest)$/.test(path) ||
+                /^preparationEvidence\.\d+\.references\.\d+\.digest$/.test(path))
+                draft = true;
+            if (/^(checks\.\d+\.verification\.\d+\.cwd|preparationEvidence\.\d+\.references\.\d+\.path)$/.test(path))
+                draft = typeof before === "string" && input.workspacePaths?.[before] === after;
+            // The only permitted prose edit substitutes exact provider check identifiers.
+            if (/^(checks\.\d+\.(expectedBehavior|expectedEvidence\.\d+|expectedBaseline|applicability\.(predicate|requiredEvidence\.\d+)|verification\.\d+\.(expectedOutcome|steps\.\d+))|baseline\.\d+\.(procedure|relevance|expectedTransition|predicateEvidence\.\d+)|preparationEvidence\.\d+\.analysis|unresolved\.\d+\.(reason|nextAction))$/.test(path) &&
+                typeof before === "string" && before !== after && relabel(before) === after)
+                draft = true;
+        }
+        if (!(input.rule === "assessment-host-bindings-v1" ? assessment : input.rule === "depth-host-bindings-v1" ? depth : draft))
+            throw new Error(`QA host transformation cannot change provider requirements or semantic fields: ${path}`);
+        effects.push({ path, beforeDigest: hashValue(before, beforePresent), afterDigest: hashValue(after, afterPresent) });
+        if (effects.length > 10000)
+            throw new Error("QA host transformation exceeds effect budget");
+    };
+    walk(input.before, input.after, "");
+    if (input.rule === "depth-host-bindings-v1") {
+        const before = input.before;
+        const after = input.after;
+        const expected = [...before.minimumReasons, ...before.riskFactors.map(risk => risk.category).filter(category => !before.minimumReasons.includes(category))];
+        if (canonicalJson(expected) !== canonicalJson(after.minimumReasons))
+            throw new Error("Depth labels must be exactly derivable from provider risk factors");
+    }
+    return { version: 1, ruleVersion: input.rule, operation: input.operation, tupleDigest: input.tupleDigest,
+        inputDigest: structuredDigest(input.before), outputDigest: structuredDigest(input.after), effects,
+        authorityClass: "host-binding-and-observation", justification: "Bind native dispatch identities and retained host observations; preserve provider/user requirements" };
+}
+export function verifyQaHostTransformation(record, before, after, workspacePaths) {
+    const expected = qaHostTransformation({ rule: record.ruleVersion, operation: record.operation, tupleDigest: record.tupleDigest, before, after, workspacePaths });
+    if (canonicalJson(expected) !== canonicalJson(record))
+        throw new Error("QA host transformation replay mismatch");
+}

package/dist/qaPreparation.d.ts

@@ -1,6 +1,12 @@
+import { type OutputContract, type SelectedDispatchTupleV2, type StructuredResponse } from "rafi-spec";
 import type { QaContractCandidateV1, QaSemanticAssessmentV1, RequirementRef, QaVerificationContractV1 } from "rafi-spec";
 import type { QaPreparationStore, LogicalPreparationBudget } from "./qaPreparationStore.js";
+/** Compatibility re-exports; canonical contract ownership is rafi-spec. */
+export { draftOutput, assessmentOutput, challengeOutput, depthOutput } from "rafi-spec";
 export interface PreparationProviderResult {
+    output?: OutputContract;
+    structured?: StructuredResponse;
+    selectedDispatch?: SelectedDispatchTupleV2;
     operationId?: string;
     text: string;
     sessionId: string;
@@ -14,7 +20,7 @@ export interface PreparationDependencies {
     /** Provider-specific wording is allowed; contract ownership is not. */
     provider?: "claude" | "codex";
     /** Each dispatch is a fresh, confined conversation, with a persisted reservation. */
-    dispatch(phase: "planner" | "prepare" | "assess" | "challenge" | "repair", instruction: string, operationId: string, remainingMs: number): Promise<PreparationProviderResult>;
+    dispatch(phase: "planner" | "prepare" | "assess" | "challenge" | "repair", instruction: string, operationId: string, remainingMs: number, output: OutputContract): Promise<PreparationProviderResult>;
     inputsCurrent(candidate: QaContractCandidateV1): boolean;
     normalizeDraft?(draft: QaContractCandidateV1, response: PreparationProviderResult): QaContractCandidateV1;
     hostFacts?: string;
@@ -29,22 +35,11 @@ export type PreparationOutcome = {
 };
 export declare const FILE_SCOPE_GUIDANCE = "File lists in plans and tickets, including likely_files and generated file-only diff expectations, are estimates of implementation, not exhaustive boundaries. Different named files or an extra relevant file do not by themselves create a material conflict or block the build. Retain and assess every original requirement; for file-list checks verify that changes serve the approved work rather than requiring an exact file list or a pre-edit snapshot proving no other files changed. Rafi owns tracker lifecycle updates. Generated instructions to mark a ticket done in a document are bookkeeping, not a Builder acceptance criterion or a material conflict; do not require the Builder to perform them, and do not require the host to amend the plan before building. Do not disregard explicit user-established security, privacy, access, or other safety restrictions, or expand the approved product functionality. Report genuine substantive or safety conflicts.";
 export declare const ROLLBACK_VERIFICATION_GUIDANCE = "When an original requirement explicitly asks to verify that rollback restores behavior, specify concrete future verification evidence rather than only inspecting rollback prose. A rollback plan alone does not require a rollback execution or mutation-testing rehearsal. For an npm test project where current uncommitted product changes represent the change to rehearse, the Builder may run rafi qa-rehearse-rollback alone from the project root; it runs npm test before and after reverting a synthetic commit of all uncommitted product changes in an independent temporary repository. It also runs git diff --exit-code against the captured pre-change HEAD after the revert and tests; success proves the tracked files match that baseline. For a requirement that a particular string be absent after rollback, inspecting its absence in the captured baseline plus that successful whole-tree comparison is concrete evidence of absence in the reverted tracked file. The rehearsal cannot use installed dependencies or symbolic links and does not prove ticket isolation or that an actual existing ticket commit was reverted. Assess whether this evidence satisfies the original requirement; do not claim it does when the original explicitly requires the actual ticket commit. Do not assume copying files to external scratch, arbitrary scripts or mutation experiments are allowed. If actual rollback execution is explicitly required but no permitted method satisfies it, report the limitation. Never perform destructive rollback in the source workspace or claim a rehearsal has already happened.";
-export declare const EXECUTABLE_CHECK_GUIDANCE = "Choose verification procedures compatible with the Builder's project permissions and workspace. Documentation is disabled unless the host-bound contract documentation.required is true. When it is false, do not invent documentation checks merely because a docs directory or API-looking path exists; an absent documentation surface is not a failure. When it is true, use only the contract's exact targets and criteria, and define an actionable absent-target outcome. Do not invent mandatory inline node -e or node --eval commands: the Builder policy may refuse them. For a JavaScript behavior or export check, prefer a project-local test file executed with the project's existing test command, or a permitted node --test invocation. Do not invent a mandatory test-first RED phase or other historical sequence merely because a plan requires tests before and after implementation: a passing baseline test is not a failing new test. When an original requirement actually requires a historical sequence, preserve it and specify concrete independently reviewable evidence paths or retained host events for each required step; a generic statement that sequencing evidence exists is not actionable, and a later passing test does not prove past events. If the project policy makes raw stdout redirection or scratch-log creation unavailable, do not turn log-file capture into a blocker: use the retained bounded tool output and host events instead, and never cite a scratch path unless that exact file was successfully created and inspected. The independent QA snapshot may have a detached HEAD even when the Builder source workspace is on a branch; do not use its branch name to infer the Builder source branch. Diff and scope checks must compare the current snapshot with the captured pre-implementation baseline, not blindly with repository HEAD: previously approved or completed ticket changes are part of that baseline and must not be reported as new work. A scope check must first enumerate every changed path outside the explicit bookkeeping/evidence exclusions, then compare that complete host-observed set with the approved product/ticket scope; do not pre-filter the list to expected filenames, because that would hide accidental extra product edits. Bounded evidence-only paths such as scratch/ are not product scope and must be excluded from product-path scope checks while their retained evidence remains subject to QA review. For a current-branch multi-ticket build, do not invent a mandatory branch-alone execution check merely to prove ticket independence; use baseline-aware source/test inspection and the permitted project tests unless the original requirement explicitly requires an actual isolated execution. For additive tickets in a current-branch multi-ticket build, \u201Cacceptable on its own\u201D is satisfied by showing that each ticket's own tests import and exercise only its own feature, pass with the shared baseline and required project tests, and do not depend on the sibling feature; do not require removing another additive feature or perform a destructive rollback experiment unless the approved requirement explicitly requires absence testing or an isolated branch. Preserve explicitly requested procedures and substantive requirements; if a required procedure cannot be run, identify the limitation rather than claiming it was executed. Independently assess whether proposed evidence actually tests the required behavior.";
+export declare const EXECUTABLE_CHECK_GUIDANCE = "Choose verification procedures compatible with the Builder's project permissions and workspace. Keep applicability and verification instructions consistent: an unconditional check must always be reported applicable, including a check whose predicate confirms an absent feature, disabled documentation, or an unrequested skill. For such a check require passed evidence of the absence, never an instruction to report the check not-applicable. If execution itself depends on a condition, encode conditional applicability with a concrete predicate and evidence. The independent assessor must flag contradictory applicability instructions before readiness. Documentation is disabled unless the host-bound contract documentation.required is true. When it is false, do not invent documentation checks merely because a docs directory or API-looking path exists; an absent documentation surface is not a failure. When it is true, use only the contract's exact targets and criteria, and define an actionable absent-target outcome. Do not invent mandatory inline node -e or node --eval commands: the Builder policy may refuse them. For a JavaScript behavior or export check, prefer a project-local test file executed with the project's existing test command, or a permitted node --test invocation. Do not invent a mandatory test-first RED phase or other historical sequence merely because a plan requires tests before and after implementation: a passing baseline test is not a failing new test. When an original requirement actually requires a historical sequence, preserve it and specify concrete independently reviewable evidence paths or retained host events for each required step; a generic statement that sequencing evidence exists is not actionable, and a later passing test does not prove past events. If the project policy makes raw stdout redirection or scratch-log creation unavailable, do not turn log-file capture into a blocker: use the retained bounded tool output and host events instead, and never cite a scratch path unless that exact file was successfully created and inspected. The independent QA snapshot may have a detached HEAD even when the Builder source workspace is on a branch; do not use its branch name to infer the Builder source branch. Diff and scope checks must compare the current snapshot with the captured pre-implementation baseline, not blindly with repository HEAD: previously approved or completed ticket changes are part of that baseline and must not be reported as new work. A scope check must first enumerate every changed path outside the explicit bookkeeping/evidence exclusions, then compare that complete host-observed set with the approved product/ticket scope; do not pre-filter the list to expected filenames, because that would hide accidental extra product edits. Bounded evidence-only paths such as scratch/ are not product scope and must be excluded from product-path scope checks while their retained evidence remains subject to QA review. For a current-branch multi-ticket build, do not invent a mandatory branch-alone execution check merely to prove ticket independence; use baseline-aware source/test inspection and the permitted project tests unless the original requirement explicitly requires an actual isolated execution. For additive tickets in a current-branch multi-ticket build, \u201Cacceptable on its own\u201D is satisfied by showing that each ticket's own tests import and exercise only its own feature, pass with the shared baseline and required project tests, and do not depend on the sibling feature; do not require removing another additive feature or perform a destructive rollback experiment unless the approved requirement explicitly requires absence testing or an isolated branch. Preserve explicitly requested procedures and substantive requirements; if a required procedure cannot be run, identify the limitation rather than claiming it was executed. Independently assess whether proposed evidence actually tests the required behavior.";
 /** Baseline bookkeeping must not block ordinary approved implementation work. */
 export declare const APPROVED_PATH_BASELINE_GUIDANCE = "Baseline membership is host-owned bookkeeping, not a Builder requirement. An approved product path, export, or test file is not a material QA concern merely because the provider cannot prove whether it was present before implementation. Do not reconstruct or disclose the full baseline, and do not turn that uncertainty into an unresolved concern. Rafi performs the exact host comparison. Do not author a provider-executed check that asks for Rafi's host postimplementation path manifest, complete changed-path inventory, or unchanged-file comparison; that host-owned comparison is already performed outside the provider snapshot and must be represented by the retained host observation, not by raw manifest disclosure or a provider check. For current-branch additive tickets, a provider-authored or inferred request to test the branch with an already-completed sibling feature removed is not an applicable requirement when the approved scope says not to remove or reconstruct that sibling; verify the ticket's own behavior and tests against the shared baseline instead. Treat sibling-absence testing as binding only when the user explicitly approved that absence requirement. Escalate only an actual host-observed out-of-scope, destructive, protected-file, or requirement-relevant change.";
 /** Ignore known non-authoritative annotations; the original provider response remains retained. */
 export declare function normalizeAssessmentMetadata<T extends QaSemanticAssessmentV1>(assessment: T): T;
-/** Accept only an exact known obligation label when a provider wraps it in a
- * descriptive object. This is a representation repair, not a host decision:
- * unknown or ambiguous objects remain unchanged and fail schema validation. */
-export declare function normalizeAssessmentObligations<T extends QaSemanticAssessmentV1>(assessment: T, allowed: string[]): T;
-/** A preparation assessor must not block on the expected absence of future
- * Builder work. Keep the concern for auditability, but make it non-material
- * only when every referenced check is postimplementation and the concern is
- * explicitly asking the Builder to implement/rerun that check. Concerns tied
- * to preimplementation checks, missing procedures, or other semantic gaps
- * remain blocking. */
-export declare function normalizeExpectedFutureAssessment<T extends QaSemanticAssessmentV1>(assessment: T, candidate: QaContractCandidateV1): T;
 /**
  * A mandatory requirement must have at least one mandatory verification check.
  * Providers occasionally return a concrete check with the weaker advisory
@@ -53,11 +48,4 @@ export declare function normalizeExpectedFutureAssessment<T extends QaSemanticAs
  * enforce readiness and independent-QA requirements for the promoted check.
  */
 export declare function enforceMandatoryCoverage(candidate: QaContractCandidateV1): QaContractCandidateV1;
-/**
- * Codex occasionally appends a made-up requirement ID to an otherwise valid
- * check. Remove only those extraneous annotations when the check still has an
- * exact authoritative reference. Never invent or remap an ID, and leave a
- * check with no valid references untouched so normal validation fails closed.
- */
-export declare function removeExtraneousRequirementReferences(candidate: QaContractCandidateV1, inventory: RequirementRef[]): QaContractCandidateV1;
 export declare function prepareVerificationContract(initial: QaContractCandidateV1, inventory: RequirementRef[], deps: PreparationDependencies): Promise<PreparationOutcome>;