ai-foreman 1.7.28 → 2.0.0

package/dist/continuity.js

@@ -1,10 +1,14 @@
+import { persistedProviderWireContract } from "rafi-spec";
 import { dispatchWithGraphAccess, withGraphSessionAccess } from "./graph/session.js";
 import { localBuildAuthority } from "./buildAdmission.js";
 import { randomUUID, createHash } from "node:crypto";
-import { continuityDeltaV1Schema, zodIssues } from "rafi-spec";
+import { continuityDeltaV1Schema, initializationOutput, zodIssues } from "rafi-spec";
 import { BuilderEventQueue } from "./activity.js";
 import { providerSessionKey } from "./sessionIdentity.js";
+import { nativePolicy, operationInstruction, journalStructuredDispatch, continuationPolicy } from "./structuredOperation.js";
 import { WorkflowDb } from "./workflowDb.js";
+import { assertSealedDispatch, withFreshRecoveryValidation } from "./structuredDispatchAuthority.js";
+import { verifyPersistedDispatch } from "./structuredDispatchRecord.js";
 export const CONTINUITY_MARKER = "RAFI_CONTINUITY_DELTA:";
 export class ContinuityValidationError extends Error {
     problems;
@@ -44,6 +48,7 @@ export class SessionUnavailableContinuityError extends Error {
         this.guidedRecovery = guidedRecovery;
     }
 }
