sealkeep 0.9.0 → 0.11.0

package/dist/src/reclaim-transaction.js

@@ -0,0 +1,1027 @@
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+import { constants as fsConstants, createReadStream } from "node:fs";
+import { link, lstat, mkdir, open, readdir, readFile, realpath, rename, rm, stat, unlink, } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { openForFlush } from "./flush.js";
+import { acquireDurableTicketLock } from "./durable-ticket-lock.js";
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const TRANSACTION_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+const JOURNAL_VERSION = 1;
+export class ReclaimConflictError extends Error {
+    code = "RECLAIM_CONFLICT";
+    constructor(message) {
+        super(message);
+        this.name = "ReclaimConflictError";
+    }
+}
+function codedError(message, code) {
+    const error = new Error(message);
+    error.code = code;
+    return error;
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+function expectedIsValid(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return Number.isSafeInteger(candidate.bytes)
+        && (candidate.bytes ?? -1) >= 0
+        && typeof candidate.sha256 === "string"
+        && SHA256_RE.test(candidate.sha256);
+}
+function digestMatches(left, right) {
+    if (!SHA256_RE.test(left) || !SHA256_RE.test(right))
+        return false;
+    return timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex"));
+}
+function fingerprintMatches(fingerprint, expected) {
+    return fingerprint.bytes === expected.bytes && digestMatches(fingerprint.sha256, expected.sha256);
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function pathWithin(candidate, root) {
+    const rel = relative(root, candidate);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+async function syncDirectory(path) {
+    let handle;
+    try {
+        handle = await open(path, "r");
+        await handle.sync();
+    }
+    catch (error) {
+        // Windows does not permit opening directories. The file fsync still gives
+        // the strongest durability primitive Node exposes there.
+        if (process.platform !== "win32")
+            throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function ensurePrivateDirectory(path) {
+    const target = resolve(path);
+    const firstCreated = await mkdir(target, { recursive: true, mode: 0o700 });
+    if (!firstCreated)
+        return;
+    // mkdir({recursive:true}) can create several namespace entries. Persist the
+    // parent that names the first new directory and every new directory inode,
+    // so a journal cannot outlive the directories needed to reconcile it.
+    const first = resolve(firstCreated);
+    await syncDirectory(dirname(first));
+    let cursor = first;
+    await syncDirectory(cursor);
+    for (const piece of relative(first, target).split(sep).filter(Boolean)) {
+        cursor = join(cursor, piece);
+        await syncDirectory(cursor);
+    }
+}
+async function removeDurably(path) {
+    try {
+        await unlink(path);
+        await syncDirectory(dirname(path));
+    }
+    catch (error) {
+        if (errorCode(error) !== "ENOENT")
+            throw error;
+    }
+}
+async function writeJsonDurably(path, value, exclusive) {
+    await ensurePrivateDirectory(dirname(path));
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o600);
+        await handle.writeFile(`${JSON.stringify(value)}\n`, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        if (exclusive) {
+            await link(temporary, path);
+            // Persist the recovery name before removing the private staging name.
+            // If power fails between these fsyncs there may be two hard links, but
+            // never a window in which the durable file has no name.
+            await syncDirectory(dirname(path));
+            await unlink(temporary);
+            await syncDirectory(dirname(path));
+        }
+        else {
+            await rename(temporary, path);
+            await syncDirectory(dirname(path));
+        }
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+export function reclaimSourceLockPath(dataDir, sourcePath) {
+    const key = createHash("sha256").update(resolve(sourcePath)).digest("hex");
+    return join(resolve(dataDir), "reclaim-locks", `${key}.claims`);
+}
+function legacyReclaimSourceLockPath(dataDir, sourcePath) {
+    const key = createHash("sha256").update(resolve(sourcePath)).digest("hex");
+    return join(resolve(dataDir), "reclaim-locks", `${key}.lock`);
+}
+export async function acquireReclaimSourceLock(dataDir, sourcePath, options = {}) {
+    const canonicalDataDir = resolve(dataDir);
+    const canonicalSource = resolve(sourcePath);
+    const queuePath = reclaimSourceLockPath(canonicalDataDir, canonicalSource);
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const pollMs = Math.max(1, options.pollMs ?? 25);
+    // An abandoned pre-ticket lock is never unlinked automatically. Doing so
+    // safely requires conditional unlink-by-inode, which Node does not expose.
+    // Its old owner cannot acquire again while the pathname remains; fail closed
+    // and let explicit singleton maintenance remove it after inspection.
+    const legacyPath = legacyReclaimSourceLockPath(canonicalDataDir, canonicalSource);
+    if (await stat(legacyPath).then(() => true, (error) => {
+        if (errorCode(error) === "ENOENT")
+            return false;
+        throw error;
+    })) {
+        throw codedError(`A legacy reclaim lock requires service-stopped maintenance before this source can be reclaimed: ${canonicalSource}`, "RECLAIM_LOCKED");
+    }
+    let ticket;
+    try {
+        ticket = await acquireDurableTicketLock(queuePath, canonicalSource, {
+            timeoutMs,
+            pollMs,
+            signal: options.signal,
+        });
+    }
+    catch (error) {
+        if (errorCode(error) === "DURABLE_LOCK_TIMEOUT") {
+            throw codedError(`Timed out waiting for reclaim lock: ${canonicalSource}`, "RECLAIM_LOCKED");
+        }
+        throw error;
+    }
+    return {
+        dataDir: canonicalDataDir,
+        sourcePath: canonicalSource,
+        lockPath: ticket.claimPath,
+        token: ticket.token,
+        assertOwned: async () => {
+            try {
+                await ticket.assertOwned();
+            }
+            catch {
+                throw new ReclaimConflictError(`Source lock ownership was lost: ${canonicalSource}`);
+            }
+        },
+        release: () => ticket.release(),
+    };
+}
+async function fingerprintRegularFile(path, io = {}) {
+    const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    const { handle } = await openForFlush(path, noFollow);
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile())
+            throw new ReclaimConflictError(`Expected a regular file: ${path}`);
+        const hash = createHash("sha256");
+        const stream = createReadStream("", { fd: handle.fd, autoClose: false, start: 0 });
+        let bytesSinceYield = 0;
+        for await (const chunk of stream) {
+            hash.update(chunk);
+            bytesSinceYield += chunk.length;
+            if (bytesSinceYield >= 16 * 1024 * 1024) {
+                bytesSinceYield = 0;
+                await io.onYield?.();
+            }
+        }
+        const after = await handle.stat({ bigint: true });
+        if (before.dev !== after.dev
+            || before.ino !== after.ino
+            || before.size !== after.size
+            || before.mtimeNs !== after.mtimeNs
+            || before.ctimeNs !== after.ctimeNs) {
+            throw new ReclaimConflictError(`File changed while it was being hashed: ${path}`);
+        }
+        if (after.size > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new ReclaimConflictError(`File is too large to journal safely: ${path}`);
+        }
+        const allocated = after.blocks * 512n;
+        if (allocated > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new ReclaimConflictError(`File allocation is too large to journal safely: ${path}`);
+        }
+        return {
+            bytes: Number(after.size),
+            sha256: hash.digest("hex"),
+            dev: after.dev.toString(),
+            ino: after.ino.toString(),
+            allocatedBytes: Number(allocated),
+            links: Number(after.nlink),
+            mtimeNs: after.mtimeNs.toString(),
+            ctimeNs: after.ctimeNs.toString(),
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function fingerprintOrNull(path, io = {}) {
+    try {
+        return await fingerprintRegularFile(path, io);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function assertExpected(actual, expected, label) {
+    if (!fingerprintMatches(actual, expected)) {
+        throw new ReclaimConflictError(`${label} does not match the expected ${expected.bytes}-byte sha256 ${expected.sha256}`);
+    }
+}
+async function assertRegularNoFollow(path) {
+    const info = await lstat(path);
+    if (info.isSymbolicLink() || !info.isFile()) {
+        throw new ReclaimConflictError(`Expected a non-symlink regular file: ${path}`);
+    }
+}
+async function identityRegularNoFollow(path) {
+    const info = await lstat(path, { bigint: true });
+    if (info.isSymbolicLink() || !info.isFile()) {
+        throw new ReclaimConflictError(`Expected a non-symlink regular file: ${path}`);
+    }
+    return { dev: info.dev.toString(), ino: info.ino.toString() };
+}
+/** Cheap final identity/change check used next to namespace mutations. */
+async function assertFingerprintMetadataUnchanged(path, expected, message) {
+    const info = await lstat(path, { bigint: true });
+    if (info.isSymbolicLink() || !info.isFile()
+        || info.dev.toString() !== expected.dev
+        || info.ino.toString() !== expected.ino
+        || info.size !== BigInt(expected.bytes)
+        || info.mtimeNs.toString() !== expected.mtimeNs
+        || info.ctimeNs.toString() !== expected.ctimeNs
+        || Number(info.nlink) !== expected.links) {
+        throw new ReclaimConflictError(message);
+    }
+}
+/** Flush the exact inode whose digest was accepted before publishing its name. */
+async function syncExactRegularFile(path, expected, io = {}) {
+    const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    const { handle } = await openForFlush(path, noFollow);
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile()
+            || before.dev.toString() !== expected.dev
+            || before.ino.toString() !== expected.ino
+            || before.size !== BigInt(expected.bytes)) {
+            throw new ReclaimConflictError(`Prepared file changed before fsync: ${path}`);
+        }
+        await handle.sync();
+        await io.afterFileSync?.(path);
+        const after = await handle.stat({ bigint: true });
+        if (before.dev !== after.dev
+            || before.ino !== after.ino
+            || before.size !== after.size
+            || before.mtimeNs !== after.mtimeNs
+            || before.ctimeNs !== after.ctimeNs
+            || before.nlink !== after.nlink) {
+            throw new ReclaimConflictError(`Prepared file changed while it was being fsynced: ${path}`);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Publish a private, complete temp file at destination using create-if-absent
+ * semantics. Both paths must be on the same filesystem. EEXIST never removes
+ * or overwrites the destination.
+ */
+export async function publishTempCreateIfAbsent(tempPath, destinationPath, expected, io = {}) {
+    const source = resolve(tempPath);
+    const destination = resolve(destinationPath);
+    if (source === destination)
+        throw new ReclaimConflictError("Temp and destination paths must differ");
+    await assertRegularNoFollow(source);
+    const measured = await fingerprintRegularFile(source, io);
+    assertExpected(measured, expected, `Temporary file ${source}`);
+    // A durable directory entry cannot compensate for an unflushed inode. The
+    // prepared pointer must survive power loss before the bulky original can be
+    // irreversibly unlinked.
+    await syncExactRegularFile(source, measured, io);
+    await link(source, destination);
+    try {
+        const published = await fingerprintRegularFile(destination, io);
+        if (!sameIdentity(measured, published)) {
+            throw new ReclaimConflictError(`Published path is not the prepared file: ${destination}`);
+        }
+        // Make the destination name durable before dropping the temp name.
+        await syncDirectory(dirname(destination));
+        await unlink(source);
+        await syncDirectory(dirname(source));
+        return published;
+    }
+    catch (error) {
+        // The source hard link is retained on every failure, so no bytes are lost.
+        throw error;
+    }
+}
+/**
+ * Move an existing file to a unique park path without overwriting either name,
+ * then validate its content. On a digest mismatch the function restores the
+ * source name when possible and otherwise leaves the parked bytes intact.
+ */
+export async function parkExistingPathNoClobber(sourcePath, parkPath, expected, io = {}) {
+    const source = resolve(sourcePath);
+    const parked = resolve(parkPath);
+    if (source === parked)
+        throw new ReclaimConflictError("Source and park paths must differ");
+    await assertRegularNoFollow(source);
+    const before = await fingerprintRegularFile(source, io);
+    await link(source, parked);
+    const linked = await fingerprintRegularFile(parked, io);
+    if (!sameIdentity(before, linked)) {
+        // A namespace race occurred after link(). Do not guess which inode is the
+        // user's winner: both source and the deterministic park name are retained.
+        throw new ReclaimConflictError(`Parked path is not the source file; both names were retained: ${parked}`);
+    }
+    // Persist the contents of the exact inode now named by the recovery path,
+    // not merely the directory entry. A directory fsync cannot make dirty file
+    // data durable. The open-fd pre/post checks also reject a concurrent append.
+    await syncExactRegularFile(parked, linked, io);
+    await assertFingerprintMetadataUnchanged(parked, linked, `Parked file changed before its durable name was committed; both names were retained: ${parked}`);
+    // The parked name must reach stable storage before source is removed.
+    await syncDirectory(dirname(parked));
+    // fsync can be slow enough for a native writer to recreate the source name.
+    // Re-check immediately before unlink; a different inode always wins and both
+    // it and the parked bytes remain untouched. Node has no unlinkat-by-fd, so a
+    // hostile same-user swap in the syscall-sized gap cannot be eliminated here.
+    const sourceBeforeUnlink = await identityRegularNoFollow(source);
+    if (!sameIdentity(linked, sourceBeforeUnlink)) {
+        throw new ReclaimConflictError(`Source was recreated while parking; both names were retained: ${source}`);
+    }
+    await assertFingerprintMetadataUnchanged(parked, linked, `Parked file changed before source unlink; both names were retained: ${parked}`);
+    await unlink(source);
+    await syncDirectory(dirname(source));
+    const after = await fingerprintRegularFile(parked, io);
+    if (!fingerprintMatches(after, expected)) {
+        try {
+            await restoreParkedCreateIfAbsent(parked, source);
+        }
+        catch {
+            // A concurrently created source wins. The unexpected parked bytes remain
+            // addressable; deleting either side here would lose user data.
+        }
+        throw new ReclaimConflictError(`Parked file changed or did not match expectation: ${source}`);
+    }
+    return after;
+}
+/** Restore a parked regular file at destination with create-if-absent semantics. */
+export async function restoreParkedCreateIfAbsent(parkPath, destinationPath, expected, io = {}) {
+    const parked = resolve(parkPath);
+    const destination = resolve(destinationPath);
+    if (parked === destination)
+        throw new ReclaimConflictError("Park and destination paths must differ");
+    await assertRegularNoFollow(parked);
+    const before = await fingerprintRegularFile(parked, io);
+    if (expected)
+        assertExpected(before, expected, `Parked file ${parked}`);
+    await link(parked, destination);
+    const restored = await fingerprintRegularFile(destination, io);
+    if (!sameIdentity(before, restored)) {
+        throw new ReclaimConflictError(`Restored path is not the parked file: ${destination}`);
+    }
+    // Persist the restored name before releasing the parked recovery name.
+    await syncDirectory(dirname(destination));
+    await unlink(parked);
+    await syncDirectory(dirname(parked));
+    return restored;
+}
+function journalDirectory(dataDir) {
+    return join(resolve(dataDir), "reclaim-transactions");
+}
+export function reclaimJournalPath(dataDir, transactionId) {
+    if (!TRANSACTION_ID_RE.test(transactionId))
+        throw new ReclaimConflictError("Invalid reclaim transaction id");
+    return join(journalDirectory(dataDir), `${transactionId}.json`);
+}
+export function reclaimTrashPath(dataDir, transactionId, sourcePath) {
+    if (!TRANSACTION_ID_RE.test(transactionId))
+        throw new ReclaimConflictError("Invalid reclaim transaction id");
+    return join(resolve(dataDir), "trash", "reclaim-transactions", transactionId, basename(resolve(sourcePath)));
+}
+function journalWire(transaction) {
+    return {
+        version: JOURNAL_VERSION,
+        id: transaction.id,
+        sourcePath: transaction.sourcePath,
+        trashPath: transaction.trashPath,
+        createdAt: transaction.createdAt,
+        updatedAt: transaction.updatedAt,
+        stage: transaction.stage,
+        original: transaction.original,
+        replacement: transaction.replacement,
+    };
+}
+async function assertTransactionLock(transaction, lock) {
+    if (lock.dataDir !== transaction.dataDir || lock.sourcePath !== transaction.sourcePath) {
+        throw new ReclaimConflictError("Reclaim lock does not cover this transaction");
+    }
+    await lock.assertOwned();
+}
+async function updateJournal(transaction, stage) {
+    transaction.stage = stage;
+    transaction.updatedAt = new Date().toISOString();
+    await writeJsonDurably(transaction.journalPath, journalWire(transaction), false);
+    return transaction;
+}
+export async function beginReclaimTransaction(dataDir, lock, input, io = {}) {
+    const requestedReplacement = input.replacement ?? null;
+    if (!expectedIsValid(input.original) || (requestedReplacement !== null && !expectedIsValid(requestedReplacement))) {
+        throw new ReclaimConflictError("Invalid reclaim file descriptor");
+    }
+    const canonicalDataDir = resolve(dataDir);
+    const sourcePath = resolve(input.sourcePath);
+    const tempPath = requestedReplacement ? resolve(requestedReplacement.tempPath) : null;
+    if (canonicalDataDir !== lock.dataDir || sourcePath !== lock.sourcePath) {
+        throw new ReclaimConflictError("Reclaim lock does not cover the requested source");
+    }
+    await lock.assertOwned();
+    if (tempPath && dirname(tempPath) !== dirname(sourcePath)) {
+        throw new ReclaimConflictError("Replacement temp must be beside its destination");
+    }
+    const original = await fingerprintRegularFile(sourcePath, io);
+    assertExpected(original, input.original, `Reclaim source ${sourcePath}`);
+    if (original.links !== 1) {
+        throw new ReclaimConflictError(`Reclaim source has ${original.links} hard links, so deleting this pathname would not truthfully free its allocation: ${sourcePath}`);
+    }
+    const replacementFingerprint = tempPath && requestedReplacement
+        ? await fingerprintRegularFile(tempPath, io)
+        : null;
+    if (replacementFingerprint && requestedReplacement) {
+        assertExpected(replacementFingerprint, requestedReplacement, `Reclaim replacement ${tempPath}`);
+    }
+    const id = input.transactionId ?? randomUUID();
+    if (!TRANSACTION_ID_RE.test(id))
+        throw new ReclaimConflictError("Invalid reclaim transaction id");
+    const createdAt = new Date().toISOString();
+    const transaction = {
+        version: JOURNAL_VERSION,
+        id,
+        dataDir: canonicalDataDir,
+        journalPath: reclaimJournalPath(canonicalDataDir, id),
+        sourcePath,
+        trashPath: reclaimTrashPath(canonicalDataDir, id, sourcePath),
+        createdAt,
+        updatedAt: createdAt,
+        stage: "prepared",
+        original,
+        replacement: replacementFingerprint && tempPath ? {
+            ...replacementFingerprint,
+            tempPath,
+        } : null,
+    };
+    await ensurePrivateDirectory(dirname(transaction.trashPath));
+    // Exclusive durable publication is deliberately the final operation here:
+    // no source namespace mutation is allowed before the recovery journal exists.
+    await writeJsonDurably(transaction.journalPath, journalWire(transaction), true);
+    return transaction;
+}
+export async function moveReclaimSource(transaction, lock, io = {}) {
+    await assertTransactionLock(transaction, lock);
+    await parkExistingPathNoClobber(transaction.sourcePath, transaction.trashPath, transaction.original, io);
+    return updateJournal(transaction, "source-moved");
+}
+export async function installReclaimReplacement(transaction, lock, io = {}) {
+    await assertTransactionLock(transaction, lock);
+    if (!transaction.replacement) {
+        throw new ReclaimConflictError("This reclaim transaction has no replacement to install");
+    }
+    await publishTempCreateIfAbsent(transaction.replacement.tempPath, transaction.sourcePath, transaction.replacement, io);
+    return updateJournal(transaction, "replacement-installed");
+}
+export async function markReclaimMetadataCommitted(transaction, lock) {
+    await assertTransactionLock(transaction, lock);
+    return updateJournal(transaction, "metadata-committed");
+}
+/**
+ * Durable point of no return. Call this only after record metadata and the
+ * append-only audit decision have both committed successfully.
+ */
+export async function markReclaimPurgeAuthorized(transaction, lock) {
+    await assertTransactionLock(transaction, lock);
+    if (transaction.stage !== "metadata-committed") {
+        throw new ReclaimConflictError(`Cannot authorize purge from stage ${transaction.stage}`);
+    }
+    return updateJournal(transaction, "purge-authorized");
+}
+async function removeExactTempDuplicate(transaction, io = {}) {
+    if (!transaction.replacement)
+        return;
+    const temp = await fingerprintOrNull(transaction.replacement.tempPath, io);
+    if (!temp || !fingerprintMatches(temp, transaction.replacement))
+        return;
+    const source = await fingerprintOrNull(transaction.sourcePath, io);
+    if (source && sameIdentity(source, temp))
+        await removeDurably(transaction.replacement.tempPath);
+}
+async function removeOwnedReplacementTemp(transaction, io = {}) {
+    if (!transaction.replacement)
+        return;
+    const temp = await fingerprintOrNull(transaction.replacement.tempPath, io);
+    if (temp && fingerprintMatches(temp, transaction.replacement)) {
+        await removeDurably(transaction.replacement.tempPath);
+    }
+}
+export async function finalizeReclaimTransaction(transaction, lock, options = {}) {
+    await assertTransactionLock(transaction, lock);
+    if (transaction.stage !== "purge-authorized") {
+        throw new ReclaimConflictError("The staged original cannot be purged before metadata and audit are committed");
+    }
+    const source = await fingerprintOrNull(transaction.sourcePath, options.io);
+    if (transaction.replacement) {
+        if (!source)
+            throw new ReclaimConflictError(`Installed reclaim replacement is missing: ${transaction.sourcePath}`);
+        assertExpected(source, transaction.replacement, `Installed reclaim replacement ${transaction.sourcePath}`);
+    }
+    else if (source) {
+        throw new ReclaimConflictError(`A new source appeared before purge; refusing to delete staged bytes: ${transaction.sourcePath}`);
+    }
+    const trash = await fingerprintOrNull(transaction.trashPath, options.io);
+    if (trash && (!sameIdentity(trash, transaction.original) || !fingerprintMatches(trash, transaction.original))) {
+        throw new ReclaimConflictError(`Reclaim staging is not the exact journaled original inode: ${transaction.trashPath}`);
+    }
+    if (trash && trash.links !== 1) {
+        throw new ReclaimConflictError(`Reclaim staging has ${trash.links} hard links, so unlinking it would not truthfully free its allocation: ${transaction.trashPath}`);
+    }
+    await removeExactTempDuplicate(transaction, options.io);
+    const replacementAllocatedBytes = source?.allocatedBytes ?? 0;
+    let releasedSourceAllocation = 0;
+    if (trash) {
+        if (!options.verifyPurgeStillSafe) {
+            throw new ReclaimConflictError("Reclaim cannot purge without a fresh external durability proof");
+        }
+        await options.verifyPurgeStillSafe(transaction);
+        await assertTransactionLock(transaction, lock);
+        // The provider proof can take minutes. Re-read inode metadata after it so
+        // an open native fd cannot append/rewrite between the accepted full hash
+        // above and unlink. This cheap check is adjacent to the irreversible call.
+        const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+        const stagedHandle = await open(transaction.trashPath, fsConstants.O_RDONLY | noFollow);
+        try {
+            const [current, currentPath] = await Promise.all([
+                stagedHandle.stat({ bigint: true }),
+                lstat(transaction.trashPath, { bigint: true }),
+            ]);
+            const currentAllocated = current.blocks * 512n;
+            if (!current.isFile() || !currentPath.isFile()
+                || current.dev !== currentPath.dev || current.ino !== currentPath.ino
+                || current.dev.toString() !== trash.dev
+                || current.ino.toString() !== trash.ino
+                || current.size !== BigInt(trash.bytes)
+                || current.mtimeNs.toString() !== trash.mtimeNs
+                || current.ctimeNs.toString() !== trash.ctimeNs
+                || currentAllocated > BigInt(Number.MAX_SAFE_INTEGER)
+                || Number(currentAllocated) !== transaction.original.allocatedBytes
+                || Number(current.nlink) !== 1 || Number(currentPath.nlink) !== 1) {
+                throw new ReclaimConflictError(`Reclaim staging changed during final durability proof: ${transaction.trashPath}`);
+            }
+            await options.io?.afterPurgeSnapshot?.(transaction.trashPath);
+            await unlink(transaction.trashPath);
+            await syncDirectory(dirname(transaction.trashPath));
+            // The open descriptor observes the inode after its staging name is gone.
+            // A hard link created in the final syscall-sized race means the blocks
+            // still exist elsewhere, so report zero rather than the logical length.
+            const after = await stagedHandle.stat({ bigint: true });
+            if (after.dev !== current.dev || after.ino !== current.ino) {
+                throw new ReclaimConflictError("The staged source inode changed while its allocation was measured");
+            }
+            releasedSourceAllocation = after.nlink === 0n ? Number(currentAllocated) : 0;
+        }
+        finally {
+            await stagedHandle.close();
+        }
+    }
+    // The purge-authorized journal remains durable across this irreversible
+    // unlink. If power fails afterwards, reconciliation observes the absent
+    // staging path, finishes final metadata, and only then removes the journal.
+    // If reconciliation finds an already-absent staging name, no durable
+    // post-unlink link-count observation survived the crash. Zero is the only
+    // truthful physical-space report in that window.
+    const freedBytes = releasedSourceAllocation > 0
+        ? Math.max(0, releasedSourceAllocation - replacementAllocatedBytes)
+        : 0;
+    await options.onPurged?.(transaction, freedBytes);
+    await removeDurably(transaction.journalPath);
+    return { freedBytes };
+}
+function rollbackParkPath(transaction) {
+    return join(dirname(transaction.sourcePath), `.${basename(transaction.sourcePath)}.sealkeep-rollback-${transaction.id}`);
+}
+async function trashIsOriginal(transaction, trash) {
+    return sameIdentity(trash, transaction.original) || fingerprintMatches(trash, transaction.original);
+}
+async function rollbackUnderLock(transaction, io = {}, callbacks = {}) {
+    const source = await fingerprintOrNull(transaction.sourcePath, io);
+    const trash = await fingerprintOrNull(transaction.trashPath, io);
+    const parkPath = rollbackParkPath(transaction);
+    const parked = await fingerprintOrNull(parkPath, io);
+    if (parked && (!transaction.replacement || !fingerprintMatches(parked, transaction.replacement))) {
+        throw new ReclaimConflictError("Rollback park contains unexpected bytes and was retained");
+    }
+    if (source && trash && sameIdentity(source, trash)) {
+        // A kill between link() and unlink() left two names for the same inode. The
+        // source is already restored, including any writes through an open fd.
+        await removeDurably(transaction.trashPath);
+        await removeOwnedReplacementTemp(transaction, io);
+        await removeDurably(transaction.journalPath);
+        return parked
+            ? `removed duplicate staging link; original source was already present; retained pointer recovery copy at ${parkPath}`
+            : "removed duplicate staging link; original source was already present";
+    }
+    if (source && sameIdentity(source, transaction.original) && !trash) {
+        await removeOwnedReplacementTemp(transaction, io);
+        await removeDurably(transaction.journalPath);
+        return parked
+            ? `original source was never moved; retained pointer recovery copy at ${parkPath}`
+            : "original source was never moved";
+    }
+    if (!trash || !(await trashIsOriginal(transaction, trash))) {
+        throw new ReclaimConflictError("Cannot roll back because the journaled original is unavailable");
+    }
+    if (!source) {
+        // Identity, rather than the old digest, intentionally authorizes this
+        // restore. An open writer may have appended after the source was parked;
+        // those bytes are part of the native transcript and must not be discarded.
+        await restoreParkedCreateIfAbsent(transaction.trashPath, transaction.sourcePath, undefined, io);
+        await removeOwnedReplacementTemp(transaction, io);
+        await removeDurably(transaction.journalPath);
+        return parked
+            ? `restored original from reclaim staging; retained pointer recovery copy at ${parkPath}`
+            : "restored original from reclaim staging";
+    }
+    if (!transaction.replacement || !fingerprintMatches(source, transaction.replacement)) {
+        throw new ReclaimConflictError("Source contains unexpected bytes; rollback refused to overwrite it");
+    }
+    if (parked) {
+        if (!sameIdentity(source, parked)) {
+            throw new ReclaimConflictError("Both source and rollback park contain distinct files; rollback refused");
+        }
+        await removeDurably(transaction.sourcePath);
+        try {
+            await restoreParkedCreateIfAbsent(transaction.trashPath, transaction.sourcePath, undefined, io);
+        }
+        catch (error) {
+            try {
+                await restoreParkedCreateIfAbsent(parkPath, transaction.sourcePath, transaction.replacement, io);
+            }
+            catch {
+                // Both names remain addressable if a contender created source.
+            }
+            throw error;
+        }
+        await removeOwnedReplacementTemp(transaction, io);
+        await removeDurably(transaction.journalPath);
+        return `finished rollback interrupted between parking and restoring the original; retained pointer recovery copy at ${parkPath}`;
+    }
+    await parkExistingPathNoClobber(transaction.sourcePath, parkPath, transaction.replacement, io);
+    await callbacks.afterReplacementParked?.(parkPath);
+    try {
+        await restoreParkedCreateIfAbsent(transaction.trashPath, transaction.sourcePath, undefined, io);
+    }
+    catch (error) {
+        try {
+            await restoreParkedCreateIfAbsent(parkPath, transaction.sourcePath, transaction.replacement, io);
+        }
+        catch {
+            // Both names remain addressable if a contender created source. Never
+            // delete the parked replacement in that case.
+        }
+        throw error;
+    }
+    // Never unlink a parked pointer. Codex may have opened the old pathname
+    // before it was parked and can append a resumed turn through that fd after
+    // every digest check. Keeping this tiny, deterministic recovery copy is the
+    // only fail-closed choice available without cooperation from Codex.
+    await removeOwnedReplacementTemp(transaction, io);
+    await removeDurably(transaction.journalPath);
+    return `restored original from reclaim staging; retained pointer recovery copy at ${parkPath}`;
+}
+export async function rollbackReclaimTransaction(transaction, lock, options = {}) {
+    await assertTransactionLock(transaction, lock);
+    await rollbackUnderLock(transaction, options.io, {
+        afterReplacementParked: options.afterReplacementParked,
+    });
+}
+function parseJournal(dataDir, journalPath, raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new ReclaimConflictError(`Invalid reclaim journal JSON: ${journalPath}`);
+    }
+    if (value.version !== JOURNAL_VERSION
+        || typeof value.id !== "string"
+        || !TRANSACTION_ID_RE.test(value.id)
+        || typeof value.sourcePath !== "string"
+        || !isAbsolute(value.sourcePath)
+        || typeof value.trashPath !== "string"
+        || !isAbsolute(value.trashPath)
+        || typeof value.createdAt !== "string"
+        || typeof value.updatedAt !== "string"
+        || !["prepared", "source-moved", "replacement-installed", "metadata-committed", "purge-authorized"].includes(String(value.stage))
+        || !expectedIsValid(value.original)
+        || typeof value.original.dev !== "string"
+        || typeof value.original.ino !== "string"
+        || !Number.isSafeInteger(value.original.allocatedBytes)
+        || (value.original.allocatedBytes ?? -1) < 0
+        || !Number.isSafeInteger(value.original.links)
+        || (value.original.links ?? 0) < 1
+        || typeof value.original.mtimeNs !== "string"
+        || typeof value.original.ctimeNs !== "string"
+        || (value.replacement !== null && (!expectedIsValid(value.replacement)
+            || typeof value.replacement.dev !== "string"
+            || typeof value.replacement.ino !== "string"
+            || !Number.isSafeInteger(value.replacement.allocatedBytes)
+            || (value.replacement.allocatedBytes ?? -1) < 0
+            || !Number.isSafeInteger(value.replacement.links)
+            || (value.replacement.links ?? 0) < 1
+            || typeof value.replacement.mtimeNs !== "string"
+            || typeof value.replacement.ctimeNs !== "string"
+            || typeof value.replacement.tempPath !== "string"))) {
+        throw new ReclaimConflictError(`Invalid reclaim journal shape: ${journalPath}`);
+    }
+    const canonicalDataDir = resolve(dataDir);
+    const expectedJournal = reclaimJournalPath(canonicalDataDir, value.id);
+    const sourcePath = resolve(value.sourcePath);
+    const expectedTrash = reclaimTrashPath(canonicalDataDir, value.id, sourcePath);
+    const tempPath = value.replacement === null
+        ? null
+        : resolve(value.replacement.tempPath);
+    if (resolve(journalPath) !== expectedJournal
+        || resolve(value.trashPath) !== expectedTrash
+        || (tempPath !== null && dirname(tempPath) !== dirname(sourcePath))) {
+        throw new ReclaimConflictError(`Reclaim journal contains non-deterministic paths: ${journalPath}`);
+    }
+    return {
+        ...value,
+        sourcePath,
+        trashPath: expectedTrash,
+        replacement: tempPath === null
+            ? null
+            : { ...value.replacement, tempPath },
+        dataDir: canonicalDataDir,
+        journalPath: expectedJournal,
+    };
+}
+async function completeCommittedUnderLock(transaction, io = {}) {
+    let source = await fingerprintOrNull(transaction.sourcePath, io);
+    const trash = await fingerprintOrNull(transaction.trashPath, io);
+    if (!trash || !(await trashIsOriginal(transaction, trash))) {
+        throw new ReclaimConflictError("Committed reclaim is missing its staged original");
+    }
+    if (source && sameIdentity(source, trash)) {
+        await removeDurably(transaction.sourcePath);
+        source = null;
+    }
+    if (!transaction.replacement) {
+        if (source)
+            throw new ReclaimConflictError("Committed reclaim source contains unexpected bytes");
+        return "completed committed source removal staging";
+    }
+    if (!source) {
+        await publishTempCreateIfAbsent(transaction.replacement.tempPath, transaction.sourcePath, transaction.replacement, io);
+    }
+    else if (!fingerprintMatches(source, transaction.replacement)) {
+        throw new ReclaimConflictError("Committed reclaim source contains unexpected bytes");
+    }
+    await removeExactTempDuplicate(transaction, io);
+    return "completed committed replacement before purging staged original";
+}
+export async function reconcileReclaimTransactions(dataDir, options) {
+    const canonicalDataDir = resolve(dataDir);
+    const directory = journalDirectory(canonicalDataDir);
+    const names = await readdir(directory).catch((error) => {
+        if (errorCode(error) === "ENOENT")
+            return [];
+        throw error;
+    });
+    const outcomes = [];
+    for (const name of names.sort()) {
+        if (!name.endsWith(".json"))
+            continue;
+        const journalPath = join(directory, name);
+        let transaction;
+        try {
+            await validateNoFollowPath(journalPath, [canonicalDataDir], { leaf: "file" });
+            transaction = parseJournal(canonicalDataDir, journalPath, await readFile(journalPath, "utf8"));
+            await validateNoFollowPath(transaction.trashPath, [canonicalDataDir], { leaf: "missing-or-file" });
+        }
+        catch (error) {
+            outcomes.push({
+                id: name.slice(0, -5),
+                status: "conflict",
+                detail: error instanceof Error ? error.message : String(error),
+            });
+            continue;
+        }
+        let lock;
+        try {
+            lock = await acquireReclaimSourceLock(canonicalDataDir, transaction.sourcePath, options.lock);
+            await options.validateTransaction(transaction);
+            const metadataCommitted = await options.isMetadataCommitted(transaction);
+            const trash = await fingerprintOrNull(transaction.trashPath, options.io);
+            try {
+                await options.validatePurgeCandidate?.(transaction);
+            }
+            catch (validationError) {
+                // Structural paths were already validated above, so byte rollback is
+                // safe here. This separate hook exists for upgrade policy/format gates:
+                // an older build may have prepared a source a newer installed agent can
+                // no longer resume. Never let that old decision cross the new boundary.
+                if (metadataCommitted) {
+                    if (!trash || !options.clearMetadataCommit)
+                        throw validationError;
+                    await options.clearMetadataCommit(transaction);
+                }
+                const detail = await rollbackUnderLock(transaction, options.io);
+                outcomes.push({
+                    id: transaction.id,
+                    sourcePath: transaction.sourcePath,
+                    status: metadataCommitted ? "rolled-back" : "cleaned",
+                    detail: `${detail}; ${validationError instanceof Error ? validationError.message : String(validationError)}`,
+                });
+                continue;
+            }
+            const trashGrewAfterSnapshot = trash
+                && sameIdentity(trash, transaction.original)
+                && !fingerprintMatches(trash, transaction.original);
+            if (metadataCommitted && trashGrewAfterSnapshot) {
+                if (!options.clearMetadataCommit) {
+                    throw new ReclaimConflictError("Original grew after archival; clearing committed metadata is required before rollback");
+                }
+                await options.clearMetadataCommit(transaction);
+                const detail = await rollbackUnderLock(transaction, options.io);
+                outcomes.push({ id: transaction.id, sourcePath: transaction.sourcePath, status: "rolled-back", detail });
+            }
+            else if (metadataCommitted) {
+                const source = await fingerprintOrNull(transaction.sourcePath, options.io);
+                const temp = transaction.replacement
+                    ? await fingerprintOrNull(transaction.replacement.tempPath, options.io)
+                    : null;
+                const replacementStillNeeded = transaction.replacement
+                    ? !source || Boolean(trash && sameIdentity(source, trash))
+                    : Boolean(source);
+                const cannotCompleteReplacement = transaction.replacement
+                    ? replacementStillNeeded && (!temp || !fingerprintMatches(temp, transaction.replacement))
+                    : replacementStillNeeded;
+                // Before the durable purge decision the original must still exist so
+                // any failure can restore it. Once purge-authorized is durable, an
+                // absent staging file means the unlink completed before the crash.
+                const originalMissingTooEarly = !trash && transaction.stage !== "purge-authorized";
+                if (cannotCompleteReplacement || originalMissingTooEarly) {
+                    if (!options.clearMetadataCommit) {
+                        throw new ReclaimConflictError("Committed reclaim cannot be completed safely; clearing metadata is required before rollback");
+                    }
+                    await options.clearMetadataCommit(transaction);
+                    const detail = await rollbackUnderLock(transaction, options.io);
+                    outcomes.push({ id: transaction.id, sourcePath: transaction.sourcePath, status: "rolled-back", detail });
+                }
+                else {
+                    let detail = transaction.stage === "purge-authorized" && !trash
+                        ? "recognized an already-purged original"
+                        : await completeCommittedUnderLock(transaction, options.io);
+                    try {
+                        if (transaction.stage !== "purge-authorized") {
+                            // The metadata mutation can land before its directory fsync
+                            // reports success, leaving an older journal stage. Normalize it
+                            // before the audit and irreversible boundary.
+                            if (transaction.stage !== "metadata-committed") {
+                                await updateJournal(transaction, "metadata-committed");
+                            }
+                            if (!options.ensureAuditCommitted) {
+                                throw new ReclaimConflictError("Committed reclaim cannot purge without a durable audit callback");
+                            }
+                            await options.ensureAuditCommitted(transaction);
+                            await markReclaimPurgeAuthorized(transaction, lock);
+                        }
+                        const finalized = await finalizeReclaimTransaction(transaction, lock, {
+                            onPurged: options.onPurged,
+                            verifyPurgeStillSafe: options.verifyPurgeStillSafe,
+                            io: options.io,
+                        });
+                        detail += `; permanently purged ${finalized.freedBytes} local bytes`;
+                        outcomes.push({ id: transaction.id, sourcePath: transaction.sourcePath, status: "completed", detail });
+                    }
+                    catch (error) {
+                        // If the irreversible unlink has not happened, an audit or final
+                        // verification failure is still fully recoverable. If staging is
+                        // already absent, the journal must remain for onPurged metadata to
+                        // finish on the next run; pretending rollback is possible would
+                        // erase the only durable account of the completed deletion.
+                        let stagedNow;
+                        try {
+                            stagedNow = await fingerprintOrNull(transaction.trashPath, options.io);
+                        }
+                        catch (inspectionError) {
+                            throw new AggregateError([error, inspectionError], "Reclaim failed and staging could not be inspected safely; the journal was retained");
+                        }
+                        if (stagedNow && options.clearMetadataCommit) {
+                            await options.clearMetadataCommit(transaction);
+                            const rollbackDetail = await rollbackUnderLock(transaction, options.io);
+                            outcomes.push({ id: transaction.id, sourcePath: transaction.sourcePath, status: "rolled-back", detail: rollbackDetail });
+                        }
+                        else {
+                            throw error;
+                        }
+                    }
+                }
+            }
+            else {
+                const sourceBefore = await fingerprintOrNull(transaction.sourcePath, options.io);
+                const trashBefore = await fingerprintOrNull(transaction.trashPath, options.io);
+                const wasNeverMoved = Boolean(sourceBefore
+                    && fingerprintMatches(sourceBefore, transaction.original)
+                    && !trashBefore);
+                const detail = await rollbackUnderLock(transaction, options.io);
+                outcomes.push({
+                    id: transaction.id,
+                    sourcePath: transaction.sourcePath,
+                    status: wasNeverMoved ? "cleaned" : "rolled-back",
+                    detail,
+                });
+            }
+        }
+        catch (error) {
+            outcomes.push({
+                id: transaction.id,
+                sourcePath: transaction.sourcePath,
+                status: "conflict",
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+        finally {
+            await lock?.release().catch(() => undefined);
+        }
+    }
+    return outcomes;
+}
+/**
+ * Resolve a native-session path beneath an allowed root while rejecting
+ * symlinks in the root or any existing descendant component. The canonical
+ * root must equal its lexical path, so a symlinked native root is not trusted.
+ */
+export async function validateNoFollowPath(candidatePath, roots, options = {}) {
+    const candidate = resolve(candidatePath);
+    const leafMode = options.leaf ?? "file";
+    for (const suppliedRoot of roots) {
+        const root = resolve(suppliedRoot);
+        if (!pathWithin(candidate, root))
+            continue;
+        const rootInfo = await lstat(root).catch(() => null);
+        if (!rootInfo || rootInfo.isSymbolicLink() || !rootInfo.isDirectory())
+            continue;
+        const canonicalRoot = await realpath(root).catch(() => null);
+        if (!canonicalRoot || canonicalRoot !== root)
+            continue;
+        const pieces = relative(root, candidate).split(sep).filter(Boolean);
+        if (pieces.length === 0)
+            continue;
+        let cursor = root;
+        let valid = true;
+        for (let index = 0; index < pieces.length; index += 1) {
+            cursor = join(cursor, pieces[index]);
+            const isLeaf = index === pieces.length - 1;
+            const info = await lstat(cursor).catch((error) => {
+                if (errorCode(error) === "ENOENT")
+                    return null;
+                throw error;
+            });
+            if (!info) {
+                if (isLeaf && leafMode === "missing-or-file")
+                    break;
+                valid = false;
+                break;
+            }
+            if (info.isSymbolicLink() || (!isLeaf && !info.isDirectory()) || (isLeaf && !info.isFile())) {
+                valid = false;
+                break;
+            }
+        }
+        if (!valid)
+            continue;
+        const parent = pieces.length === 0 ? root : dirname(candidate);
+        const canonicalParent = await realpath(parent).catch(() => null);
+        if (!canonicalParent || !pathWithin(canonicalParent, canonicalRoot))
+            continue;
+        if (leafMode === "file") {
+            const canonicalCandidate = await realpath(candidate).catch(() => null);
+            if (!canonicalCandidate || !pathWithin(canonicalCandidate, canonicalRoot))
+                continue;
+        }
+        return candidate;
+    }
+    throw new ReclaimConflictError(`Path is not a no-follow regular file under an allowed root: ${candidate}`);
+}