loopforge 3.9.2 → 4.0.7

package/dist/round-transaction.js

@@ -5,17 +5,64 @@
  * feedback storage. The committed feedback embeds the decision so replay after
  * a process crash is idempotent.
  */
-import { deriveObservationDeltas } from "./evidence-provider.js";
+import { createHash } from "node:crypto";
+import { deriveObservationDeltas, observationVersionIssue } from "./evidence-provider.js";
+import { EVIDENCE_POSTURE_CAPS, rollbackEvidencePosture, } from "./evidence-posture.js";
 import { RoundCoordinator, } from "./round-coordinator.js";
 import { logEvent } from "./observability.js";
 import { deriveContractId, deriveContractItemIds, isRecord } from "./token-utils.js";
-import { GIT_OBSERVATION_SCHEMA_VERSION, PROMPT_ARTIFACT_SCHEMA_VERSION, } from "./protocol.js";
+import { PROMPT_ARTIFACT_SCHEMA_VERSION, isPromptContextMode, isPromptContextReason, } from "./protocol.js";
+import { promptContextPairIssue } from "./context-boundary.js";
 import { commandConfigHash, getPolicy } from "./policy.js";
 import { policyMetrics } from "./policy-metrics.js";
 import { VaultRoundCommitStore } from "./storage.js";
-/** v3.9.1: schema 3 embeds Git observation schema 2 (complete boundary
- *  fingerprints) and later adds optional diagnostics/manifest fields. */
-export const ROUND_TRANSACTION_SCHEMA_VERSION = 3;
+import { transactionIdentityIssue } from "./transaction-identity.js";
+/** v3.9.7: schema 5 adds the transaction before-image, explicit mid-round
+ *  checkpoints and the redo restore marker. v4.0.3: schema 7 requires the
+ *  persisted `EvidencePosture` on every result and adds the transient
+ *  `RetryContext`. v4.0.4: schema 8 embeds the schema-10 PromptArtifact
+ *  (`fresh_invocation`) and the renamed `SelfEvaluation.agent_stop_reason`.
+ *  v4.0.6: schema 9 is a BREAKING shape break — the committed evaluation
+ *  carries a required `outcome`, one `execution_report.claims` channel
+ *  (`cr-`/`rci-`) and `round_contract.supersedes`; `success`,
+ *  `agent_stop_reason`, `contract_transition`, `tests_reported`,
+ *  `criterion_claims` and `contract_item_claims` are gone. Every earlier
+ *  version is reported as legacy by `legacyTransactionRounds`; there is no
+ *  compatibility migration. */
+export const ROUND_TRANSACTION_SCHEMA_VERSION = 9;
+/** Maximum distinct mid-round checkpoints one transaction may reference. */
+export const MAX_MID_CHECKPOINTS_PER_TRANSACTION = 32;
+/** The root branch identity for every loop. */
+export function rootBranchId(loopId) {
+    return `loop:${loopId}:branch:root`;
+}
+/** v3.9.6: deterministic transaction identity. The logical round identity is
+ *  still `roundId`; this id prevents a deep redo from replaying an abandoned
+ *  commit at the same numeric round. */
+export function deriveTransactionId(input) {
+    const payload = [
+        input.kind,
+        input.branchId,
+        input.roundId,
+        String(input.attempt),
+        input.promptHash ?? "",
+        input.kind === "rollback" && input.recovery
+            ? [
+                input.recovery.target.checkpoint_id,
+                input.recovery.target.content_hash,
+                String(input.recovery.target.redo_round),
+                input.recovery.reason,
+                input.recovery.target.transaction_id,
+                (input.recovery.abandonedRounds ?? []).join(","),
+                (input.recovery.failedRounds ?? []).join(","),
+                [...(input.recovery.observedSkippedFiles ?? [])].sort().join(","),
+                [...(input.recovery.reportedSkippedFiles ?? [])].sort().join(","),
+                [...(input.recovery.triggerFindings ?? [])].sort().join(","),
+            ].join("\n")
+            : "",
+    ].join("\n");
+    return `tx-${createHash("sha256").update(payload).digest("hex").slice(0, 24)}`;
+}
 /** v3.8: the closed set of machine-observation statuses. */
 const OBSERVATION_STATUSES = [
     "observed", "passed", "failed", "timeout", "unavailable", "error", "aborted",
@@ -64,16 +111,45 @@ export function makeRoundId(loopId, round) {
     }
     return `loop:${loopId}:round:${round}`;
 }