+export const CONTINUITY_REQUIRED_INSTRUCTION = "Include the required bounded continuity object in the operation response; continuity cannot be null for this session.";
 export function validateContinuityDelta(value) {
     const problems = [];
     if (!value || typeof value !== "object" || Array.isArray(value))
@@ -74,20 +79,6 @@ export function validateContinuityDelta(value) {
         throw new ContinuityValidationError(problems);
     return output;
 }
-export function parseContinuityDelta(text) {
-    const lines = text.split(/\r?\n/);
-    const markerIndexes = lines.flatMap((line, index) => line.trimStart().startsWith(CONTINUITY_MARKER) ? [index] : []);
-    const cleanText = lines.filter((_line, index) => !markerIndexes.includes(index)).join("\n").trimEnd();
-    if (markerIndexes.length !== 1)
-        return { cleanText, error: new ContinuityValidationError([markerIndexes.length ? "multiple continuity markers" : "missing continuity marker"]) };
-    const raw = lines[markerIndexes[0]].trimStart().slice(CONTINUITY_MARKER.length).trim();
-    try {
-        return { delta: validateContinuityDelta(JSON.parse(raw)), cleanText };
-    }
-    catch (error) {
-        return { cleanText, error: error instanceof ContinuityValidationError ? error : new ContinuityValidationError([`marker is not valid JSON: ${String(error)}`]) };
-    }
-}
 export function mergeContinuityDeltas(deltas) {
     const result = baselineContinuityDelta();
     for (const delta of deltas) {
@@ -136,7 +127,7 @@ export class ContinuityAdapter {
             db.ensureRun(options.runId);
             if (!db.continuityHead(options.runId, options.role)) {
                 db.appendContinuityEvent({ runId: options.runId, role: "host", kind: "role_baseline", payload: { role: options.role, provider: options.settings.make, model: options.settings.model }, authoritativeStateRevision: this.revision() });
-                db.publishContinuityCheckpoint({ runId: options.runId, role: options.role, delta: baselineContinuityDelta(), authoritativeStateRevision: this.revision() });
+                db.publishContinuityCheckpoint({ runId: options.runId, role: options.role, delta: baselineContinuityDelta(), hostEventKind: "role-baseline", inputCheckpointDigests: [], authoritativeStateRevision: this.revision() });
             }
             const initialSession = options.adapter.sessionRef?.() ?? options.adapter.sessionId();
             if (initialSession)
@@ -166,7 +157,7 @@ export class ContinuityAdapter {
         }
         this.validatingFreshRecovery = true;
         try {
-            const result = await this.sendTurn("Fresh recovery validation only. Do not use tools, change files, implement work, or request a handoff. Acknowledge this new session and emit the required continuity record using only the supplied instructions.", { responseOnly: true });
+            const result = await withFreshRecoveryValidation(this.options.projectDir, this.options.runId, this.options.role, authorization => this.sendTurn("Fresh recovery validation only. Do not use tools, change files, implement work, or request a handoff. Acknowledge this new session and include the required continuity object. " + operationInstruction(initializationOutput), nativePolicy(initializationOutput, { responseOnly: true, journalRunId: this.options.runId, dispatchId: `fresh-recovery:${authorization.decisionDigest}` })));
             if (result.isError || result.failure || this.recoveryLeasePending)
                 throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "fresh recovery did not establish a valid continuity checkpoint");
         }
@@ -179,13 +170,35 @@ export class ContinuityAdapter {
         }
     }
     get agent() { return this.adapter.agent; }
+    /** Every confirmed dispatch publishes a checkpoint, so continuity is mandatory. */
+    structuredDispatchRequirement() {
+        return { instruction: CONTINUITY_REQUIRED_INSTRUCTION, validate: response => { validateContinuityDelta(response.continuity); } };
+    }
     async sendTurn(instruction, policy) {
-        return withGraphSessionAccess(this.options.projectDir, this.adapter, () => this.sendTurnOwned(instruction, policy));
+        if (!policy?.output)
+            throw new Error("Continuity dispatch requires a native operation contract");
+        if (policy.dispatchCapability) {
+            assertSealedDispatch(this.options.projectDir, policy.dispatchCapability, policy.selectedDispatch, instruction);
+            return this.sendTurnOwned(instruction, policy);
+        }
+        // The continuity requirement is applied by journalStructuredDispatch through
+        // structuredDispatchRequirement(), before sealing, on every dispatch path.
+        const hostInstruction = instruction;
+        return withGraphSessionAccess(this.options.projectDir, this.adapter, () => policy?.output
+            ? journalStructuredDispatch(this.options.projectDir, this, instruction, { ...policy, journalRunId: policy.journalRunId ?? this.options.runId }, (text, selected) => this.sendTurnOwned(text, selected))
+            : this.sendTurnOwned(instruction, policy)).then(result => {
+            if (result.failure?.category === "session-unavailable") {
+                this.recordSessionUnavailable(result.failure, hostInstruction);
+                throw new SessionUnavailableContinuityError(this.options.runId, this.options.role, result.failure);
+            }
+            return { ...result, hostInstruction };
+        });
     }
     async sendTurnOwned(instruction, policy) {
-        const providerInstruction = `${instruction}\n\n${continuityInstruction(this.options.role)}`;
+        const providerInstruction = instruction;
         const journal = new WorkflowDb(this.options.projectDir);
-        const dispatchId = `dispatch:${this.options.runId}:${this.options.role}:${randomUUID()}`;
+        const dispatchId = policy?.dispatchId ?? `dispatch:${this.options.runId}:${this.options.role}:${randomUUID()}`;
+        const beforeSession = this.adapter.sessionRef?.();
         let original;
         try {
             journal.atomic(() => {
@@ -204,22 +217,32 @@ export class ContinuityAdapter {
                 if (!(this.validatingFreshRecovery && this.recoveryLeasePending && policy?.responseOnly) && owner && session && (owner.providerSessionId !== session || (owner.sessionKey && ref && owner.sessionKey !== providerSessionKey(ref)))) {
                     throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "provider session no longer owns role dispatch authority");
                 }
-                if (journal.unresolvedRoleDispatches(this.options.runId, this.options.role).length)
+                if (journal.unresolvedRoleDispatches(this.options.runId, this.options.role).filter(item => item.idempotencyKey !== dispatchId).length)
                     throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "a previous dispatched turn has no durable completion; reconcile it before sending more work");
-                journal.planOperation({ runId: this.options.runId, idempotencyKey: dispatchId, kind: "provider-dispatch", intent: { role: this.options.role, sessionRef: this.adapter.sessionRef?.(), instructionDigest: sha(instruction), instructionBytes: Buffer.byteLength(instruction) } });
-                journal.updateOperation(dispatchId, "in_progress");
+                if (!policy?.selectedDispatch)
+                    journal.planOperation({ runId: this.options.runId, idempotencyKey: dispatchId, kind: "provider-dispatch", intent: { role: this.options.role, sessionRef: this.adapter.sessionRef?.(), instructionDigest: sha(instruction), instructionBytes: Buffer.byteLength(instruction) } });
+                if (!policy?.selectedDispatch)
+                    journal.updateOperation(dispatchId, "in_progress");
                 journal.appendContinuityEvent({ runId: this.options.runId, role: "host", kind: "turn_started", payload: { role: this.options.role, dispatchId, instructionDigest: sha(instruction), instructionBytes: Buffer.byteLength(instruction) }, authoritativeStateRevision: this.revision() });
             });
             try {
                 original = await dispatchWithGraphAccess(this.options.projectDir, this.adapter, providerInstruction, policy, (text, p) => this.adapter.sendTurn(text, p));
             }
             catch (error) {
-                journal.updateOperation(dispatchId, "uncertain", { error: String(error) });
+                if (!policy?.selectedDispatch)
+                    journal.updateOperation(dispatchId, "uncertain", { error: String(error) });
                 throw error;
             }
-            const responseDigest = journal.putEvidence("handoff", original.rawResponse ?? original.text);
+            // Preserve the native transport result before interpreting it or publishing
+            // a checkpoint. The outer journal remains the sole completion owner.
+            // journalStructuredDispatch owns the one retained raw receipt for native
+            // turns. Continuity records retain only its durable reference/fact.
+            const responseDigest = policy?.selectedDispatch ? undefined : journal.putEvidence("handoff", Buffer.from(JSON.stringify(original)));
             journal.atomic(() => {
-                journal.updateOperation(dispatchId, original.failure?.dispatchState === "unknown" ? "uncertain" : original.failure?.dispatchState === "not-sent" ? "failed" : "confirmed", { result: { responseDigest, isError: original.isError, failure: original.failure, turnId: original.turnId, sessionRef: this.adapter.sessionRef?.() } });
+                journal.appendContinuityEvent({ runId: this.options.runId, role: this.options.role, kind: "provider_response_received",
+                    payload: { dispatchId, ...(responseDigest ? { responseDigest } : { journalOwnedEvidence: true }) }, authoritativeStateRevision: this.revision() });
+                if (!policy?.selectedDispatch)
+                    journal.updateOperation(dispatchId, original.failure?.dispatchState === "unknown" ? "uncertain" : original.failure?.dispatchState === "not-sent" ? "failed" : "confirmed", { result: { responseDigest, isError: original.isError, failure: original.failure, turnId: original.turnId, sessionRef: this.adapter.sessionRef?.() } });
                 if (original.failure?.dispatchState === "not-sent")
                     journal.appendContinuityEvent({ runId: this.options.runId, role: this.options.role, kind: "turn_not_sent", payload: { dispatchId, role: this.options.role }, authoritativeStateRevision: this.revision() });
             });
@@ -227,152 +250,162 @@ export class ContinuityAdapter {
         finally {
             journal.close();
         }
-        if (policy?.handback) {
-            const parsed = parseContinuityDelta(original.rawResponse ?? original.text);
-            // The delivery journal owns the sole repair allowance and validates execution
-            // before a checkpoint is published. Never transfer/replay inside this turn.
-            return { ...original, text: parsed.cleanText, hostInstruction: instruction,
-                providerInstruction: original.providerInstruction ?? providerInstruction,
-                rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText,
-                continuityErrors: parsed.error?.problems ?? [] };
+        return original;
+    }
+    async postConfirmedDispatch(reference) {
+        const db = new WorkflowDb(this.options.projectDir);
+        let original;
+        let context;
+        let response;
+        try {
+            const operation = db.operation(reference.dispatchId);
+            if (operation?.runId !== this.options.runId || reference.runId !== this.options.runId || db.structuredOwnerDispatch(reference.dispatchId).tupleDigest !== reference.tupleDigest)
+                throw new Error("Continuity postprocessing belongs to a foreign dispatch");
+            original = db.retainedStructuredTurn(reference.dispatchId);
+            context = db.structuredProcessingContext(reference.dispatchId);
+            const tuple = original.selectedDispatch;
+            const contract = persistedProviderWireContract(tuple).canonical;
+            response = db.replayStructuredDispatch(reference.dispatchId, contract);
         }
-        const activeSession = this.adapter.sessionRef?.() ?? this.adapter.sessionId();
-        if (activeSession) {
-            const leaseDb = new WorkflowDb(this.options.projectDir);
+        finally {
+            db.close();
+        }
+        const delta = validateContinuityDelta(response.continuity);
+        if (this.recoveryLeasePending && (response.result.kind !== "completed" || !response.result.payload.ready))
+            throw new Error("Fresh recovery requires a completed initialization checkpoint");
+        if (!context.policy.handback) {
+            this.publish(delta, "turn_completed", original);
+        }
+        if (response.result.kind === "handoff-request") {
+            if (context.policy.handback || this.options.durableSingleTurn || this.validatingFreshRecovery)
+                throw new Error("This operation cannot transfer its session");
+            // Publication is complete before the explicitly linked acceptance stage.
+            const completed = new WorkflowDb(this.options.projectDir);
             try {
-                leaseDb.claimInitialRoleLease(this.options.runId, this.options.role, activeSession);
+                completed.beginStructuredHandoff(reference.dispatchId);
+                completed.completeStructuredPostprocessing(reference.dispatchId);
             }
             finally {
-                leaseDb.close();
+                completed.close();
             }
-        }
-        if (original.failure?.category === "session-unavailable") {
-            this.recordSessionUnavailable(original.failure, instruction);
-            throw new SessionUnavailableContinuityError(this.options.runId, this.options.role, original.failure);
-        }
-        if (original.isError || original.failure)
-            return original;
-        const parsed = parseContinuityDelta(original.text);
-        if (parsed.delta && !original.isError && !original.failure) {
-            this.publish(parsed.delta, "turn_completed", original);
-            this.moveRecoveryLeaseAfterCheckpoint();
-            if (this.options.durableSingleTurn || this.validatingFreshRecovery) {
-                return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
-                    rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
+            const successor = await this.options.handleHandoffRequest?.({ version: 1, reason: response.result.reason, roleState: response.result.roleState, delta, predecessorDispatchId: reference.dispatchId }, this.adapter, context.instruction);
+            if (!successor || successor === this.adapter)
+                throw new Error("Handoff request did not establish a validated successor");
+            const continuation = new WorkflowDb(this.options.projectDir);
+            let continuationId;
+            try {
+                const session = successor.sessionRef?.();
+                if (!session)
+                    throw new Error("Handoff successor has no scoped session");
+                continuationId = continuation.planStructuredContinuation(reference.dispatchId, session);
             }
-            const successor = await this.options.handleHandoffRequest?.(original.text, this.adapter, instruction);
-            if (successor && successor !== this.adapter) {
-                await this.adoptValidatedSuccessor(successor);
-                return this.sendTurn([
-                    "Continue the frozen action after the accepted Rafi handoff. Do not repeat completed side effects.",
-                    instruction,
-                ].join("\n\n"), policy);
+            finally {
+                continuation.close();
             }
-            return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
-                rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
+            await this.adoptValidatedSuccessor(successor);
+            const tuple = original.selectedDispatch;
+            const output = persistedProviderWireContract(tuple).canonical;
+            return this.sendTurn("Continue the frozen action after the accepted handoff. Reconcile receipts; do not repeat completed side effects.\n" + context.instruction, nativePolicy(output, { ...continuationPolicy(context.policy, reference.dispatchId), dispatchId: continuationId }));
         }
-        if (this.options.durableSingleTurn || (this.validatingFreshRecovery && this.recoveryLeasePending && policy?.responseOnly)) {
-            const invalidDb = new WorkflowDb(this.options.projectDir);
+        return { ...original, hostInstruction: context.instruction, continuityErrors: [], continuity: delta };
+    }
+    observeEvents(listener) {
+        if (!this.adapter.observeEvents)
+            throw new Error("wrapped provider does not expose turn observation");
+        return this.adapter.observeEvents(listener);
+    }
+    acceptHandbackTurn(turn) {
+        if (turn.structured) {
+            if (turn.isError || turn.failure || turn.structured.state !== "candidate")
+                throw new Error("cannot publish an invalid handback checkpoint");
+            const db = new WorkflowDb(this.options.projectDir);
+            let retained;
             try {
-                invalidDb.appendContinuityEvent({ runId: this.options.runId, role: "host", kind: "continuity_invalid", payload: { problems: parsed.error?.problems }, authoritativeStateRevision: this.revision() });
+                if (!turn.selectedDispatch || db.operation(turn.selectedDispatch.dispatchId)?.runId !== this.options.runId)
+                    throw new Error("Foreign handback dispatch");
+                retained = db.retainedStructuredTurn(turn.selectedDispatch.dispatchId);
             }
             finally {
-                invalidDb.close();
+                db.close();
             }
-            return { ...original, isError: true, continuityErrors: parsed.error?.problems ?? ["unknown continuity error"], text: `QA continuity record was invalid: ${parsed.error?.problems.join("; ") ?? "unknown error"}`,
-                hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
-                rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
+            const tuple = retained.selectedDispatch;
+            const owner = new WorkflowDb(this.options.projectDir);
+            try {
+                const response = verifyPersistedDispatch(persistedProviderWireContract(tuple).canonical, owner.structuredOwnerDispatch(tuple.dispatchId), retained.structured, tuple);
+                this.publish(validateContinuityDelta(response.continuity), "handback_turn_completed", retained);
+            }
+            finally {
+                owner.close();
+            }
+            return;
         }
-        const budget = new WorkflowDb(this.options.projectDir);
+        throw new Error("Handback acceptance requires a native receipt and validated continuity");
+    }
+    /** Explicit restart recovery of the already accepted action; never repeats acceptance. */
+    async resumePlannedContinuation() {
+        const db = new WorkflowDb(this.options.projectDir);
+        let continuation;
+        let context;
+        let output;
         try {
-            const maximum = budget.autonomyPolicy(this.options.runId)?.limits.protocolCorrections ?? 1;
-            if (!budget.reserveRecoveryAllowance(this.options.runId, policy?.logicalActionId ?? sha(instruction), "protocol-correction", maximum)) {
-                throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "shared protocol correction budget exhausted");
+            continuation = db.structuredContinuation(this.options.runId, this.options.role);
+            if (!continuation)
+                return;
+            const operation = db.operation(continuation.continuationId);
+            if (operation?.status === "confirmed") {
+                if (db.pendingStructuredPostprocessing(this.options.runId).includes(continuation.continuationId)) {
+                    await this.postConfirmedDispatch({ dispatchId: continuation.continuationId, runId: this.options.runId,
+                        tupleDigest: db.structuredOwnerDispatch(continuation.continuationId).tupleDigest });
+                    db.completeStructuredPostprocessing(continuation.continuationId);
+                    db.finishStructuredContinuation(continuation.continuationId);
+                }
+                const turn = db.retainedStructuredTurn(continuation.continuationId);
+                const descriptor = persistedProviderWireContract(turn.selectedDispatch);
+                const response = db.replayStructuredDispatch(continuation.continuationId, descriptor.canonical);
+                return { ...turn, continuity: validateContinuityDelta(response.continuity) };
             }
+            if (continuation.state !== "continuation-planned" || operation && operation.status !== "planned")
+                throw new Error("Continuation may already have been submitted; explicit reconciliation is required");
+            const current = this.adapter.sessionRef?.();
+            if (!current || providerSessionKey(current) !== providerSessionKey(continuation.successor))
+                throw new Error("Reattach the durably accepted successor before continuation recovery");
+            context = db.structuredProcessingContext(continuation.predecessorId);
+            const predecessor = db.retainedStructuredTurn(continuation.predecessorId);
+            output = persistedProviderWireContract(predecessor.selectedDispatch).canonical;
         }
         finally {
-            budget.close();
-        }
-        const repair = await dispatchWithGraphAccess(this.options.projectDir, this.adapter, [
-            "Continuity protocol repair only. Do not run tools, repeat work, or change files.",
-            `Your prior turn's continuity record was invalid: ${parsed.error?.problems.join("; ")}.`,
-            continuityInstruction(),
-            "Return only the continuity record.",
-        ].join("\n"), { ...policy, purpose: "response-repair", responseOnly: true }, (text, p) => this.adapter.sendTurn(text, p));
-        const repaired = parseContinuityDelta(repair.text);
-        if (repaired.delta && !repair.isError && !repair.failure) {
-            this.publish(repaired.delta, "turn_completed_after_repair", original);
-            this.moveRecoveryLeaseAfterCheckpoint();
-            const successor = await this.options.handleHandoffRequest?.(original.text, this.adapter, instruction);
-            if (successor && successor !== this.adapter) {
-                await this.adoptValidatedSuccessor(successor);
-                return this.sendTurn(["Continue the frozen action after the accepted Rafi handoff. Do not repeat completed side effects.", instruction].join("\n\n"), policy);
-            }
-            return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
-                rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
+            db.close();
         }
-        const invalidDb = new WorkflowDb(this.options.projectDir);
+        return this.sendTurn("Continue the frozen action after the accepted handoff. Reconcile receipts; do not repeat completed side effects.\n" + context.instruction, nativePolicy(output, { ...continuationPolicy(context.policy, continuation.predecessorId), dispatchId: continuation.continuationId }));
+    }
+    async recoverConfirmedPublications() {
+        const db = new WorkflowDb(this.options.projectDir);
+        let pending;
         try {
-            invalidDb.appendContinuityEvent({ runId: this.options.runId, role: "host", kind: "continuity_invalid_twice", payload: { original: parsed.error?.problems, repair: repaired.error?.problems }, authoritativeStateRevision: this.revision() });
-            invalidDb.setContinuityHeadState(this.options.runId, this.options.role, "invalid");
+            pending = db.pendingStructuredPostprocessing(this.options.runId);
         }
         finally {
-            invalidDb.close();
+            db.close();
         }
-        const handoff = this.reconstructionHandoff();
-        if (this.options.recoverWithHandoff) {
-            let successor;
+        for (const dispatchId of pending) {
+            const current = new WorkflowDb(this.options.projectDir);
+            let reference;
             try {
-                successor = await this.options.recoverWithHandoff({
-                    reason: "continuity delta and same-session repair were both invalid",
-                    reconstruction: handoff,
-                    predecessor: this.adapter,
-                });
+                reference = { dispatchId, runId: this.options.runId, tupleDigest: current.structuredOwnerDispatch(dispatchId).tupleDigest };
             }
-            catch (error) {
-                throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, `fresh validated successor also failed after the same-session repair: ${error instanceof Error ? error.message : String(error)}`);
+            finally {
+                current.close();
             }
-            if (!successor.sessionId() || successor.sessionId() === this.adapter.sessionId()) {
-                await successor.close().catch(() => { });
-                throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "validated recovery callback did not return a genuinely fresh successor");
+            await this.postConfirmedDispatch(reference);
+            const completed = new WorkflowDb(this.options.projectDir);
+            try {
+                completed.completeStructuredPostprocessing(dispatchId);
+                completed.finishStructuredContinuation(dispatchId);
+            }
+            finally {
+                completed.close();
             }
-            await this.adoptValidatedSuccessor(successor);
-            return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction,
-                rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
-        }
-        if (!this.options.createSuccessor)
-            throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "continuity repair failed in the original session and no validated successor is configured");
-        const successor = await this.options.createSuccessor(handoff);
-        const accepted = await dispatchWithGraphAccess(this.options.projectDir, successor, `${handoff}\n\nReply with HANDOFF_ACCEPTED on the first line, then ${continuityInstruction()}`, { purpose: "contract-acceptance", responseOnly: true }, (text, p) => successor.sendTurn(text, p));
-        const successorDelta = parseContinuityDelta(accepted.text);
-        const firstAcceptanceLine = accepted.text.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
-        if (firstAcceptanceLine !== "HANDOFF_ACCEPTED" || !successorDelta.delta || !successor.sessionId()) {
-            await successor.close().catch(() => { });
-            throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "fresh successor did not validate and accept the cumulative checkpoint");
-        }
-        await this.adoptValidatedSuccessor(successor);
-        this.publish(successorDelta.delta, "fresh_successor_accepted", accepted);
-        const leaseDb = new WorkflowDb(this.options.projectDir);
-        try {
-            leaseDb.moveRoleLeaseAfterValidatedRecovery(this.options.runId, this.options.role, successor.sessionRef?.() ?? successor.sessionId(), "double-invalid continuity recovery");
-        }
-        finally {
-            leaseDb.close();
         }
-        return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction,
-            rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
-    }
-    observeEvents(listener) {
-        if (!this.adapter.observeEvents)
-            throw new Error("wrapped provider does not expose turn observation");
-        return this.adapter.observeEvents(listener);
-    }
-    acceptHandbackTurn(turn) {
-        const parsed = parseContinuityDelta(turn.rawResponse ?? turn.text);
-        if (turn.isError || turn.failure || !parsed.delta)
-            throw new Error("cannot publish an invalid handback checkpoint");
-        this.publish(parsed.delta, "handback_turn_completed", turn);
-        this.moveRecoveryLeaseAfterCheckpoint();
     }
     sessionId() { return this.adapter.sessionId(); }
     sessionRef() { return this.adapter.sessionRef?.(); }
@@ -422,30 +455,32 @@ export class ContinuityAdapter {
         const db = new WorkflowDb(this.options.projectDir);
         try {
             const sessionRef = this.adapter.sessionRef?.();
-            return db.atomic(() => {
-                db.appendContinuityEvent({ runId: this.options.runId, role: this.options.role, kind, payload: { isError: result.isError, numTurns: result.numTurns, sessionId: this.adapter.sessionId(), sessionRef, delta }, authoritativeStateRevision: this.revision(), sessionRef });
-                return db.publishContinuityCheckpoint({ runId: this.options.runId, role: this.options.role, delta, authoritativeStateRevision: this.revision(), sessionRef });
+            let moved = false;
+            const checkpoint = db.atomic(() => {
+                if (this.recoveryLeasePending && sessionRef)
+                    db.assertFreshRecoveryValidation(result.selectedDispatch.dispatchId, sessionRef);
+                const prior = db.providerCheckpoint(result.selectedDispatch.dispatchId, kind);
+                if (prior) {
+                    if (JSON.stringify(prior.delta) !== JSON.stringify(delta))
+                        throw new Error("Conflicting repeated continuity publication");
+                    return prior;
+                }
+                db.appendContinuityEvent({ runId: this.options.runId, role: this.options.role, kind, payload: { dispatchId: result.selectedDispatch.dispatchId, isError: result.isError, numTurns: result.numTurns, sessionId: this.adapter.sessionId(), sessionRef, delta }, authoritativeStateRevision: this.revision(), sessionRef });
+                const published = db.publishContinuityCheckpoint({ runId: this.options.runId, role: this.options.role, delta, authoritativeStateRevision: this.revision(), sessionRef, origin: { kind: "provider", dispatchId: result.selectedDispatch.dispatchId, publicationKind: kind } });
+                if (this.recoveryLeasePending && sessionRef) {
+                    db.moveRoleLeaseAfterValidatedRecovery(this.options.runId, this.options.role, sessionRef, "explicit fresh-recovery-only continuation");
+                    moved = true;
+                }
+                return published;
             });
+            if (moved)
+                this.recoveryLeasePending = false;
+            return checkpoint;
         }
         finally {
             db.close();
         }
     }
-    moveRecoveryLeaseAfterCheckpoint() {
-        if (!this.recoveryLeasePending)
-            return;
-        const session = this.adapter.sessionRef?.() ?? this.adapter.sessionId();
-        if (!session)
-            return;
-        const db = new WorkflowDb(this.options.projectDir);
-        try {
-            db.moveRoleLeaseAfterValidatedRecovery(this.options.runId, this.options.role, session, "explicit fresh-recovery-only continuation");
-        }
-        finally {
-            db.close();
-        }
-        this.recoveryLeasePending = false;
-    }
     recordSessionUnavailable(failure, instruction) {
         const sessionRef = this.adapter.sessionRef?.();
         const db = new WorkflowDb(this.options.projectDir);
@@ -473,22 +508,6 @@ export class ContinuityAdapter {
             db.close();
         }
     }
-    reconstructionHandoff() {
-        const db = new WorkflowDb(this.options.projectDir);
-        try {
-            const checkpoints = db.continuityCheckpoints(this.options.runId, this.options.role);
-            const events = db.continuityEvents(this.options.runId, checkpoints.at(-1)?.sequence ?? 0);
-            return [
-                `Validated cumulative recovery for run ${this.options.runId}, role ${this.options.role}.`,
-                JSON.stringify(mergeContinuityDeltas(checkpoints.map((checkpoint) => checkpoint.delta))),
-                `Later host facts: ${JSON.stringify(events.map((event) => ({ kind: event.kind, payload: event.payload, digest: event.digest })))}`,
-                "The prior in-flight operation is unknown unless a host fact proves completion. Reconcile receipts before retrying side effects.",
-            ].join("\n\n");
-        }
-        finally {
-            db.close();
-        }
-    }
     revision() { return this.options.authoritativeStateRevision?.() ?? this.options.settings.settings_revision; }
     pumpEvents() {
         const source = this.adapter;

package/dist/continuityOrigin.d.ts

@@ -0,0 +1,13 @@
+import type Database from "better-sqlite3";
+export type CheckpointOrigin = {
+    kind: "provider";
+    dispatchId: string;
+    publicationKind: string;
+} | {
+    kind: "host";
+    eventSequence: number;
+    inputCheckpointDigests: string[];
+};
+/** Read-only replay: never opens a writer or migrates storage. */
+export declare function verifyCheckpointOrigin(db: Database.Database, projectDir: string, checkpointId: number, visited?: Set<number>): void;
+export declare function verifyContinuityHeads(db: Database.Database, projectDir: string, runId: string): void;

package/dist/continuityOrigin.js

@@ -0,0 +1,91 @@
+import { persistedProviderWireContract } from "rafi-spec";
+import { createHash } from "node:crypto";
+import { canonicalJson } from "rafi-spec";
+import { graphDerivedAllowed } from "./graph/derived.js";
+import { hydrateStructuredReceipt, persistedDispatchTuple, verifyPersistedDispatch } from "./structuredDispatchRecord.js";
+/** Read-only replay: never opens a writer or migrates storage. */
+export function verifyCheckpointOrigin(db, projectDir, checkpointId, visited = new Set()) {
+    if (visited.has(checkpointId))
+        throw new Error("Cyclic checkpoint provenance");
+    visited.add(checkpointId);
+    const checkpoint = db.prepare("SELECT * FROM continuity_checkpoints WHERE checkpoint_id=?").get(checkpointId);
+    const row = db.prepare("SELECT origin_json,delta_digest FROM continuity_checkpoint_origins WHERE checkpoint_id=?").get(checkpointId);
+    if (!checkpoint || !row || hash(checkpoint.delta_json) !== row.delta_digest)
+        throw new Error("Checkpoint has no verified provenance");
+    const origin = JSON.parse(row.origin_json);
+    if (origin.kind === "provider") {
+        const operation = db.prepare("SELECT * FROM operation_journal WHERE idempotency_key=?").get(origin.dispatchId);
+        if (!operation || operation.run_id !== checkpoint.run_id || operation.status !== "confirmed")
+            throw new Error("Checkpoint origin is not a confirmed dispatch in this run");
+        const intent = JSON.parse(operation.intent_json), result = JSON.parse(operation.result_json);
+        const tuple = persistedDispatchTuple(intent.sealedDispatch);
+        if (canonicalJson(intent.tuple) !== intent.sealedDispatch.tupleJson || tuple.dispatchId !== origin.dispatchId || intent.sessionRef?.role !== checkpoint.role)
+            throw new Error("Checkpoint origin tuple/role mismatch");
+        const frozen = intent.sessionRef;
+        if (!frozen || frozen.sessionId !== tuple.sessionId || frozen.provider !== tuple.provider || frozen.generation !== tuple.generation)
+            throw new Error("Checkpoint origin frozen session mismatch");
+        const review = db.prepare("SELECT intent_json FROM qa_turns WHERE operation_id=?").get(origin.dispatchId);
+        if (review && canonicalJson(JSON.parse(review.intent_json).sealedDispatch) !== canonicalJson(intent.sealedDispatch))
+            throw new Error("Checkpoint QA owner differs from transport intent");
+        const delivery = db.prepare("SELECT record_json FROM qa_delivery_turns WHERE turn_record_id=?").get(origin.dispatchId);
+        if (delivery && canonicalJson(JSON.parse(delivery.record_json).sealedDispatch) !== canonicalJson(intent.sealedDispatch))
+            throw new Error("Checkpoint remediation owner differs from transport intent");
+        const descriptor = persistedProviderWireContract(tuple);
+        if (!descriptor || result.validation !== "accepted")
+            throw new Error("Checkpoint origin descriptor/validation mismatch");
+        const read = (digest) => {
+            const bytes = db.prepare("SELECT content FROM content_refs WHERE digest=?").get(digest)?.content;
+            if (!bytes || hash(bytes) !== digest || !graphDerivedAllowed(db, projectDir, digest))
+                throw new Error("Checkpoint origin evidence missing, altered or revoked");
+            return bytes;
+        };
+        const retained = JSON.parse(read(result.responseDigest).toString());
+        if (retained.tupleDigest !== tuple.digest)
+            throw new Error("Checkpoint origin receipt tuple mismatch");
+        const response = verifyPersistedDispatch(descriptor.canonical, intent.sealedDispatch, hydrateStructuredReceipt(retained, read));
+        if (canonicalJson(response.continuity) !== canonicalJson(JSON.parse(checkpoint.delta_json)))
+            throw new Error("Checkpoint delta differs from its native origin");
+        if (checkpoint.session_ref_json) {
+            const session = JSON.parse(checkpoint.session_ref_json);
+            if (["provider", "role", "stream", "cwd", "configRoot", "workspaceIdentity", "ticketId", "deliveryUnitId"].some(field => session[field] !== frozen[field]))
+                throw new Error("Checkpoint scoped session differs from transport");
+            if (session.sessionId !== tuple.sessionId || session.generation !== tuple.generation) {
+                // Generation promotion is permitted only by the recorded accepted handoff.
+                const acceptance = db.prepare("SELECT acceptance_receipt_digest FROM handoffs WHERE run_id=? AND successor_session_id=? AND generation=? AND state='accepted'").get(checkpoint.run_id, session.sessionId, session.generation);
+                if (!acceptance)
+                    throw new Error("Checkpoint session differs from its dispatch");
+                const receipt = JSON.parse(read(acceptance.acceptance_receipt_digest).toString());
+                if (receipt.runId !== checkpoint.run_id || receipt.role !== checkpoint.role || receipt.acceptanceCheckpointDigest !== checkpoint.digest
+                    || canonicalJson(receipt.successorSessionRef) !== canonicalJson(session) || session.sessionId !== tuple.sessionId)
+                    throw new Error("Checkpoint generation promotion lacks its exact accepted handoff lineage");
+            }
+        }
+    }
+    else if (origin.kind === "host") {
+        const event = db.prepare("SELECT run_id,role,payload_json FROM continuity_events WHERE sequence=?").get(origin.eventSequence);
+        if (!event || event.run_id !== checkpoint.run_id || event.role !== "host" || JSON.parse(event.payload_json).checkpointDeltaDigest !== row.delta_digest)
+            throw new Error("Host checkpoint event provenance mismatch");
+        for (const digest of origin.inputCheckpointDigests) {
+            const input = db.prepare("SELECT checkpoint_id FROM continuity_checkpoints WHERE run_id=? AND digest=?").get(checkpoint.run_id, digest);
+            if (!input || input.checkpoint_id >= checkpointId)
+                throw new Error("Host checkpoint input is unavailable or not a predecessor");
+            verifyCheckpointOrigin(db, projectDir, input.checkpoint_id, new Set(visited));
+        }
+    }
+    else
+        throw new Error("Unknown checkpoint provenance");
+}
+function hash(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+export function verifyContinuityHeads(db, projectDir, runId) {
+    const heads = db.prepare("SELECT * FROM continuity_heads WHERE run_id=? ORDER BY role").all(runId);
+    const roles = heads.filter(head => head.role !== "run");
+    for (const head of roles) {
+        const checkpoint = db.prepare("SELECT checkpoint_id,event_sequence FROM continuity_checkpoints WHERE run_id=? AND role=? AND digest=?").get(runId, head.role, head.digest);
+        if (!checkpoint || checkpoint.event_sequence !== head.event_sequence)
+            throw new Error("Continuity head has no matching checkpoint");
+        verifyCheckpointOrigin(db, projectDir, checkpoint.checkpoint_id);
+    }
+    const run = heads.find(head => head.role === "run");
+    if (run && (run.digest !== hash(canonicalJson(roles.map(row => ({ role: row.role, digest: row.digest })))) || run.event_sequence !== Math.max(...roles.map(row => row.event_sequence))))
+        throw new Error("Run continuity head differs from its verified role heads");
+}