@aipt/platform-kernel 0.1.5

package/dist/filesystem-transaction.js

@@ -0,0 +1,749 @@
+import { chmod, lstat, mkdir, open, readFile, realpath, rename, rm, stat, unlink, } from "node:fs/promises";
+import { constants } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { canonicalize, sha256Digest } from "./integrity.js";
+import { calculatePlanId } from "./planner.js";
+import { parseChangePlan, parseTransactionJournal } from "./schemas.js";
+import { traceDurabilityOperation, } from "./durability-trace.js";
+const preparedToken = Symbol("prepared-transaction");
+const activeTransactions = new Map();
+const DEFAULT_MAX_FILE_BYTES = 5 * 1024 * 1024;
+const DEFAULT_MAX_TRANSACTION_BYTES = 25 * 1024 * 1024;
+const APPLY_DURABILITY_BATCH_SIZE = 8;
+class CrashInjectionSignal extends Error {
+}
+async function runPrepareCheckpoint(hooks, checkpoint, operationIndex) {
+    try {
+        await hooks?.onCheckpoint?.(checkpoint, operationIndex);
+    }
+    catch (error) {
+        throw new CrashInjectionSignal("Simulated prepare crash", { cause: error });
+    }
+}
+export class FilesystemTransactionError extends Error {
+    code;
+    relativePath;
+    operationIndex;
+    constructor(code, message, relativePath, operationIndex) {
+        super(message);
+        this.code = code;
+        this.relativePath = relativePath;
+        this.operationIndex = operationIndex;
+    }
+}
+function transactionPaths(projectRoot, planId) {
+    const platformDirectory = path.join(projectRoot, ".dyyto");
+    const transactionDirectory = path.join(platformDirectory, "transactions", planId);
+    return {
+        platformDirectory,
+        lock: path.join(platformDirectory, "transaction-lock.json"),
+        transactionDirectory,
+        journal: path.join(transactionDirectory, "journal.json"),
+        preimages: path.join(transactionDirectory, "preimages"),
+        quarantine: path.join(transactionDirectory, "quarantine"),
+    };
+}
+async function exists(target) {
+    try {
+        await lstat(target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function traceContext(trace, directory = false) {
+    if (trace?.sink === undefined)
+        return undefined;
+    return {
+        sink: trace.sink,
+        phase: trace.phase,
+        pathCategory: directory ? "directory" : trace.category,
+        barrierId: trace.barrierId,
+    };
+}
+function traceInput(sink, phase, category, barrierId) {
+    return sink === undefined ? undefined : { sink, phase, category, barrierId };
+}
+async function syncDirectory(directory, trace) {
+    const handle = await open(directory, constants.O_RDONLY);
+    try {
+        await traceDurabilityOperation({
+            context: traceContext(trace, true),
+            operation: "directory-sync",
+            run: () => handle.sync(),
+        });
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writeExclusive(target, bytes, mode = 0o600, trace) {
+    const handle = await open(target, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, mode);
+    try {
+        await traceDurabilityOperation({
+            context: traceContext(trace),
+            operation: "write",
+            bytes: bytes.byteLength,
+            run: () => handle.writeFile(bytes),
+        });
+        await traceDurabilityOperation({
+            context: traceContext(trace),
+            operation: "file-sync",
+            bytes: bytes.byteLength,
+            run: () => handle.sync(),
+        });
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writeJsonAtomic(target, value, trace) {
+    const directory = path.dirname(target);
+    const temporary = path.join(directory, `.tmp-${randomUUID()}`);
+    const bytes = Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
+    await writeExclusive(temporary, bytes, 0o600, trace);
+    await traceDurabilityOperation({
+        context: traceContext(trace),
+        operation: "rename",
+        bytes: bytes.byteLength,
+        run: () => rename(temporary, target),
+    });
+    await syncDirectory(directory, trace);
+}
+function journalWithDigest(journal) {
+    return { ...journal, journalDigest: sha256Digest(canonicalize(journal)) };
+}
+function verifyJournal(value) {
+    let journal;
+    try {
+        journal = parseTransactionJournal(value);
+    }
+    catch {
+        throw new FilesystemTransactionError("JOURNAL_CORRUPTED", "Transaction journal shape is invalid");
+    }
+    const { journalDigest, ...content } = journal;
+    if (journalDigest !== sha256Digest(canonicalize(content))) {
+        throw new FilesystemTransactionError("JOURNAL_CORRUPTED", "Transaction journal digest or shape is invalid");
+    }
+    const paths = new Set();
+    for (const [index, operation] of journal.operations.entries()) {
+        if (operation.index !== index ||
+            paths.has(operation.path) ||
+            (operation.kind === "create" && operation.before.kind !== "absent") ||
+            (operation.kind !== "create" && operation.before.kind !== "present") ||
+            (operation.kind !== "remove" && operation.desiredDigest === undefined) ||
+            (operation.kind === "remove" && operation.desiredDigest !== undefined)) {
+            throw new FilesystemTransactionError("JOURNAL_CORRUPTED", "Transaction journal operation is inconsistent");
+        }
+        paths.add(operation.path);
+    }
+    return journal;
+}
+async function readJournal(target) {
+    try {
+        return verifyJournal(JSON.parse(await readFile(target, "utf8")));
+    }
+    catch (error) {
+        if (error instanceof FilesystemTransactionError)
+            throw error;
+        throw new FilesystemTransactionError("JOURNAL_CORRUPTED", "Transaction journal cannot be read");
+    }
+}
+async function persistJournal(target, journal, trace) {
+    const { journalDigest: _previousDigest, ...content } = journal;
+    const next = journalWithDigest(content);
+    await writeJsonAtomic(target, next, trace);
+    return next;
+}
+async function resolveSafeProjectRoot(input) {
+    const resolved = path.resolve(input);
+    const parsed = path.parse(resolved);
+    if (resolved === parsed.root || resolved === path.resolve(homedir())) {
+        throw new FilesystemTransactionError("PROJECT_ROOT_UNSAFE", "Project root cannot be the filesystem root or user home");
+    }
+    const rootStat = await lstat(resolved);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new FilesystemTransactionError("PROJECT_ROOT_UNSAFE", "Project root must be a real directory");
+    }
+    const canonical = await realpath(resolved);
+    if (canonical !== resolved) {
+        throw new FilesystemTransactionError("PROJECT_ROOT_UNSAFE", "Project root cannot resolve through a symbolic link");
+    }
+    return canonical;
+}
+function resolveTarget(projectRoot, relativePath) {
+    if (((relativePath === ".dyyto" || relativePath.startsWith(".dyyto/")) && relativePath !== ".dyyto/application-config-binding.json") ||
+        relativePath.length === 0 ||
+        path.posix.isAbsolute(relativePath) ||
+        path.win32.isAbsolute(relativePath) ||
+        relativePath.includes("\\") ||
+        relativePath.split("/").some((segment) => segment === "." || segment === "..")) {
+        throw new FilesystemTransactionError("PROJECT_ROOT_UNSAFE", "Target path is unsafe", relativePath);
+    }
+    const target = path.resolve(projectRoot, ...relativePath.split("/"));
+    if (!target.startsWith(`${projectRoot}${path.sep}`)) {
+        throw new FilesystemTransactionError("PROJECT_ROOT_UNSAFE", "Target escapes project root", relativePath);
+    }
+    return target;
+}
+async function assertNoSymlink(projectRoot, relativePath) {
+    const segments = relativePath.split("/");
+    let current = projectRoot;
+    for (const segment of segments) {
+        current = path.join(current, segment);
+        try {
+            const item = await lstat(current);
+            if (item.isSymbolicLink()) {
+                throw new FilesystemTransactionError("PATH_SYMLINK_UNSAFE", "Symbolic links are not valid transaction targets", relativePath);
+            }
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+    }
+}
+async function readCurrent(target) {
+    try {
+        const item = await lstat(target);
+        if (!item.isFile() || item.isSymbolicLink()) {
+            throw new FilesystemTransactionError("PATH_SYMLINK_UNSAFE", "Transaction target must be a regular file");
+        }
+        const bytes = await readFile(target);
+        return { bytes, digest: sha256Digest(bytes), mode: item.mode & 0o777 };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function validatePlanIdentity(plan, approvedPlanId, now) {
+    parseChangePlan(plan);
+    const { planId: _planId, ...content } = plan;
+    if (calculatePlanId(content) !== plan.planId) {
+        throw new FilesystemTransactionError("PLAN_CONTENT_MISMATCH", "Plan content does not match planId");
+    }
+    if (plan.planId !== approvedPlanId) {
+        throw new FilesystemTransactionError("PLAN_APPROVAL_MISMATCH", "Approval does not match planId");
+    }
+    if (plan.state !== "reviewable") {
+        throw new FilesystemTransactionError("PLAN_PRECONDITION_FAILED", "Only reviewable plans can be applied");
+    }
+    if (Date.parse(plan.expiresAt) <= Date.parse(now)) {
+        throw new FilesystemTransactionError("PLAN_EXPIRED", "Plan has expired");
+    }
+}
+function supportedOperations(plan) {
+    const ready = plan.operations.filter((operation) => operation.disposition === "ready");
+    for (const operation of ready) {
+        if (!(((operation.ownership === "owned-file" || operation.ownership === "seed-file") && ["create", "replace", "remove"].includes(operation.kind)) ||
+            (operation.ownership === "managed-region" && operation.kind === "merge" && operation.regionId !== undefined))) {
+            throw new FilesystemTransactionError("OPERATION_UNSUPPORTED", "Operation ownership is not supported", operation.path);
+        }
+    }
+    return ready;
+}
+async function acquireLock(lockPath, lock, trace) {
+    try {
+        await writeExclusive(lockPath, Buffer.from(`${JSON.stringify(lock, null, 2)}\n`), 0o600, trace);
+        await syncDirectory(path.dirname(lockPath), trace);
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            throw new FilesystemTransactionError("TRANSACTION_ACTIVE", "Another platform transaction is active");
+        }
+        throw error;
+    }
+}
+async function readLock(lockPath) {
+    try {
+        const value = JSON.parse(await readFile(lockPath, "utf8"));
+        if (value.schemaVersion !== 1 ||
+            typeof value.transactionId !== "string" ||
+            typeof value.planId !== "string" ||
+            typeof value.startedAt !== "string" ||
+            typeof value.nonce !== "string") {
+            throw new Error("invalid lock");
+        }
+        return value;
+    }
+    catch {
+        throw new FilesystemTransactionError("JOURNAL_CORRUPTED", "Transaction lock is invalid");
+    }
+}
+function asPrepared(projectRoot, plan, transactionId) {
+    return {
+        [preparedToken]: true,
+        projectRoot,
+        plan,
+        transactionId,
+    };
+}
+export async function prepareApplyWithHooks(input, hooks) {
+    validatePlanIdentity(input.plan, input.approvedPlanId, input.now);
+    const projectRoot = await resolveSafeProjectRoot(input.projectRoot);
+    const operations = supportedOperations(input.plan);
+    const desiredPaths = new Set(input.plan.operations
+        .filter((operation) => operation.kind !== "remove" && operation.disposition !== "conflict")
+        .map((operation) => operation.path));
+    for (const key of input.desiredContents.keys()) {
+        if (!desiredPaths.has(key)) {
+            throw new FilesystemTransactionError("DESIRED_CONTENT_MISMATCH", "Desired content is not declared by the plan", key);
+        }
+    }
+    for (const operation of operations) {
+        resolveTarget(projectRoot, operation.path);
+        await assertNoSymlink(projectRoot, operation.path);
+        if (operation.kind !== "remove") {
+            const bytes = input.desiredContents.get(operation.path);
+            if (bytes === undefined || sha256Digest(bytes) !== operation.desiredDigest) {
+                throw new FilesystemTransactionError("DESIRED_CONTENT_MISMATCH", "Desired content digest does not match the plan", operation.path);
+            }
+        }
+    }
+    const paths = transactionPaths(projectRoot, input.plan.planId);
+    await mkdir(paths.platformDirectory, { recursive: true, mode: 0o700 });
+    await assertNoSymlink(projectRoot, ".dyyto");
+    const transactionId = randomUUID();
+    await acquireLock(paths.lock, {
+        schemaVersion: 1,
+        transactionId,
+        planId: input.plan.planId,
+        startedAt: input.now,
+        nonce: randomUUID(),
+    }, traceInput(hooks?.durabilityTrace, "prepare", "lock", `${transactionId}:prepare-lock`));
+    const maxFileBytes = input.limits?.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    const maxTransactionBytes = input.limits?.maxTransactionBytes ?? DEFAULT_MAX_TRANSACTION_BYTES;
+    let totalBytes = 0;
+    const journalOperations = [];
+    const persistedPreimageIndexes = [];
+    let createdTransactionDirectory = false;
+    try {
+        await runPrepareCheckpoint(hooks, "lock-created");
+        if (await exists(paths.transactionDirectory)) {
+            throw new FilesystemTransactionError("PLAN_PRECONDITION_FAILED", "This plan already has a transaction record");
+        }
+        await mkdir(paths.preimages, { recursive: true, mode: 0o700 });
+        await mkdir(paths.quarantine, { recursive: true, mode: 0o700 });
+        createdTransactionDirectory = true;
+        for (const [index, operation] of operations.entries()) {
+            const target = resolveTarget(projectRoot, operation.path);
+            await assertNoSymlink(projectRoot, operation.path);
+            const current = await readCurrent(target);
+            if (operation.kind === "create") {
+                if (current !== undefined) {
+                    throw new FilesystemTransactionError("PLAN_PRECONDITION_FAILED", "Create target now exists", operation.path, index);
+                }
+            }
+            else if (current === undefined || current.digest !== operation.baseDigest) {
+                throw new FilesystemTransactionError("PLAN_PRECONDITION_FAILED", "Target no longer matches plan base digest", operation.path, index);
+            }
+            let before = { kind: "absent" };
+            if (current !== undefined) {
+                totalBytes += current.bytes.byteLength;
+                if (current.bytes.byteLength > maxFileBytes || totalBytes > maxTransactionBytes) {
+                    throw new FilesystemTransactionError("PREIMAGE_LIMIT_EXCEEDED", "Preimage size limit exceeded", operation.path, index);
+                }
+                const preimage = path.join(paths.preimages, `${index}.bin`);
+                await writeExclusive(preimage, current.bytes, 0o600, traceInput(hooks?.durabilityTrace, "prepare", "preimage", `${transactionId}:preimage:${index}`));
+                persistedPreimageIndexes.push(index);
+                await runPrepareCheckpoint(hooks, "preimage-written-pending-directory-sync", index);
+                before = {
+                    kind: "present",
+                    digest: current.digest,
+                    mode: current.mode,
+                    preimageDigest: sha256Digest(current.bytes),
+                };
+            }
+            journalOperations.push({
+                index,
+                path: operation.path,
+                kind: operation.kind,
+                before,
+                ...(operation.desiredDigest === undefined ? {} : { desiredDigest: operation.desiredDigest }),
+                status: "pending",
+            });
+        }
+        if (persistedPreimageIndexes.length > 0) {
+            await syncDirectory(paths.preimages, traceInput(hooks?.durabilityTrace, "prepare", "directory", `${transactionId}:preimages-directory-batch`));
+            for (const index of persistedPreimageIndexes) {
+                await runPrepareCheckpoint(hooks, "preimage-persisted", index);
+            }
+        }
+        let journal = journalWithDigest({
+            schemaVersion: 1,
+            transactionId,
+            planId: input.plan.planId,
+            approvedPlanId: input.approvedPlanId,
+            projectRootDigest: sha256Digest(projectRoot),
+            state: "prepared",
+            createdAt: input.now,
+            updatedAt: input.now,
+            operations: journalOperations,
+        });
+        await writeJsonAtomic(paths.journal, journal, traceInput(hooks?.durabilityTrace, "prepare", "journal", `${transactionId}:journal-prepared`));
+        activeTransactions.set(transactionId, { desiredContents: input.desiredContents, journal });
+        await runPrepareCheckpoint(hooks, "journal-prepared");
+        return asPrepared(projectRoot, input.plan, transactionId);
+    }
+    catch (error) {
+        if (error instanceof CrashInjectionSignal) {
+            activeTransactions.delete(transactionId);
+            throw new FilesystemTransactionError("RECOVERY_REQUIRED", "Prepare was interrupted; recovery is required");
+        }
+        try {
+            if (createdTransactionDirectory) {
+                await rm(paths.transactionDirectory, { recursive: true, force: true });
+            }
+            await unlink(paths.lock);
+            await syncDirectory(paths.platformDirectory);
+        }
+        catch {
+            throw new FilesystemTransactionError("RECOVERY_REQUIRED", "Prepare failed and transaction lock could not be released");
+        }
+        throw error;
+    }
+}
+export async function prepareApply(input) {
+    return prepareApplyWithHooks(input);
+}
+async function markRecoveryRequired(paths, journal, operationIndex, sink) {
+    return persistJournal(paths.journal, {
+        ...journal,
+        state: "recovery-required",
+        updatedAt: new Date().toISOString(),
+        failure: { code: "APPLY_INTERRUPTED", ...(operationIndex === undefined ? {} : { operationIndex }) },
+    }, traceInput(sink, "apply", "journal", `${journal.transactionId}:recovery-required`));
+}
+async function applyOperation(projectRoot, paths, transactionId, operation, desiredContents, hooks) {
+    const target = resolveTarget(projectRoot, operation.path);
+    await assertNoSymlink(projectRoot, operation.path);
+    const current = await readCurrent(target);
+    if (operation.before.kind === "absent") {
+        if (current !== undefined) {
+            throw new FilesystemTransactionError("PLAN_PRECONDITION_FAILED", "Create target changed after prepare", operation.path, operation.index);
+        }
+    }
+    else if (current === undefined || current.digest !== operation.before.digest) {
+        throw new FilesystemTransactionError("PLAN_PRECONDITION_FAILED", "Target changed after prepare", operation.path, operation.index);
+    }
+    if (operation.kind === "remove") {
+        const quarantine = path.join(paths.quarantine, `${operation.index}.bin`);
+        const trace = traceInput(hooks?.durabilityTrace, "apply", "target", `${transactionId}:target:${operation.index}`);
+        await traceDurabilityOperation({
+            context: traceContext(trace),
+            operation: "rename",
+            run: () => rename(target, quarantine),
+        });
+        await hooks?.onCheckpoint?.("target-renamed-pending-directory-sync", operation.index);
+        return [path.dirname(target), paths.quarantine];
+    }
+    const bytes = desiredContents.get(operation.path);
+    if (bytes === undefined || sha256Digest(bytes) !== operation.desiredDigest) {
+        throw new FilesystemTransactionError("DESIRED_CONTENT_MISMATCH", "Desired bytes are missing or changed", operation.path, operation.index);
+    }
+    await mkdir(path.dirname(target), { recursive: true });
+    await assertNoSymlink(projectRoot, operation.path);
+    const temporary = path.join(path.dirname(target), `.dyyto-${transactionId}-${operation.index}.tmp`);
+    const trace = traceInput(hooks?.durabilityTrace, "apply", "target", `${transactionId}:target:${operation.index}`);
+    await writeExclusive(temporary, bytes, operation.before.kind === "present" ? operation.before.mode & 0o777 : 0o644, trace);
+    await hooks?.onCheckpoint?.("temporary-file-synced", operation.index);
+    await traceDurabilityOperation({
+        context: traceContext(trace),
+        operation: "rename",
+        bytes: bytes.byteLength,
+        run: () => rename(temporary, target),
+    });
+    await hooks?.onCheckpoint?.("target-renamed-pending-directory-sync", operation.index);
+    return [path.dirname(target)];
+}
+export async function applyPreparedWithHooks(prepared, hooks) {
+    const internal = activeTransactions.get(prepared.transactionId);
+    if (internal === undefined || prepared[preparedToken] !== true) {
+        throw new FilesystemTransactionError("PLAN_PRECONDITION_FAILED", "Prepared transaction is not active");
+    }
+    const paths = transactionPaths(prepared.projectRoot, prepared.plan.planId);
+    let journal = await persistJournal(paths.journal, {
+        ...internal.journal,
+        state: "applying",
+        updatedAt: new Date().toISOString(),
+    }, traceInput(hooks?.durabilityTrace, "apply", "journal", `${prepared.transactionId}:applying`));
+    try {
+        await hooks?.onCheckpoint?.("prepared");
+        const directoryBarriers = new Map();
+        for (let offset = 0; offset < journal.operations.length; offset += APPLY_DURABILITY_BATCH_SIZE) {
+            const operationBatch = journal.operations.slice(offset, offset + APPLY_DURABILITY_BATCH_SIZE);
+            const settled = await Promise.allSettled(operationBatch.map((operation) => applyOperation(prepared.projectRoot, paths, prepared.transactionId, operation, internal.desiredContents, hooks)));
+            const failure = settled.find((result) => result.status === "rejected");
+            if (failure?.status === "rejected")
+                throw failure.reason;
+            for (const result of settled) {
+                if (result.status !== "fulfilled")
+                    continue;
+                for (const directory of result.value) {
+                    if (!directoryBarriers.has(directory)) {
+                        directoryBarriers.set(directory, traceInput(hooks?.durabilityTrace, "apply", "directory", `${prepared.transactionId}:target-directory-batch`));
+                    }
+                }
+            }
+        }
+        for (const [directory, trace] of directoryBarriers) {
+            await syncDirectory(directory, trace);
+        }
+        for (const operation of journal.operations) {
+            await hooks?.onCheckpoint?.("target-renamed", operation.index);
+            operation.status = "applied";
+            await hooks?.onCheckpoint?.("operation-applied", operation.index);
+        }
+        journal = await persistJournal(paths.journal, {
+            ...journal,
+            operations: journal.operations,
+            updatedAt: new Date().toISOString(),
+        }, traceInput(hooks?.durabilityTrace, "apply", "journal", `${prepared.transactionId}:operation-batch`));
+        for (const operation of journal.operations) {
+            await hooks?.onCheckpoint?.("operation-journaled", operation.index);
+        }
+        journal = await persistJournal(paths.journal, {
+            ...journal,
+            state: "applied",
+            updatedAt: new Date().toISOString(),
+        }, traceInput(hooks?.durabilityTrace, "apply", "journal", `${prepared.transactionId}:applied`));
+        await hooks?.onCheckpoint?.("applied");
+        await unlink(paths.lock);
+        await syncDirectory(paths.platformDirectory);
+        activeTransactions.delete(prepared.transactionId);
+        return snapshot(journal);
+    }
+    catch (error) {
+        journal = await markRecoveryRequired(paths, journal, error instanceof FilesystemTransactionError ? error.operationIndex : undefined, hooks?.durabilityTrace);
+        activeTransactions.set(prepared.transactionId, {
+            desiredContents: internal.desiredContents,
+            journal,
+        });
+        throw new FilesystemTransactionError("RECOVERY_REQUIRED", "Apply was interrupted; recovery is required");
+    }
+}
+export async function applyPrepared(prepared) {
+    return applyPreparedWithHooks(prepared);
+}
+function snapshot(journal) {
+    return {
+        transactionId: journal.transactionId,
+        planId: journal.planId,
+        state: journal.state,
+        operations: journal.operations,
+    };
+}
+export async function inspectTransaction(input) {
+    const projectRoot = await resolveSafeProjectRoot(input.projectRoot);
+    const paths = transactionPaths(projectRoot, input.planId);
+    if (!(await exists(paths.journal))) {
+        if (!(await exists(paths.lock)))
+            return null;
+        const lock = await readLock(paths.lock);
+        if (lock.planId !== input.planId)
+            return null;
+        return {
+            transactionId: lock.transactionId,
+            planId: lock.planId,
+            state: "preparing",
+            operations: [],
+        };
+    }
+    return snapshot(await readJournal(paths.journal));
+}
+async function restoreBytes(target, bytes, mode) {
+    await mkdir(path.dirname(target), { recursive: true });
+    const temporary = path.join(path.dirname(target), `.dyyto-recover-${randomUUID()}.tmp`);
+    await writeExclusive(temporary, bytes, mode & 0o777);
+    await rename(temporary, target);
+    await chmod(target, mode & 0o777);
+    await syncDirectory(path.dirname(target));
+}
+export async function recoverTransactionWithHooks(input) {
+    const projectRoot = await resolveSafeProjectRoot(input.projectRoot);
+    const paths = transactionPaths(projectRoot, input.planId);
+    if (!(await exists(paths.journal))) {
+        if (!(await exists(paths.lock))) {
+            throw new FilesystemTransactionError("JOURNAL_CORRUPTED", "No transaction record exists");
+        }
+        const lock = await readLock(paths.lock);
+        if (lock.planId !== input.planId) {
+            throw new FilesystemTransactionError("TRANSACTION_ACTIVE", "Transaction lock belongs to another plan");
+        }
+        await rm(paths.transactionDirectory, { recursive: true, force: true });
+        await mkdir(paths.transactionDirectory, { recursive: true, mode: 0o700 });
+        const recovered = journalWithDigest({
+            schemaVersion: 1,
+            transactionId: lock.transactionId,
+            planId: lock.planId,
+            approvedPlanId: lock.planId,
+            projectRootDigest: sha256Digest(projectRoot),
+            state: "recovered",
+            createdAt: lock.startedAt,
+            updatedAt: input.now,
+            operations: [],
+        });
+        await writeJsonAtomic(paths.journal, recovered);
+        await unlink(paths.lock);
+        await syncDirectory(paths.platformDirectory);
+        return snapshot(recovered);
+    }
+    let journal = await readJournal(paths.journal);
+    if (journal.state === "recovered")
+        return snapshot(journal);
+    if (journal.state === "applied") {
+        for (const operation of journal.operations) {
+            const current = await readCurrent(resolveTarget(projectRoot, operation.path));
+            const matchesAppliedState = operation.kind === "remove"
+                ? current === undefined
+                : current?.digest === operation.desiredDigest;
+            if (!matchesAppliedState) {
+                throw new FilesystemTransactionError("RECOVERY_CONFLICT", "Completed transaction target changed before lock cleanup", operation.path, operation.index);
+            }
+        }
+        if (await exists(paths.lock)) {
+            const lock = await readLock(paths.lock);
+            if (lock.transactionId !== journal.transactionId || lock.planId !== journal.planId) {
+                throw new FilesystemTransactionError("TRANSACTION_ACTIVE", "Transaction lock belongs to another transaction");
+            }
+            await unlink(paths.lock);
+            await syncDirectory(paths.platformDirectory);
+        }
+        activeTransactions.delete(journal.transactionId);
+        return snapshot(journal);
+    }
+    if (journal.projectRootDigest !== sha256Digest(projectRoot)) {
+        throw new FilesystemTransactionError("JOURNAL_CORRUPTED", "Journal belongs to a different project root");
+    }
+    if (await exists(paths.lock)) {
+        const lock = await readLock(paths.lock);
+        if (lock.transactionId !== journal.transactionId || lock.planId !== journal.planId) {
+            throw new FilesystemTransactionError("TRANSACTION_ACTIVE", "Transaction lock belongs to another transaction");
+        }
+    }
+    else {
+        await acquireLock(paths.lock, {
+            schemaVersion: 1,
+            transactionId: journal.transactionId,
+            planId: journal.planId,
+            startedAt: input.now,
+            nonce: randomUUID(),
+        });
+    }
+    journal = await persistJournal(paths.journal, {
+        ...journal,
+        state: "recovering",
+        updatedAt: input.now,
+    });
+    for (const operation of [...journal.operations].reverse()) {
+        if (operation.status === "restored")
+            continue;
+        const target = resolveTarget(projectRoot, operation.path);
+        await assertNoSymlink(projectRoot, operation.path);
+        if (operation.kind !== "remove") {
+            const temporary = path.join(path.dirname(target), `.dyyto-${journal.transactionId}-${operation.index}.tmp`);
+            if (await exists(temporary)) {
+                const temporaryState = await readCurrent(temporary);
+                if (temporaryState?.digest !== operation.desiredDigest) {
+                    throw new FilesystemTransactionError("RECOVERY_CONFLICT", "Transaction temporary file was modified externally", operation.path, operation.index);
+                }
+                await unlink(temporary);
+                await syncDirectory(path.dirname(temporary));
+            }
+        }
+        const current = await readCurrent(target);
+        if (operation.before.kind === "absent") {
+            if (current !== undefined) {
+                if (current.digest !== operation.desiredDigest) {
+                    throw new FilesystemTransactionError("RECOVERY_CONFLICT", "Recovery would overwrite external content", operation.path, operation.index);
+                }
+                await unlink(target);
+                await syncDirectory(path.dirname(target));
+            }
+        }
+        else {
+            if (current?.digest === operation.before.digest) {
+                // Already restored.
+            }
+            else {
+                const quarantine = path.join(paths.quarantine, `${operation.index}.bin`);
+                const desiredWasApplied = current?.digest === operation.desiredDigest;
+                const removedWasApplied = operation.kind === "remove" && current === undefined && (await exists(quarantine));
+                const approvedConflict = input.approvedConflicts?.find((item) => item.path === operation.path && item.currentDigest === current?.digest);
+                if (!desiredWasApplied && !removedWasApplied && !approvedConflict) {
+                    throw new FilesystemTransactionError("RECOVERY_CONFLICT", "Recovery would overwrite external content", operation.path, operation.index);
+                }
+                const preimage = await readFile(path.join(paths.preimages, `${operation.index}.bin`));
+                if (sha256Digest(preimage) !== operation.before.preimageDigest) {
+                    throw new FilesystemTransactionError("JOURNAL_CORRUPTED", "Preimage digest is invalid", operation.path, operation.index);
+                }
+                await restoreBytes(target, preimage, operation.before.mode);
+                if (removedWasApplied)
+                    await rm(quarantine, { force: true });
+            }
+        }
+        operation.status = "restored";
+        journal = await persistJournal(paths.journal, {
+            ...journal,
+            operations: journal.operations,
+            updatedAt: input.now,
+        });
+        await input.hooks?.onCheckpoint?.("operation-journaled", operation.index);
+    }
+    journal = await persistJournal(paths.journal, {
+        ...journal,
+        state: "recovered",
+        updatedAt: input.now,
+    });
+    await unlink(paths.lock);
+    await syncDirectory(paths.platformDirectory);
+    activeTransactions.delete(journal.transactionId);
+    return snapshot(journal);
+}
+export async function recoverTransaction(input) {
+    return recoverTransactionWithHooks(input);
+}
+export async function recoverTransactionWithApprovedConflicts(input) {
+    if (input.approvedConflicts.length === 0 || new Set(input.approvedConflicts.map((item) => item.path)).size !== input.approvedConflicts.length || input.approvedConflicts.some((item) => !/^sha256:[a-f0-9]{64}$/u.test(item.currentDigest)))
+        throw new FilesystemTransactionError("PLAN_PRECONDITION_FAILED", "Recovery override conflicts are invalid");
+    return recoverTransactionWithHooks(input);
+}
+/**
+ * Rolls back a fully applied transaction when a required external adoption step
+ * (for example package installation) fails. The same preimages and drift checks
+ * used by crash recovery apply; user changes are never overwritten.
+ */
+export async function rollbackAppliedTransaction(input) {
+    const projectRoot = await resolveSafeProjectRoot(input.projectRoot);
+    const paths = transactionPaths(projectRoot, input.planId);
+    let journal = await readJournal(paths.journal);
+    if (journal.state === "recovered")
+        return snapshot(journal);
+    if (journal.state !== "applied")
+        throw new FilesystemTransactionError("PLAN_PRECONDITION_FAILED", "Only an applied transaction can be rolled back");
+    let conflict;
+    for (const operation of journal.operations) {
+        const current = await readCurrent(resolveTarget(projectRoot, operation.path));
+        const matchesApplied = operation.kind === "remove" ? current === undefined : current?.digest === operation.desiredDigest;
+        const alreadyRestored = operation.before.kind === "absent" ? current === undefined : current?.digest === operation.before.digest;
+        if (!matchesApplied && !alreadyRestored) {
+            conflict = operation;
+            break;
+        }
+    }
+    await acquireLock(paths.lock, { schemaVersion: 1, transactionId: journal.transactionId, planId: journal.planId, startedAt: input.now, nonce: randomUUID() });
+    journal = await persistJournal(paths.journal, { ...journal, state: "recovery-required", updatedAt: input.now, failure: { code: input.failureCode } });
+    if (conflict !== undefined)
+        throw new FilesystemTransactionError("RECOVERY_CONFLICT", "Rollback would overwrite external content", conflict.path, conflict.index);
+    activeTransactions.set(journal.transactionId, { desiredContents: new Map(), journal });
+    return recoverTransaction({ projectRoot, planId: input.planId, now: input.now });
+}
+//# sourceMappingURL=filesystem-transaction.js.map