@planu/cli 4.13.0 → 5.0.0

package/dist/storage/migrations/canonical-storage.js

@@ -0,0 +1,712 @@
+/* eslint-disable no-restricted-syntax, no-param-reassign, complexity, max-lines, max-lines-per-function -- journaled migration keeps its state machine and private contract together for auditability */
+import { copyFile, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { homedir, tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
+import { acquireLock as acquireFileMutex, releaseLock as releaseFileMutex, } from '../../engine/safety/file-mutex.js';
+import { assertNoObsoleteFileLock } from '../../engine/safety/obsolete-lock-guard.js';
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function assertAbsolute(path, label) {
+    if (!path.trim() || !isAbsolute(path)) {
+        throw new Error(`[Planu] ${label} must be absolute`);
+    }
+    return resolve(path);
+}
+function assertNarrowLegacyRoot(path) {
+    const root = parse(path).root;
+    const segments = relative(root, path).split(sep).filter(Boolean);
+    const protectedRoots = new Set([resolve(homedir()), resolve(tmpdir()), resolve(process.cwd())]);
+    if (path === root || segments.length < 2 || protectedRoots.has(path)) {
+        throw new Error(`[Planu] Legacy root is too broad for safe migration: ${path}`);
+    }
+}
+function isInside(parent, child) {
+    const rel = relative(parent, child);
+    return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel));
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+async function listFiles(root, current = root) {
+    const entries = await readdir(current, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const path = join(current, entry.name);
+        if (entry.isSymbolicLink()) {
+            throw new Error(`[Planu] Migration refuses symlink: ${path}`);
+        }
+        if (entry.isDirectory()) {
+            files.push(...(await listFiles(root, path)));
+        }
+        else if (entry.isFile()) {
+            files.push(path);
+        }
+        else {
+            throw new Error(`[Planu] Migration refuses non-regular file: ${path}`);
+        }
+    }
+    return files;
+}
+export async function inventoryStorageRoot(rootInput) {
+    const root = assertAbsolute(rootInput, 'inventory root');
+    const info = await lstat(root);
+    if (info.isSymbolicLink() || !info.isDirectory()) {
+        throw new Error(`[Planu] Migration root must be a real directory: ${root}`);
+    }
+    const files = [];
+    let totalBytes = 0;
+    for (const path of await listFiles(root)) {
+        const content = await readFile(path);
+        const relativePath = relative(root, path).split(sep).join('/');
+        files.push({ relativePath, size: content.byteLength, sha256: sha256(content) });
+        totalBytes += content.byteLength;
+    }
+    const digest = sha256(files.map((file) => `${file.relativePath}\0${file.size}\0${file.sha256}\n`).join(''));
+    return { root, files, totalBytes, digest };
+}
+function migrationPaths(destinationRoot) {
+    const prefix = join(dirname(destinationRoot), `.${basename(destinationRoot)}.canonical-migration`);
+    return {
+        journalPath: `${prefix}.journal.json`,
+        stagingRoot: `${prefix}.staging`,
+        backupRoot: `${prefix}.backup`,
+        lockPath: `${prefix}.lock`,
+    };
+}
+async function writeJournal(path, journal) {
+    journal.updatedAt = new Date().toISOString();
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(journal, null, 2)}\n`, { mode: 0o600 });
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+function isSafeInventory(value, expectedRoot) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const inventory = value;
+    const files = inventory.files;
+    return (inventory.root === expectedRoot &&
+        typeof inventory.digest === 'string' &&
+        /^[a-f0-9]{64}$/.test(inventory.digest) &&
+        Number.isSafeInteger(inventory.totalBytes) &&
+        (inventory.totalBytes ?? -1) >= 0 &&
+        Array.isArray(files) &&
+        files.every((file) => {
+            if (!file || typeof file !== 'object') {
+                return false;
+            }
+            const entry = file;
+            return (typeof entry.relativePath === 'string' &&
+                entry.relativePath.length > 0 &&
+                !entry.relativePath.startsWith('/') &&
+                !entry.relativePath.split('/').includes('..') &&
+                Number.isSafeInteger(entry.size) &&
+                entry.size >= 0 &&
+                typeof entry.sha256 === 'string' &&
+                /^[a-f0-9]{64}$/.test(entry.sha256));
+        }));
+}
+function validateJournal(value, expected) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('[Planu] Invalid migration journal structure');
+    }
+    const journal = value;
+    const phases = [
+        'prepared',
+        'switched',
+        'verified',
+        'completed',
+        'rolled-back',
+    ];
+    const validSources = Array.isArray(journal.sourceInventories) &&
+        journal.sourceInventories.length <= expected.legacyRoots.length &&
+        journal.sourceInventories.every((inventory) => {
+            if (!inventory || typeof inventory !== 'object') {
+                return false;
+            }
+            const rootValue = inventory.root;
+            const sourceRoot = expected.legacyRoots.find((root) => root === rootValue);
+            return sourceRoot !== undefined && isSafeInventory(inventory, sourceRoot);
+        });
+    if (journal.schemaVersion !== 1 ||
+        journal.destinationRoot !== expected.destinationRoot ||
+        journal.stagingRoot !== expected.stagingRoot ||
+        journal.backupRoot !== expected.backupRoot ||
+        JSON.stringify(journal.legacyRoots) !== JSON.stringify(expected.legacyRoots) ||
+        !journal.phase ||
+        !phases.includes(journal.phase) ||
+        typeof journal.destinationExisted !== 'boolean' ||
+        typeof journal.updatedAt !== 'string' ||
+        !Array.isArray(journal.collisions) ||
+        !validSources ||
+        !isSafeInventory(journal.expectedInventory, expected.stagingRoot)) {
+        throw new Error('[Planu] Invalid or unsafe migration journal');
+    }
+    return journal;
+}
+async function readJournal(path, expected) {
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        return validateJournal(parsed, expected);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+async function retireCompletedJournalForNewSources(journalPath, expected) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(journalPath, 'utf8'));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+    if (!parsed || typeof parsed !== 'object' || !('legacyRoots' in parsed)) {
+        throw new Error('[Planu] Invalid or unsafe migration journal');
+    }
+    const rawRoots = parsed.legacyRoots;
+    if (!Array.isArray(rawRoots) || !rawRoots.every((root) => typeof root === 'string')) {
+        throw new Error('[Planu] Invalid or unsafe migration journal');
+    }
+    if (JSON.stringify(rawRoots) === JSON.stringify(expected.legacyRoots)) {
+        return;
+    }
+    const previousRoots = rawRoots.map((root) => assertAbsolute(root, 'journal legacyRoot'));
+    for (const root of previousRoots) {
+        assertNarrowLegacyRoot(root);
+        if (isInside(root, expected.destinationRoot) || isInside(expected.destinationRoot, root)) {
+            throw new Error('[Planu] Invalid or unsafe migration journal');
+        }
+    }
+    const previous = validateJournal(parsed, { ...expected, legacyRoots: previousRoots });
+    if (previous.phase !== 'completed') {
+        throw new Error('[Planu] Active migration journal does not match requested roots');
+    }
+    // A completed destination remains live and may legitimately receive newer
+    // canonical records. Re-inventory its real directory instead of requiring
+    // the historical generation digest to remain frozen forever.
+    await inventoryStorageRoot(expected.destinationRoot);
+    await rm(journalPath, { force: true });
+}
+function recordTimestamp(value) {
+    if (!value || typeof value !== 'object') {
+        return 0;
+    }
+    const record = value;
+    for (const field of ['updatedAt', 'lastAnalyzed', 'modifiedAt', 'createdAt']) {
+        if (typeof record[field] === 'string') {
+            const parsed = Date.parse(record[field]);
+            if (Number.isFinite(parsed)) {
+                return parsed;
+            }
+        }
+    }
+    return 0;
+}
+function mergeKnowledge(source, destination) {
+    if (!source || typeof source !== 'object' || Array.isArray(source)) {
+        throw new Error('[Planu] Invalid legacy knowledge.json');
+    }
+    if (!destination || typeof destination !== 'object' || Array.isArray(destination)) {
+        throw new Error('[Planu] Invalid destination knowledge.json');
+    }
+    const sourceRecord = source;
+    const destinationRecord = destination;
+    if (recordTimestamp(source) > recordTimestamp(destination)) {
+        return { value: { ...destinationRecord, ...sourceRecord }, resolution: 'source-newer' };
+    }
+    return { value: { ...sourceRecord, ...destinationRecord }, resolution: 'destination-newer' };
+}
+function specKey(value, index) {
+    if (value && typeof value === 'object') {
+        const record = value;
+        if (typeof record.uuid === 'string' && record.uuid) {
+            return `uuid:${record.uuid}`;
+        }
+        if (typeof record.id === 'string' && record.id) {
+            return `id:${record.id}`;
+        }
+    }
+    return `anonymous:${index}`;
+}
+function unwrapSpecs(value) {
+    if (Array.isArray(value)) {
+        return { rows: value, envelope: false };
+    }
+    if (value && typeof value === 'object' && Array.isArray(value.data)) {
+        return { rows: value.data, envelope: true };
+    }
+    throw new Error('[Planu] specs.json must contain an array or canonical envelope');
+}
+function conflictingUuidIdentity(left, right) {
+    if (!left || typeof left !== 'object' || !right || typeof right !== 'object') {
+        return false;
+    }
+    const leftRecord = left;
+    const rightRecord = right;
+    return (typeof leftRecord.uuid === 'string' &&
+        leftRecord.uuid.length > 0 &&
+        leftRecord.uuid === rightRecord.uuid &&
+        typeof leftRecord.id === 'string' &&
+        typeof rightRecord.id === 'string' &&
+        leftRecord.id !== rightRecord.id);
+}
+/** Reject split-brain source rows before any merge Map can discard one of them. */
+function validateRawSpecRows(rows, owningProjectId) {
+    const ids = new Map();
+    const identities = new Map();
+    for (const record of rows) {
+        if (!record || typeof record !== 'object') {
+            throw new Error('[Planu] Canonical spec ownership conflict during migration');
+        }
+        const value = record;
+        const id = typeof value.id === 'string' && value.id.length > 0 ? value.id : undefined;
+        const uuid = typeof value.uuid === 'string' && value.uuid.length > 0 ? value.uuid : undefined;
+        if (id !== undefined) {
+            if (ids.has(id)) {
+                throw new Error('[Planu] Canonical spec identity conflict during migration');
+            }
+            ids.set(id, uuid);
+        }
+        if (typeof value.projectId !== 'string' || value.projectId !== owningProjectId) {
+            throw new Error('[Planu] Canonical spec ownership conflict during migration');
+        }
+        const aliases = Array.isArray(value.uuidAliases)
+            ? value.uuidAliases
+            : [];
+        for (const identity of [uuid, ...aliases]) {
+            if (typeof identity !== 'string' || identity.length === 0 || id === undefined) {
+                continue;
+            }
+            const owner = identities.get(identity);
+            if (owner !== undefined && owner !== id) {
+                throw new Error('[Planu] Canonical spec identity conflict during migration');
+            }
+            identities.set(identity, id);
+        }
+    }
+}
+function validateSpecsDocument(value, owningProjectId) {
+    validateRawSpecRows(unwrapSpecs(value).rows, owningProjectId);
+}
+function mergeSpecs(source, destination, owningProjectId) {
+    const sourceStore = unwrapSpecs(source);
+    const destinationStore = unwrapSpecs(destination);
+    validateRawSpecRows(sourceStore.rows, owningProjectId);
+    validateRawSpecRows(destinationStore.rows, owningProjectId);
+    const merged = new Map();
+    for (const [index, record] of destinationStore.rows.entries()) {
+        const key = specKey(record, index);
+        const previous = merged.get(key);
+        if (previous !== undefined && conflictingUuidIdentity(previous, record)) {
+            throw new Error('[Planu] Canonical spec identity conflict during migration');
+        }
+        merged.set(key, record);
+    }
+    let sourceWon = false;
+    for (const [index, record] of sourceStore.rows.entries()) {
+        const key = specKey(record, index);
+        const current = merged.get(key);
+        if (current === undefined) {
+            merged.set(key, record);
+            continue;
+        }
+        if (conflictingUuidIdentity(current, record)) {
+            throw new Error('[Planu] Canonical spec identity conflict during migration');
+        }
+        if (recordTimestamp(record) > recordTimestamp(current)) {
+            merged.set(key, record);
+            sourceWon = true;
+        }
+    }
+    // Legacy fixtures may omit UUID/project metadata, but a merger must never
+    // silently publish two canonical IDs or UUID identities when they are present.
+    const seenIds = new Set();
+    const seenUuids = new Set();
+    for (const record of merged.values()) {
+        if (!record || typeof record !== 'object') {
+            continue;
+        }
+        const value = record;
+        if (typeof value.id === 'string' && value.id.length > 0) {
+            if (seenIds.has(value.id)) {
+                throw new Error('[Planu] Canonical spec identity conflict during migration');
+            }
+            seenIds.add(value.id);
+        }
+        const aliases = Array.isArray(value.uuidAliases)
+            ? value.uuidAliases
+            : [];
+        const identities = [value.uuid, ...aliases];
+        for (const identity of identities) {
+            if (typeof identity !== 'string' || identity.length === 0) {
+                continue;
+            }
+            if (seenUuids.has(identity)) {
+                throw new Error('[Planu] Canonical spec identity conflict during migration');
+            }
+            seenUuids.add(identity);
+        }
+    }
+    return {
+        value: sourceStore.envelope || destinationStore.envelope
+            ? { schemaVersion: 1, data: [...merged.values()] }
+            : [...merged.values()],
+        resolution: sourceWon ? 'source-newer' : 'destination-newer',
+    };
+}
+async function mergeFile(sourceRoot, sourceDigest, stagingRoot, destinationRoot, file, collisions) {
+    const sourcePath = join(sourceRoot, ...file.relativePath.split('/'));
+    const stagingPath = join(stagingRoot, ...file.relativePath.split('/'));
+    const destinationPath = join(destinationRoot, ...file.relativePath.split('/'));
+    const current = await readFile(sourcePath);
+    if (sha256(current) !== file.sha256) {
+        throw new Error(`[Planu] Legacy source changed during migration: ${sourcePath}`);
+    }
+    if (file.relativePath === 'specs.json') {
+        validateSpecsDocument(JSON.parse(current.toString('utf8')), basename(destinationRoot));
+    }
+    await mkdir(dirname(stagingPath), { recursive: true });
+    if (!(await exists(stagingPath))) {
+        await copyFile(sourcePath, stagingPath);
+        return;
+    }
+    const staged = await readFile(stagingPath);
+    if (sha256(staged) === file.sha256) {
+        return;
+    }
+    let resolution;
+    let archivedPath;
+    if (file.relativePath === 'knowledge.json' || file.relativePath === 'specs.json') {
+        const sourceJson = JSON.parse(current.toString('utf8'));
+        const destinationJson = JSON.parse(await readFile(stagingPath, 'utf8'));
+        const merged = file.relativePath === 'knowledge.json'
+            ? mergeKnowledge(sourceJson, destinationJson)
+            : mergeSpecs(sourceJson, destinationJson, basename(destinationRoot));
+        await writeFile(stagingPath, `${JSON.stringify(merged.value, null, 2)}\n`, { mode: 0o600 });
+        resolution = merged.resolution;
+    }
+    else {
+        archivedPath = join(destinationRoot, 'migration-conflicts', sourceDigest, ...file.relativePath.split('/'));
+        const stagedArchivePath = join(stagingRoot, 'migration-conflicts', sourceDigest, ...file.relativePath.split('/'));
+        if (await exists(stagedArchivePath)) {
+            const archived = await readFile(stagedArchivePath);
+            if (sha256(archived) !== file.sha256) {
+                throw new Error(`[Planu] Migration conflict archive collision: ${stagedArchivePath}`);
+            }
+        }
+        else {
+            await mkdir(dirname(stagedArchivePath), { recursive: true });
+            await copyFile(sourcePath, stagedArchivePath);
+            const archived = await readFile(stagedArchivePath);
+            if (sha256(archived) !== file.sha256) {
+                throw new Error(`[Planu] Migration conflict archive verification failed: ${stagedArchivePath}`);
+            }
+        }
+        resolution = 'source-archived';
+    }
+    const collision = {
+        relativePath: file.relativePath,
+        sourcePath,
+        destinationPath,
+        ...(archivedPath ? { archivedPath } : {}),
+        resolution,
+    };
+    collisions.push(collision);
+}
+async function planCollisions(sourceInventories, destination, destinationRoot) {
+    const state = new Map((destination?.files ?? []).map((file) => [file.relativePath, { sha256: file.sha256 }]));
+    const collisions = [];
+    for (const inventory of sourceInventories) {
+        for (const file of inventory.files) {
+            const sourcePath = join(inventory.root, ...file.relativePath.split('/'));
+            const current = state.get(file.relativePath);
+            const schemaFile = file.relativePath === 'knowledge.json' || file.relativePath === 'specs.json';
+            if (!current) {
+                const schemaValue = schemaFile
+                    ? JSON.parse(await readFile(sourcePath, 'utf8'))
+                    : undefined;
+                if (file.relativePath === 'specs.json') {
+                    validateSpecsDocument(schemaValue, basename(destinationRoot));
+                }
+                state.set(file.relativePath, {
+                    sha256: file.sha256,
+                    ...(schemaFile ? { value: schemaValue } : {}),
+                });
+                continue;
+            }
+            if (current.sha256 === file.sha256) {
+                continue;
+            }
+            let resolution;
+            let archivedPath;
+            if (schemaFile) {
+                const source = JSON.parse(await readFile(sourcePath, 'utf8'));
+                const target = current.value ??
+                    JSON.parse(await readFile(join(destinationRoot, ...file.relativePath.split('/')), 'utf8'));
+                const merged = file.relativePath === 'knowledge.json'
+                    ? mergeKnowledge(source, target)
+                    : mergeSpecs(source, target, basename(destinationRoot));
+                resolution = merged.resolution;
+                state.set(file.relativePath, {
+                    sha256: sha256(JSON.stringify(merged.value)),
+                    value: merged.value,
+                });
+            }
+            else {
+                resolution = 'source-archived';
+                archivedPath = join(destinationRoot, 'migration-conflicts', inventory.digest, ...file.relativePath.split('/'));
+            }
+            collisions.push({
+                relativePath: file.relativePath,
+                sourcePath,
+                destinationPath: join(destinationRoot, ...file.relativePath.split('/')),
+                ...(archivedPath ? { archivedPath } : {}),
+                resolution,
+            });
+        }
+    }
+    return collisions;
+}
+async function prepare(journal) {
+    await rm(journal.stagingRoot, { recursive: true, force: true });
+    if (journal.destinationExisted) {
+        await mkdir(journal.stagingRoot, { recursive: true });
+        for (const file of (await inventoryStorageRoot(journal.destinationRoot)).files) {
+            const source = join(journal.destinationRoot, ...file.relativePath.split('/'));
+            const target = join(journal.stagingRoot, ...file.relativePath.split('/'));
+            await mkdir(dirname(target), { recursive: true });
+            await copyFile(source, target);
+        }
+    }
+    else {
+        await mkdir(journal.stagingRoot, { recursive: true });
+    }
+    journal.collisions = [];
+    for (const inventory of journal.sourceInventories) {
+        for (const file of inventory.files) {
+            await mergeFile(inventory.root, inventory.digest, journal.stagingRoot, journal.destinationRoot, file, journal.collisions);
+        }
+    }
+    const stagedSpecs = join(journal.stagingRoot, 'specs.json');
+    if (await exists(stagedSpecs)) {
+        validateSpecsDocument(JSON.parse(await readFile(stagedSpecs, 'utf8')), basename(journal.destinationRoot));
+    }
+    journal.expectedInventory = await inventoryStorageRoot(journal.stagingRoot);
+}
+async function switchDestination(journal) {
+    if (await exists(journal.destinationRoot)) {
+        if (await exists(journal.backupRoot)) {
+            throw new Error('[Planu] Migration found both destination and rollback backup');
+        }
+        await rename(journal.destinationRoot, journal.backupRoot);
+    }
+    await rename(journal.stagingRoot, journal.destinationRoot);
+}
+async function rollbackSwitch(journal) {
+    await rm(journal.stagingRoot, { recursive: true, force: true });
+    if (await exists(journal.backupRoot)) {
+        await rm(journal.destinationRoot, { recursive: true, force: true });
+        await rename(journal.backupRoot, journal.destinationRoot);
+    }
+    else if (!journal.destinationExisted) {
+        await rm(journal.destinationRoot, { recursive: true, force: true });
+    }
+    journal.phase = 'rolled-back';
+}
+async function verifyDestination(journal) {
+    const actual = await inventoryStorageRoot(journal.destinationRoot);
+    if (actual.digest !== journal.expectedInventory.digest) {
+        throw new Error('[Planu] Canonical destination checksum verification failed');
+    }
+    return actual;
+}
+async function acquireMigrationLock(path) {
+    try {
+        await assertNoObsoleteFileLock(path, 'canonical storage migration');
+        const handle = await acquireFileMutex(path, 1);
+        return () => releaseFileMutex(handle);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'LOCK_TIMEOUT') {
+            throw new Error(`[Planu] Canonical migration is already running: ${path}`, { cause: error });
+        }
+        throw error;
+    }
+}
+function result(status, journal, journalPath, resumed, destinationInventory, reason) {
+    return {
+        status,
+        destinationRoot: journal.destinationRoot,
+        journalPath,
+        sourceInventories: journal.sourceInventories,
+        destinationInventory,
+        collisions: journal.collisions,
+        resumed,
+        ...(reason ? { reason } : {}),
+    };
+}
+/** Migrate explicit legacy roots into one canonical absolute directory. */
+export async function migrateCanonicalStorage(input) {
+    const destinationRoot = assertAbsolute(input.destinationRoot, 'destinationRoot');
+    const legacyRoots = [
+        ...new Set(input.legacyRoots.map((path) => assertAbsolute(path, 'legacyRoot'))),
+    ];
+    for (const source of legacyRoots) {
+        assertNarrowLegacyRoot(source);
+        if (isInside(source, destinationRoot) || isInside(destinationRoot, source)) {
+            throw new Error('[Planu] Legacy and destination roots must not overlap');
+        }
+    }
+    const paths = migrationPaths(destinationRoot);
+    const existingRoots = [];
+    for (const source of legacyRoots) {
+        if (await exists(source)) {
+            existingRoots.push(source);
+        }
+    }
+    const sourceInventories = await Promise.all(existingRoots.map(inventoryStorageRoot));
+    const destinationInventory = (await exists(destinationRoot))
+        ? await inventoryStorageRoot(destinationRoot)
+        : null;
+    const emptyJournal = {
+        schemaVersion: 1,
+        destinationRoot,
+        legacyRoots,
+        phase: 'prepared',
+        stagingRoot: paths.stagingRoot,
+        backupRoot: paths.backupRoot,
+        sourceInventories,
+        expectedInventory: destinationInventory ?? {
+            root: paths.stagingRoot,
+            files: [],
+            totalBytes: 0,
+            digest: sha256(''),
+        },
+        collisions: [],
+        destinationExisted: destinationInventory !== null,
+        updatedAt: new Date().toISOString(),
+    };
+    if (input.dryRun) {
+        if (sourceInventories.length === 0) {
+            return result('noop', emptyJournal, paths.journalPath, false, destinationInventory);
+        }
+        emptyJournal.collisions = await planCollisions(sourceInventories, destinationInventory, destinationRoot);
+        return result('planned', emptyJournal, paths.journalPath, false, destinationInventory);
+    }
+    const release = await acquireMigrationLock(paths.lockPath);
+    let journal = emptyJournal;
+    let resumed = false;
+    let journalLoaded = false;
+    try {
+        await retireCompletedJournalForNewSources(paths.journalPath, {
+            destinationRoot,
+            legacyRoots,
+            stagingRoot: paths.stagingRoot,
+            backupRoot: paths.backupRoot,
+        });
+        const existingJournal = await readJournal(paths.journalPath, {
+            destinationRoot,
+            legacyRoots,
+            stagingRoot: paths.stagingRoot,
+            backupRoot: paths.backupRoot,
+        });
+        journal = existingJournal ?? emptyJournal;
+        resumed = existingJournal !== null;
+        journalLoaded = true;
+        if (!existingJournal && sourceInventories.length === 0) {
+            return result('noop', emptyJournal, paths.journalPath, false, destinationInventory);
+        }
+        if (journal.destinationRoot !== destinationRoot ||
+            JSON.stringify(journal.legacyRoots) !== JSON.stringify(legacyRoots)) {
+            throw new Error('[Planu] Existing migration journal does not match requested roots');
+        }
+        if (journal.phase === 'completed') {
+            const verified = await verifyDestination(journal);
+            return result('noop', journal, paths.journalPath, true, verified);
+        }
+        if (journal.phase === 'rolled-back') {
+            journal = emptyJournal;
+        }
+        if (journal.phase === 'prepared') {
+            const stagingExists = await exists(journal.stagingRoot);
+            if (resumed && !stagingExists && (await exists(journal.destinationRoot))) {
+                const possibleSwitched = await inventoryStorageRoot(journal.destinationRoot);
+                if (possibleSwitched.digest === journal.expectedInventory.digest) {
+                    journal.phase = 'switched';
+                    await writeJournal(paths.journalPath, journal);
+                }
+                else {
+                    await prepare(journal);
+                    await writeJournal(paths.journalPath, journal);
+                }
+            }
+            else if (!stagingExists) {
+                await prepare(journal);
+                await writeJournal(paths.journalPath, journal);
+            }
+            else {
+                const staged = await inventoryStorageRoot(journal.stagingRoot);
+                if (staged.digest !== journal.expectedInventory.digest) {
+                    await prepare(journal);
+                    await writeJournal(paths.journalPath, journal);
+                }
+            }
+            if (journal.phase === 'prepared') {
+                await switchDestination(journal);
+                journal.phase = 'switched';
+                await writeJournal(paths.journalPath, journal);
+            }
+        }
+        const verified = await verifyDestination(journal);
+        journal.phase = 'verified';
+        await writeJournal(paths.journalPath, journal);
+        for (const source of journal.legacyRoots) {
+            await rm(source, { recursive: true, force: true });
+        }
+        await rm(journal.backupRoot, { recursive: true, force: true });
+        journal.phase = 'completed';
+        await writeJournal(paths.journalPath, journal);
+        return result(resumed ? 'resumed' : 'migrated', journal, paths.journalPath, resumed, verified);
+    }
+    catch (error) {
+        if (!journalLoaded) {
+            throw error;
+        }
+        if (journal.phase === 'prepared' || journal.phase === 'switched') {
+            await rollbackSwitch(journal);
+            await writeJournal(paths.journalPath, journal);
+            return result('rolled-back', journal, paths.journalPath, resumed, destinationInventory, error instanceof Error ? error.message : String(error));
+        }
+        return result('error', journal, paths.journalPath, resumed, null, error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        await release();
+    }
+}
+export const CANONICAL_MIGRATION_INTERNALS = Object.freeze({ migrationPaths });
+//# sourceMappingURL=canonical-storage.js.map