@papillon6814/copi 0.1.0 → 0.2.1

package/dist/src/storage-journal.js

@@ -0,0 +1,613 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { types as utilTypes } from "node:util";
+const itemPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const lowercaseUuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const sha256Pattern = /^[0-9a-f]{64}$/;
+const excludedNames = new Set([
+    ".git", ".cache", ".npm", "auth", "node_modules", "cache", "caches", "history", "sessions",
+    "auth.json", "mcp-auth.json", "oauth.json",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+    const ownKeys = Object.keys(value);
+    return ownKeys.length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+function isSha256(value) {
+    return typeof value === "string" && sha256Pattern.test(value);
+}
+function isOptionalSha256(value) {
+    return value === null || isSha256(value);
+}
+function isStableSourcesCommitment(value) {
+    return value === "absent" || isSha256(value);
+}
+function isStableItemsCommitment(value) {
+    return value === "absent" || isSha256(value);
+}
+function isMigrationBackupDir(value) {
+    if (typeof value !== "string" || path.posix.normalize(value) !== value)
+        return false;
+    const parts = value.split("/");
+    return parts.length === 2 && parts[0] === ".migration-backups" &&
+        /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(parts[1]);
+}
+function isUint64Decimal(value) {
+    if (typeof value !== "string" || !/^(?:0|[1-9][0-9]*)$/.test(value))
+        return false;
+    try {
+        return BigInt(value) <= 18446744073709551615n;
+    }
+    catch {
+        return false;
+    }
+}
+function isSafeSourcesTarget(value) {
+    if (!value || value.includes("\\") || value.includes("\0") || path.posix.isAbsolute(value))
+        return false;
+    const parts = value.split("/");
+    if (parts.length < 2 || parts[0] !== "sources" || parts.some((part) => part === "" || part === "." || part === ".."))
+        return false;
+    if (path.posix.normalize(value) !== value)
+        return false;
+    return !parts.slice(1).some((part) => {
+        const lower = part.toLowerCase();
+        return excludedNames.has(lower) || lower === ".env" || lower.startsWith(".env");
+    });
+}
+function assertCommonJournal(value, expected) {
+    if (typeof expected.root !== "string" || typeof expected.token !== "string" ||
+        typeof value.root !== "string" || value.root !== expected.root ||
+        typeof value.token !== "string" || value.token !== expected.token ||
+        !isOptionalSha256(value.oldCatalog) || !isSha256(value.newCatalog) || !Array.isArray(value.operations)) {
+        throw new Error("Invalid storage journal envelope or root/token/catalog commitment.");
+    }
+}
+function assertItemId(value) {
+    if (typeof value !== "string" || !itemPattern.test(value))
+        throw new Error("Invalid storage journal item UUID.");
+}
+function assertUniqueItemIds(ids) {
+    if (new Set(ids).size !== ids.length)
+        throw new Error("Duplicate item UUID in storage journal.");
+}
+function assertNoTargetOverlap(targets) {
+    for (let index = 0; index < targets.length; index += 1) {
+        const left = targets[index];
+        for (const right of targets.slice(index + 1)) {
+            if (left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)) {
+                throw new Error("Duplicate or overlapping sources targets in storage journal.");
+            }
+        }
+    }
+}
+function hasStrictExactKeys(value, keys) {
+    if (utilTypes.isProxy(value))
+        return false;
+    try {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return false;
+        const ownKeys = Reflect.ownKeys(value);
+        if (ownKeys.length !== keys.length || ownKeys.some((key) => typeof key !== "string" || !keys.includes(key)))
+            return false;
+        return keys.every((key) => {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            return descriptor !== undefined && Object.hasOwn(descriptor, "value") && descriptor.enumerable === true;
+        });
+    }
+    catch {
+        return false;
+    }
+}
+function isStrictDenseArray(value) {
+    if (utilTypes.isProxy(value) || !Array.isArray(value))
+        return false;
+    try {
+        const ownKeys = Reflect.ownKeys(value);
+        const length = Object.getOwnPropertyDescriptor(value, "length");
+        if (!length || !Object.hasOwn(length, "value") || length.enumerable !== false ||
+            typeof length.value !== "number" || !Number.isSafeInteger(length.value) || length.value < 0 ||
+            ownKeys.length !== length.value + 1)
+            return false;
+        for (let index = 0; index < length.value; index += 1) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (!descriptor || !Object.hasOwn(descriptor, "value") || descriptor.enumerable !== true)
+                return false;
+        }
+        return ownKeys.every((key) => key === "length" || typeof key === "string" &&
+            Number.isSafeInteger(Number(key)) && String(Number(key)) === key && Number(key) >= 0 && Number(key) < length.value);
+    }
+    catch {
+        return false;
+    }
+}
+function isCanonicalRelativePath(value) {
+    if (typeof value !== "string" || value.includes("\\") || value.includes("\0") || path.posix.isAbsolute(value) ||
+        Buffer.from(value, "utf8").toString("utf8") !== value)
+        return false;
+    if (value === ".")
+        return true;
+    return value.length > 0 && path.posix.normalize(value) === value &&
+        value.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (isRecord(value)) {
+        const keys = Object.keys(value).sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+    }
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        throw new Error("V5 canonical JSON cannot encode an undefined value.");
+    return encoded;
+}
+export function canonicalStorageJournalJson(value) {
+    return canonicalJson(value);
+}
+function inventoryHash(nodes) {
+    return createHash("sha256").update("copi-inventory-v1\0", "utf8").update(canonicalJson(nodes), "utf8").digest("hex");
+}
+function validateStartInventory(value) {
+    if (!isRecord(value) || !hasStrictExactKeys(value, ["version", "nodes", "hash"]) || value.version !== 1 ||
+        !isStrictDenseArray(value.nodes) || !isSha256(value.hash)) {
+        throw new Error("Invalid v5 start inventory envelope.");
+    }
+    const nodes = [];
+    const seenPaths = new Set();
+    const seenIdentities = new Set();
+    let previousPath;
+    for (const node of value.nodes) {
+        if (!isRecord(node) || !hasStrictExactKeys(node, ["path", "kind", "mode", "dev", "ino", "bytesHash"]) ||
+            !isCanonicalRelativePath(node.path) || (node.kind !== "file" && node.kind !== "directory") ||
+            typeof node.mode !== "number" || !Number.isInteger(node.mode) || node.mode < 0 || node.mode > 0o7777 ||
+            !isUint64Decimal(node.dev) || !isUint64Decimal(node.ino) || !isSha256(node.bytesHash)) {
+            throw new Error("Invalid v5 inventory node.");
+        }
+        if (previousPath !== undefined && Buffer.compare(Buffer.from(previousPath), Buffer.from(node.path)) >= 0) {
+            throw new Error("V5 inventory nodes must be uniquely ordered by UTF-8 path bytes.");
+        }
+        if (seenPaths.has(node.path))
+            throw new Error("Duplicate path in v5 start inventory.");
+        const identity = `${node.dev}:${node.ino}`;
+        if (seenIdentities.has(identity))
+            throw new Error("V5 start inventory contains an unsafe hardlink alias.");
+        seenPaths.add(node.path);
+        seenIdentities.add(identity);
+        previousPath = node.path;
+        nodes.push({ path: node.path, kind: node.kind, mode: node.mode, dev: node.dev, ino: node.ino, bytesHash: node.bytesHash });
+    }
+    const byPath = new Map(nodes.map((node) => [node.path, node]));
+    const rootNode = byPath.get(".");
+    if (!rootNode || rootNode.kind !== "directory")
+        throw new Error("V5 start inventory must include its root directory.");
+    const children = new Map();
+    for (const node of nodes) {
+        if (node.path === ".")
+            continue;
+        const parent = path.posix.dirname(node.path);
+        const parentNode = byPath.get(parent);
+        if (!parentNode || parentNode.kind !== "directory")
+            throw new Error("V5 inventory node has no recorded directory parent.");
+        const list = children.get(parent) ?? [];
+        list.push([path.posix.basename(node.path), node.kind]);
+        children.set(parent, list);
+    }
+    for (const node of nodes) {
+        if (node.kind !== "directory")
+            continue;
+        const listing = children.get(node.path) ?? [];
+        listing.sort(([left], [right]) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+        const expectedHash = createHash("sha256").update("copi-directory-v1\0", "utf8")
+            .update(canonicalJson(listing), "utf8").digest("hex");
+        if (node.bytesHash !== expectedHash)
+            throw new Error(`V5 directory listing commitment is invalid for ${node.path}.`);
+    }
+    if (value.hash !== inventoryHash(nodes))
+        throw new Error("V5 start inventory hash does not match its canonical nodes.");
+    return { version: 1, nodes, hash: value.hash };
+}
+export function parseMigrationStartInventory(value) {
+    return validateStartInventory(value);
+}
+function parseLegacyMigrationJournalV5(value, expected) {
+    const keys = [
+        "version", "mode", "root", "token", "oldCatalog", "newCatalog", "stableItemsTree", "stableSourcesTree",
+        "stableSourcesTreeNext", "backupDir", "backupManifest", "operations", "ownedDirectories", "startInventory",
+    ];
+    if (!hasStrictExactKeys(value, keys) || value.mode !== "legacy-migration" || !isStrictDenseArray(value.operations) ||
+        value.operations.length !== 0 || !isStrictDenseArray(value.ownedDirectories) || value.ownedDirectories.length !== 0) {
+        throw new Error("Invalid v5 adopt-only legacy-migration journal object.");
+    }
+    assertCommonJournal(value, expected);
+    if (value.oldCatalog === null || !lowercaseUuidPattern.test(value.token) ||
+        !isStableItemsCommitment(value.stableItemsTree) || !isStableSourcesCommitment(value.stableSourcesTree) ||
+        value.stableSourcesTreeNext !== value.stableSourcesTree || !isMigrationBackupDir(value.backupDir) ||
+        !isSha256(value.backupManifest) || !path.isAbsolute(value.root) || path.resolve(value.root) !== value.root) {
+        throw new Error("Invalid v5 catalog, root, token, tree, or backup commitment.");
+    }
+    const startInventory = validateStartInventory(value.startInventory);
+    const catalog = startInventory.nodes.find((node) => node.path === "catalog.json");
+    if (!catalog || catalog.kind !== "file" || catalog.bytesHash !== value.oldCatalog) {
+        throw new Error("V5 start inventory catalog proof does not match the old catalog commitment.");
+    }
+    return {
+        version: 5,
+        mode: "legacy-migration",
+        root: value.root,
+        token: value.token,
+        oldCatalog: value.oldCatalog,
+        newCatalog: value.newCatalog,
+        stableItemsTree: value.stableItemsTree,
+        stableSourcesTree: value.stableSourcesTree,
+        stableSourcesTreeNext: value.stableSourcesTreeNext,
+        backupDir: value.backupDir,
+        backupManifest: value.backupManifest,
+        operations: [],
+        ownedDirectories: [],
+        startInventory,
+    };
+}
+function parseLegacyMigrationJournal(value, expected) {
+    const hasNextSourcesTree = Object.hasOwn(value, "nextSourcesTree");
+    const requiredKeys = [
+        "version", "mode", "root", "token", "oldCatalog", "newCatalog", "stableItemsTree", "stableSourcesTree",
+        "stableSourcesTreeNext", "backupDir", "backupManifest", "operations", "ownedDirectories",
+    ];
+    if (!hasExactKeys(value, hasNextSourcesTree ? [...requiredKeys, "nextSourcesTree"] : requiredKeys) ||
+        value.mode !== "legacy-migration" || !Array.isArray(value.ownedDirectories)) {
+        throw new Error("Invalid legacy-migration v4 storage journal object.");
+    }
+    assertCommonJournal(value, expected);
+    if (value.oldCatalog === null || !isStableItemsCommitment(value.stableItemsTree) ||
+        !isStableSourcesCommitment(value.stableSourcesTree) || !isStableSourcesCommitment(value.stableSourcesTreeNext) ||
+        !isMigrationBackupDir(value.backupDir) || !isSha256(value.backupManifest)) {
+        throw new Error("Invalid v4 catalog, tree, backup directory, or manifest commitment.");
+    }
+    if (!path.isAbsolute(expected.root) || path.resolve(expected.root) !== expected.root ||
+        !path.isAbsolute(value.root) || path.resolve(value.root) !== value.root) {
+        throw new Error("V4 storage journal root must be canonical and absolute.");
+    }
+    const operations = [];
+    for (const operation of value.operations) {
+        if (!isRecord(operation) || !hasExactKeys(operation, ["itemId", "target", "kind", "oldTree", "newTree"])) {
+            throw new Error("Invalid legacy-migration v4 operation.");
+        }
+        assertItemId(operation.itemId);
+        if (typeof operation.target !== "string" || !isSafeSourcesTarget(operation.target) ||
+            (operation.kind !== "file" && operation.kind !== "tree") || operation.oldTree !== null || !isSha256(operation.newTree)) {
+            throw new Error("V4 migration operations must add only safe sources targets with null old-tree commitments.");
+        }
+        operations.push({ itemId: operation.itemId, target: operation.target, kind: operation.kind, oldTree: null, newTree: operation.newTree });
+    }
+    assertUniqueItemIds(operations.map((operation) => operation.itemId));
+    assertNoTargetOverlap(operations.map((operation) => operation.target));
+    if (operations.length > 0 && value.stableItemsTree === "absent") {
+        throw new Error("V4 source additions require the fixed legacy items tree commitment.");
+    }
+    const ownedDirectories = [];
+    const ownedPaths = new Set();
+    const ownedIdentities = new Set();
+    for (const entry of value.ownedDirectories) {
+        if (!isRecord(entry) || !hasExactKeys(entry, ["path", "stage", "dev", "ino"]) ||
+            typeof entry.path !== "string" || (entry.path !== "sources" && !/^sources\/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(entry.path)) ||
+            typeof entry.stage !== "string" || !/^next-(?:sources|(?:0|[1-9][0-9]*))$/.test(entry.stage) ||
+            !isUint64Decimal(entry.dev) || !isUint64Decimal(entry.ino) || ownedPaths.has(entry.path)) {
+            throw new Error("Invalid or duplicate v4 owned source directory identity.");
+        }
+        const identity = `${entry.dev}:${entry.ino}`;
+        if (ownedIdentities.has(identity))
+            throw new Error("V4 owned source directories must have distinct recorded identities.");
+        ownedPaths.add(entry.path);
+        ownedIdentities.add(identity);
+        ownedDirectories.push({ path: entry.path, stage: entry.stage, dev: entry.dev, ino: entry.ino });
+    }
+    const beforeSources = value.stableSourcesTree;
+    const afterSources = value.stableSourcesTreeNext;
+    const hasNextSourcesTreeValue = isSha256(value.nextSourcesTree);
+    if (operations.length === 0) {
+        if (afterSources !== beforeSources || ownedDirectories.length !== 0 || hasNextSourcesTree) {
+            throw new Error("An adopt-only v4 journal must preserve the sources tree and contain no staged ownership.");
+        }
+    }
+    else {
+        if (afterSources === "absent" || afterSources === beforeSources ||
+            (beforeSources === "absent" ? !hasNextSourcesTree || !hasNextSourcesTreeValue : hasNextSourcesTree)) {
+            throw new Error("V4 new-source operations require changed after-state and exact absent-root stage metadata.");
+        }
+        const expectedOwned = new Map();
+        if (beforeSources === "absent")
+            expectedOwned.set("sources", "next-sources");
+        for (const [index, operation] of operations.entries()) {
+            if (operation.kind !== "file")
+                continue;
+            expectedOwned.set(`sources/${operation.itemId}`, beforeSources === "absent" ? "next-sources" : `next-${index}`);
+        }
+        if (ownedDirectories.length !== expectedOwned.size ||
+            ownedDirectories.some((directory) => expectedOwned.get(directory.path) !== directory.stage)) {
+            throw new Error("V4 new-source operations are missing exact root or new-file-parent stage custody.");
+        }
+    }
+    return {
+        version: 4,
+        mode: "legacy-migration",
+        root: value.root,
+        token: value.token,
+        oldCatalog: value.oldCatalog,
+        newCatalog: value.newCatalog,
+        stableItemsTree: value.stableItemsTree,
+        stableSourcesTree: value.stableSourcesTree,
+        stableSourcesTreeNext: value.stableSourcesTreeNext,
+        backupDir: value.backupDir,
+        backupManifest: value.backupManifest,
+        operations,
+        ownedDirectories,
+        ...(hasNextSourcesTree ? { nextSourcesTree: value.nextSourcesTree } : {}),
+    };
+}
+export function parseStorageJournal(value, expected) {
+    if (!isRecord(value) ||
+        (value.version !== 1 && value.version !== 2 && value.version !== 3 && value.version !== 4 && value.version !== 5)) {
+        throw new Error("Unsupported or invalid storage journal version.");
+    }
+    if (value.version === 5)
+        return parseLegacyMigrationJournalV5(value, expected);
+    if (value.version === 4)
+        return parseLegacyMigrationJournal(value, expected);
+    if (value.version === 3) {
+        const catalogOnlyKeys = [
+            "version", "mode", "root", "token", "oldCatalog", "newCatalog", "stableSourcesTree", "operations",
+        ];
+        if (!hasExactKeys(value, catalogOnlyKeys) || value.mode !== "catalog-only") {
+            throw new Error("Invalid catalog-only v3 storage journal object.");
+        }
+        assertCommonJournal(value, expected);
+        if (!isStableSourcesCommitment(value.stableSourcesTree) || value.operations.length !== 0) {
+            throw new Error("Invalid catalog-only v3 tree commitment or operations.");
+        }
+        return {
+            version: 3,
+            mode: "catalog-only",
+            root: value.root,
+            token: value.token,
+            oldCatalog: value.oldCatalog,
+            newCatalog: value.newCatalog,
+            stableSourcesTree: value.stableSourcesTree,
+            operations: [],
+        };
+    }
+    const commonKeys = ["version", "root", "token", "oldCatalog", "newCatalog", "operations"];
+    const hasAdditionMetadata = Object.hasOwn(value, "stableSourcesTreeNext") || Object.hasOwn(value, "nextSourcesTree") || Object.hasOwn(value, "ownedDirectories");
+    const completeAdditionMetadata = ["stableSourcesTreeNext", "nextSourcesTree", "ownedDirectories"].every((key) => Object.hasOwn(value, key));
+    const expectedKeys = value.version === 1 ? commonKeys : [...commonKeys, "stableSourcesTree", ...(hasAdditionMetadata ? ["stableSourcesTreeNext", "nextSourcesTree", "ownedDirectories"] : [])];
+    if (!hasExactKeys(value, expectedKeys) || (hasAdditionMetadata && !completeAdditionMetadata))
+        throw new Error("Invalid storage journal object.");
+    assertCommonJournal(value, expected);
+    if (value.version === 1) {
+        const operations = [];
+        for (const valueOperation of value.operations) {
+            if (!isRecord(valueOperation) || !hasExactKeys(valueOperation, ["itemId", "oldTree", "newTree"])) {
+                throw new Error("Invalid legacy storage journal operation.");
+            }
+            assertItemId(valueOperation.itemId);
+            if (!isOptionalSha256(valueOperation.oldTree) || !isSha256(valueOperation.newTree)) {
+                throw new Error("Invalid legacy storage journal tree commitment.");
+            }
+            operations.push({ itemId: valueOperation.itemId, oldTree: valueOperation.oldTree, newTree: valueOperation.newTree });
+        }
+        assertUniqueItemIds(operations.map((operation) => operation.itemId));
+        return {
+            version: 1,
+            root: value.root,
+            token: value.token,
+            oldCatalog: value.oldCatalog,
+            newCatalog: value.newCatalog,
+            operations,
+        };
+    }
+    if (!isStableSourcesCommitment(value.stableSourcesTree))
+        throw new Error("Invalid stable sources tree commitment in v2 storage journal.");
+    const operations = [];
+    for (const valueOperation of value.operations) {
+        if (!isRecord(valueOperation) || !hasExactKeys(valueOperation, ["itemId", "target", "kind", "oldTree", "newTree"])) {
+            throw new Error("Invalid sources storage journal operation.");
+        }
+        assertItemId(valueOperation.itemId);
+        if (typeof valueOperation.target !== "string" || !isSafeSourcesTarget(valueOperation.target) ||
+            (valueOperation.kind !== "file" && valueOperation.kind !== "tree") ||
+            !isOptionalSha256(valueOperation.oldTree) || !isSha256(valueOperation.newTree)) {
+            throw new Error("Invalid sources storage journal target, kind, or tree commitment.");
+        }
+        operations.push({
+            itemId: valueOperation.itemId,
+            target: valueOperation.target,
+            kind: valueOperation.kind,
+            oldTree: valueOperation.oldTree,
+            newTree: valueOperation.newTree,
+        });
+    }
+    assertUniqueItemIds(operations.map((operation) => operation.itemId));
+    assertNoTargetOverlap(operations.map((operation) => operation.target));
+    const hasNewTargets = operations.some((operation) => operation.oldTree === null);
+    if (hasAdditionMetadata !== hasNewTargets) {
+        throw new Error("V2 new-target journal metadata does not match its operations.");
+    }
+    if (!hasAdditionMetadata) {
+        if (value.stableSourcesTree === "absent")
+            throw new Error("Legacy v2 journal cannot start from an absent sources root.");
+        return {
+            version: 2,
+            root: value.root,
+            token: value.token,
+            oldCatalog: value.oldCatalog,
+            newCatalog: value.newCatalog,
+            stableSourcesTree: value.stableSourcesTree,
+            operations,
+        };
+    }
+    if (!isSha256(value.stableSourcesTreeNext) || !isSha256(value.nextSourcesTree) || !Array.isArray(value.ownedDirectories)) {
+        throw new Error("Invalid v2 new-target tree or directory ownership commitment.");
+    }
+    const ownedDirectories = [];
+    const ownedPaths = new Set();
+    for (const entry of value.ownedDirectories) {
+        if (!isRecord(entry) || !hasExactKeys(entry, ["path", "stage", "dev", "ino"]) ||
+            typeof entry.path !== "string" || (entry.path !== "sources" && !isSafeSourcesTarget(entry.path)) ||
+            typeof entry.stage !== "string" || !/^next-(?:sources|(?:0|[1-9][0-9]*))$/.test(entry.stage) ||
+            typeof entry.dev !== "number" || !Number.isSafeInteger(entry.dev) || entry.dev < 0 ||
+            typeof entry.ino !== "number" || !Number.isSafeInteger(entry.ino) || entry.ino < 0 || ownedPaths.has(entry.path)) {
+            throw new Error("Invalid or duplicate v2 owned source directory identity.");
+        }
+        const stageIndex = entry.stage === "next-sources" ? undefined : Number(entry.stage.slice("next-".length));
+        if (entry.path === "sources") {
+            if (entry.stage !== "next-sources" || value.stableSourcesTree !== "absent")
+                throw new Error("New sources root ownership must come from its private stage when the root was absent.");
+        }
+        else {
+            const match = /^sources\/([0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i.exec(entry.path);
+            const operationIndex = match ? operations.findIndex((operation) => operation.itemId === match[1]) : -1;
+            const operation = operations[operationIndex];
+            if (!match || !operation || operation.oldTree !== null || operation.kind !== "file" ||
+                (entry.stage !== "next-sources" && (stageIndex !== operationIndex || entry.stage !== `next-${operationIndex}`))) {
+                throw new Error("Owned source directory is not bound to a new file item operation.");
+            }
+        }
+        ownedPaths.add(entry.path);
+        ownedDirectories.push({ path: entry.path, stage: entry.stage, dev: entry.dev, ino: entry.ino });
+    }
+    if (value.stableSourcesTree === "absent" && !ownedPaths.has("sources")) {
+        throw new Error("Absent v2 sources root has no recorded private creation stage.");
+    }
+    for (const [index, operation] of operations.entries()) {
+        if (operation.kind !== "file" || operation.oldTree !== null)
+            continue;
+        const parent = ownedDirectories.find((directory) => directory.path === `sources/${operation.itemId}`);
+        const expectedStage = value.stableSourcesTree === "absent" ? "next-sources" : `next-${index}`;
+        if (!parent || parent.stage !== expectedStage)
+            throw new Error("New file operation is missing its exact private parent-directory custody record.");
+    }
+    return {
+        version: 2,
+        root: value.root,
+        token: value.token,
+        oldCatalog: value.oldCatalog,
+        newCatalog: value.newCatalog,
+        stableSourcesTree: value.stableSourcesTree,
+        stableSourcesTreeNext: value.stableSourcesTreeNext,
+        nextSourcesTree: value.nextSourcesTree,
+        ownedDirectories,
+        operations,
+    };
+}
+function assertCatalogItems(catalog, label) {
+    if (!catalog || catalog.version !== 2 || !Array.isArray(catalog.items)) {
+        throw new Error(`Invalid ${label} sources catalog.`);
+    }
+    const items = new Map();
+    const targets = [];
+    for (const item of catalog.items) {
+        if (!item || typeof item.id !== "string" || items.has(item.id) || !item.content ||
+            (item.content.kind !== "file" && item.content.kind !== "tree") ||
+            typeof item.content.path !== "string" || !isSafeSourcesTarget(item.content.path) ||
+            item.content.kind !== (item.kind === "skill" ? "tree" : "file")) {
+            throw new Error(`Invalid or duplicate content target in ${label} sources catalog.`);
+        }
+        items.set(item.id, item);
+        targets.push(item.content.path);
+    }
+    assertNoTargetOverlap(targets);
+    return items;
+}
+export function validateLegacyMigrationJournalTargets(journal, previous, next) {
+    if (!journal || (journal.version !== 4 && journal.version !== 5) || journal.mode !== "legacy-migration" || journal.oldCatalog === null ||
+        !Array.isArray(journal.operations) || !previous || previous.version !== 1 || !Array.isArray(previous.items) ||
+        !Array.isArray(previous.groups) || !next || next.version !== 2 || !Array.isArray(next.groups)) {
+        throw new Error("Legacy migration target validation requires its fixed v4 journal, v1 catalog, and v2 catalog.");
+    }
+    const nextItems = assertCatalogItems(next, "legacy migration next");
+    for (const id of nextItems.keys())
+        assertItemId(id);
+    const previousItems = new Map();
+    for (const item of previous.items) {
+        if (!item || typeof item.id !== "string" || previousItems.has(item.id))
+            throw new Error("Invalid or duplicate item in the legacy migration source catalog.");
+        assertItemId(item.id);
+        previousItems.set(item.id, item);
+    }
+    if (previous.items.length !== next.items.length || JSON.stringify(previous.groups) !== JSON.stringify(next.groups)) {
+        throw new Error("Legacy migration must preserve v1 item membership and group relationships exactly.");
+    }
+    for (const [index, oldItem] of previous.items.entries()) {
+        const migrated = next.items[index];
+        if (!migrated || migrated.id !== oldItem.id)
+            throw new Error("Legacy migration must preserve catalog item order and identity.");
+        const { content: _content, ...migratedLegacy } = migrated;
+        if (JSON.stringify(migratedLegacy) !== JSON.stringify(oldItem)) {
+            throw new Error("Legacy migration may add source content locations but must preserve all v1 item metadata and descriptors.");
+        }
+    }
+    const operationIds = [];
+    const operationTargets = [];
+    if (journal.operations.length > 0 && journal.stableItemsTree === "absent") {
+        throw new Error("Legacy migration cannot stage source additions without the fixed v1 items tree.");
+    }
+    for (const operation of journal.operations) {
+        assertItemId(operation.itemId);
+        const oldItem = previousItems.get(operation.itemId);
+        const nextItem = nextItems.get(operation.itemId);
+        if (!oldItem || !nextItem || operation.oldTree !== null || !isSha256(operation.newTree) ||
+            operation.target !== nextItem.content.path || operation.kind !== nextItem.content.kind) {
+            throw new Error("Legacy migration operation target or kind is not bound to the corresponding v1 and v2 catalog item.");
+        }
+        const targetParts = operation.target.split("/");
+        if ((operation.kind === "tree" && (operation.target !== `sources/${operation.itemId}` || nextItem.kind !== "skill" ||
+            !nextItem.files.some((file) => file.path === "SKILL.md"))) ||
+            (operation.kind === "file" && (targetParts.length !== 3 || targetParts[0] !== "sources" ||
+                targetParts[1] !== operation.itemId || nextItem.files.length !== 1 || nextItem.files[0]?.path !== targetParts[2]))) {
+            throw new Error("Legacy migration new target does not match the v2 item root and R2 placement contract.");
+        }
+        operationIds.push(operation.itemId);
+        operationTargets.push(operation.target);
+    }
+    assertUniqueItemIds(operationIds);
+    assertNoTargetOverlap(operationTargets);
+}
+export function validateSourcesJournalTargets(journal, previous, next) {
+    if (!journal || journal.version !== 2 || !Array.isArray(journal.operations)) {
+        throw new Error("Sources journal target validation requires a v2 journal.");
+    }
+    const nextItems = assertCatalogItems(next, "next");
+    const previousItems = previous === null ? null : assertCatalogItems(previous, "previous");
+    const operationIds = [];
+    const operationTargets = [];
+    for (const operation of journal.operations) {
+        if (!operation || typeof operation !== "object" || Array.isArray(operation))
+            throw new Error("Invalid sources journal operation.");
+        assertItemId(operation.itemId);
+        if (typeof operation.target !== "string" || !isSafeSourcesTarget(operation.target) ||
+            (operation.kind !== "file" && operation.kind !== "tree") ||
+            !isOptionalSha256(operation.oldTree) || !isSha256(operation.newTree)) {
+            throw new Error("Invalid sources journal operation.");
+        }
+        const item = nextItems.get(operation.itemId);
+        if (!item || item.content.path !== operation.target || item.content.kind !== operation.kind) {
+            throw new Error("Sources journal target or kind does not match the next catalog item.");
+        }
+        const oldItem = previousItems?.get(operation.itemId);
+        if (oldItem) {
+            if (oldItem.content.path !== item.content.path || oldItem.content.kind !== item.content.kind || operation.oldTree === null) {
+                throw new Error("Existing sources item changed target or lacks its old tree commitment.");
+            }
+        }
+        else if (operation.oldTree !== null) {
+            throw new Error("New sources item must not have an old tree commitment.");
+        }
+        operationIds.push(operation.itemId);
+        operationTargets.push(operation.target);
+    }
+    assertUniqueItemIds(operationIds);
+    assertNoTargetOverlap(operationTargets);
+}

package/dist/src/storage-root-lease.d.ts

@@ -0,0 +1,7 @@
+export interface StorageRootLease {
+    assertCurrent(): Promise<void>;
+    updateExpectedMode(mode: number): Promise<void>;
+    close(): Promise<void>;
+}
+/** Holds a crash-released macOS O_EXLOCK on the library root directory descriptor. */
+export declare function acquireRootLease(root: string, waitMilliseconds?: number): Promise<StorageRootLease>;