@papillon6814/copi 0.1.0 → 0.2.1

package/dist/src/migration-backup.d.ts

@@ -0,0 +1,22 @@
+export interface MigrationBackupInputEntry {
+    readonly originalPath: string;
+    readonly sha256: string;
+    readonly mode: number;
+}
+export interface MigrationBackupManifestEntry extends MigrationBackupInputEntry {
+    readonly backupPath: string;
+}
+export interface MigrationBackupManifest {
+    readonly version: 1;
+    readonly entries: readonly MigrationBackupManifestEntry[];
+}
+export interface MigrationBackupExpected {
+    readonly libraryRoot: string;
+    readonly backupDir: string;
+    readonly manifestBytes: Buffer;
+    readonly manifestSha256: string;
+    readonly entries: readonly MigrationBackupInputEntry[];
+}
+export declare function buildMigrationBackupManifest(entries: readonly MigrationBackupInputEntry[]): Buffer;
+export declare function parseMigrationBackupManifest(bytes: Buffer): MigrationBackupManifest;
+export declare function verifyMigrationBackup(expectedValue: MigrationBackupExpected): Promise<void>;

package/dist/src/migration-backup.js

@@ -0,0 +1,403 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { types as utilTypes } from "node:util";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+const sha256Pattern = /^[0-9a-f]{64}$/;
+const backupUuidPattern = /^\.migration-backups\/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const manifestName = "manifest.json";
+const isNativeProxy = utilTypes.isProxy;
+const privateDirectoryMode = 0o700;
+const privateFileMode = 0o600;
+function digest(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function isProxyObject(value) {
+    return ((typeof value === "object" && value !== null) || typeof value === "function") && isNativeProxy(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+    const actual = Object.keys(value);
+    return actual.length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function snapshotOwnDataRecord(value, expectedKeys) {
+    if (typeof value !== "object" || value === null || isProxyObject(value))
+        return undefined;
+    try {
+        if (Array.isArray(value))
+            return undefined;
+        const ownKeys = Reflect.ownKeys(value);
+        if (ownKeys.length !== expectedKeys.length || ownKeys.some((key) => typeof key !== "string" || !expectedKeys.includes(key))) {
+            return undefined;
+        }
+        const snapshot = Object.create(null);
+        for (const key of expectedKeys) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || !Object.hasOwn(descriptor, "value") || descriptor.enumerable !== true)
+                return undefined;
+            snapshot[key] = descriptor.value;
+        }
+        return snapshot;
+    }
+    catch {
+        return undefined;
+    }
+}
+function snapshotDenseOwnDataArray(value) {
+    try {
+        if (isProxyObject(value) || !Array.isArray(value))
+            return undefined;
+        const ownKeys = Reflect.ownKeys(value);
+        const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+        if (!lengthDescriptor || !Object.hasOwn(lengthDescriptor, "value") || lengthDescriptor.enumerable !== false ||
+            typeof lengthDescriptor.value !== "number" || !Number.isSafeInteger(lengthDescriptor.value) || lengthDescriptor.value < 0 ||
+            ownKeys.length !== lengthDescriptor.value + 1) {
+            return undefined;
+        }
+        const length = lengthDescriptor.value;
+        const ownKeySet = new Set();
+        for (const key of ownKeys) {
+            if (typeof key !== "string" ||
+                (key !== "length" && (!Number.isSafeInteger(Number(key)) || Number(key) < 0 || Number(key) >= length || String(Number(key)) !== key))) {
+                return undefined;
+            }
+            ownKeySet.add(key);
+        }
+        if (!ownKeySet.has("length"))
+            return undefined;
+        const snapshot = [];
+        for (let index = 0; index < length; index += 1) {
+            const key = String(index);
+            if (!ownKeySet.has(key))
+                return undefined;
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || !Object.hasOwn(descriptor, "value") || descriptor.enumerable !== true)
+                return undefined;
+            snapshot.push(descriptor.value);
+        }
+        return snapshot;
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeOriginalPath(value) {
+    if (typeof value !== "string" || value.length === 0 || value.includes("\\") || value.includes("\0") ||
+        path.posix.isAbsolute(value) || path.posix.normalize(value) !== value)
+        return false;
+    const parts = value.split("/");
+    if (parts.some((part) => part.length === 0 || part === "." || part === ".."))
+        return false;
+    return value === "catalog.json" || (parts.length > 1 && (parts[0] === "items" || parts[0] === "sources"));
+}
+function normalizeInputEntries(value) {
+    const inputEntries = snapshotDenseOwnDataArray(value);
+    if (!inputEntries)
+        throw new Error("Migration backup entries must be a dense own-data array; Proxy arrays are not accepted.");
+    const entries = inputEntries.map((entry) => {
+        const fields = snapshotOwnDataRecord(entry, ["originalPath", "sha256", "mode"]);
+        if (!fields || !safeOriginalPath(fields.originalPath) || typeof fields.sha256 !== "string" || !sha256Pattern.test(fields.sha256) ||
+            typeof fields.mode !== "number" || !Number.isInteger(fields.mode) || fields.mode < 0 || fields.mode > 0o777) {
+            throw new Error("Invalid path, SHA-256 digest, mode, Proxy, or own-data fields in migration backup entry.");
+        }
+        return {
+            originalPath: fields.originalPath,
+            sha256: fields.sha256,
+            mode: fields.mode,
+        };
+    });
+    entries.sort((left, right) => compareStrings(left.originalPath, right.originalPath));
+    if (!entries.some((entry) => entry.originalPath === "catalog.json")) {
+        throw new Error("Migration backup manifest must cover catalog.json.");
+    }
+    for (let index = 1; index < entries.length; index += 1) {
+        const previous = entries[index - 1].originalPath;
+        const current = entries[index].originalPath;
+        if (previous === current || current.startsWith(`${previous}/`)) {
+            throw new Error("Duplicate or overlapping paths in migration backup manifest.");
+        }
+    }
+    return entries;
+}
+function serializeManifest(entries) {
+    const manifest = {
+        version: 1,
+        entries: entries.map((entry) => ({
+            originalPath: entry.originalPath,
+            backupPath: `files/${entry.originalPath}`,
+            sha256: entry.sha256,
+            mode: entry.mode,
+        })),
+    };
+    return Buffer.from(`${JSON.stringify(manifest)}\n`, "utf8");
+}
+export function buildMigrationBackupManifest(entries) {
+    return serializeManifest(normalizeInputEntries(entries));
+}
+function parseManifestObject(value) {
+    if (!isRecord(value) || !hasExactKeys(value, ["version", "entries"]) || value.version !== 1 || !Array.isArray(value.entries)) {
+        throw new Error("Invalid migration backup manifest envelope.");
+    }
+    const entries = [];
+    let previousPath;
+    for (const valueEntry of value.entries) {
+        if (!isRecord(valueEntry) || !hasExactKeys(valueEntry, ["originalPath", "backupPath", "sha256", "mode"]) ||
+            !safeOriginalPath(valueEntry.originalPath) || valueEntry.backupPath !== `files/${valueEntry.originalPath}` ||
+            typeof valueEntry.sha256 !== "string" || !sha256Pattern.test(valueEntry.sha256) ||
+            typeof valueEntry.mode !== "number" || !Number.isInteger(valueEntry.mode) || valueEntry.mode < 0 || valueEntry.mode > 0o777) {
+            throw new Error("Invalid path, backup mapping, SHA-256 digest, mode, or fields in migration backup manifest entry.");
+        }
+        if (previousPath !== undefined && compareStrings(previousPath, valueEntry.originalPath) >= 0) {
+            throw new Error("Migration backup manifest entries are not in strict canonical order.");
+        }
+        previousPath = valueEntry.originalPath;
+        entries.push({
+            originalPath: valueEntry.originalPath,
+            backupPath: valueEntry.backupPath,
+            sha256: valueEntry.sha256,
+            mode: valueEntry.mode,
+        });
+    }
+    const normalized = normalizeInputEntries(entries.map(({ originalPath, sha256, mode }) => ({ originalPath, sha256, mode })));
+    if (normalized.length !== entries.length)
+        throw new Error("Invalid migration backup manifest coverage.");
+    return { version: 1, entries };
+}
+export function parseMigrationBackupManifest(bytes) {
+    if (isProxyObject(bytes))
+        throw new Error("Proxy-backed migration backup manifest bytes are not accepted.");
+    if (!Buffer.isBuffer(bytes))
+        throw new Error("Migration backup manifest must be supplied as fixed bytes.");
+    let value;
+    try {
+        value = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new Error("Invalid JSON in migration backup manifest.");
+    }
+    const manifest = parseManifestObject(value);
+    const expectedBytes = serializeManifest(manifest.entries.map(({ originalPath, sha256, mode }) => ({ originalPath, sha256, mode })));
+    if (!bytes.equals(expectedBytes))
+        throw new Error("Migration backup manifest bytes are not in the fixed canonical encoding.");
+    return manifest;
+}
+function isDirectoryPath(value) {
+    return path.isAbsolute(value) && path.resolve(value) === value;
+}
+function isWithin(root, target) {
+    const relative = path.relative(root, target);
+    return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
+}
+function stableDirectoryState(target, stat) {
+    return {
+        path: target,
+        dev: stat.dev,
+        ino: stat.ino,
+        mode: stat.mode,
+        size: stat.size,
+        mtimeNs: stat.mtimeNs,
+        ctimeNs: stat.ctimeNs,
+    };
+}
+function sameDirectoryState(left, right) {
+    return left.path === right.path && left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+        left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+function directoryIdentity(state) {
+    return { path: state.path, dev: state.dev, ino: state.ino, mode: state.mode };
+}
+async function canonicalDirectoryChain(root) {
+    if (!isDirectoryPath(root))
+        throw new Error("Migration backup library root must be an absolute canonical path.");
+    const identities = [];
+    const rootName = path.parse(root).root;
+    let current = rootName;
+    const rootStat = await lstat(current, { bigint: true });
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || await realpath(current) !== current) {
+        throw new Error("Migration backup library root has an unsafe filesystem root.");
+    }
+    identities.push({ path: current, dev: rootStat.dev, ino: rootStat.ino, mode: rootStat.mode });
+    const segments = root.slice(rootName.length).split(path.sep).filter((segment) => segment.length > 0);
+    for (const segment of segments) {
+        current = path.join(current, segment);
+        const stat = await lstat(current, { bigint: true });
+        if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(current) !== current) {
+            throw new Error("Migration backup library root or an ancestor is not a canonical real directory.");
+        }
+        identities.push({ path: current, dev: stat.dev, ino: stat.ino, mode: stat.mode });
+    }
+    return identities;
+}
+async function assertDirectoryIdentities(states) {
+    for (const expected of states) {
+        const current = await lstat(expected.path, { bigint: true });
+        if (!current.isDirectory() || current.isSymbolicLink() || current.dev !== expected.dev || current.ino !== expected.ino ||
+            current.mode !== expected.mode || await realpath(expected.path) !== expected.path) {
+            throw new Error("Migration backup directory identity or canonical path changed during verification.");
+        }
+    }
+}
+async function checkedPrivateDirectory(target, libraryRoot, expectedMode) {
+    if (!isWithin(libraryRoot, target))
+        throw new Error("Migration backup directory escapes its canonical library root.");
+    const before = await lstat(target, { bigint: true });
+    if (!before.isDirectory() || before.isSymbolicLink() || (before.mode & 4095n) !== BigInt(expectedMode) || await realpath(target) !== target) {
+        throw new Error("Migration backup contains a noncanonical directory or one with the wrong private mode.");
+    }
+    return stableDirectoryState(target, before);
+}
+async function assertDirectoryUnchanged(expected) {
+    const [after, canonical] = await Promise.all([lstat(expected.path, { bigint: true }), realpath(expected.path)]);
+    if (!after.isDirectory() || after.isSymbolicLink() || canonical !== expected.path ||
+        !sameDirectoryState(expected, stableDirectoryState(expected.path, after))) {
+        throw new Error("Migration backup directory changed while it was being enumerated.");
+    }
+}
+function sameFileState(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs && left.mode === right.mode;
+}
+async function readPrivateFile(target, libraryRoot, expectedAncestors) {
+    const before = await lstat(target, { bigint: true });
+    if (!before.isFile() || before.isSymbolicLink() || (before.mode & 4095n) !== BigInt(privateFileMode) || await realpath(target) !== target ||
+        !isWithin(libraryRoot, target)) {
+        throw new Error("Migration backup contains a noncanonical, nonregular, or nonprivate file.");
+    }
+    const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const opened = await handle.stat({ bigint: true });
+        if (!opened.isFile() || !sameFileState(before, opened))
+            throw new Error("Migration backup file changed while it was opened.");
+        const bytes = await handle.readFile();
+        const [afterHandle, afterPath, canonicalAfter] = await Promise.all([
+            handle.stat({ bigint: true }),
+            lstat(target, { bigint: true }),
+            realpath(target),
+        ]);
+        if (!afterPath.isFile() || afterPath.isSymbolicLink() || canonicalAfter !== target ||
+            !sameFileState(opened, afterHandle) || !sameFileState(opened, afterPath)) {
+            throw new Error("Migration backup file identity, mode, or bytes changed while being read.");
+        }
+        await assertDirectoryIdentities(expectedAncestors);
+        return bytes;
+    }
+    finally {
+        await handle.close();
+    }
+}
+function expectedTree(manifest) {
+    const children = new Map();
+    const ensure = (directory) => {
+        let value = children.get(directory);
+        if (!value) {
+            value = { directories: new Set(), files: new Set() };
+            children.set(directory, value);
+        }
+        return value;
+    };
+    ensure(".");
+    ensure("files");
+    ensure(".").files.add(manifestName);
+    ensure(".").directories.add("files");
+    for (const entry of manifest.entries) {
+        const relative = entry.backupPath;
+        const parts = relative.split("/");
+        let current = "";
+        for (const part of parts.slice(0, -1)) {
+            const parent = current || ".";
+            current = current ? `${current}/${part}` : part;
+            ensure(parent).directories.add(part);
+            ensure(current);
+        }
+        ensure(current || ".").files.add(parts.at(-1));
+    }
+    return children;
+}
+export async function verifyMigrationBackup(expectedValue) {
+    const expected = snapshotOwnDataRecord(expectedValue, ["libraryRoot", "backupDir", "manifestBytes", "manifestSha256", "entries"]);
+    if (!expected || typeof expected.libraryRoot !== "string" || typeof expected.backupDir !== "string" ||
+        isProxyObject(expected.manifestBytes) || !Buffer.isBuffer(expected.manifestBytes) || typeof expected.manifestSha256 !== "string" ||
+        !sha256Pattern.test(expected.manifestSha256)) {
+        throw new Error("Invalid fixed migration backup verification expectation; Proxy objects and non-own-data fields are not accepted.");
+    }
+    const libraryRoot = expected.libraryRoot;
+    const backupDir = expected.backupDir;
+    if (!backupUuidPattern.test(backupDir) || path.posix.normalize(backupDir) !== backupDir) {
+        throw new Error("Migration backup directory must be the canonical relative .migration-backups UUID path.");
+    }
+    const manifestBytes = Buffer.from(expected.manifestBytes);
+    const manifestSha256 = expected.manifestSha256;
+    const inputEntries = normalizeInputEntries(expected.entries);
+    if (digest(manifestBytes) !== manifestSha256)
+        throw new Error("Fixed migration backup manifest bytes do not match their expected SHA-256.");
+    const expectedManifest = parseMigrationBackupManifest(manifestBytes);
+    if (!buildMigrationBackupManifest(inputEntries).equals(manifestBytes) ||
+        expectedManifest.entries.length !== inputEntries.length) {
+        throw new Error("Fixed migration backup manifest does not exactly cover the expected input entries.");
+    }
+    for (let index = 0; index < inputEntries.length; index += 1) {
+        const input = inputEntries[index];
+        const manifestEntry = expectedManifest.entries[index];
+        if (input.originalPath !== manifestEntry.originalPath || input.sha256 !== manifestEntry.sha256 || input.mode !== manifestEntry.mode) {
+            throw new Error("Fixed migration backup manifest entry differs from the expected input coverage.");
+        }
+    }
+    const rootIdentities = await canonicalDirectoryChain(libraryRoot);
+    const backupParent = path.join(libraryRoot, ".migration-backups");
+    const backupParentState = await checkedPrivateDirectory(backupParent, libraryRoot, privateDirectoryMode);
+    const backupRoot = path.join(libraryRoot, ...backupDir.split("/"));
+    const children = expectedTree(expectedManifest);
+    const expectedFileEntries = new Map();
+    for (const entry of expectedManifest.entries)
+        expectedFileEntries.set(entry.backupPath, entry);
+    const visit = async (relative, ancestors) => {
+        const target = relative === "." ? backupRoot : path.join(backupRoot, ...relative.split("/"));
+        const state = await checkedPrivateDirectory(target, libraryRoot, privateDirectoryMode);
+        const expectedChildren = children.get(relative);
+        if (!expectedChildren)
+            throw new Error("Unexpected directory in migration backup.");
+        const names = (await readdir(target)).sort(compareStrings);
+        const expectedNames = [...expectedChildren.directories, ...expectedChildren.files].sort(compareStrings);
+        if (names.length !== expectedNames.length || names.some((name, index) => name !== expectedNames[index])) {
+            throw new Error("Migration backup has missing or unknown extra filesystem entries.");
+        }
+        const currentAncestors = [...ancestors, directoryIdentity(state)];
+        for (const name of names) {
+            const childRelative = relative === "." ? name : `${relative}/${name}`;
+            if (expectedChildren.directories.has(name)) {
+                await visit(childRelative, currentAncestors);
+                continue;
+            }
+            const bytes = await readPrivateFile(path.join(target, name), libraryRoot, [...rootIdentities, ...currentAncestors]);
+            if (childRelative === manifestName) {
+                if (!bytes.equals(manifestBytes) || digest(bytes) !== manifestSha256) {
+                    throw new Error("Stored migration backup manifest differs from the fixed manifest bytes or hash.");
+                }
+                const parsed = parseMigrationBackupManifest(bytes);
+                if (parsed.entries.length !== expectedManifest.entries.length)
+                    throw new Error("Stored migration backup manifest coverage changed.");
+                continue;
+            }
+            const manifestEntry = expectedFileEntries.get(childRelative);
+            if (!manifestEntry || digest(bytes) !== manifestEntry.sha256) {
+                throw new Error("Migration backup data is missing its fixed entry or does not match the expected SHA-256.");
+            }
+        }
+        const finalNames = (await readdir(target)).sort(compareStrings);
+        await assertDirectoryUnchanged(state);
+        if (names.length !== finalNames.length || names.some((name, index) => name !== finalNames[index])) {
+            throw new Error("Migration backup directory entries changed during verification.");
+        }
+    };
+    await visit(".", [
+        ...rootIdentities,
+        directoryIdentity(backupParentState),
+    ]);
+    await assertDirectoryIdentities(rootIdentities);
+    await assertDirectoryUnchanged(backupParentState);
+}

