openplanr 1.25.3 → 2.0.0

package/dist/services/operate/storage-layout.js

@@ -0,0 +1,1244 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, cp, lstat, mkdir, readdir, readFile, realpath, rename, rm, writeFile, } from 'node:fs/promises';
+import path from 'node:path';
+import { assertOperatePathCustody } from './path-custody.js';
+import { withOperateProjectTransaction } from './project-transaction-lock.js';
+import { OperateStore } from './store.js';
+const PRIVATE_IGNORE_ENTRIES = ['/state/', '/packets/', '/archive/'];
+const LEGACY_OPERATE_DIRECTORY = 'operate-v2';
+const MIGRATION_PROGRESS_FILE = '.migration-in-progress.json';
+const ROLLBACK_PROGRESS_PATTERN = /^\.operate-rollback-([a-f0-9]{32})\.json$/u;
+const BUNDLED_LEGACY_VERIFIER_VERSION = '1.0.0';
+async function projectFingerprint(projectDir) {
+    const canonicalProject = await realpath(path.resolve(projectDir));
+    return `sha256:${createHash('sha256')
+        .update(`openplanr-operate-project\0${canonicalProject}`)
+        .digest('hex')}`;
+}
+function legacyProofPayload(proof) {
+    return JSON.stringify({
+        kind: proof.kind,
+        schemaVersion: proof.schemaVersion,
+        protocolVersion: proof.protocolVersion,
+        source: proof.source,
+        projectFingerprint: proof.projectFingerprint,
+        tree: { hash: proof.tree.hash, fileCount: proof.tree.fileCount },
+        replay: {
+            currentGeneration: proof.replay.currentGeneration,
+            stateCanonicalHash: proof.replay.stateCanonicalHash,
+            eventHead: { sequence: proof.replay.eventHead.sequence, hash: proof.replay.eventHead.hash },
+            artifactHashes: proof.replay.artifactHashes.map(({ artifactId, rawHash }) => ({
+                artifactId,
+                rawHash,
+            })),
+        },
+        verifier: {
+            implementation: proof.verifier.implementation,
+            verifierVersion: proof.verifier.verifierVersion,
+        },
+        verifiedAt: proof.verifiedAt,
+    });
+}
+function legacyProofHash(proof) {
+    return `sha256:${createHash('sha256').update(legacyProofPayload(proof)).digest('hex')}`;
+}
+async function exists(target) {
+    try {
+        await lstat(target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function isDirectory(target) {
+    try {
+        const metadata = await lstat(target);
+        if (metadata.isSymbolicLink()) {
+            throw Object.assign(new Error('Operate storage custody cannot be a symbolic link.'), {
+                code: 'OPERATE_STORE_INCOMPATIBLE',
+            });
+        }
+        return metadata.isDirectory();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function atomicWrite(projectDir, target, content) {
+    await assertOperatePathCustody(projectDir, target, {
+        code: 'OPERATE_STORE_INCOMPATIBLE',
+        message: 'Operate storage writes cannot traverse symbolic links.',
+    });
+    await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    await assertOperatePathCustody(projectDir, path.dirname(target), {
+        code: 'OPERATE_STORE_INCOMPATIBLE',
+        message: 'Operate storage writes cannot traverse symbolic links.',
+        requireDirectory: true,
+    });
+    const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(temporary, content, { flag: 'wx', mode: 0o600 });
+    await rename(temporary, target);
+    await assertOperatePathCustody(projectDir, target, {
+        code: 'OPERATE_STORE_INCOMPATIBLE',
+        message: 'Operate storage writes cannot traverse symbolic links.',
+        requireFile: true,
+    });
+}
+async function ensureIgnoreFile(projectDir, target) {
+    await assertOperatePathCustody(projectDir, target, {
+        code: 'OPERATE_STORE_INCOMPATIBLE',
+        message: 'Operate ignore-file custody cannot traverse symbolic links.',
+    });
+    let existing = '';
+    try {
+        existing = await readFile(target, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const lines = existing.split(/\r?\n/u).filter(Boolean);
+    for (const entry of PRIVATE_IGNORE_ENTRIES) {
+        if (!lines.includes(entry))
+            lines.push(entry);
+    }
+    const next = `${lines.join('\n')}\n`;
+    if (next !== existing)
+        await atomicWrite(projectDir, target, next);
+}
+async function createLayout(projectDir, root) {
+    await assertOperatePathCustody(projectDir, root, {
+        code: 'OPERATE_STORE_INCOMPATIBLE',
+        message: 'Operate storage layout cannot traverse symbolic links.',
+    });
+    await Promise.all(['state', 'packets', 'projections', 'archive'].map(async (directory) => await mkdir(path.join(root, directory), { recursive: true, mode: 0o700 })));
+    for (const directory of [
+        root,
+        ...['state', 'packets', 'projections', 'archive'].map((entry) => path.join(root, entry)),
+    ]) {
+        await assertOperatePathCustody(projectDir, directory, {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+            message: 'Operate storage layout cannot traverse symbolic links.',
+            requireDirectory: true,
+        });
+    }
+    await Promise.all([root, 'state', 'packets', 'projections', 'archive'].map(async (directory) => await chmod(directory === root ? root : path.join(root, directory), 0o700)));
+    await ensureIgnoreFile(projectDir, path.join(root, '.gitignore'));
+    await ensureIgnoreFile(projectDir, path.join(root, '.ignore'));
+}
+async function isCurrentLayout(root) {
+    return ((await isDirectory(path.join(root, 'state'))) &&
+        (await isDirectory(path.join(root, 'packets'))) &&
+        (await isDirectory(path.join(root, 'projections'))) &&
+        (await isDirectory(path.join(root, 'archive'))));
+}
+async function digestTree(root) {
+    const rootMetadata = await lstat(root);
+    if (rootMetadata.isSymbolicLink() || !rootMetadata.isDirectory()) {
+        throw Object.assign(new Error('Operate storage tree custody must be one real directory.'), {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+        });
+    }
+    const records = [];
+    const walk = async (directory) => {
+        const entries = await readdir(directory, { withFileTypes: true });
+        entries.sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            const absolute = path.join(directory, entry.name);
+            const relative = path.relative(root, absolute).split(path.sep).join('/');
+            const metadata = await lstat(absolute);
+            if (metadata.isSymbolicLink()) {
+                throw Object.assign(new Error(`Operate storage contains a symbolic link: ${relative}`), {
+                    code: 'OPERATE_STORE_INCOMPATIBLE',
+                });
+            }
+            if (metadata.isDirectory()) {
+                await walk(absolute);
+                continue;
+            }
+            if (!metadata.isFile()) {
+                throw Object.assign(new Error(`Operate storage contains an unsupported entry: ${relative}`), {
+                    code: 'OPERATE_STORE_INCOMPATIBLE',
+                });
+            }
+            const bytes = await readFile(absolute);
+            records.push({
+                path: relative,
+                hash: createHash('sha256').update(bytes).digest('hex'),
+                size: bytes.byteLength,
+            });
+        }
+    };
+    await walk(root);
+    return {
+        hash: `sha256:${createHash('sha256').update(JSON.stringify(records)).digest('hex')}`,
+        fileCount: records.length,
+    };
+}
+async function privatizeTree(root) {
+    const walk = async (target) => {
+        const metadata = await lstat(target);
+        if (metadata.isSymbolicLink()) {
+            throw Object.assign(new Error('Operate archive custody cannot contain symbolic links.'), {
+                code: 'OPERATE_STORE_INCOMPATIBLE',
+            });
+        }
+        if (metadata.isDirectory()) {
+            await chmod(target, 0o700);
+            for (const entry of await readdir(target))
+                await walk(path.join(target, entry));
+            return;
+        }
+        if (!metadata.isFile()) {
+            throw Object.assign(new Error('Operate archive custody contains an unsupported entry.'), {
+                code: 'OPERATE_STORE_INCOMPATIBLE',
+            });
+        }
+        await chmod(target, 0o600);
+    };
+    await walk(root);
+}
+async function captureTreeModes(root) {
+    const modes = new Map();
+    const walk = async (target) => {
+        const metadata = await lstat(target);
+        if (!metadata.isDirectory() && !metadata.isFile()) {
+            throw Object.assign(new Error('Operate storage contains an unsupported mode-bearing entry.'), {
+                code: 'OPERATE_STORE_INCOMPATIBLE',
+            });
+        }
+        modes.set(path.relative(root, target), metadata.mode & 0o777);
+        if (metadata.isDirectory()) {
+            for (const entry of await readdir(target))
+                await walk(path.join(target, entry));
+        }
+    };
+    await walk(root);
+    return modes;
+}
+async function restoreTreeModes(root, modes) {
+    const entries = [...modes.entries()].sort(([left], [right]) => right.split(path.sep).length - left.split(path.sep).length);
+    for (const [relative, mode] of entries)
+        await chmod(path.join(root, relative), mode);
+}
+async function assertLegacyReplayProof(projectDir, value, expectedTree) {
+    const proof = value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+    const exactKeys = [
+        'kind',
+        'schemaVersion',
+        'protocolVersion',
+        'source',
+        'projectFingerprint',
+        'tree',
+        'replay',
+        'verifier',
+        'verifiedAt',
+        'receiptHash',
+    ].sort();
+    const tree = proof.tree !== null && typeof proof.tree === 'object' && !Array.isArray(proof.tree)
+        ? proof.tree
+        : {};
+    const replay = proof.replay !== null && typeof proof.replay === 'object' && !Array.isArray(proof.replay)
+        ? proof.replay
+        : {};
+    const eventHead = replay.eventHead !== null &&
+        typeof replay.eventHead === 'object' &&
+        !Array.isArray(replay.eventHead)
+        ? replay.eventHead
+        : {};
+    const verifier = proof.verifier !== null && typeof proof.verifier === 'object' && !Array.isArray(proof.verifier)
+        ? proof.verifier
+        : {};
+    const artifacts = Array.isArray(replay.artifactHashes) ? replay.artifactHashes : [];
+    if (JSON.stringify(Object.keys(proof).sort()) !== JSON.stringify(exactKeys) ||
+        proof.kind !== 'operate-legacy-replay-proof' ||
+        proof.schemaVersion !== '1.0.0' ||
+        proof.protocolVersion !== '2.0.0' ||
+        proof.source !== 'operate-v2' ||
+        proof.projectFingerprint !== (await projectFingerprint(projectDir)) ||
+        JSON.stringify(Object.keys(tree).sort()) !== JSON.stringify(['fileCount', 'hash']) ||
+        tree.hash !== expectedTree.hash ||
+        tree.fileCount !== expectedTree.fileCount ||
+        JSON.stringify(Object.keys(replay).sort()) !==
+            JSON.stringify(['artifactHashes', 'currentGeneration', 'eventHead', 'stateCanonicalHash']) ||
+        typeof replay.currentGeneration !== 'string' ||
+        replay.currentGeneration.length === 0 ||
+        typeof replay.stateCanonicalHash !== 'string' ||
+        !/^sha256:[a-f0-9]{64}$/u.test(replay.stateCanonicalHash) ||
+        JSON.stringify(Object.keys(eventHead).sort()) !== JSON.stringify(['hash', 'sequence']) ||
+        !Number.isInteger(eventHead.sequence) ||
+        Number(eventHead.sequence) < 0 ||
+        (Number(eventHead.sequence) === 0
+            ? eventHead.hash !== null
+            : typeof eventHead.hash !== 'string' || !/^sha256:[a-f0-9]{64}$/u.test(eventHead.hash)) ||
+        JSON.stringify(Object.keys(verifier).sort()) !==
+            JSON.stringify(['implementation', 'verifierVersion']) ||
+        verifier.implementation !== 'bundled-compatibility-reader' ||
+        verifier.verifierVersion !== BUNDLED_LEGACY_VERIFIER_VERSION ||
+        typeof proof.verifiedAt !== 'string' ||
+        Number.isNaN(Date.parse(proof.verifiedAt)) ||
+        typeof proof.receiptHash !== 'string' ||
+        !/^sha256:[a-f0-9]{64}$/u.test(proof.receiptHash)) {
+        throw Object.assign(new Error('Legacy Operate replay proof is malformed, stale, or foreign.'), {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+        });
+    }
+    let priorArtifactId = '';
+    const normalizedArtifacts = artifacts.map((candidate) => {
+        const artifact = candidate !== null && typeof candidate === 'object' && !Array.isArray(candidate)
+            ? candidate
+            : {};
+        if (JSON.stringify(Object.keys(artifact).sort()) !== JSON.stringify(['artifactId', 'rawHash']) ||
+            typeof artifact.artifactId !== 'string' ||
+            artifact.artifactId.length === 0 ||
+            artifact.artifactId <= priorArtifactId ||
+            typeof artifact.rawHash !== 'string' ||
+            !/^sha256:[a-f0-9]{64}$/u.test(artifact.rawHash)) {
+            throw Object.assign(new Error('Legacy Operate replay proof has invalid Artifact hashes.'), {
+                code: 'OPERATE_STORE_INCOMPATIBLE',
+            });
+        }
+        priorArtifactId = artifact.artifactId;
+        return Object.freeze({ artifactId: artifact.artifactId, rawHash: artifact.rawHash });
+    });
+    const unsigned = Object.freeze({
+        kind: 'operate-legacy-replay-proof',
+        schemaVersion: '1.0.0',
+        protocolVersion: '2.0.0',
+        source: 'operate-v2',
+        projectFingerprint: proof.projectFingerprint,
+        tree: Object.freeze({ hash: tree.hash, fileCount: tree.fileCount }),
+        replay: Object.freeze({
+            currentGeneration: replay.currentGeneration,
+            stateCanonicalHash: replay.stateCanonicalHash,
+            eventHead: Object.freeze({
+                sequence: eventHead.sequence,
+                hash: eventHead.hash,
+            }),
+            artifactHashes: Object.freeze(normalizedArtifacts),
+        }),
+        verifier: Object.freeze({
+            implementation: 'bundled-compatibility-reader',
+            verifierVersion: BUNDLED_LEGACY_VERIFIER_VERSION,
+        }),
+        verifiedAt: proof.verifiedAt,
+    });
+    if (proof.receiptHash !== legacyProofHash(unsigned)) {
+        throw Object.assign(new Error('Legacy Operate replay proof integrity does not match its exact bytes.'), {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+        });
+    }
+    return Object.freeze({ ...unsigned, receiptHash: proof.receiptHash });
+}
+/**
+ * Rechecks a pre-change verifier receipt against exact current custody without
+ * activating, moving, or interpreting any legacy accepted result bytes.
+ */
+export async function verifyOperateLegacyReplayProof(projectDir, value) {
+    const legacyRoot = path.join(path.resolve(projectDir), '.planr', LEGACY_OPERATE_DIRECTORY);
+    await assertOperatePathCustody(projectDir, legacyRoot, {
+        code: 'OPERATE_STORE_INCOMPATIBLE',
+        message: 'Legacy Operate proof custody cannot traverse symbolic links.',
+        requireDirectory: true,
+    });
+    if (!(await isDirectory(legacyRoot))) {
+        throw Object.assign(new Error('No legacy Operate Store is available for proof verification.'), {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+        });
+    }
+    const proof = await assertLegacyReplayProof(projectDir, value, await digestTree(legacyRoot));
+    await new OperateStore(projectDir, { root: legacyRoot }).verifyReplayProofCustody(proof.replay);
+    return proof;
+}
+function assertMigrationProgress(value) {
+    const input = value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+    const keys = Object.keys(input).sort();
+    if (JSON.stringify(keys) !==
+        JSON.stringify([
+            'kind',
+            'nonce',
+            'schemaVersion',
+            'sources',
+            'stamp',
+            'verificationProofHash',
+        ]) ||
+        input.kind !== 'operate-storage-migration-progress' ||
+        input.schemaVersion !== '1.0.0' ||
+        typeof input.nonce !== 'string' ||
+        !/^[a-f0-9]{32}$/u.test(input.nonce) ||
+        typeof input.stamp !== 'string' ||
+        (input.verificationProofHash !== null &&
+            (typeof input.verificationProofHash !== 'string' ||
+                !/^sha256:[a-f0-9]{64}$/u.test(input.verificationProofHash))) ||
+        !Array.isArray(input.sources) ||
+        input.sources.length < 1 ||
+        input.sources.length > 2) {
+        throw Object.assign(new Error('Interrupted Operate migration progress is invalid.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    const seen = new Set();
+    const sources = input.sources.map((candidate) => {
+        const source = candidate !== null && typeof candidate === 'object' && !Array.isArray(candidate)
+            ? candidate
+            : {};
+        if (JSON.stringify(Object.keys(source).sort()) !==
+            JSON.stringify(['archiveId', 'fileCount', 'hash', 'source']) ||
+            !['operate-v2', 'operate-legacy'].includes(String(source.source)) ||
+            typeof source.hash !== 'string' ||
+            !/^sha256:[a-f0-9]{64}$/u.test(source.hash) ||
+            !Number.isInteger(source.fileCount) ||
+            Number(source.fileCount) < 0 ||
+            typeof source.archiveId !== 'string' ||
+            source.archiveId !== `${input.stamp}-${source.source}` ||
+            seen.has(String(source.source))) {
+            throw Object.assign(new Error('Interrupted Operate migration source custody is invalid.'), {
+                code: 'OPERATE_STORE_CORRUPT',
+            });
+        }
+        seen.add(String(source.source));
+        return Object.freeze({
+            source: source.source,
+            hash: source.hash,
+            fileCount: Number(source.fileCount),
+            archiveId: source.archiveId,
+        });
+    });
+    return Object.freeze({
+        kind: 'operate-storage-migration-progress',
+        schemaVersion: '1.0.0',
+        nonce: input.nonce,
+        stamp: input.stamp,
+        verificationProofHash: input.verificationProofHash,
+        sources: Object.freeze(sources),
+    });
+}
+async function readMigrationProgress(projectDir, root) {
+    await assertOperatePathCustody(projectDir, path.join(root, 'archive', MIGRATION_PROGRESS_FILE), {
+        code: 'OPERATE_STORE_INCOMPATIBLE',
+        message: 'Operate migration progress cannot traverse symbolic links.',
+    });
+    try {
+        return assertMigrationProgress(JSON.parse(await readFile(path.join(root, 'archive', MIGRATION_PROGRESS_FILE), 'utf8')));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        if (error instanceof SyntaxError) {
+            throw Object.assign(new Error('Interrupted Operate migration progress is not valid JSON.'), {
+                code: 'OPERATE_STORE_CORRUPT',
+            });
+        }
+        throw error;
+    }
+}
+async function recoverPreActivationMigration(projectDir, onArchive) {
+    const planrRoot = path.join(path.resolve(projectDir), '.planr');
+    const entries = await readdir(planrRoot, { withFileTypes: true });
+    const stageEntries = entries
+        .filter((entry) => entry.isDirectory() && /^\.operate-stage-[a-f0-9]+$/u.test(entry.name))
+        .map((entry) => entry.name);
+    const parkedEntries = entries
+        .filter((entry) => entry.isDirectory() && /^\.operate-legacy-[a-f0-9]+$/u.test(entry.name))
+        .map((entry) => entry.name);
+    if (stageEntries.length !== 1 || parkedEntries.length > 1) {
+        throw Object.assign(new Error('Interrupted Operate migration staging custody is ambiguous.'), {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+        });
+    }
+    const match = /^\.operate-stage-([a-f0-9]{32})$/u.exec(stageEntries[0]);
+    if (!match) {
+        throw Object.assign(new Error('Interrupted Operate migration staging identity is invalid.'), {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+        });
+    }
+    const nonce = match[1];
+    const staging = path.join(planrRoot, stageEntries[0]);
+    const root = path.join(planrRoot, 'operate');
+    const parkedNeutral = path.join(planrRoot, `.operate-legacy-${nonce}`);
+    for (const candidate of [
+        staging,
+        root,
+        parkedNeutral,
+        path.join(planrRoot, LEGACY_OPERATE_DIRECTORY),
+    ]) {
+        await assertOperatePathCustody(projectDir, candidate, {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+            message: 'Interrupted Operate migration custody cannot traverse symbolic links.',
+        });
+    }
+    if (parkedEntries.length === 1 && parkedEntries[0] !== path.basename(parkedNeutral)) {
+        throw Object.assign(new Error('Interrupted Operate parked custody does not match staging.'), {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+        });
+    }
+    const progress = await readMigrationProgress(projectDir, staging);
+    if (!progress) {
+        const sourceV2 = path.join(planrRoot, LEGACY_OPERATE_DIRECTORY);
+        if (parkedEntries.length === 0 && (await exists(sourceV2))) {
+            const recoveryRoot = path.join(planrRoot, 'operate-recovery');
+            const preservedStage = path.join(recoveryRoot, `abandoned-stage-${nonce}`);
+            await assertOperatePathCustody(projectDir, recoveryRoot, {
+                code: 'OPERATE_STORE_INCOMPATIBLE',
+                message: 'Operate migration recovery cannot traverse symbolic links.',
+            });
+            await mkdir(recoveryRoot, { recursive: true, mode: 0o700 });
+            await assertOperatePathCustody(projectDir, recoveryRoot, {
+                code: 'OPERATE_STORE_INCOMPATIBLE',
+                message: 'Operate migration recovery cannot traverse symbolic links.',
+                requireDirectory: true,
+            });
+            if (await exists(preservedStage)) {
+                throw Object.assign(new Error('Interrupted Operate staging recovery already exists.'), {
+                    code: 'OPERATE_STORE_INCOMPATIBLE',
+                });
+            }
+            await rename(staging, preservedStage);
+            return await migrateOperateStorageUnlocked(projectDir, { onArchive });
+        }
+        throw Object.assign(new Error('Interrupted Operate staging has no progress receipt and cannot be resumed safely.'), { code: 'OPERATE_STORE_CORRUPT' });
+    }
+    if (!(await isCurrentLayout(staging))) {
+        throw Object.assign(new Error('Interrupted Operate staging layout is incomplete.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    if (progress.nonce !== nonce) {
+        throw Object.assign(new Error('Interrupted Operate staging progress is missing or foreign.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    const neutralSource = progress.sources.find(({ source }) => source === 'operate-legacy');
+    const v2Source = progress.sources.find(({ source }) => source === 'operate-v2');
+    const rootExists = await exists(root);
+    const parkedExists = await exists(parkedNeutral);
+    if ((neutralSource === undefined && (rootExists || parkedExists)) ||
+        (neutralSource !== undefined && !rootExists && !parkedExists) ||
+        (rootExists && parkedExists)) {
+        throw Object.assign(new Error('Interrupted Operate neutral custody is incomplete or ambiguous.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    const assertSourceDigest = async (sourcePath, source) => {
+        const digest = await digestTree(sourcePath);
+        if (digest.hash !== source.hash || digest.fileCount !== source.fileCount) {
+            throw Object.assign(new Error(`Interrupted ${source.source} custody changed before activation.`), {
+                code: 'OPERATE_STORE_CORRUPT',
+            });
+        }
+    };
+    if (neutralSource) {
+        await assertSourceDigest(rootExists ? root : parkedNeutral, neutralSource);
+    }
+    if (v2Source) {
+        const legacyV2Root = path.join(planrRoot, LEGACY_OPERATE_DIRECTORY);
+        if (!(await exists(legacyV2Root))) {
+            throw Object.assign(new Error('Interrupted legacy 2.0 custody is missing before activation.'), {
+                code: 'OPERATE_STORE_CORRUPT',
+            });
+        }
+        await assertSourceDigest(legacyV2Root, v2Source);
+    }
+    let parkedDuringRecovery = false;
+    if (neutralSource && rootExists) {
+        await rename(root, parkedNeutral);
+        parkedDuringRecovery = true;
+    }
+    try {
+        await rename(staging, root);
+    }
+    catch (error) {
+        if (parkedDuringRecovery && (await exists(parkedNeutral)) && !(await exists(root))) {
+            await rename(parkedNeutral, root);
+        }
+        throw error;
+    }
+    return await completeInterruptedMigration(projectDir, progress, onArchive);
+}
+async function completeInterruptedMigration(projectDir, progress, onArchive) {
+    const planrRoot = path.join(path.resolve(projectDir), '.planr');
+    const root = path.join(planrRoot, 'operate');
+    const parkedNeutral = path.join(planrRoot, `.operate-legacy-${progress.nonce}`);
+    const archives = [];
+    await assertOperatePathCustody(projectDir, root, {
+        code: 'OPERATE_STORE_INCOMPATIBLE',
+        message: 'Interrupted Operate migration root cannot traverse symbolic links.',
+        requireDirectory: true,
+    });
+    for (const source of progress.sources) {
+        const archivePath = path.join(root, 'archive', source.archiveId);
+        if (!(await exists(archivePath))) {
+            const sourcePath = source.source === 'operate-v2'
+                ? path.join(planrRoot, LEGACY_OPERATE_DIRECTORY)
+                : parkedNeutral;
+            if (!(await exists(sourcePath))) {
+                throw Object.assign(new Error(`Interrupted ${source.source} custody is missing.`), {
+                    code: 'OPERATE_STORE_CORRUPT',
+                });
+            }
+            await rename(sourcePath, archivePath);
+        }
+        await privatizeTree(archivePath);
+        const digest = await digestTree(archivePath);
+        if (digest.hash !== source.hash || digest.fileCount !== source.fileCount) {
+            throw Object.assign(new Error(`Interrupted ${source.source} custody changed before recovery.`), {
+                code: 'OPERATE_STORE_CORRUPT',
+            });
+        }
+        const archive = Object.freeze({
+            archiveId: source.archiveId,
+            source: source.source,
+            ...digest,
+        });
+        archives.push(archive);
+        await onArchive?.(archive);
+    }
+    const receipt = Object.freeze({
+        kind: 'operate-storage-migration-receipt',
+        migrated: true,
+        archives: Object.freeze(archives),
+        verificationProofHash: progress.verificationProofHash,
+        activatedState: await digestTree(path.join(root, 'state')),
+        rollbackArchiveId: progress.sources.find(({ source }) => source === 'operate-v2')?.archiveId ?? null,
+    });
+    await atomicWrite(projectDir, path.join(root, 'archive', `${progress.stamp}-migration-receipt.json`), `${JSON.stringify(receipt, null, 2)}\n`);
+    await rm(path.join(root, 'archive', MIGRATION_PROGRESS_FILE), { force: true });
+    return receipt;
+}
+export async function inspectOperateStorage(projectDir) {
+    const planrRoot = path.join(path.resolve(projectDir), '.planr');
+    const root = path.join(planrRoot, 'operate');
+    const legacyV2Root = path.join(planrRoot, LEGACY_OPERATE_DIRECTORY);
+    for (const candidate of [planrRoot, root, legacyV2Root]) {
+        await assertOperatePathCustody(projectDir, candidate, {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+            message: 'Operate storage inspection cannot traverse symbolic links.',
+        });
+    }
+    const neutralExists = await exists(root);
+    const current = neutralExists && (await isCurrentLayout(root));
+    const oldV2 = await exists(legacyV2Root);
+    const progress = current ? await readMigrationProgress(projectDir, root) : null;
+    const planrEntries = await readdir(planrRoot, { withFileTypes: true }).catch((error) => {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    const rollbackMarkers = planrEntries.filter((entry) => ROLLBACK_PROGRESS_PATTERN.test(entry.name));
+    const interruptedCandidates = planrEntries.filter((entry) => /^\.operate-stage-[a-f0-9-]+$/u.test(entry.name) ||
+        /^\.operate-legacy-[a-f0-9-]+$/u.test(entry.name) ||
+        /^\.operate-v2-restore-[a-f0-9-]+$/u.test(entry.name) ||
+        /^\.operate-neutral-restore-[a-f0-9-]+$/u.test(entry.name) ||
+        (rollbackMarkers.length > 0 && /^\.operate-forward-[a-f0-9-]+$/u.test(entry.name)));
+    for (const entry of interruptedCandidates) {
+        await assertOperatePathCustody(projectDir, path.join(planrRoot, entry.name), {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+            message: 'Interrupted Operate migration custody cannot traverse symbolic links.',
+            requireDirectory: true,
+        });
+    }
+    for (const entry of rollbackMarkers) {
+        await assertOperatePathCustody(projectDir, path.join(planrRoot, entry.name), {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+            message: 'Interrupted Operate rollback progress cannot traverse symbolic links.',
+            requireFile: true,
+        });
+    }
+    const interruptedEntries = [...interruptedCandidates, ...rollbackMarkers]
+        .map((entry) => entry.name)
+        .sort();
+    if (progress)
+        interruptedEntries.push(`operate/archive/${MIGRATION_PROGRESS_FILE}`);
+    return Object.freeze({
+        status: interruptedEntries.length > 0
+            ? 'interrupted'
+            : current && !oldV2
+                ? 'ready'
+                : neutralExists || oldV2
+                    ? 'migration-required'
+                    : 'empty',
+        root,
+        legacyV2Root: oldV2 ? legacyV2Root : null,
+        legacyNeutralRoot: neutralExists && (!current || oldV2) ? root : null,
+        privatePaths: Object.freeze(PRIVATE_IGNORE_ENTRIES.map((entry) => path.join(root, entry.slice(1)))),
+        interruptedEntries: Object.freeze(interruptedEntries),
+    });
+}
+export async function ensureOperateStorageLayout(projectDir) {
+    const inspection = await inspectOperateStorage(projectDir);
+    if (inspection.status === 'migration-required' || inspection.status === 'interrupted') {
+        throw Object.assign(new Error('Existing Operate storage must be replay-verified and archived before this runtime can start.'), { code: 'OPERATE_STORE_INCOMPATIBLE' });
+    }
+    await createLayout(projectDir, inspection.root);
+    return inspection.root;
+}
+async function migrateOperateStorageUnlocked(projectDir, options = {}) {
+    const inspection = await inspectOperateStorage(projectDir);
+    if (inspection.status === 'interrupted') {
+        const progress = await readMigrationProgress(projectDir, inspection.root);
+        if (progress) {
+            return await completeInterruptedMigration(projectDir, progress, options.onArchive);
+        }
+        return await recoverPreActivationMigration(projectDir, options.onArchive);
+    }
+    if (inspection.status === 'ready') {
+        return Object.freeze({
+            kind: 'operate-storage-migration-receipt',
+            migrated: false,
+            archives: [],
+            verificationProofHash: null,
+            activatedState: null,
+            rollbackArchiveId: null,
+        });
+    }
+    if (inspection.status === 'empty') {
+        await createLayout(projectDir, inspection.root);
+        return Object.freeze({
+            kind: 'operate-storage-migration-receipt',
+            migrated: false,
+            archives: [],
+            verificationProofHash: null,
+            activatedState: null,
+            rollbackArchiveId: null,
+        });
+    }
+    if (!inspection.legacyV2Root) {
+        throw Object.assign(new Error('This legacy Operate layout has no bundled deterministic converter. Its bytes were preserved unchanged.'), { code: 'OPERATE_STORE_INCOMPATIBLE' });
+    }
+    const sources = (await Promise.all([
+        inspection.legacyV2Root
+            ? Promise.all([
+                digestTree(inspection.legacyV2Root),
+                captureTreeModes(inspection.legacyV2Root),
+            ]).then(([digest, modes]) => ({
+                source: 'operate-v2',
+                path: inspection.legacyV2Root,
+                digest,
+                modes,
+            }))
+            : null,
+        inspection.legacyNeutralRoot
+            ? Promise.all([
+                digestTree(inspection.legacyNeutralRoot),
+                captureTreeModes(inspection.legacyNeutralRoot),
+            ]).then(([digest, modes]) => ({
+                source: 'operate-legacy',
+                path: inspection.legacyNeutralRoot,
+                digest,
+                modes,
+            }))
+            : null,
+    ])).filter((entry) => entry !== null);
+    const { runPinnedLegacyReplayVerifier } = await import('./pinned-legacy-replay-runner.js');
+    const verificationProof = await verifyOperateLegacyReplayProof(projectDir, await runPinnedLegacyReplayVerifier(projectDir));
+    const verificationProofHash = verificationProof.receiptHash;
+    const planrRoot = path.dirname(inspection.root);
+    const nonce = randomUUID().replaceAll('-', '');
+    const staging = path.join(planrRoot, `.operate-stage-${nonce}`);
+    const parkedNeutral = path.join(planrRoot, `.operate-legacy-${nonce}`);
+    await createLayout(projectDir, staging);
+    const legacyV2Source = sources.find(({ source }) => source === 'operate-v2');
+    if (!legacyV2Source) {
+        throw Object.assign(new Error('The verified legacy Operate Store disappeared before staging.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    await rm(path.join(staging, 'state'), { recursive: true, force: true });
+    await cp(legacyV2Source.path, path.join(staging, 'state'), {
+        recursive: true,
+        errorOnExist: true,
+        preserveTimestamps: true,
+    });
+    await privatizeTree(path.join(staging, 'state'));
+    const activatedState = await digestTree(path.join(staging, 'state'));
+    if (activatedState.hash !== legacyV2Source.digest.hash ||
+        activatedState.fileCount !== legacyV2Source.digest.fileCount) {
+        await rm(staging, { recursive: true, force: true });
+        throw Object.assign(new Error('The staged Operate state does not match the verified source.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    await new OperateStore(projectDir, {
+        root: path.join(staging, 'state'),
+    }).verifyReplayProofCustody(verificationProof.replay);
+    const stamp = (options.now ?? new Date()).toISOString().replaceAll(':', '-');
+    const progress = Object.freeze({
+        kind: 'operate-storage-migration-progress',
+        schemaVersion: '1.0.0',
+        nonce,
+        stamp,
+        verificationProofHash,
+        sources: Object.freeze(sources.map((entry) => Object.freeze({
+            source: entry.source,
+            hash: entry.digest.hash,
+            fileCount: entry.digest.fileCount,
+            archiveId: `${stamp}-${entry.source}`,
+        }))),
+    });
+    await atomicWrite(projectDir, path.join(staging, 'archive', MIGRATION_PROGRESS_FILE), `${JSON.stringify(progress, null, 2)}\n`);
+    await options.afterStagePrepared?.();
+    const archives = [];
+    let neutralParked = false;
+    let stagingActivated = false;
+    const moved = new Map();
+    try {
+        if (inspection.legacyNeutralRoot) {
+            await rename(inspection.legacyNeutralRoot, parkedNeutral);
+            neutralParked = true;
+            await options.afterParkNeutral?.();
+        }
+        await rename(staging, inspection.root);
+        stagingActivated = true;
+        await options.afterActivate?.();
+        for (const entry of sources) {
+            const currentPath = entry.source === 'operate-legacy' ? parkedNeutral : entry.path;
+            const archivePath = path.join(inspection.root, 'archive', `${stamp}-${entry.source}`);
+            await rename(currentPath, archivePath);
+            moved.set(archivePath, { originalPath: currentPath, modes: entry.modes });
+            await privatizeTree(archivePath);
+            const archivedDigest = await digestTree(archivePath);
+            if (archivedDigest.hash !== entry.digest.hash ||
+                archivedDigest.fileCount !== entry.digest.fileCount) {
+                throw Object.assign(new Error(`Archived ${entry.source} bytes changed during migration.`), {
+                    code: 'OPERATE_STORE_CORRUPT',
+                });
+            }
+            const archive = Object.freeze({
+                archiveId: path.basename(archivePath),
+                source: entry.source,
+                ...archivedDigest,
+            });
+            archives.push(archive);
+            await options.onArchive?.(archive);
+        }
+        const receipt = Object.freeze({
+            kind: 'operate-storage-migration-receipt',
+            migrated: true,
+            archives: Object.freeze(archives),
+            verificationProofHash,
+            activatedState,
+            rollbackArchiveId: `${stamp}-operate-v2`,
+        });
+        await atomicWrite(projectDir, path.join(inspection.root, 'archive', `${stamp}-migration-receipt.json`), `${JSON.stringify(receipt, null, 2)}\n`);
+        await rm(path.join(inspection.root, 'archive', MIGRATION_PROGRESS_FILE), { force: true });
+        return receipt;
+    }
+    catch (error) {
+        if (error.code === 'OPERATE_MIGRATION_INTERRUPTED')
+            throw error;
+        for (const [archivePath, original] of [...moved.entries()].reverse()) {
+            if (await exists(archivePath)) {
+                await rename(archivePath, original.originalPath);
+                await restoreTreeModes(original.originalPath, original.modes);
+            }
+        }
+        if (stagingActivated && (await exists(inspection.root)))
+            await rename(inspection.root, staging);
+        if (neutralParked && (await exists(parkedNeutral)))
+            await rename(parkedNeutral, inspection.root);
+        if (await exists(staging))
+            await rm(staging, { recursive: true, force: true });
+        throw error;
+    }
+}
+export async function migrateOperateStorage(projectDir, options = {}) {
+    return await withOperateProjectTransaction(projectDir, async () => await migrateOperateStorageUnlocked(projectDir, options));
+}
+function parsedMigrationReceipt(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const receipt = value;
+    const activatedState = receipt.activatedState !== null &&
+        typeof receipt.activatedState === 'object' &&
+        !Array.isArray(receipt.activatedState)
+        ? receipt.activatedState
+        : null;
+    const archiveRecords = Array.isArray(receipt.archives)
+        ? receipt.archives.map((entry) => entry !== null && typeof entry === 'object' && !Array.isArray(entry)
+            ? entry
+            : null)
+        : [];
+    const seenSources = new Set();
+    if (receipt.kind !== 'operate-storage-migration-receipt' ||
+        receipt.migrated !== true ||
+        archiveRecords.length < 1 ||
+        archiveRecords.length > 2 ||
+        archiveRecords.some((archive) => {
+            if (archive === null ||
+                !['operate-v2', 'operate-legacy'].includes(String(archive.source)) ||
+                seenSources.has(String(archive.source)) ||
+                typeof archive.archiveId !== 'string' ||
+                !/^[0-9T.Z-]+-operate-(?:v2|legacy)$/u.test(archive.archiveId) ||
+                typeof archive.hash !== 'string' ||
+                !/^sha256:[a-f0-9]{64}$/u.test(archive.hash) ||
+                !Number.isSafeInteger(archive.fileCount) ||
+                Number(archive.fileCount) < 0) {
+                return true;
+            }
+            seenSources.add(String(archive.source));
+            return false;
+        }) ||
+        typeof receipt.rollbackArchiveId !== 'string' ||
+        !seenSources.has('operate-v2') ||
+        activatedState === null ||
+        typeof activatedState.hash !== 'string' ||
+        !/^sha256:[a-f0-9]{64}$/u.test(activatedState.hash) ||
+        !Number.isSafeInteger(activatedState.fileCount) ||
+        Number(activatedState.fileCount) < 0 ||
+        (receipt.verificationProofHash !== null &&
+            (typeof receipt.verificationProofHash !== 'string' ||
+                !/^sha256:[a-f0-9]{64}$/u.test(receipt.verificationProofHash)))) {
+        return null;
+    }
+    return receipt;
+}
+function assertRollbackProgress(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw Object.assign(new Error('Interrupted Operate rollback progress is invalid.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    const progress = value;
+    const archive = (candidate, expectedSource) => {
+        if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate)) {
+            throw Object.assign(new Error('Interrupted Operate rollback archive is invalid.'), {
+                code: 'OPERATE_STORE_CORRUPT',
+            });
+        }
+        const record = candidate;
+        if (record.source !== expectedSource ||
+            typeof record.archiveId !== 'string' ||
+            !/^[0-9T.Z-]+-operate-(?:v2|legacy)$/u.test(record.archiveId) ||
+            typeof record.hash !== 'string' ||
+            !/^sha256:[a-f0-9]{64}$/u.test(record.hash) ||
+            !Number.isSafeInteger(record.fileCount) ||
+            Number(record.fileCount) < 0) {
+            throw Object.assign(new Error('Interrupted Operate rollback archive custody is invalid.'), {
+                code: 'OPERATE_STORE_CORRUPT',
+            });
+        }
+        return Object.freeze({
+            source: expectedSource,
+            archiveId: record.archiveId,
+            hash: record.hash,
+            fileCount: Number(record.fileCount),
+        });
+    };
+    if (progress.kind !== 'operate-storage-rollback-progress' ||
+        progress.schemaVersion !== '1.0.0' ||
+        typeof progress.nonce !== 'string' ||
+        !/^[a-f0-9]{32}$/u.test(progress.nonce) ||
+        progress.forwardSnapshotId !== `.operate-forward-${progress.nonce}`) {
+        throw Object.assign(new Error('Interrupted Operate rollback progress is invalid.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    return Object.freeze({
+        kind: 'operate-storage-rollback-progress',
+        schemaVersion: '1.0.0',
+        nonce: progress.nonce,
+        forwardSnapshotId: progress.forwardSnapshotId,
+        v2: archive(progress.v2, 'operate-v2'),
+        neutral: progress.neutral === null ? null : archive(progress.neutral, 'operate-legacy'),
+    });
+}
+async function readRollbackProgress(projectDir) {
+    const planrRoot = path.join(path.resolve(projectDir), '.planr');
+    const entries = await readdir(planrRoot, { withFileTypes: true }).catch((error) => {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    const names = entries
+        .map((entry) => entry.name)
+        .filter((name) => ROLLBACK_PROGRESS_PATTERN.test(name));
+    if (names.length > 1) {
+        throw Object.assign(new Error('Multiple interrupted Operate rollbacks are ambiguous.'), {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+        });
+    }
+    if (names.length === 0)
+        return null;
+    const progressPath = path.join(planrRoot, names[0]);
+    await assertOperatePathCustody(projectDir, progressPath, {
+        code: 'OPERATE_STORE_INCOMPATIBLE',
+        message: 'Operate rollback progress cannot traverse symbolic links.',
+        requireFile: true,
+    });
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(progressPath, 'utf8'));
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        throw Object.assign(new Error('Interrupted Operate rollback progress is not valid JSON.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    const value = assertRollbackProgress(parsed);
+    if (path.basename(progressPath) !== `.operate-rollback-${value.nonce}.json`) {
+        throw Object.assign(new Error('Interrupted Operate rollback identity is invalid.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    return Object.freeze({ path: progressPath, value });
+}
+async function completeInterruptedRollback(projectDir, progressPath, progress, hooks = {}) {
+    const planrRoot = path.join(path.resolve(projectDir), '.planr');
+    const root = path.join(planrRoot, 'operate');
+    const legacyRoot = path.join(planrRoot, LEGACY_OPERATE_DIRECTORY);
+    const stagedV2 = path.join(planrRoot, `.operate-v2-restore-${progress.nonce}`);
+    const stagedNeutral = path.join(planrRoot, `.operate-neutral-restore-${progress.nonce}`);
+    const forwardSnapshot = path.join(planrRoot, progress.forwardSnapshotId);
+    for (const candidate of [root, legacyRoot, stagedV2, stagedNeutral, forwardSnapshot]) {
+        await assertOperatePathCustody(projectDir, candidate, {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+            message: 'Operate rollback custody cannot traverse symbolic links.',
+        });
+    }
+    const assertDigest = async (target, expected, label) => {
+        const digest = await digestTree(target);
+        if (digest.hash !== expected.hash || digest.fileCount !== expected.fileCount) {
+            throw Object.assign(new Error(`${label} no longer matches rollback custody.`), {
+                code: 'OPERATE_STORE_CORRUPT',
+            });
+        }
+        return digest;
+    };
+    if (!(await exists(legacyRoot))) {
+        if (!(await exists(stagedV2))) {
+            throw Object.assign(new Error('Interrupted legacy Operate rollback custody is missing.'), {
+                code: 'OPERATE_STORE_CORRUPT',
+            });
+        }
+        await assertDigest(stagedV2, progress.v2, 'Staged legacy Operate state');
+        await rename(stagedV2, legacyRoot);
+        await hooks.afterRestoreV2?.();
+    }
+    const restoredTree = await assertDigest(legacyRoot, progress.v2, 'Restored legacy Operate state');
+    if (!(await exists(forwardSnapshot))) {
+        if (!(await exists(root)) || !(await isCurrentLayout(root))) {
+            throw Object.assign(new Error('Interrupted Operate forward state is missing or incomplete.'), {
+                code: 'OPERATE_STORE_CORRUPT',
+            });
+        }
+        await rename(root, forwardSnapshot);
+        await hooks.afterParkForward?.();
+    }
+    if (!(await isCurrentLayout(forwardSnapshot))) {
+        throw Object.assign(new Error('Preserved Operate forward state is incomplete.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    let restoredLegacyTree = null;
+    if (progress.neutral) {
+        if (!(await exists(root))) {
+            if (!(await exists(stagedNeutral))) {
+                throw Object.assign(new Error('Interrupted neutral Operate rollback custody is missing.'), {
+                    code: 'OPERATE_STORE_CORRUPT',
+                });
+            }
+            await assertDigest(stagedNeutral, progress.neutral, 'Staged neutral Operate state');
+            await rename(stagedNeutral, root);
+            await hooks.afterRestoreNeutral?.();
+        }
+        restoredLegacyTree = await assertDigest(root, progress.neutral, 'Restored neutral Operate state');
+    }
+    else if (await exists(root)) {
+        throw Object.assign(new Error('Operate rollback produced an unexpected neutral state.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    await rm(progressPath);
+    return Object.freeze({
+        kind: 'operate-storage-rollback-receipt',
+        restoredSource: 'operate-v2',
+        restoredTree,
+        restoredLegacyTree,
+        forwardSnapshotId: progress.forwardSnapshotId,
+    });
+}
+/**
+ * Restores the pre-migration Store without deleting the activated Store.
+ * The forward state is moved intact to a private recovery snapshot so rollback
+ * remains lossless even after the new runtime has accepted later writes.
+ */
+async function rollbackOperateStorageMigrationUnlocked(projectDir, hooks = {}) {
+    const interrupted = await readRollbackProgress(projectDir);
+    if (interrupted) {
+        return await completeInterruptedRollback(projectDir, interrupted.path, interrupted.value, hooks);
+    }
+    const planrRoot = path.join(path.resolve(projectDir), '.planr');
+    const orphanedRestoreEntries = (await readdir(planrRoot, { withFileTypes: true }).catch((error) => {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }))
+        .filter((entry) => entry.isDirectory() &&
+        (/^\.operate-v2-restore-[a-f0-9]{32}$/u.test(entry.name) ||
+            /^\.operate-neutral-restore-[a-f0-9]{32}$/u.test(entry.name)))
+        .map((entry) => path.join(planrRoot, entry.name));
+    if (orphanedRestoreEntries.length > 0) {
+        const root = path.join(planrRoot, 'operate');
+        const legacyRoot = path.join(planrRoot, LEGACY_OPERATE_DIRECTORY);
+        if (!(await isCurrentLayout(root)) || (await exists(legacyRoot))) {
+            throw Object.assign(new Error('Orphaned Operate rollback staging is ambiguous.'), {
+                code: 'OPERATE_STORE_INCOMPATIBLE',
+            });
+        }
+        const recoveryRoot = path.join(planrRoot, 'operate-recovery');
+        await assertOperatePathCustody(projectDir, recoveryRoot, {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+            message: 'Operate rollback recovery cannot traverse symbolic links.',
+        });
+        await mkdir(recoveryRoot, { recursive: true, mode: 0o700 });
+        for (const entry of orphanedRestoreEntries) {
+            await assertOperatePathCustody(projectDir, entry, {
+                code: 'OPERATE_STORE_INCOMPATIBLE',
+                message: 'Orphaned Operate rollback staging cannot traverse symbolic links.',
+                requireDirectory: true,
+            });
+            const preserved = path.join(recoveryRoot, `abandoned-${path.basename(entry)}`);
+            if (await exists(preserved)) {
+                throw Object.assign(new Error('Operate rollback recovery custody already exists.'), {
+                    code: 'OPERATE_STORE_INCOMPATIBLE',
+                });
+            }
+            await rename(entry, preserved);
+        }
+    }
+    const inspection = await inspectOperateStorage(projectDir);
+    if (inspection.status !== 'ready') {
+        throw Object.assign(new Error('Operate storage rollback requires one ready migrated layout.'), {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+        });
+    }
+    const receiptNames = (await readdir(path.join(inspection.root, 'archive')))
+        .filter((entry) => entry.endsWith('-migration-receipt.json'))
+        .sort()
+        .reverse();
+    let receipt = null;
+    for (const name of receiptNames) {
+        try {
+            receipt = parsedMigrationReceipt(JSON.parse(await readFile(path.join(inspection.root, 'archive', name), 'utf8')));
+        }
+        catch (error) {
+            if (error instanceof SyntaxError)
+                continue;
+            throw error;
+        }
+        if (receipt)
+            break;
+    }
+    if (!receipt?.rollbackArchiveId) {
+        throw Object.assign(new Error('No verified Operate migration rollback archive is available.'), {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+        });
+    }
+    const expectedArchive = receipt.archives.find(({ source, archiveId }) => source === 'operate-v2' && archiveId === receipt?.rollbackArchiveId);
+    if (!expectedArchive) {
+        throw Object.assign(new Error('The Operate migration receipt has no matching rollback custody.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    const legacyRoot = path.join(planrRoot, LEGACY_OPERATE_DIRECTORY);
+    if (await exists(legacyRoot)) {
+        throw Object.assign(new Error('A legacy version 2 Operate Store already exists; rollback is ambiguous.'), {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+        });
+    }
+    const archiveRoot = path.join(inspection.root, 'archive', receipt.rollbackArchiveId);
+    const neutralArchive = receipt.archives.find(({ source }) => source === 'operate-legacy') ?? null;
+    const neutralArchiveRoot = neutralArchive
+        ? path.join(inspection.root, 'archive', neutralArchive.archiveId)
+        : null;
+    await assertOperatePathCustody(projectDir, archiveRoot, {
+        code: 'OPERATE_STORE_INCOMPATIBLE',
+        message: 'Operate rollback custody cannot traverse symbolic links.',
+        requireDirectory: true,
+    });
+    const archiveDigest = await digestTree(archiveRoot);
+    if (archiveDigest.hash !== expectedArchive.hash ||
+        archiveDigest.fileCount !== expectedArchive.fileCount) {
+        throw Object.assign(new Error('The Operate rollback archive no longer matches its receipt.'), {
+            code: 'OPERATE_STORE_CORRUPT',
+        });
+    }
+    if (neutralArchiveRoot) {
+        await assertOperatePathCustody(projectDir, neutralArchiveRoot, {
+            code: 'OPERATE_STORE_INCOMPATIBLE',
+            message: 'Neutral Operate rollback custody cannot traverse symbolic links.',
+            requireDirectory: true,
+        });
+        const neutralDigest = await digestTree(neutralArchiveRoot);
+        if (neutralDigest.hash !== neutralArchive?.hash ||
+            neutralDigest.fileCount !== neutralArchive.fileCount) {
+            throw Object.assign(new Error('The neutral Operate rollback archive no longer matches its receipt.'), { code: 'OPERATE_STORE_CORRUPT' });
+        }
+    }
+    const nonce = randomUUID().replaceAll('-', '');
+    const stagedLegacy = path.join(planrRoot, `.operate-v2-restore-${nonce}`);
+    const stagedNeutral = path.join(planrRoot, `.operate-neutral-restore-${nonce}`);
+    const forwardSnapshotId = `.operate-forward-${nonce}`;
+    try {
+        await cp(archiveRoot, stagedLegacy, {
+            recursive: true,
+            errorOnExist: true,
+            preserveTimestamps: true,
+        });
+        await privatizeTree(stagedLegacy);
+        const restoredTree = await digestTree(stagedLegacy);
+        if (restoredTree.hash !== archiveDigest.hash ||
+            restoredTree.fileCount !== archiveDigest.fileCount) {
+            throw Object.assign(new Error('The staged Operate rollback copy failed custody verification.'), {
+                code: 'OPERATE_STORE_CORRUPT',
+            });
+        }
+        if (neutralArchiveRoot && neutralArchive) {
+            await cp(neutralArchiveRoot, stagedNeutral, {
+                recursive: true,
+                errorOnExist: true,
+                preserveTimestamps: true,
+            });
+            await privatizeTree(stagedNeutral);
+            const stagedNeutralDigest = await digestTree(stagedNeutral);
+            if (stagedNeutralDigest.hash !== neutralArchive.hash ||
+                stagedNeutralDigest.fileCount !== neutralArchive.fileCount) {
+                throw Object.assign(new Error('The staged neutral Operate rollback copy failed custody verification.'), { code: 'OPERATE_STORE_CORRUPT' });
+            }
+        }
+        const progress = Object.freeze({
+            kind: 'operate-storage-rollback-progress',
+            schemaVersion: '1.0.0',
+            nonce,
+            forwardSnapshotId,
+            v2: expectedArchive,
+            neutral: neutralArchive,
+        });
+        const progressPath = path.join(planrRoot, `.operate-rollback-${nonce}.json`);
+        await atomicWrite(projectDir, progressPath, `${JSON.stringify(progress, null, 2)}\n`);
+        await hooks.afterProgress?.();
+        return await completeInterruptedRollback(projectDir, progressPath, progress, hooks);
+    }
+    catch (error) {
+        if (!(await exists(path.join(planrRoot, `.operate-rollback-${nonce}.json`)))) {
+            await rm(stagedLegacy, { recursive: true, force: true });
+            await rm(stagedNeutral, { recursive: true, force: true });
+        }
+        throw error;
+    }
+}
+export async function rollbackOperateStorageMigration(projectDir, hooks = {}) {
+    return await withOperateProjectTransaction(projectDir, async () => await rollbackOperateStorageMigrationUnlocked(projectDir, hooks));
+}
+//# sourceMappingURL=storage-layout.js.map