-export function prepareRoundTransaction(loopId, round, beforeEvidence, promptArtifact) {
+export function prepareRoundTransaction(loopId, round, beforeEvidence, promptArtifact, opts = {}) {
     const now = Date.now();
+    const roundId = makeRoundId(loopId, round);
+    const branchId = opts.branchId ?? rootBranchId(loopId);
+    const kind = opts.kind ?? "evaluation";
+    const observedGit = beforeEvidence.some((observation) => observation.kind === "git" && observation.status === "observed");
+    // A direct library caller may have no checkpoint store attached. The
+    // schema-5 invariant still records the explicit machine fact.
+    const beforeCheckpointError = opts.beforeCheckpointError ??
+        (observedGit && !opts.beforeCheckpoint
+            ? {
+                code: "store_unavailable",
+                detail: "no workspace checkpoint store was attached to this prepare",
+                at: now,
+            }
+            : undefined);
     return {
         schemaVersion: ROUND_TRANSACTION_SCHEMA_VERSION,
-        roundId: makeRoundId(loopId, round),
+        branchId,
+        transactionId: deriveTransactionId({
+            kind,
+            branchId,
+            roundId,
+            attempt: 1,
+            promptHash: promptArtifact?.promptHash,
+        }),
+        kind,
+        roundId,
         loopId,
         round,
         attempt: 1,
         phase: promptArtifact ? "prompted" : "prepared",
         beforeEvidence,
+        ...(opts.beforeCheckpoint ? { beforeCheckpoint: opts.beforeCheckpoint } : {}),
+        ...(beforeCheckpointError ? { beforeCheckpointError } : {}),
+        ...(opts.operatorAcceptance
+            ? { operatorAcceptance: opts.operatorAcceptance }
+            : {}),
+        ...(opts.compiled ? { compiled: opts.compiled } : {}),
         createdAt: now,
         updatedAt: now,
         promptArtifact,
@@ -82,7 +158,7 @@ export function prepareRoundTransaction(loopId, round, beforeEvidence, promptArt
 /** Attach the next prompt attempt to a rejected logical round without changing
  * its identity or evidence baseline. Evaluation fields belong to the previous
  * attempt and are cleared before the Agent receives the retry prompt. */
-export function prepareRejectedAttempt(rejected, promptArtifact) {
+export function prepareRejectedAttempt(rejected, promptArtifact, compiled, operatorAcceptance) {
     if (rejected.phase !== "rejected") {
         throw new Error(`Cannot retry transaction in phase ${rejected.phase}`);
     }
@@ -92,13 +168,49 @@ export function prepareRejectedAttempt(rejected, promptArtifact) {
     if (promptArtifact.attempt !== rejected.attempt + 1) {
         throw new Error(`Retry prompt attempt mismatch: ${promptArtifact.attempt} !== ${rejected.attempt + 1}`);
     }
+    if (rejected.retryContext) {
+        if (rejected.retryContext.rejectedAttempt !== rejected.attempt ||
+            rejected.retryContext.attempt !== promptArtifact.attempt) {
+            throw new Error("Retry context identity does not match the rejected attempt");
+        }
+    }
+    const transactionId = deriveTransactionId({
+        kind: rejected.kind,
+        branchId: rejected.branchId,
+        roundId: rejected.roundId,
+        attempt: promptArtifact.attempt,
+        promptHash: promptArtifact.promptHash,
+    });
+    // The round-start before-image is the SAME workspace state across attempts;
+    // only its owning transaction identity changes. Mid-round savepoints belong
+    // to the rejected attempt and are not carried into the retry.
+    const beforeCheckpoint = rejected.beforeCheckpoint
+        ? { ...rejected.beforeCheckpoint, transactionId }
+        : undefined;
     return {
         ...rejected,
+        transactionId,
+        ...(beforeCheckpoint ? { beforeCheckpoint } : {}),
+        ...(rejected.beforeCheckpointError
+            ? { beforeCheckpointError: rejected.beforeCheckpointError }
+            : {}),
+        ...(rejected.restore ? { restore: rejected.restore } : {}),
+        ...(compiled !== undefined
+            ? { compiled }
+            : rejected.compiled
+                ? { compiled: rejected.compiled }
+                : {}),
+        ...(operatorAcceptance !== undefined
+            ? { operatorAcceptance }
+            : rejected.operatorAcceptance
+                ? { operatorAcceptance: rejected.operatorAcceptance }
+                : {}),
         attempt: promptArtifact.attempt,
         phase: "prompted",
         afterEvidence: undefined,
         evaluation: undefined,
         result: undefined,
+        checkpoints: undefined,
         // The rejected attempt's diagnostics were returned in its receipt; the
         // retry has not submitted a new payload yet.
         normalizationDiagnostics: undefined,
@@ -107,6 +219,82 @@ export function prepareRejectedAttempt(rejected, promptArtifact) {
         updatedAt: Date.now(),
     };
 }
+/** v4.0.5: re-bind a held RETRY prompt to a newly compiled artifact for the
+ *  SAME logical round and attempt. This is not a new attempt: attempt, round,
+ *  before evidence, retry facts, restore marker and branch stay byte-identical;
+ *  only the prompt-derived identity (artifact, prompt hash, transaction id and
+ *  the owning ids on checkpoints) changes.
+ *
+ *  Context preservation is enforced here, not by convention:
+ *  - the artifact identity must equal the held identity;
+ *  - an invocation-recovery recompile must be
+ *    `fresh_invocation / invocation_recovery`;
+ *  - every other recompile must keep the held mode and reason exactly.
+ *
+ *  Evaluation/result fields of the rejected attempt are cleared before the
+ *  Agent receives the new prompt, exactly like `prepareRejectedAttempt`. */
+export function rebindHeldPrompt(held, artifact, compiled, operatorAcceptance) {
+    if (held.phase !== "prompted" || !held.promptArtifact) {
+        throw new Error(`Cannot recompile a prompt in phase ${held.phase}`);
+    }
+    if (artifact.roundId !== held.roundId) {
+        throw new Error(`Held prompt identity mismatch: ${artifact.roundId} !== ${held.roundId}`);
+    }
+    if (artifact.round !== held.round || artifact.attempt !== held.attempt) {
+        throw new Error("Held prompt round/attempt mismatch: a recompile must keep the same " +
+            `round/attempt (${artifact.round}/${artifact.attempt} !== ` +
+            `${held.round}/${held.attempt})`);
+    }
+    const previous = held.promptArtifact;
+    if (artifact.contextReason === "invocation_recovery") {
+        if (artifact.contextMode !== "fresh_invocation") {
+            throw new Error("invocation_recovery requires a fresh_invocation recompile");
+        }
+    }
+    else if (artifact.contextMode !== previous.contextMode ||
+        artifact.contextReason !== previous.contextReason) {
+        throw new Error("A held-prompt recompile must preserve the context boundary: " +
+            `${previous.contextMode}/${previous.contextReason} !== ` +
+            `${artifact.contextMode}/${artifact.contextReason}`);
+    }
+    const transactionId = deriveTransactionId({
+        kind: held.kind,
+        branchId: held.branchId,
+        roundId: held.roundId,
+        attempt: artifact.attempt,
+        promptHash: artifact.promptHash,
+    });
+    const beforeCheckpoint = held.beforeCheckpoint
+        ? { ...held.beforeCheckpoint, transactionId }
+        : undefined;
+    const checkpoints = held.checkpoints
+        ? held.checkpoints.map((item) => ({ ...item, transactionId }))
+        : undefined;
+    return {
+        ...held,
+        transactionId,
+        ...(beforeCheckpoint ? { beforeCheckpoint } : {}),
+        ...(checkpoints ? { checkpoints } : {}),
+        ...(compiled !== undefined
+            ? { compiled }
+            : held.compiled
+                ? { compiled: held.compiled }
+                : {}),
+        ...(operatorAcceptance !== undefined
+            ? { operatorAcceptance }
+            : held.operatorAcceptance
+                ? { operatorAcceptance: held.operatorAcceptance }
+                : {}),
+        phase: "prompted",
+        afterEvidence: undefined,
+        evaluation: undefined,
+        result: undefined,
+        normalizationDiagnostics: undefined,
+        submittedFields: undefined,
+        promptArtifact: artifact,
+        updatedAt: Date.now(),
+    };
+}
 /** v3.8: Shape check for a persisted contract binding. */
 function isContractBinding(value) {
     if (!isRecord(value))
@@ -117,10 +305,309 @@ function isContractBinding(value) {
         return false;
     return isRecord(value.config_hash_by_command);
 }
+const EVIDENCE_POSTURE_STATUSES = [
+    "verified", "insufficient", "contradicted", "unknown", "not_applicable",
+];
+const CONTRACT_ITEM_STATUSES = [
+    "pending", "insufficient", "contradicted", "verified",
+];
+const CONTRACT_CLOSURES = [
+    "open", "verified", "blocked", "superseded",
+];
+const FILE_RECONCILIATIONS = [
+    "match", "mismatch", "unknown", "not_applicable",
+];
+function isNonNegativeInteger(value) {
+    return Number.isInteger(value) && value >= 0;
+}
+function isVerificationFlag(value) {
+    if (!isRecord(value))
+        return false;
+    // `severity` and `check` are the structural facts every consumer keys on.
+    // `field`/`detail` are present on every runtime-generated flag but are
+    // optional here so an older committed flag shape does not make the whole
+    // round unreadable.
+    return (value.severity === "info" || value.severity === "warn" ||
+        value.severity === "error") &&
+        typeof value.check === "string" &&
+        (value.field === undefined || typeof value.field === "string") &&
+        (value.detail === undefined || typeof value.detail === "string") &&
+        (value.ref === undefined || typeof value.ref === "string");
+}
+/** v4.0.3: schema 7 structural validation of the persisted evidence posture.
+ *  A committed round without a well-formed posture is a HARD break — it is not
+ *  committed history and is reported as legacy, never silently re-derived. */
+export function isEvidencePosture(value) {
+    if (!isRecord(value))
+        return false;
+    if (!Number.isInteger(value.round) || value.round < 1)
+        return false;
+    if (value.kind !== "evaluation" && value.kind !== "rollback")
+        return false;
+    if (!EVIDENCE_POSTURE_STATUSES.includes(String(value.status))) {
+        return false;
+    }
+    if (typeof value.machineBackedSuccess !== "boolean" ||
+        typeof value.verificationConfigured !== "boolean")
+        return false;
+    const workspace = value.workspace;
+    if (!isRecord(workspace) ||
+        (workspace.status !== "observed" && workspace.status !== "unknown" &&
+            workspace.status !== "not_applicable") ||
+        !isNonNegativeInteger(workspace.changedPathCount))
+        return false;
+    if (value.files !== null) {
+        const files = value.files;
+        if (!isRecord(files) ||
+            !FILE_RECONCILIATIONS.includes(String(files.reconciliation)) ||
+            !isNonNegativeInteger(files.reported) ||
+            !isNonNegativeInteger(files.observed))
+            return false;
+    }
+    if (!Array.isArray(value.providers) ||
+        value.providers.length > EVIDENCE_POSTURE_CAPS.providers)
+        return false;
+    for (const provider of value.providers) {
+        if (!isRecord(provider) ||
+            typeof provider.providerId !== "string" ||
+            (provider.kind !== "git" && provider.kind !== "custom") ||
+            !OBSERVATION_STATUSES.includes(String(provider.status))) {
+            return false;
+        }
+    }
+    if (!Array.isArray(value.commands) ||
+        value.commands.length > EVIDENCE_POSTURE_CAPS.commands)
+        return false;
+    for (const command of value.commands) {
+        if (!isRecord(command) ||
+            typeof command.commandId !== "string" ||
+            !OBSERVATION_STATUSES.includes(String(command.status)) ||
+            typeof command.required !== "boolean")
+            return false;
+    }
+    if (value.contract !== null) {
+        const contract = value.contract;
+        if (!isRecord(contract) ||
+            typeof contract.id !== "string" ||
+            contract.id.length === 0 ||
+            !CONTRACT_CLOSURES.includes(String(contract.closure)) ||
+            !isNonNegativeInteger(contract.verifiedCount) ||
+            !isNonNegativeInteger(contract.insufficientCount) ||
+            !isNonNegativeInteger(contract.contradictedCount) ||
+            !isNonNegativeInteger(contract.pendingCount) ||
+            !Array.isArray(contract.items) ||
+            contract.items.length > EVIDENCE_POSTURE_CAPS.contractItems)
+            return false;
+        for (const item of contract.items) {
+            if (!isRecord(item) ||
+                typeof item.id !== "string" ||
+                !CONTRACT_ITEM_STATUSES.includes(String(item.status)) ||
+                !stringArray(item.criterionRefs) ||
+                !stringArray(item.reasons))
+                return false;
+        }
+    }
+    if (!Array.isArray(value.findings) ||
+        value.findings.length > EVIDENCE_POSTURE_CAPS.findings)
+        return false;
+    for (const finding of value.findings) {
+        if (!isRecord(finding) ||
+            typeof finding.id !== "string" ||
+            typeof finding.check !== "string" ||
+            (finding.severity !== "info" && finding.severity !== "warn" &&
+                finding.severity !== "error") ||
+            (finding.ref !== undefined && typeof finding.ref !== "string"))
+            return false;
+    }
+    const omitted = value.omitted;
+    if (!isRecord(omitted) ||
+        !isNonNegativeInteger(omitted.providers) ||
+        !isNonNegativeInteger(omitted.commands) ||
+        !isNonNegativeInteger(omitted.contractItems) ||
+        !isNonNegativeInteger(omitted.findings))
+        return false;
+    if (value.kind === "rollback") {
+        // A directive abandons work; it never carries evaluation evidence.
+        if (value.status !== "not_applicable" ||
+            value.machineBackedSuccess !== false ||
+            value.verificationConfigured !== false ||
+            workspace.status !== "not_applicable" ||
+            workspace.changedPathCount !== 0 ||
+            value.files !== null ||
+            value.providers.length > 0 ||
+            value.commands.length > 0 ||
+            value.contract !== null ||
+            value.findings.length > 0 ||
+            omitted.providers !== 0 ||
+            omitted.commands !== 0 ||
+            omitted.contractItems !== 0 ||
+            omitted.findings !== 0)
+            return false;
+    }
+    return true;
+}
+/** v4.0.3: structural validation of the transient retry context. It is only
+ *  legal on a rejected attempt or its held retry prompt. */
+export function isRetryContext(value) {
+    if (!isRecord(value))
+        return false;
+    if (!Number.isInteger(value.attempt) || value.attempt < 2)
+        return false;
+    if (!Number.isInteger(value.rejectedAttempt) ||
+        value.rejectedAttempt < 1)
+        return false;
+    if (value.attempt !== value.rejectedAttempt + 1)
+        return false;
+    if (typeof value.rejectionNotice !== "string")
+        return false;
+    if (!Array.isArray(value.verificationFlags) ||
+        !value.verificationFlags.every(isVerificationFlag))
+        return false;
+    if (!isEvidencePosture(value.evidencePosture))
+        return false;
+    if (value.evidencePosture.kind !== "evaluation")
+        return false;
+    if (typeof value.rejectedAt !== "number")
+        return false;
+    return true;
+}
 export function isProcessResult(value) {
     if (!isRecord(value))
         return false;
-    return ["continue", "stop", "reject", "terminate", "backtrack"].includes(String(value.action)) && Array.isArray(value.verificationFlags);
+    // v4.0.6: every committed decision carries a well-formed Agent outcome
+    // (null only for a rollback directive) and its derived success projection.
+    const outcome = value.agentOutcome;
+    const validOutcome = outcome === null || outcome === "success" ||
+        outcome === "partial" || outcome === "failed" || outcome === "blocked";
+    return ["continue", "stop", "reject", "terminate", "backtrack", "recovery"].includes(String(value.action)) && validOutcome &&
+        typeof value.agentSuccessClaim === "boolean" &&
+        Array.isArray(value.verificationFlags) &&
+        value.verificationFlags.every(isVerificationFlag) &&
+        isEvidencePosture(value.evidencePosture);
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isOperatorAcceptance(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.task === "string" &&
+        stringArray(value.success_criteria) &&
+        stringArray(value.hard_constraints);
+}
+function isCheckpointRole(value) {
+    return value === "before" || value === "mid";
+}
+function isCompiledRoundFacts(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.task === "string" &&
+        typeof value.goalId === "string" &&
+        stringArray(value.constraintsActive) &&
+        stringArray(value.constraintsRetired);
+}
+const CHECKPOINT_ID_RE = /^ck-[a-f0-9]{24}$/;
+const CONTENT_HASH_RE = /^[a-f0-9]{64}$/;
+function isCheckpointRef(value) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.checkpointId !== "string" ||
+        !CHECKPOINT_ID_RE.test(value.checkpointId))
+        return false;
+    if (typeof value.contentHash !== "string" ||
+        !CONTENT_HASH_RE.test(value.contentHash))
+        return false;
+    if (!isCheckpointRole(value.role))
+        return false;
+    if (!Number.isInteger(value.round) || value.round < 1)
+        return false;
+    if (typeof value.roundId !== "string" || value.roundId.length === 0)
+        return false;
+    if (typeof value.transactionId !== "string" || value.transactionId.length === 0)
+        return false;
+    if (typeof value.branchId !== "string" || value.branchId.length === 0)
+        return false;
+    if (!Number.isInteger(value.redoRound) || value.redoRound < 1)
+        return false;
+    if (typeof value.createdAt !== "number")
+        return false;
+    return true;
+}
+function isRecoveryTarget(value) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.checkpoint_id !== "string" ||
+        !CHECKPOINT_ID_RE.test(value.checkpoint_id))
+        return false;
+    if (typeof value.content_hash !== "string" ||
+        !CONTENT_HASH_RE.test(value.content_hash))
+        return false;
+    if (!isCheckpointRole(value.role))
+        return false;
+    if (!Number.isInteger(value.round) || value.round < 1)
+        return false;
+    if (typeof value.round_id !== "string" || value.round_id.length === 0)
+        return false;
+    if (typeof value.transaction_id !== "string" || value.transaction_id.length === 0)
+        return false;
+    if (!Number.isInteger(value.redo_round) || value.redo_round < 1)
+        return false;
+    return true;
+}
+function isRecoveryDirective(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.origin !== "agent" && value.origin !== "machine")
+        return false;
+    if (typeof value.reason !== "string" ||
+        typeof value.transaction_id !== "string" ||
+        value.transaction_id.length === 0) {
+        return false;
+    }
+    if (!isRecoveryTarget(value.target))
+        return false;
+    if (value.trigger_rule !== undefined && typeof value.trigger_rule !== "string")
+        return false;
+    if (!stringArray(value.skipped_files) ||
+        !stringArray(value.skipped_discoveries) ||
+        !stringArray(value.approaches) ||
+        !stringArray(value.wrong_assumptions))
+        return false;
+    if (!Array.isArray(value.failed_rounds) ||
+        !value.failed_rounds.every((item) => Number.isInteger(item)))
+        return false;
+    if (value.observed_skipped_files !== undefined &&
+        !stringArray(value.observed_skipped_files))
+        return false;
+    if (value.reported_skipped_files !== undefined &&
+        !stringArray(value.reported_skipped_files))
+        return false;
+    if (value.abandoned_rounds !== undefined &&
+        (!Array.isArray(value.abandoned_rounds) ||
+            !value.abandoned_rounds.every((item) => Number.isInteger(item)))) {
+        return false;
+    }
+    if (value.trigger_findings !== undefined &&
+        (!Array.isArray(value.trigger_findings) ||
+            !value.trigger_findings.every(isVerificationFlag)))
+        return false;
+    return true;
+}
+function isBeforeCheckpointError(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.code === "string" &&
+        typeof value.detail === "string" &&
+        typeof value.at === "number";
+}
+function isRestoreMarker(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.directiveTransactionId === "string" &&
+        value.directiveTransactionId.length > 0 &&
+        Number.isInteger(value.redoRound) &&
+        value.redoRound >= 1 &&
+        typeof value.verifiedAt === "number";
 }
 function parseMachineObservations(value) {
     if (!Array.isArray(value))
@@ -140,14 +627,13 @@ function parseMachineObservations(value) {
             !isRecord(item.data))
             return null;
         // v3.9.1: Git observations moved to schema 2 (complete boundary
-        // fingerprints); command/custom observations remain schema 1. A
-        // mismatched Git observation is a hard break, reported by
-        // legacyTransactionRounds as an "observation" envelope loss.
-        const expectedVersion = item.kind === "git"
-            ? GIT_OBSERVATION_SCHEMA_VERSION
-            : 1;
-        if (item.schemaVersion !== expectedVersion)
+        // fingerprints); command/custom observations remain schema 1. Custom
+        // observation data is opaque — it never carries a progress fact. ONE
+        // judgment is shared with legacyTransactionRounds, so the parser can never
+        // reject a round the reporter does not report (or the reverse).
+        if (observationVersionIssue(item.kind, item.schemaVersion, item.data, item.status)) {
             return null;
+        }
         if (item.kind === "git" && item.status === "observed") {
             const data = item.data;
             if (!Array.isArray(data.dirty) ||
@@ -169,6 +655,30 @@ export function parseRoundTransactionSnapshot(value) {
         return null;
     if (value.schemaVersion !== ROUND_TRANSACTION_SCHEMA_VERSION)
         return null;
+    if (value.kind !== "evaluation" && value.kind !== "rollback")
+        return null;
+    if (typeof value.branchId !== "string" || value.branchId.length === 0)
+        return null;
+    if (typeof value.transactionId !== "string" || value.transactionId.length === 0) {
+        return null;
+    }
+    if (value.operatorAcceptance !== undefined &&
+        !isOperatorAcceptance(value.operatorAcceptance))
+        return null;
+    if (value.compiled !== undefined && !isCompiledRoundFacts(value.compiled)) {
+        return null;
+    }
+    if (value.kind === "rollback") {
+        if (!isRecoveryDirective(value.recovery))
+            return null;
+        if (!isOperatorAcceptance(value.operatorAcceptance))
+            return null;
+        if (value.compiled !== undefined)
+            return null;
+    }
+    else if (value.recovery !== undefined) {
+        return null;
+    }
     if (typeof value.roundId !== "string" || typeof value.loopId !== "string") {
         return null;
     }
@@ -179,6 +689,17 @@ export function parseRoundTransactionSnapshot(value) {
     if (!["prepared", "prompted", "evaluated", "rejected", "committed", "terminated"]
         .includes(String(value.phase)))
         return null;
+    // Schema 6 structural invariant: a submitted evaluation always carries the
+    // compile facts and the immutable operator surface. A round without them
+    // cannot be re-derived from the same document, so it is not committed
+    // history.
+    if (value.kind === "evaluation" &&
+        (value.phase === "evaluated" || value.phase === "committed")) {
+        if (!isOperatorAcceptance(value.operatorAcceptance))
+            return null;
+        if (!isCompiledRoundFacts(value.compiled))
+            return null;
+    }
     const beforeEvidence = parseMachineObservations(value.beforeEvidence);
     if (!beforeEvidence)
         return null;
@@ -187,8 +708,83 @@ export function parseRoundTransactionSnapshot(value) {
         : parseMachineObservations(value.afterEvidence);
     if (value.afterEvidence !== undefined && !afterEvidence)
         return null;
+    const snapshotRound = value.round;
+    const snapshotRoundId = value.roundId;
+    const snapshotTransactionId = value.transactionId;
+    const snapshotBranchId = value.branchId;
+    if (value.kind === "rollback") {
+        // A rollback directive may carry the abandoned transaction's evidence,
+        // but never that transaction's savepoints or restore marker. The
+        // directive's `target` is the only checkpoint reference.
+        if (value.beforeCheckpoint !== undefined ||
+            value.beforeCheckpointError !== undefined ||
+            value.checkpoints !== undefined ||
+            value.restore !== undefined)
+            return null;
+    }
+    else {
+        if (value.beforeCheckpoint !== undefined) {
+            if (!isCheckpointRef(value.beforeCheckpoint))
+                return null;
+            const ref = value.beforeCheckpoint;
+            if (ref.role !== "before" ||
+                ref.round !== snapshotRound ||
+                ref.roundId !== snapshotRoundId ||
+                ref.transactionId !== snapshotTransactionId ||
+                ref.branchId !== snapshotBranchId ||
+                ref.redoRound !== snapshotRound)
+                return null;
+        }
+        if (value.beforeCheckpointError !== undefined &&
+            !isBeforeCheckpointError(value.beforeCheckpointError))
+            return null;
+        if ((value.beforeCheckpoint === undefined) ===
+            (value.beforeCheckpointError === undefined)) {
+            const observedGitBefore = beforeEvidence.some((observation) => observation.kind === "git" && observation.status === "observed");
+            // A Git-observed transaction owes a before-image or an explicit error.
+            if (observedGitBefore)
+                return null;
+        }
+        if (value.checkpoints !== undefined) {
+            if (!Array.isArray(value.checkpoints) ||
+                value.checkpoints.length > MAX_MID_CHECKPOINTS_PER_TRANSACTION)
+                return null;
+            const seen = new Set();
+            for (const item of value.checkpoints) {
+                if (!isCheckpointRef(item))
+                    return null;
+                if (item.role !== "mid" ||
+                    item.round !== snapshotRound ||
+                    item.roundId !== snapshotRoundId ||
+                    item.transactionId !== snapshotTransactionId ||
+                    item.branchId !== snapshotBranchId ||
+                    item.redoRound !== snapshotRound)
+                    return null;
+                if (seen.has(item.checkpointId))
+                    return null;
+                seen.add(item.checkpointId);
+            }
+        }
+        if (value.restore !== undefined) {
+            if (!isRestoreMarker(value.restore))
+                return null;
+            if (value.restore.redoRound !== snapshotRound)
+                return null;
+            if (value.restore.directiveTransactionId !== snapshotBranchId)
+                return null;
+        }
+    }
     if (value.result !== undefined && !isProcessResult(value.result))
         return null;
+    if (value.retryContext !== undefined) {
+        if (!isRetryContext(value.retryContext))
+            return null;
+        // Transient retry facts exist only between a rejection and the next
+        // attempt. A committed/terminated document that carries them would leak
+        // rejected-attempt evidence into history.
+        if (value.phase !== "rejected" && value.phase !== "prompted")
+            return null;
+    }
     if (value.contractBinding !== undefined && !isContractBinding(value.contractBinding))
         return null;
     if (value.normalizationDiagnostics !== undefined) {
@@ -214,9 +810,10 @@ export function parseRoundTransactionSnapshot(value) {
             return null;
         }
     }
-    // A normalized/committed round always carries its attempted manifest. Its
-    // absence is not a supported legacy shape.
-    if ((value.phase === "evaluated" || value.phase === "committed") &&
+    // A normalized/committed evaluation always carries its attempted manifest.
+    // A rollback directive is not an evaluation and has no manifest.
+    if (value.kind === "evaluation" &&
+        (value.phase === "evaluated" || value.phase === "committed") &&
         value.submittedFields === undefined) {
         return null;
     }
@@ -229,12 +826,57 @@ export function parseRoundTransactionSnapshot(value) {
         // is not committed history, and `legacyTransactionRounds` reports the
         // loss explicitly instead of the loop looking complete while rounds are
         // missing.
+        // v3.9.4: schema 4 requires the ID-level coverage proof. A missing or
+        // malformed coverage object is a hard break, never an empty projection.
+        const coverage = artifact.coverage;
+        const coverageValid = isRecord(coverage) &&
+            Array.isArray(coverage.active) &&
+            coverage.active.every((entry) => isRecord(entry) &&
+                typeof entry.id === "string" &&
+                typeof entry.kind === "string") &&
+            Array.isArray(coverage.rendered) &&
+            coverage.rendered.every((id) => typeof id === "string") &&
+            Array.isArray(coverage.omitted) &&
+            coverage.omitted.every((entry) => isRecord(entry) &&
+                typeof entry.id === "string" &&
+                typeof entry.reason === "string") &&
+            typeof coverage.complete === "boolean";
+        // v4.0.2/v4.0.4: the context boundary is a REQUIRED artifact fact. An
+        // artifact without a legal pair is a hard break, never an implicit
+        // "fresh_invocation" default.
+        // v4.0.5: the shared runtime whitelists are the only legality source; the
+        // optional invocation instruction, when present, must be a non-empty
+        // string. A malformed value is reported as legacy, never silently
+        // accepted.
+        const contextModeValid = isPromptContextMode(artifact.contextMode);
+        const contextReasonValid = isPromptContextReason(artifact.contextReason);
+        const instructionValid = artifact.currentUserInstruction === undefined ||
+            (typeof artifact.currentUserInstruction === "string" &&
+                artifact.currentUserInstruction.trim().length > 0);
         if (artifact.schemaVersion !== PROMPT_ARTIFACT_SCHEMA_VERSION ||
             typeof artifact.roundId !== "string" ||
+            // v4.0.3: the artifact identity is part of the transaction identity.
+            artifact.roundId !== snapshotRoundId ||
+            artifact.round !== snapshotRound ||
+            artifact.attempt !== value.attempt ||
             typeof artifact.renderedPrompt !== "string" ||
             typeof artifact.promptHash !== "string" ||
             typeof artifact.stateHash !== "string" ||
-            !["l0", "l1", "l2"].includes(String(artifact.level)))
+            !["l0", "l1", "l2"].includes(String(artifact.level)) ||
+            !contextModeValid ||
+            !contextReasonValid ||
+            !instructionValid ||
+            !coverageValid)
+            return null;
+        // v4.0.4: the SAME legality guard the assembler enforces. An illegal
+        // pair (for example a retry reason on attempt 1) is not committed history.
+        if (promptContextPairIssue({
+            level: artifact.level,
+            mode: artifact.contextMode,
+            reason: artifact.contextReason,
+            attempt: artifact.attempt,
+            round: artifact.round,
+        }) !== null)
             return null;
     }
     const snapshot = {
@@ -248,12 +890,10 @@ export function parseRoundTransactionSnapshot(value) {
     return snapshot;
 }
 export class RoundTransactionCoordinator {
-    engine;
     store;
     commitStore;
-    constructor(engine, store, commitStore) {
-        this.engine = engine;
-        this.store = store ?? engine.getStore();
+    constructor(store, commitStore) {
+        this.store = store;
         this.commitStore = commitStore ?? new VaultRoundCommitStore(this.store);
     }
     process(input) {
@@ -292,18 +932,20 @@ export class RoundTransactionCoordinator {
             task: input.task,
             currentRound: snapshot.round,
             maxRounds: input.maxRounds,
+            ...(input.history ? { history: input.history } : {}),
             selfEval: input.selfEval,
-            lastSelfEval: input.lastSelfEval,
             consecutiveRejections: input.consecutiveRejections,
             lastRejectionCheck: input.lastRejectionCheck,
             evidenceDeltas: roundDeltas,
             beforeEvidence: snapshot.beforeEvidence,
-            successTrajectory: input.successTrajectory,
-            backtrackSkippedFiles: input.backtrackSkippedFiles,
-            backtrackSkippedFingerprints: input.backtrackSkippedFingerprints,
-            backtrackTargetGitHead: input.backtrackTargetGitHead,
-            backtrackTargetDirty: input.backtrackTargetDirty,
             entrypointTrust: input.entrypointTrust,
+            // v3.9.4: the SAME manifest the receipt reads.
+            submittedFields: input.submittedFields ?? snapshot.submittedFields,
+            ...(input.beforeCheckpoint ? { beforeCheckpoint: input.beforeCheckpoint } : {}),
+            afterEvidence: input.actualEvidence,
+            ...(input.resolveCheckpointManifest
+                ? { resolveCheckpointManifest: input.resolveCheckpointManifest }
+                : {}),
         });
         const evaluated = {
             ...snapshot,
@@ -312,6 +954,8 @@ export class RoundTransactionCoordinator {
             afterEvidence: input.actualEvidence,
             evaluation: input.selfEval,
             result,
+            // A terminated attempt has no next retry; transient facts die with it.
+            ...(result.action === "terminate" ? { retryContext: undefined } : {}),
             ...(input.normalizationDiagnostics !== undefined
                 ? { normalizationDiagnostics: input.normalizationDiagnostics }
                 : {}),
@@ -330,9 +974,40 @@ export class RoundTransactionCoordinator {
                 replayed: false,
             });
         }
+        if ((result.action === "recovery" || result.action === "backtrack") && result.recovery) {
+            const recovery = {
+                ...result.recovery,
+                transaction_id: deriveTransactionId({
+                    kind: "rollback",
+                    branchId: snapshot.branchId,
+                    roundId: snapshot.roundId,
+                    attempt: 1,
+                    promptHash: snapshot.promptArtifact?.promptHash,
+                    recovery: {
+                        target: result.recovery.target,
+                        reason: result.recovery.reason,
+                        abandonedRounds: result.recovery.abandoned_rounds,
+                        failedRounds: result.recovery.failed_rounds,
+                        observedSkippedFiles: result.recovery.observed_skipped_files,
+                        reportedSkippedFiles: result.recovery.reported_skipped_files,
+                        triggerFindings: (result.recovery.trigger_findings ?? [])
+                            .map((flag) => flag.check),
+                    },
+                }),
+            };
+            return this.commitRecovery({
+                snapshot,
+                loopId: snapshot.loopId,
+                recovery,
+                actualEvidence: input.actualEvidence,
+            });
+        }
         const committedSnapshot = {
             ...evaluated,
             phase: "committed",
+            // v4.0.3: transient retry facts die at the commit boundary. The retry
+            // prompt artifact remains the record of what the Agent was asked.
+            retryContext: undefined,
             // v3.8: the contract binding is resolved HERE, at commit time, because
             // the command configuration in force at declaration is not recoverable
             // from the Vault afterwards. Machine-recomputed — never agent-supplied.
@@ -342,20 +1017,32 @@ export class RoundTransactionCoordinator {
             })(),
             updatedAt: Date.now(),
         };
+        if (!snapshot.compiled || !snapshot.operatorAcceptance) {
+            throw new Error("An evaluation commit requires compile facts and the operator acceptance snapshot");
+        }
         const metadata = {
             schema_version: ROUND_TRANSACTION_SCHEMA_VERSION,
             round_id: snapshot.roundId,
             snapshot: committedSnapshot,
             result,
         };
-        this.engine.autoFeedback(input.selfEval, snapshot.loopId, snapshot.round, input.task, metadata);
+        try {
+            this.commitStore.appendFeedback(snapshot.loopId, snapshot.round, metadata);
+        }
+        catch (error) {
+            policyMetrics.recordVaultWriteError("feedback_persist");
+            logEvent("vault_write_error", { error: "feedback_persist" });
+            throw error;
+        }
         // v3.7.1: a backtrack decision commits as the CURRENT round, which the
         // incremental hydration cache never re-reads before the restore compile
         // (it targets the same round). Drop the cache so the rollback — and its
         // Recovery Brief facts — is visible to the very next compile.
-        if (result.action === "backtrack") {
-            this.engine.invalidateHydrationCache(snapshot.loopId);
-        }
+        logEvent("round_complete", {
+            loopId: snapshot.loopId,
+            round: snapshot.round,
+            agentSuccessClaim: result.agentSuccessClaim,
+        });
         const persisted = this.readCommitted(committedSnapshot);
         if (!persisted) {
             throw new Error(`Round transaction commit failed: ${snapshot.roundId}`);
@@ -368,9 +1055,126 @@ export class RoundTransactionCoordinator {
         });
         return finish({ snapshot: committedSnapshot, result, replayed: false });
     }
+    /** v3.9.6: commit an Agent-initiated rollback directive. This path does not
+     *  run verification or enforcement: abandoning work is an action, not a
+     *  success claim. The directive is a typed event, not a `:feedback` round. */
+    commitRecovery(input) {
+        const { snapshot, recovery } = input;
+        if (snapshot.kind !== "evaluation") {
+            throw new Error(`Cannot recover from a ${snapshot.kind} transaction`);
+        }
+        const existing = this.readRecoveryCommitted(input.loopId, snapshot.round, recovery.transaction_id);
+        if (existing) {
+            policyMetrics.recordRound(input.loopId, existing.result, true);
+            return existing;
+        }
+        const committedSnapshot = {
+            ...snapshot,
+            kind: "rollback",
+            transactionId: recovery.transaction_id,
+            phase: "committed",
+            afterEvidence: input.actualEvidence,
+            // A machine recovery keeps the triggering evaluation as the record of
+            // what was abandoned. An agent recovery has no evaluation at all.
+            evaluation: recovery.origin === "machine" ? snapshot.evaluation : undefined,
+            result: undefined,
+            // The operator surface is immutable and survives the rollback. The
+            // directive carries the same byte-identical copy as the abandoned
+            // evaluation so a cold process can still recover it.
+            ...(snapshot.operatorAcceptance
+                ? { operatorAcceptance: snapshot.operatorAcceptance }
+                : {}),
+            compiled: undefined,
+            // The abandoned transaction's savepoints/restore marker belong to that
+            // attempt, not to the child branch. The directive target is the only
+            // recovery point recorded by this event.
+            beforeCheckpoint: undefined,
+            beforeCheckpointError: undefined,
+            checkpoints: undefined,
+            restore: undefined,
+            retryContext: undefined,
+            recovery,
+            submittedFields: recovery.origin === "machine"
+                ? (snapshot.submittedFields ?? [])
+                : [],
+            normalizationDiagnostics: recovery.origin === "machine"
+                ? (snapshot.normalizationDiagnostics ?? [])
+                : [],
+            updatedAt: Date.now(),
+        };
+        const result = {
+            action: recovery.origin === "machine" ? "backtrack" : "recovery",
+            origin: recovery.origin,
+            reason: recovery.reason,
+            recovery,
+            verificationFlags: [],
+            agentSuccessClaim: false,
+            agentOutcome: null,
+            gateContradicted: false,
+            evidencePosture: rollbackEvidencePosture(snapshot.round),
+            newConsecutiveRejections: 0,
+            shouldPushSuccessTrajectory: false,
+        };
+        if (!committedSnapshot.operatorAcceptance) {
+            throw new Error("A rollback directive requires the immutable operator acceptance snapshot");
+        }
+        const envelope = {
+            schema_version: ROUND_TRANSACTION_SCHEMA_VERSION,
+            round_id: snapshot.roundId,
+            snapshot: committedSnapshot,
+            result,
+        };
+        try {
+            this.commitStore.appendRollbackDirective(input.loopId, snapshot.round, recovery.transaction_id, envelope);
+        }
+        catch (error) {
+            policyMetrics.recordVaultWriteError("rollback_persist");
+            logEvent("vault_write_error", { error: "rollback_persist" });
+            throw error;
+        }
+        const persisted = this.readRecoveryCommitted(input.loopId, snapshot.round, recovery.transaction_id);
+        if (!persisted) {
+            throw new Error(`Rollback directive read-back failed: ${recovery.transaction_id}`);
+        }
+        policyMetrics.recordRound(input.loopId, result, false);
+        logEvent("rollback_directive_committed", {
+            loopId: input.loopId,
+            round: snapshot.round,
+            transactionId: recovery.transaction_id,
+            origin: recovery.origin,
+            target: recovery.target,
+        });
+        return { snapshot: committedSnapshot, result, replayed: false };
+    }
+    readRecoveryCommitted(loopId, round, transactionId) {
+        const entry = this.commitStore.findRollback(loopId, round, transactionId);
+        if (!entry)
+            return null;
+        const lineage = isRecord(entry.loop_lineage) ? entry.loop_lineage : null;
+        const transaction = lineage && isRecord(lineage.round_transaction)
+            ? lineage.round_transaction
+            : null;
+        if (!transaction)
+            return null;
+        const snapshot = parseRoundTransactionSnapshot(transaction.snapshot);
+        const result = transaction.result;
+        if (!snapshot || snapshot.kind !== "rollback" || !isProcessResult(result)) {
+            return null;
+        }
+        if (transactionIdentityIssue(entry, {
+            loopId,
+            round,
+            schemaVersion: ROUND_TRANSACTION_SCHEMA_VERSION,
+            transactionId,
+        }))
+            return null;
+        return { snapshot, result, replayed: true };
+    }
     /** Recover an already committed decision without evaluating or writing. */
     recover(snapshot) {
-        const outcome = this.readCommitted(snapshot);
+        const outcome = snapshot.kind === "rollback"
+            ? this.readRecoveryCommitted(snapshot.loopId, snapshot.round, snapshot.transactionId)
+            : this.readCommitted(snapshot);
         if (outcome) {
             policyMetrics.recordRound(snapshot.loopId, outcome.result, true);
         }
@@ -382,28 +1186,41 @@ export class RoundTransactionCoordinator {
         for (const entry of entries) {
             if (entry.task_id !== taskId)
                 continue;
-            const outcome = this.outcomeFromEntry(entry, expected.roundId, opts?.skipBacktrack === true);
+            const outcome = this.outcomeFromEntry(entry, expected, opts?.skipBacktrack === true);
             if (outcome)
                 return outcome;
         }
         return null;
     }
-    outcomeFromEntry(entry, expectedRoundId, skipBacktrack = false) {
+    outcomeFromEntry(entry, expected, skipBacktrack = false) {
         const lineage = isRecord(entry.loop_lineage) ? entry.loop_lineage : null;
         const transaction = lineage && isRecord(lineage.round_transaction)
             ? lineage.round_transaction
             : null;
-        if (!transaction || transaction.round_id !== expectedRoundId)
+        if (!transaction || transaction.round_id !== expected.roundId)
+            return null;
+        if (transactionIdentityIssue(entry, {
+            loopId: expected.loopId,
+            round: expected.round,
+            schemaVersion: ROUND_TRANSACTION_SCHEMA_VERSION,
+            transactionId: expected.transactionId,
+        }))
             return null;
         const snapshot = parseRoundTransactionSnapshot(transaction.snapshot);
         const result = transaction.result;
         if (!snapshot || !isProcessResult(result))
             return null;
+        // v3.9.7: the numeric round identity is NOT enough. A deep restore reuses
+        // `target.redo_round`, where the abandoned branch already committed a
+        // feedback round with the same roundId. Replaying it would silently discard
+        // the redo submission. The transaction id is the branch-scoped identity.
+        if (snapshot.transactionId !== expected.transactionId)
+            return null;
         // v3.2.1: a committed backtrack is a roll-back directive, not a terminal
         // decision. The restored round reuses the same roundId, so replaying it
         // would silently discard the agent's redo submission and re-emit the
         // backtrack prompt forever (the redo's work is never evaluated, and the
-        // R4/R9 terminate guards never run because evaluation is short-circuited).
+        // the terminate guards never run because evaluation is short-circuited).
         // Crash recovery still replays backtracks (recover() → reconcileCommittedRound
         // resets the round counter from the committed decision); only the advance
         // path skips them so the redo is evaluated normally.