package/dist/src/migration-inventory.d.ts

@@ -0,0 +1,9 @@
+import type { MigrationStartInventory } from "./storage-journal.ts";
+export interface MigrationInventoryScanOptions {
+    readonly excludedPrefixes?: readonly string[];
+    readonly rootScope?: "library" | "subtree";
+}
+export declare function isManagedMigrationRootName(name: string): boolean;
+export declare function listManagedMigrationRootEntries(root: string): Promise<string[]>;
+export declare function projectMigrationInventory(inventory: MigrationStartInventory, excludedPrefixes: readonly string[], omittedProofPaths?: readonly string[]): MigrationStartInventory;
+export declare function scanMigrationInventory(libraryDir: string, options?: MigrationInventoryScanOptions): Promise<MigrationStartInventory>;

package/dist/src/migration-inventory.js

@@ -0,0 +1,237 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+const compareUtf8 = (left, right) => Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        const record = value;
+        const keys = Object.keys(record).sort(compareUtf8);
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+    }
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        throw new Error("Migration inventory contains a non-JSON value.");
+    return encoded;
+}
+function sameNodeState(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode && left.size === right.size &&
+        left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+function fileMode(stat) {
+    return Number(stat.mode & 4095n);
+}
+function decodeName(name) {
+    let decoded;
+    try {
+        decoded = new TextDecoder("utf-8", { fatal: true }).decode(name);
+    }
+    catch {
+        throw new Error("Migration inventory encountered a non-UTF-8 filesystem name; refusing to omit it.");
+    }
+    if (!decoded || decoded === "." || decoded === ".." || decoded.includes("/") || decoded.includes("\\") ||
+        decoded.includes("\0") || !Buffer.from(decoded, "utf8").equals(name)) {
+        throw new Error("Migration inventory encountered a noncanonical filesystem name.");
+    }
+    return decoded;
+}
+const managedRootNames = new Set([
+    "catalog.json", "items", "sources", ".migration-backups", ".copi-transaction", ".copi-transaction-recovery",
+]);
+const resolutionPrefixBytes = Buffer.from(".copi-migration-resolution", "ascii");
+function managedRootName(raw) {
+    if (!raw.subarray(0, resolutionPrefixBytes.length).equals(resolutionPrefixBytes)) {
+        const exact = [...managedRootNames].find((name) => raw.equals(Buffer.from(name, "ascii")));
+        if (!exact)
+            return undefined;
+    }
+    return decodeName(raw);
+}
+export function isManagedMigrationRootName(name) {
+    if (typeof name !== "string" || !name || name.includes("/") || name.includes("\\") || name.includes("\0"))
+        return false;
+    if (managedRootNames.has(name) || name.startsWith(".copi-migration-resolution"))
+        return true;
+    return false;
+}
+export async function listManagedMigrationRootEntries(root) {
+    if (typeof root !== "string" || !path.isAbsolute(root) || path.resolve(root) !== root || await realpath(root) !== root) {
+        throw new Error("Managed migration root listing requires a canonical absolute library root.");
+    }
+    const names = await readdir(root, { encoding: "buffer" });
+    return names.map(managedRootName).filter((name) => name !== undefined).sort(compareUtf8);
+}
+function sameRootState(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+        left.isDirectory() && right.isDirectory() && !left.isSymbolicLink() && !right.isSymbolicLink();
+}
+function selectedNames(rawNames, relative, rootScope, excludedPrefixes) {
+    const selected = [];
+    for (const raw of rawNames) {
+        const name = relative === "." && rootScope === "library" ? managedRootName(raw) : decodeName(raw);
+        if (name === undefined)
+            continue;
+        const childPath = relative === "." ? name : `${relative}/${name}`;
+        if (excludedPrefixes.some((prefix) => childPath === prefix || childPath.startsWith(`${prefix}/`)))
+            continue;
+        selected.push({ raw, name });
+    }
+    selected.sort((left, right) => Buffer.compare(left.raw, right.raw));
+    return selected;
+}
+async function scanOnce(root, excludedPrefixes, rootScope) {
+    const rootBefore = await lstat(root, { bigint: true });
+    if (!rootBefore.isDirectory() || rootBefore.isSymbolicLink() || await realpath(root) !== root) {
+        throw new Error("Migration inventory root must be a canonical real directory.");
+    }
+    const nodes = new Map();
+    const transient = [];
+    const visit = async (absolute, relative, expected) => {
+        const before = await lstat(absolute, { bigint: true });
+        if (before.isSymbolicLink())
+            throw new Error(`Migration inventory encountered a symbolic link: ${relative}`);
+        if (expected && !(relative === "." ? sameRootState(expected, before) : sameNodeState(expected, before))) {
+            throw new Error(`Migration inventory directory changed while scanning: ${relative}`);
+        }
+        const kind = before.isDirectory() ? "directory" : before.isFile() ? "file" : undefined;
+        if (!kind)
+            throw new Error(`Migration inventory encountered a special filesystem node: ${relative}`);
+        if (await realpath(absolute) !== absolute)
+            throw new Error(`Migration inventory path is not canonical: ${relative}`);
+        const base = { path: relative, kind, mode: fileMode(before), dev: before.dev.toString(), ino: before.ino.toString() };
+        transient.push(relative === "."
+            ? `${relative}:${before.dev}:${before.ino}:${before.mode}`
+            : `${relative}:${before.size}:${before.mtimeNs}:${before.ctimeNs}`);
+        if (kind === "file") {
+            const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const opened = await handle.stat({ bigint: true });
+                if (!opened.isFile() || !sameNodeState(before, opened))
+                    throw new Error(`Migration inventory file changed while opening: ${relative}`);
+                const bytes = await handle.readFile();
+                const [afterHandle, afterPath, canonical] = await Promise.all([
+                    handle.stat({ bigint: true }), lstat(absolute, { bigint: true }), realpath(absolute),
+                ]);
+                if (!afterPath.isFile() || afterPath.isSymbolicLink() || canonical !== absolute ||
+                    !sameNodeState(opened, afterHandle) || !sameNodeState(opened, afterPath)) {
+                    throw new Error(`Migration inventory file changed while reading: ${relative}`);
+                }
+                nodes.set(relative, { ...base, bytesHash: sha256(bytes) });
+            }
+            finally {
+                await handle.close();
+            }
+            return;
+        }
+        const beforeNames = selectedNames(await readdir(absolute, { encoding: "buffer" }), relative, rootScope, excludedPrefixes);
+        if (beforeNames.some((entry, index) => index > 0 && Buffer.compare(beforeNames[index - 1].raw, entry.raw) === 0)) {
+            throw new Error(`Migration inventory encountered duplicate directory names: ${relative}`);
+        }
+        const children = [];
+        for (const entry of beforeNames) {
+            const childPath = relative === "." ? entry.name : `${relative}/${entry.name}`;
+            const childAbsolute = path.join(absolute, entry.name);
+            const childStat = await lstat(childAbsolute, { bigint: true });
+            if (childStat.isSymbolicLink())
+                throw new Error(`Migration inventory encountered a symbolic link: ${childPath}`);
+            const childKind = childStat.isDirectory() ? "directory" : childStat.isFile() ? "file" : undefined;
+            if (!childKind)
+                throw new Error(`Migration inventory encountered a special filesystem node: ${childPath}`);
+            children.push({ name: entry.name, kind: childKind });
+            await visit(childAbsolute, childPath, childStat);
+        }
+        const [after, rawAfterNames, canonical] = await Promise.all([
+            lstat(absolute, { bigint: true }), readdir(absolute, { encoding: "buffer" }), realpath(absolute),
+        ]);
+        const afterNames = selectedNames(rawAfterNames, relative, rootScope, excludedPrefixes);
+        const directoryStateMatches = relative === "." ? sameRootState(before, after) : sameNodeState(before, after);
+        if (!directoryStateMatches || canonical !== absolute || afterNames.length !== beforeNames.length ||
+            beforeNames.some((entry, index) => !entry.raw.equals(afterNames[index].raw))) {
+            throw new Error(`Migration inventory directory changed while scanning: ${relative}`);
+        }
+        nodes.set(relative, { ...base, children });
+    };
+    await visit(root, ".", rootBefore);
+    const rootAfter = await lstat(root, { bigint: true });
+    if (!sameRootState(rootBefore, rootAfter) || await realpath(root) !== root) {
+        throw new Error("Migration library root changed while capturing its inventory.");
+    }
+    const identities = new Set();
+    const inventoryNodes = [];
+    for (const node of [...nodes.values()].sort((left, right) => compareUtf8(left.path, right.path))) {
+        const identity = `${node.dev}:${node.ino}`;
+        if (identities.has(identity))
+            throw new Error(`Migration inventory contains an unsafe hardlink alias: ${node.path}`);
+        identities.add(identity);
+        const bytesHash = node.kind === "file"
+            ? node.bytesHash
+            : sha256(Buffer.concat([
+                Buffer.from("copi-directory-v1\0", "utf8"),
+                Buffer.from(canonicalJson((node.children ?? []).map(({ name, kind }) => [name, kind])), "utf8"),
+            ]));
+        inventoryNodes.push({ path: node.path, kind: node.kind, mode: node.mode, dev: node.dev, ino: node.ino, bytesHash });
+    }
+    const inventory = {
+        version: 1,
+        nodes: inventoryNodes,
+        hash: sha256(Buffer.concat([
+            Buffer.from("copi-inventory-v1\0", "utf8"),
+            Buffer.from(canonicalJson(inventoryNodes), "utf8"),
+        ])),
+    };
+    return { inventory, transientState: transient.sort(compareUtf8).join("\n") };
+}
+export function projectMigrationInventory(inventory, excludedPrefixes, omittedProofPaths = []) {
+    const excluded = (nodePath) => excludedPrefixes.some((prefix) => nodePath === prefix || nodePath.startsWith(`${prefix}/`));
+    const proofOmissions = new Set(omittedProofPaths);
+    const allNodes = inventory.nodes.filter((node) => !excluded(node.path));
+    const nodes = allNodes.filter((node) => !proofOmissions.has(node.path)).map((node) => {
+        if (node.kind !== "directory")
+            return { ...node };
+        // Omitted proofs are absent from the projected namespace, including the directory child-list commitment.
+        const children = allNodes.filter((candidate) => candidate.path !== node.path && !proofOmissions.has(candidate.path) &&
+            path.posix.dirname(candidate.path) === node.path)
+            .map((candidate) => [path.posix.basename(candidate.path), candidate.kind])
+            .sort(([left], [right]) => compareUtf8(left, right));
+        return {
+            ...node,
+            bytesHash: sha256(Buffer.concat([
+                Buffer.from("copi-directory-v1\0", "utf8"),
+                Buffer.from(canonicalJson(children), "utf8"),
+            ])),
+        };
+    });
+    return {
+        version: 1,
+        nodes,
+        hash: sha256(Buffer.concat([
+            Buffer.from("copi-inventory-v1\0", "utf8"),
+            Buffer.from(canonicalJson(nodes), "utf8"),
+        ])),
+    };
+}
+export async function scanMigrationInventory(libraryDir, options = {}) {
+    if (typeof libraryDir !== "string" || !path.isAbsolute(libraryDir) || path.resolve(libraryDir) !== libraryDir ||
+        await realpath(libraryDir) !== libraryDir) {
+        throw new Error("Migration inventory requires a canonical absolute library root.");
+    }
+    const excludedPrefixes = options.excludedPrefixes ?? [];
+    const rootScope = options.rootScope ?? "library";
+    if (rootScope !== "library" && rootScope !== "subtree")
+        throw new Error("Migration inventory root scope must be library or subtree.");
+    if (!Array.isArray(excludedPrefixes) || excludedPrefixes.some((prefix) => typeof prefix !== "string" ||
+        !prefix || prefix.startsWith("/") || prefix.includes("\\") || prefix.includes("\0") ||
+        prefix.split("/").some((part) => part === "" || part === "." || part === ".."))) {
+        throw new Error("Migration inventory exclusion prefixes must be canonical library-relative paths.");
+    }
+    const first = await scanOnce(libraryDir, excludedPrefixes, rootScope);
+    const second = await scanOnce(libraryDir, excludedPrefixes, rootScope);
+    if (first.inventory.hash !== second.inventory.hash || first.transientState !== second.transientState ||
+        canonicalJson(first.inventory.nodes) !== canonicalJson(second.inventory.nodes)) {
+        throw new Error("Migration inventory changed between the required complete scans.");
+    }
+    return structuredClone(first.inventory);
+}