@allocator-one/rcl 4.5.4 → 4.5.6

package/dist/converge/pending-legacy-resume.js

@@ -10,6 +10,7 @@ import { claimConvergeAttempt, convergeAttemptStatePath, previewConvergeAttemptS
 import { withRecoveryTarget } from './target-ownership.js';
 import { bindOriginalCouncil } from '../dispatch/original-execution.js';
 import { createOriginalLaunch } from '../dispatch/original-launch.js';
+import { consumeBoundAsyncHistory, snapshotAsyncHistory } from '../dispatch/async-lane.js';
 import { uuidv7 } from '../report/uuid.js';
 import { captureSupplementalAsync } from '../report/supplemental-async.js';
 import { stableStringify } from '../report/run-header.js';
@@ -17,8 +18,9 @@ import { readStable } from '../telemetry/recovery/files.js';
 import { serializeRecoveryDocument } from '../evidence/original-run/journal.js';
 import { prepareLockRoot } from '../evidence/original-run/lock-path.js';
 import { retainStaleFile } from './stale-report-storage.js';
-import { createPendingRecoverySource, createOrdinaryMigrationSource, pendingRecoverySourceSchema } from './pending-recovery-source.js';
+import { createPendingRecoverySource, createOrdinaryMigrationSource, createCycleMigrationSource, pendingRecoverySourceSchema } from './pending-recovery-source.js';
 import { validateOrdinaryPendingPackage } from './ordinary-pending-package.js';
+import { assertReviewCyclePair } from './fresh-review.js';
 const digestSchema = z.string().regex(/^[a-f0-9]{64}$/);
 const ordinaryPendingFinalizationReceiptBodySchema = z.object({
     version: z.literal(1),
@@ -41,20 +43,66 @@ const ordinaryPendingFinalizationReceiptBodySchema = z.object({
     sourceAttemptStateSha256: digestSchema,
     finalizedNativeStateSha256: digestSchema,
 }).strict();
-const ordinaryPendingFinalizationReceiptSchema = ordinaryPendingFinalizationReceiptBodySchema.extend({
-    receiptDigest: digestSchema,
-}).strict().superRefine((receipt, context) => {
+const cyclePendingFinalizationReceiptBodySchema = ordinaryPendingFinalizationReceiptBodySchema.omit({
+    version: true,
+    operation: true,
+    retainedAsyncSha256: true,
+}).extend({
+    version: z.literal(2),
+    operation: z.literal('cycle-pending-finalize-only'),
+    retainedAsyncSha256: z.array(digestSchema),
+    cycleId: z.string().uuid(),
+    operationId: z.string().uuid(),
+    repo: z.string().min(1),
+    prNumber: z.number().int().positive().safe(),
+    attemptCap: z.number().int().positive().safe(),
+    roundCap: z.number().int().positive().safe(),
+    asyncAttribution: z.literal('cycle-history-unattributed'),
+}).strict();
+const pendingFinalizationReceiptBodySchema = z.union([
+    ordinaryPendingFinalizationReceiptBodySchema,
+    cyclePendingFinalizationReceiptBodySchema,
+]);
+const ordinaryPendingFinalizationReceiptSchema = z.union([
+    ordinaryPendingFinalizationReceiptBodySchema.extend({ receiptDigest: digestSchema }).strict(),
+    cyclePendingFinalizationReceiptBodySchema.extend({ receiptDigest: digestSchema }).strict(),
+]).superRefine((receipt, context) => {
     const { receiptDigest, ...body } = receipt;
     if (receiptDigest !== createHash('sha256').update(stableStringify(body)).digest('hex')) {
         context.addIssue({ code: 'custom', message: 'Pending finalization receipt digest is invalid' });
     }
     if (receipt.nextFreeAttempt !== receipt.finalizedAttempt + 1 ||
         receipt.attemptsUsed !== receipt.finalizedAttempt || receipt.attemptsUsed > receipt.cap ||
-        new Set(receipt.retainedAsyncSha256).size !== receipt.retainedAsyncSha256.length) {
+        (receipt.version === 1 && (receipt.retainedAsyncSha256.length === 0 ||
+            new Set(receipt.retainedAsyncSha256).size !== receipt.retainedAsyncSha256.length))) {
         context.addIssue({ code: 'custom', message: 'Pending finalization accounting is inconsistent' });
     }
+    if (receipt.version === 2 && (receipt.attemptCap !== receipt.cap || receipt.round > receipt.roundCap)) {
+        context.addIssue({ code: 'custom', message: 'Cycle pending finalization accounting is inconsistent' });
+    }
 });
 function fail(code) { throw new Error(`pending_legacy_resume_${code}`); }
+function cyclePendingPreviewSha256(input) {
+    return createHash('sha256').update(stableStringify({
+        version: 1,
+        operation: 'cycle-pending-finalize-preview',
+        ...input,
+        retainedAsyncSha256: [...input.retainedAsyncSha256].sort(),
+    })).digest('hex');
+}
+function assertCyclePendingPreviewBinding(options, sourceDigest, migrationPackageSha256) {
+    if (options.currentPrHeadSha === undefined)
+        return;
+    const expected = cyclePendingPreviewSha256({ target: options.target, headSha: options.headSha,
+        baseSha: options.baseSha, currentPrHeadSha: options.currentPrHeadSha,
+        pendingInputSha256: options.pendingInputSha256,
+        nativeStateSha256: options.nativeStateSha256,
+        attemptStateSha256: options.attemptStateSha256,
+        retainedAsyncSha256: options.retainedAsyncSha256, maxAttempts: options.maxAttempts,
+        sourceDigest, migrationPackageSha256 });
+    if (options.previewSha256 !== expected)
+        fail('preview_binding_mismatch');
+}
 function defaultOwnerAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -90,12 +138,18 @@ function sourceFromFinalized(target, launch, attempts, migrationPackage) {
         const migrationPackageSha256 = createHash('sha256').update(stableStringify(migrationPackage)).digest('hex');
         if (migrationPackageSha256 !== recovery.migrationPackageSha256)
             fail('finalization_mismatch');
-        const source = createOrdinaryMigrationSource({ version: 1, target, headSha: launch.headSha,
+        const common = { target, headSha: launch.headSha,
             inputSha256: launch.inputSha256, pendingAttempt: launch.attempt, round: launch.round,
             originalPid: launch.pid, startedAt: launch.startedAt, blockingOutcome: recovery.blockingOutcome,
             reason: recovery.reason, nativeStateSha256: recovery.nativeStateSha256,
             attemptStateSha256: recovery.attemptStateSha256, retainedAsyncSha256: recovery.retainedAsyncSha256,
-            migrationPackageSha256 });
+            migrationPackageSha256 };
+        const source = migrationPackage.version === 2
+            ? createCycleMigrationSource({ version: 2, ...common, cycle: migrationPackage.cycle,
+                cycleId: migrationPackage.cycle.id, operationId: migrationPackage.cycle.operationId,
+                attemptCap: migrationPackage.attemptCap, roundCap: migrationPackage.roundCap,
+                attemptsUsed: migrationPackage.attemptsUsed, asyncAttribution: 'cycle-history-unattributed' })
+            : createOrdinaryMigrationSource({ version: 1, ...common });
         if (source.digest !== recovery.sourceDigest)
             fail('finalization_mismatch');
         return source;
@@ -112,40 +166,109 @@ function sourceFromFinalized(target, launch, attempts, migrationPackage) {
         digest: recovery.sourceDigest,
     });
 }
+function packageExpected(state, attempts, current, input) {
+    return {
+        target: input.target, headSha: current.headSha, inputSha256: current.inputSha256,
+        baseSha: input.baseSha, attempt: current.attempt, round: current.round, pid: current.pid,
+        retainedAsyncSha256: input.retainedAsyncSha256,
+        ...(state.cycle ? { cycle: state.cycle, attemptCap: attempts.cap,
+            roundCap: state.roundCap, attemptsUsed: attempts.attemptsUsed } : {}),
+    };
+}
+async function assertCycleRecovery(options, state, attempts, packet) {
+    if (!state.cycle) {
+        if (packet.version === 2)
+            fail('cycle_mismatch');
+        return;
+    }
+    await assertReviewCyclePair(options.gitCommonDir, options.target, state.cycle);
+    if (packet.version !== 2 || !isDeepStrictEqual(packet.cycle, state.cycle))
+        fail('cycle_mismatch');
+    const remote = options.cycleRemote;
+    if (!remote || remote.repo.toLowerCase() !== state.cycle.repo ||
+        remote.prNumber !== state.cycle.prNumber || remote.url !== state.cycle.url)
+        fail('cycle_remote_mismatch');
+    if ((await remote.current())?.id !== state.cycle.id)
+        fail('cycle_superseded');
+    if (attempts.cap !== packet.attemptCap || state.roundCap !== packet.roundCap ||
+        attempts.attemptsUsed !== packet.attemptsUsed)
+        fail('cycle_accounting_mismatch');
+}
 function validateOptions(input) {
     const hashes = input?.retainedAsyncSha256;
+    const cycleFinalizePreview = input?.migrationPackage?.version === 2 &&
+        input.previewMode === 'finalize-only';
+    const currentPrHeadValid = input?.currentPrHeadSha === undefined ||
+        (cycleFinalizePreview && /^[a-f0-9]{40}$/.test(input.currentPrHeadSha));
     if (!input || typeof input.gitCommonDir !== 'string' || typeof input.target !== 'string' || !input.target.trim() ||
         !/^[a-f0-9]{40}$/.test(input.headSha ?? '') ||
         (input.migrationPackage && !/^[a-f0-9]{40}$/.test(input.baseSha ?? '')) ||
         !/^[a-f0-9]{64}$/.test(input.pendingInputSha256 ?? '') ||
         !/^[a-f0-9]{64}$/.test(input.recoveryInputSha256 ?? '') ||
         typeof input.retryReason !== 'string' || !input.retryReason.trim() || input.retryReason.length > 500 ||
-        !Array.isArray(hashes) || hashes.length === 0 || hashes.some(value => !/^[a-f0-9]{64}$/.test(value)) ||
-        new Set(hashes).size !== hashes.length || typeof input.validate !== 'function' ||
+        !Array.isArray(hashes) || hashes.some(value => !/^[a-f0-9]{64}$/.test(value)) ||
+        (!cycleFinalizePreview && (hashes.length === 0 || new Set(hashes).size !== hashes.length)) ||
+        typeof input.validate !== 'function' ||
         typeof input.run !== 'function' || typeof input.loadRetainedAsync !== 'function' ||
         (!input.migrationPackage && !input.legacyRetry) ||
         !Number.isSafeInteger(input.maxAttempts) || input.maxAttempts < 1 ||
         !Number.isSafeInteger(input.maxPhysicalCalls) || input.maxPhysicalCalls < 1 ||
         !Number.isSafeInteger(input.maxAttemptsPerCell) || input.maxAttemptsPerCell < 1 ||
         !Number.isSafeInteger(input.maxDurationMs) || input.maxDurationMs < 1 || input.maxDurationMs > 2_147_483_647 ||
-        (input.previewMode !== undefined && !['combined', 'finalize-only'].includes(input.previewMode))) {
+        (input.previewMode !== undefined && !['combined', 'finalize-only'].includes(input.previewMode)) ||
+        !currentPrHeadValid) {
         fail('invalid_input');
     }
 }
 function validateFinalizeOptions(input) {
     const hashes = input?.retainedAsyncSha256;
+    const cycleBacked = input?.migrationPackage?.version === 2;
+    const hasCurrentPrHead = input?.currentPrHeadSha !== undefined;
+    const hasPreviewSha = input?.previewSha256 !== undefined;
+    const hasStoreDir = typeof input?.cycleHistory?.storeDir === 'string' &&
+        input.cycleHistory.storeDir.trim().length > 0;
+    const hasStoreResolver = typeof input?.cycleHistory?.resolveStoreDir === 'function';
     if (!input || typeof input.gitCommonDir !== 'string' || typeof input.target !== 'string' || !input.target.trim() ||
         !/^[a-f0-9]{40}$/.test(input.headSha ?? '') || !/^[a-f0-9]{40}$/.test(input.baseSha ?? '') ||
         !/^[a-f0-9]{64}$/.test(input.pendingInputSha256 ?? '') ||
         !/^[a-f0-9]{64}$/.test(input.nativeStateSha256 ?? '') ||
         !/^[a-f0-9]{64}$/.test(input.attemptStateSha256 ?? '') ||
-        !Array.isArray(hashes) || hashes.length === 0 || hashes.some(value => !/^[a-f0-9]{64}$/.test(value)) ||
-        new Set(hashes).size !== hashes.length || typeof input.loadRetainedAsync !== 'function' ||
+        !Array.isArray(hashes) || hashes.some(value => !/^[a-f0-9]{64}$/.test(value)) ||
+        (!cycleBacked && (hashes.length === 0 || new Set(hashes).size !== hashes.length)) ||
+        typeof input.loadRetainedAsync !== 'function' ||
         (input.writeFinalizedState !== undefined && typeof input.writeFinalizedState !== 'function') ||
-        !input.migrationPackage || !Number.isSafeInteger(input.maxAttempts) || input.maxAttempts < 1) {
+        (input.consumeCycleHistory !== undefined && typeof input.consumeCycleHistory !== 'function') ||
+        (cycleBacked && (!input.cycleHistory || hasStoreDir === hasStoreResolver ||
+            typeof input.cycleHistory.targetKey !== 'string' || !input.cycleHistory.targetKey.trim() ||
+            !Number.isSafeInteger(input.cycleHistory.maxResults) || input.cycleHistory.maxResults < 1)) ||
+        !input.migrationPackage || !Number.isSafeInteger(input.maxAttempts) || input.maxAttempts < 1 ||
+        hasCurrentPrHead !== hasPreviewSha ||
+        (hasCurrentPrHead && (!cycleBacked || !/^[a-f0-9]{40}$/.test(input.currentPrHeadSha) ||
+            !/^[a-f0-9]{64}$/.test(input.previewSha256)))) {
         fail('invalid_input');
     }
 }
+async function reconcileFinalizedCycleHistory(options, mode) {
+    if (options.migrationPackage.version !== 2)
+        return;
+    const history = options.cycleHistory;
+    let storeDir;
+    try {
+        storeDir = history.storeDir ?? await history.resolveStoreDir();
+    }
+    catch (error) {
+        if (mode !== 'new-receipt' && error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (mode === 'advanced-replay') {
+        const live = await snapshotAsyncHistory(storeDir, history.targetKey, history.maxResults);
+        if (live.artifacts.length > 0)
+            fail('cycle_history_ambiguous_after_successor');
+        return;
+    }
+    await (options.consumeCycleHistory ?? consumeBoundAsyncHistory)(storeDir, history.targetKey, options.retainedAsyncSha256, history.maxResults);
+}
 async function archiveAsync(common, source, artifacts, packet) {
     validateAsyncArtifacts(source, artifacts, packet);
     const directory = await prepareLockRoot(join(common, 'rcl-converge-pending-recovery', source.digest));
@@ -269,7 +392,7 @@ async function assertFinalizedStateMatchesReceipt(common, receipt) {
     return { native: native.raw, attempts: attempts.raw, exact: false };
 }
 function createFinalizationReceipt(input) {
-    const body = ordinaryPendingFinalizationReceiptBodySchema.parse(input);
+    const body = pendingFinalizationReceiptBodySchema.parse(input);
     return ordinaryPendingFinalizationReceiptSchema.parse({
         ...body,
         receiptDigest: createHash('sha256').update(stableStringify(body)).digest('hex'),
@@ -284,10 +407,16 @@ function assertReceiptMatchesInput(receipt, input, migrationPackageSha256) {
         receipt.retainedAsyncSha256.join(',') !== [...input.retainedAsyncSha256].sort().join(',')) {
         fail('finalization_receipt_mismatch');
     }
+    if (receipt.version === 2 && (input.migrationPackage.cycle?.id !== receipt.cycleId ||
+        input.migrationPackage.cycle.operationId !== receipt.operationId))
+        fail('finalization_receipt_mismatch');
     return validateOrdinaryPendingPackage(input.migrationPackage, {
         target: receipt.target, headSha: receipt.headSha, inputSha256: receipt.inputSha256,
         baseSha: receipt.baseSha, attempt: receipt.finalizedAttempt, round: receipt.round,
         pid: receipt.originalPid, retainedAsyncSha256: receipt.retainedAsyncSha256,
+        ...(receipt.version === 2 ? { cycle: input.migrationPackage.cycle,
+            attemptCap: receipt.attemptCap, roundCap: receipt.roundCap,
+            attemptsUsed: receipt.attemptsUsed } : {}),
     });
 }
 async function readArchivedAsync(common, sourceDigest, retainedAsyncSha256) {
@@ -327,14 +456,26 @@ export async function finalizeOrdinaryPendingLaunch(input) {
         const existingReceipt = await readFinalizationReceipt(options.gitCommonDir, migrationPackageSha256);
         if (existingReceipt) {
             const packet = assertReceiptMatchesInput(existingReceipt, options, migrationPackageSha256);
+            assertCyclePendingPreviewBinding(options, existingReceipt.sourceDigest, migrationPackageSha256);
             const state = await assertFinalizedStateMatchesReceipt(options.gitCommonDir, existingReceipt);
+            const [currentRun, currentAttempts] = await Promise.all([
+                loadConvergeRunState(options.gitCommonDir, options.target),
+                previewConvergeAttemptState(options.gitCommonDir, options.target),
+            ]);
+            if (!currentRun || !currentAttempts)
+                fail('finalization_receipt_state_mismatch');
+            await assertCycleRecovery(options, currentRun, currentAttempts, packet.version === 2 ? { ...packet, attemptsUsed: currentAttempts.attemptsUsed } : packet);
             validateAsyncArtifacts({ retainedAsyncSha256: existingReceipt.retainedAsyncSha256 }, await readArchivedAsync(options.gitCommonDir, existingReceipt.sourceDigest, existingReceipt.retainedAsyncSha256), packet);
             const snapshotsPresent = await finalizationSnapshotsPresent(options.gitCommonDir, existingReceipt);
+            // Revalidate at the last supported boundary before replay can publish
+            // missing snapshots or consume retained cycle history.
+            await assertCycleRecovery(options, currentRun, currentAttempts, packet.version === 2 ? { ...packet, attemptsUsed: currentAttempts.attemptsUsed } : packet);
             if (!snapshotsPresent) {
                 if (!state.exact)
                     fail('finalization_receipt_state_mismatch');
                 await retainFinalizationSnapshots(options.gitCommonDir, existingReceipt, state.attempts, state.native);
             }
+            await reconcileFinalizedCycleHistory(options, state.exact ? 'exact-replay' : 'advanced-replay');
             return { receipt: existingReceipt, reusedReceipt: true,
                 snapshotBindingUpgraded: !snapshotsPresent };
         }
@@ -351,11 +492,8 @@ export async function finalizeOrdinaryPendingLaunch(input) {
             current.inputSha256 !== options.pendingInputSha256 || !['pending', 'failed'].includes(current.status)) {
             fail('launch_mismatch');
         }
-        const packet = validateOrdinaryPendingPackage(options.migrationPackage, {
-            target: options.target, headSha: current.headSha, inputSha256: current.inputSha256,
-            baseSha: options.baseSha, attempt: current.attempt, round: current.round, pid: current.pid,
-            retainedAsyncSha256: options.retainedAsyncSha256,
-        });
+        const packet = validateOrdinaryPendingPackage(options.migrationPackage, packageExpected(state, attempts, current, options));
+        await assertCycleRecovery(options, state, attempts, packet);
         let source;
         let sourceAttemptStateBytes;
         if (current.status === 'pending') {
@@ -366,12 +504,18 @@ export async function finalizeOrdinaryPendingLaunch(input) {
                 readStable(convergeAttemptStatePath(options.gitCommonDir, options.target)),
             ]);
             sourceAttemptStateBytes = attemptBytes.raw;
-            source = createOrdinaryMigrationSource({ version: 1, target: options.target,
+            const commonSource = { target: options.target,
                 headSha: current.headSha, inputSha256: current.inputSha256, pendingAttempt: current.attempt,
                 round: current.round, originalPid: current.pid, startedAt: current.startedAt,
                 blockingOutcome: 'unknown', reason: 'coordinator_exited_without_durable_blocking_receipts',
                 nativeStateSha256: nativeBytes.sha256, attemptStateSha256: attemptBytes.sha256,
-                retainedAsyncSha256: options.retainedAsyncSha256, migrationPackageSha256 });
+                retainedAsyncSha256: options.retainedAsyncSha256, migrationPackageSha256 };
+            source = packet.version === 2
+                ? createCycleMigrationSource({ version: 2, ...commonSource, cycle: state.cycle,
+                    cycleId: state.cycle.id, operationId: state.cycle.operationId,
+                    attemptCap: attempts.cap, roundCap: state.roundCap, attemptsUsed: attempts.attemptsUsed,
+                    asyncAttribution: 'cycle-history-unattributed' })
+                : createOrdinaryMigrationSource({ version: 1, ...commonSource });
         }
         else {
             source = sourceFromFinalized(options.target, current, attempts, packet);
@@ -379,6 +523,7 @@ export async function finalizeOrdinaryPendingLaunch(input) {
         if (source.nativeStateSha256 !== options.nativeStateSha256 ||
             source.attemptStateSha256 !== options.attemptStateSha256)
             fail('source_digest_mismatch');
+        assertCyclePendingPreviewBinding(options, source.digest, migrationPackageSha256);
         // Once the failed/unknown native state exists, archive publication already
         // completed. Resume from those immutable bytes so a lost acknowledgment
         // does not depend on the original async store still being available.
@@ -399,7 +544,7 @@ export async function finalizeOrdinaryPendingLaunch(input) {
         // Construct and validate the exact receipt before the first write. The
         // native serializer is shared with writeState, so its post-state digest is
         // known without publishing a partially validated operation.
-        const receipt = createFinalizationReceipt({ version: 1, operation: 'ordinary-pending-finalize-only',
+        const receiptCommon = {
             target: options.target, headSha: current.headSha, baseSha: options.baseSha,
             inputSha256: current.inputSha256, sourceDigest: source.digest, migrationPackageSha256,
             finalizedAttempt: current.attempt, round: current.round, originalPid: current.pid,
@@ -407,13 +552,24 @@ export async function finalizeOrdinaryPendingLaunch(input) {
             blockingOutcome: 'unknown', retainedAsyncSha256: options.retainedAsyncSha256,
             sourceNativeStateSha256: source.nativeStateSha256,
             sourceAttemptStateSha256: source.attemptStateSha256,
-            finalizedNativeStateSha256 });
+            finalizedNativeStateSha256
+        };
+        const receipt = packet.version === 2
+            ? createFinalizationReceipt({ version: 2, operation: 'cycle-pending-finalize-only', ...receiptCommon,
+                cycleId: state.cycle.id, operationId: state.cycle.operationId,
+                repo: state.cycle.repo, prNumber: state.cycle.prNumber,
+                attemptCap: attempts.cap, roundCap: state.roundCap,
+                asyncAttribution: 'cycle-history-unattributed' })
+            : createFinalizationReceipt({ version: 1, operation: 'ordinary-pending-finalize-only', ...receiptCommon });
         if (current.status === 'pending') {
             await preflightConvergeRunStateWrite(options.gitCommonDir, state, ownership);
         }
         // Every fallible authentication and accounting check above precedes the
         // first durable write. Archive publication is idempotent if this process
         // stops before the native failed/unknown state or receipt is published.
+        // Revalidate remote cycle membership after those reads and immediately
+        // before archive publication so live PR or cycle drift fails closed.
+        await assertCycleRecovery(options, state, attempts, packet);
         await archiveAsync(options.gitCommonDir, source, artifacts, packet);
         if (current.status === 'pending') {
             await (options.writeFinalizedState ?? writeState)(options.gitCommonDir, state, ownership);
@@ -424,6 +580,10 @@ export async function finalizeOrdinaryPendingLaunch(input) {
         const finalizedAttempts = await readStable(convergeAttemptStatePath(options.gitCommonDir, options.target));
         sourceAttemptStateBytes ??= finalizedAttempts.raw;
         await retainFinalizationSnapshots(options.gitCommonDir, receipt, sourceAttemptStateBytes, finalizedNative.raw);
+        // Cycle history is consumed while the target remains recovery-locked and
+        // before the terminal receipt makes a successor eligible. Partial cleanup
+        // is safe to retry because consumption validates occurrence subsets.
+        await reconcileFinalizedCycleHistory(options, 'new-receipt');
         await retainFinalizationReceipt(options.gitCommonDir, receipt);
         return { receipt, reusedReceipt: false, snapshotBindingUpgraded: false };
     });
@@ -434,12 +594,12 @@ function validateAsyncArtifacts(source, artifacts, packet) {
     if (expected.length !== actual.length || expected.some((item, index) => item !== actual[index])) {
         fail('async_binding_mismatch');
     }
+    const actualDescriptors = [];
     for (const artifact of artifacts) {
         const bytes = Buffer.from(artifact.bytesBase64, 'base64');
         if (createHash('sha256').update(bytes).digest('hex') !== artifact.sha256)
             fail('async_binding_mismatch');
         if (packet) {
-            const descriptor = packet.retainedAsync.find(item => item.sha256 === artifact.sha256);
             let row;
             try {
                 row = JSON.parse(bytes.toString('utf8'));
@@ -447,9 +607,15 @@ function validateAsyncArtifacts(source, artifacts, packet) {
             catch {
                 fail('async_binding_mismatch');
             }
-            if (!descriptor || row.model !== descriptor.model || row.role !== descriptor.role ||
-                row.provider !== descriptor.provider)
-                fail('async_binding_mismatch');
+            actualDescriptors.push(JSON.stringify([artifact.sha256, row.model, row.role, row.provider]));
+        }
+    }
+    if (packet) {
+        const expectedDescriptors = packet.retainedAsync.map(item => JSON.stringify([item.sha256, item.model, item.role, item.provider])).sort();
+        actualDescriptors.sort();
+        if (expectedDescriptors.length !== actualDescriptors.length ||
+            expectedDescriptors.some((item, index) => item !== actualDescriptors[index])) {
+            fail('async_binding_mismatch');
         }
     }
 }
@@ -481,26 +647,40 @@ export async function previewOrdinaryPendingLaunch(input) {
         }
         if ((options.ownerAlive ?? defaultOwnerAlive)(current.pid))
             fail('owner_alive');
-        const packet = validateOrdinaryPendingPackage(options.migrationPackage, {
-            target: options.target, headSha: current.headSha, inputSha256: current.inputSha256,
-            baseSha: options.baseSha, attempt: current.attempt, round: current.round, pid: current.pid,
-            retainedAsyncSha256: options.retainedAsyncSha256,
-        });
+        const packet = validateOrdinaryPendingPackage(options.migrationPackage, packageExpected(state, attempts, current, options));
+        await assertCycleRecovery(options, state, attempts, packet);
         const [nativeBytes, attemptBytes] = await Promise.all([
             readStable(convergeRunStatePath(options.gitCommonDir, options.target)),
             readStable(convergeAttemptStatePath(options.gitCommonDir, options.target)),
         ]);
-        const source = createOrdinaryMigrationSource({ version: 1, target: options.target,
+        const commonSource = { target: options.target,
             headSha: current.headSha, inputSha256: current.inputSha256, pendingAttempt: current.attempt,
             round: current.round, originalPid: current.pid, startedAt: current.startedAt,
             blockingOutcome: 'unknown', reason: 'coordinator_exited_without_durable_blocking_receipts',
             nativeStateSha256: nativeBytes.sha256, attemptStateSha256: attemptBytes.sha256,
             retainedAsyncSha256: options.retainedAsyncSha256,
             migrationPackageSha256: createHash('sha256').update(stableStringify(packet)).digest('hex'),
-        });
+        };
+        const source = packet.version === 2
+            ? createCycleMigrationSource({ version: 2, ...commonSource, cycle: state.cycle,
+                cycleId: state.cycle.id, operationId: state.cycle.operationId,
+                attemptCap: attempts.cap, roundCap: state.roundCap, attemptsUsed: attempts.attemptsUsed,
+                asyncAttribution: 'cycle-history-unattributed' })
+            : createOrdinaryMigrationSource({ version: 1, ...commonSource });
         validateAsyncArtifacts(source, await options.loadRetainedAsync(), packet);
+        const currentPrBinding = options.currentPrHeadSha === undefined ? {} : {
+            currentPrHeadSha: options.currentPrHeadSha,
+            previewSha256: cyclePendingPreviewSha256({ target: options.target, headSha: options.headSha,
+                baseSha: options.baseSha, currentPrHeadSha: options.currentPrHeadSha,
+                pendingInputSha256: options.pendingInputSha256,
+                nativeStateSha256: nativeBytes.sha256, attemptStateSha256: attemptBytes.sha256,
+                retainedAsyncSha256: options.retainedAsyncSha256, maxAttempts: options.maxAttempts,
+                sourceDigest: source.digest,
+                migrationPackageSha256: createHash('sha256').update(stableStringify(packet)).digest('hex') }),
+        };
         return { source, nativeStateSha256: nativeBytes.sha256, attemptStateSha256: attemptBytes.sha256,
-            attemptsUsed: attempts.attemptsUsed, cap: attempts.cap, nextAttempt: current.attempt + 1 };
+            attemptsUsed: attempts.attemptsUsed, cap: attempts.cap, nextAttempt: current.attempt + 1,
+            ...currentPrBinding };
     });
 }
 async function runBound(options, ownership, state, claim, source, launch, resume) {