@playcraft/cli 0.1.49-beta → 0.1.50-beta

package/dist/workspace-runtime/workspaces/asset-transfer-storage.js

@@ -0,0 +1,389 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, open, readdir, realpath, rename, rm, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ASSET_TRANSFER_BODY_MAX_BYTES, ASSET_TRANSFER_CHUNK_BYTES, ASSET_TRANSFER_FILE_MAX_BYTES, assetBundleReceiptSchema, assetTransferChunkSchema, assetTransferManifestSchema, assetTransferStatusSchema, hashAssetTransferManifest, isAssetBundleReceiptForManifest, } from '@playcraft/common/cloud-workspace/runtime';
+export class AssetTransferError extends Error {
+    code;
+    status;
+    constructor(code, status = 409) {
+        super(code);
+        this.code = code;
+        this.status = status;
+    }
+}
+const locks = new Map();
+export const ASSET_TRANSFER_MAX_ACTIVE = 4;
+export const ASSET_TRANSFER_TTL_MS = 24 * 60 * 60 * 1000;
+export const assetTransferMissing = (error) => error?.code === 'ENOENT';
+const failPath = () => { throw new AssetTransferError('invalid_workspace_path', 400); };
+/** Every path component is checked before use, including the private transfer directory. */
+export async function safeAssetTransferDirectory(root, path = '', create = false) {
+    const rootStat = await lstat(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || await realpath(root) !== root)
+        failPath();
+    let current = root;
+    for (const part of path.split('/').filter(Boolean)) {
+        if (part === '.' || part === '..' || /[\\:\x00-\x1f\x7f]/.test(part))
+            failPath();
+        current = join(current, part);
+        if (create)
+            await mkdir(current, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+                throw error; });
+        const stat = await lstat(current);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(current) !== current)
+            failPath();
+    }
+    return current;
+}
+export async function syncAssetTransferDirectory(path) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function hashAssetTransferFile(path, limit = ASSET_TRANSFER_FILE_MAX_BYTES, allowLinks = false, expectedChunks) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || !allowLinks && before.nlink !== 1 || before.size > limit)
+            failPath();
+        const hash = createHash('sha256');
+        let chunkHash = createHash('sha256'), chunkBytes = 0, chunkIndex = 0;
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        let size = 0;
+        for (;;) {
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, size);
+            if (!bytesRead)
+                break;
+            size += bytesRead;
+            if (size > limit)
+                throw new AssetTransferError('asset_transfer_too_large', 413);
+            hash.update(buffer.subarray(0, bytesRead));
+            if (expectedChunks) {
+                let offset = 0;
+                while (offset < bytesRead) {
+                    const length = Math.min(bytesRead - offset, ASSET_TRANSFER_CHUNK_BYTES - chunkBytes);
+                    chunkHash.update(buffer.subarray(offset, offset + length));
+                    chunkBytes += length;
+                    offset += length;
+                    if (chunkBytes === ASSET_TRANSFER_CHUNK_BYTES) {
+                        if (chunkHash.digest('hex') !== expectedChunks[chunkIndex++])
+                            throw new AssetTransferError('asset_transfer_content_mismatch');
+                        chunkHash = createHash('sha256');
+                        chunkBytes = 0;
+                    }
+                }
+            }
+        }
+        const after = await handle.stat();
+        if (size !== before.size || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+            throw new AssetTransferError('content_conflict');
+        if (expectedChunks && (chunkBytes && chunkHash.digest('hex') !== expectedChunks[chunkIndex++] || chunkIndex !== expectedChunks.length))
+            throw new AssetTransferError('asset_transfer_content_mismatch');
+        return { dev: before.dev, ino: before.ino, size, contentHash: hash.digest('hex') };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function saveAssetTransfer(transfer) {
+    await safeAssetTransferDirectory(transfer.directory);
+    const temporary = join(transfer.directory, `record-${randomUUID()}.tmp`);
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(transfer.record));
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await safeAssetTransferDirectory(transfer.directory);
+    await rename(temporary, join(transfer.directory, 'record.json'));
+    await syncAssetTransferDirectory(transfer.directory);
+}
+async function readRecord(directory) {
+    const handle = await open(join(directory, 'record.json'), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || ![1, 2].includes(stat.nlink) || stat.size > ASSET_TRANSFER_BODY_MAX_BYTES * 4)
+            throw new AssetTransferError('invalid_asset_transfer', 400);
+        const value = JSON.parse(await handle.readFile('utf8'));
+        const manifest = assetTransferManifestSchema.parse(value.manifest);
+        if (value.version !== 1 || value.manifestHash !== hashAssetTransferManifest(manifest)
+            || !['uploading', 'publishing', 'completed'].includes(value.status))
+            throw new AssetTransferError('invalid_asset_transfer', 400);
+        if (value.receipt)
+            value.receipt = assetBundleReceiptSchema.parse(value.receipt);
+        if (!Number.isFinite(value.createdAt) || value.status === 'completed'
+            && !isAssetBundleReceiptForManifest(manifest, value.manifestHash, value.receipt)
+            || value.status !== 'completed' && value.receipt)
+            throw new AssetTransferError('invalid_asset_transfer', 400);
+        if (stat.nlink === 2) {
+            // Creation uses an exclusive link so the same identifier can never replace a session.
+            // A crash before unlinking that private temporary name must remain resumable.
+            let repaired = false;
+            for (const name of await readdir(directory)) {
+                if (!/^create-[a-f0-9-]{36}\.tmp$/i.test(name))
+                    continue;
+                const alias = join(directory, name), linked = await lstat(alias);
+                if (!linked.isFile() || linked.isSymbolicLink() || linked.dev !== stat.dev || linked.ino !== stat.ino || linked.nlink !== 2)
+                    continue;
+                await unlink(alias);
+                await syncAssetTransferDirectory(directory);
+                repaired = true;
+                break;
+            }
+            if (!repaired || (await handle.stat()).nlink !== 1)
+                throw new AssetTransferError('invalid_asset_transfer', 400);
+        }
+        value.manifest = manifest;
+        return value;
+    }
+    finally {
+        await handle.close();
+    }
+}
+function validId(id) {
+    if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(id))
+        throw new AssetTransferError('invalid_asset_transfer', 400);
+}
+export async function withAssetTransfer(root, scope, id, action) {
+    validId(id);
+    const key = `${root}\0${id}`;
+    const previous = locks.get(key) ?? Promise.resolve();
+    const next = previous.catch(() => undefined).then(async () => {
+        const rootReal = await realpath(root);
+        let directory;
+        try {
+            directory = await safeAssetTransferDirectory(rootReal, `.playcraft-temp/asset-transfers/${id}`);
+        }
+        catch (error) {
+            if (assetTransferMissing(error))
+                throw new AssetTransferError('asset_transfer_not_found', 404);
+            throw error;
+        }
+        let record;
+        try {
+            record = await readRecord(directory);
+        }
+        catch (error) {
+            if (assetTransferMissing(error))
+                throw new AssetTransferError('asset_transfer_not_found', 404);
+            throw error;
+        }
+        if (record.manifest.transferId !== id || Object.keys(scope).some(key => record.scope?.[key] !== scope[key]))
+            throw new AssetTransferError('asset_transfer_not_found', 404);
+        if (record.status === 'uploading' && !record.publication && Date.now() - record.createdAt > ASSET_TRANSFER_TTL_MS) {
+            await rm(directory, { recursive: true });
+            throw new AssetTransferError('asset_transfer_expired', 410);
+        }
+        return action({ root: rootReal, directory, record });
+    });
+    locks.set(key, next);
+    try {
+        return await next;
+    }
+    finally {
+        if (locks.get(key) === next)
+            locks.delete(key);
+    }
+}
+async function saveProgress(transfer, files) {
+    const temporary = join(transfer.directory, `progress-${randomUUID()}.tmp`);
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(files));
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await safeAssetTransferDirectory(transfer.directory);
+    await rename(temporary, join(transfer.directory, 'progress.json'));
+    await syncAssetTransferDirectory(transfer.directory);
+}
+async function readProgress(transfer) {
+    try {
+        const handle = await open(join(transfer.directory, 'progress.json'), constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.nlink !== 1 || stat.size > 256 * 1024)
+                return undefined;
+            const files = JSON.parse(await handle.readFile('utf8'));
+            if (!Array.isArray(files) || files.length !== transfer.record.manifest.files.length
+                || files.some((file, index) => file.fileIndex !== index || !Array.isArray(file.receivedChunks)
+                    || file.receivedChunks.some(chunk => !Number.isInteger(chunk) || chunk < 0 || chunk >= transfer.record.manifest.files[index].chunkHashes.length)))
+                return undefined;
+            return files;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function assetTransferView(transfer, scan = true) {
+    const { record } = transfer;
+    let files = record.status === 'completed'
+        ? record.manifest.files.map((file, fileIndex) => ({ fileIndex, receivedChunks: file.chunkHashes.map((_, index) => index) }))
+        : scan ? undefined : await readProgress(transfer);
+    if (!files) {
+        files = [];
+        for (const [fileIndex, file] of record.manifest.files.entries()) {
+            const receivedChunks = [];
+            for (const [chunkIndex, expected] of file.chunkHashes.entries()) {
+                try {
+                    await safeAssetTransferDirectory(transfer.directory, 'chunks');
+                    const chunk = await hashAssetTransferFile(join(transfer.directory, 'chunks', `${fileIndex}-${chunkIndex}`), ASSET_TRANSFER_CHUNK_BYTES);
+                    const size = Math.min(ASSET_TRANSFER_CHUNK_BYTES, file.size - chunkIndex * ASSET_TRANSFER_CHUNK_BYTES);
+                    if (chunk.contentHash === expected && chunk.size === size)
+                        receivedChunks.push(chunkIndex);
+                }
+                catch (error) {
+                    if (!assetTransferMissing(error))
+                        throw error;
+                }
+            }
+            files.push({ fileIndex, receivedChunks });
+        }
+        await saveProgress(transfer, files);
+    }
+    const ready = files.every(file => file.receivedChunks.length === record.manifest.files[file.fileIndex].chunkHashes.length);
+    return assetTransferStatusSchema.parse({ transferId: record.manifest.transferId, manifestHash: record.manifestHash,
+        status: record.status === 'uploading' ? ready ? 'ready' : 'uploading' : record.status, files,
+        ...(record.receipt ? { receipt: record.receipt } : {}) });
+}
+async function createAssetTransferUnlocked(root, scope, input) {
+    const manifest = assetTransferManifestSchema.parse(input);
+    if ([...manifest.files.map(file => file.path), ...(manifest.directories ?? [])].some(path => /[\x00-\x1f\x7f]/.test(path)))
+        failPath();
+    const rootReal = await realpath(root);
+    const parent = await safeAssetTransferDirectory(rootReal, '.playcraft-temp/asset-transfers', true);
+    const present = await lstat(join(parent, manifest.transferId)).catch(error => { if (assetTransferMissing(error))
+        return undefined; throw error; });
+    if (!present) {
+        let active = 0;
+        for (const item of await readdir(parent, { withFileTypes: true })) {
+            if (!item.isDirectory())
+                continue;
+            try {
+                const directory = await safeAssetTransferDirectory(parent, item.name);
+                const record = await readRecord(directory);
+                if (record.status === 'uploading' && !record.publication && Date.now() - record.createdAt > ASSET_TRANSFER_TTL_MS) {
+                    await rm(directory, { recursive: true });
+                    continue;
+                }
+                if (record.status !== 'completed')
+                    active++;
+            }
+            catch {
+                active++;
+            }
+        }
+        if (active >= ASSET_TRANSFER_MAX_ACTIVE)
+            throw new AssetTransferError('asset_transfer_session_limit');
+    }
+    const directory = await safeAssetTransferDirectory(rootReal, `.playcraft-temp/asset-transfers/${manifest.transferId}`, true);
+    const record = { version: 1, createdAt: Date.now(), scope, manifest, manifestHash: hashAssetTransferManifest(manifest), status: 'uploading' };
+    const temporary = join(directory, `create-${randomUUID()}.tmp`);
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(record));
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await link(temporary, join(directory, 'record.json'));
+        await syncAssetTransferDirectory(directory);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    finally {
+        await unlink(temporary).catch(() => undefined);
+    }
+    return withAssetTransfer(rootReal, scope, manifest.transferId, async (transfer) => {
+        if (transfer.record.manifestHash !== record.manifestHash)
+            throw new AssetTransferError('asset_transfer_manifest_conflict');
+        return assetTransferView(transfer);
+    });
+}
+export async function createAssetTransfer(root, scope, input) {
+    const key = `${await realpath(root)}\0create`;
+    const previous = locks.get(key) ?? Promise.resolve();
+    const next = previous.catch(() => undefined).then(() => createAssetTransferUnlocked(root, scope, input));
+    locks.set(key, next);
+    try {
+        return await next;
+    }
+    finally {
+        if (locks.get(key) === next)
+            locks.delete(key);
+    }
+}
+export const getAssetTransfer = (root, scope, id) => withAssetTransfer(root, scope, id, assetTransferView);
+async function acknowledgeChunk(transfer, fileIndex, chunkIndex) {
+    const files = await readProgress(transfer);
+    if (!files)
+        return assetTransferView(transfer);
+    if (!files[fileIndex].receivedChunks.includes(chunkIndex)) {
+        files[fileIndex].receivedChunks = [...files[fileIndex].receivedChunks, chunkIndex].sort((a, b) => a - b);
+        await saveProgress(transfer, files);
+    }
+    return assetTransferView(transfer, false);
+}
+export async function putAssetTransferChunk(root, scope, id, input) {
+    const chunk = assetTransferChunkSchema.parse(input);
+    return withAssetTransfer(root, scope, id, async (transfer) => {
+        if (transfer.record.status === 'publishing')
+            throw new AssetTransferError('asset_transfer_busy');
+        const file = transfer.record.manifest.files[chunk.fileIndex];
+        const expected = file?.chunkHashes[chunk.chunkIndex];
+        const bytes = Buffer.from(chunk.contentBase64, 'base64');
+        if (!file || !expected || bytes.length !== Math.min(ASSET_TRANSFER_CHUNK_BYTES, file.size - chunk.chunkIndex * ASSET_TRANSFER_CHUNK_BYTES)
+            || createHash('sha256').update(bytes).digest('hex') !== expected || bytes.toString('base64') !== chunk.contentBase64)
+            throw new AssetTransferError('asset_transfer_chunk_mismatch');
+        if (transfer.record.status === 'completed')
+            return assetTransferView(transfer, false);
+        const directory = await safeAssetTransferDirectory(transfer.directory, 'chunks', true);
+        const destination = join(directory, `${chunk.fileIndex}-${chunk.chunkIndex}`);
+        try {
+            const stored = await hashAssetTransferFile(destination, ASSET_TRANSFER_CHUNK_BYTES);
+            if (stored.size === bytes.length && stored.contentHash === expected)
+                return acknowledgeChunk(transfer, chunk.fileIndex, chunk.chunkIndex);
+        }
+        catch (error) {
+            if (!assetTransferMissing(error))
+                throw error;
+        }
+        const temporary = join(directory, `chunk-${randomUUID()}.tmp`);
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await safeAssetTransferDirectory(transfer.directory, 'chunks');
+        await rename(temporary, destination);
+        await syncAssetTransferDirectory(directory);
+        return acknowledgeChunk(transfer, chunk.fileIndex, chunk.chunkIndex);
+    });
+}
+export const cancelAssetTransfer = (root, scope, id) => withAssetTransfer(root, scope, id, async (transfer) => {
+    if (transfer.record.status === 'publishing')
+        throw new AssetTransferError('asset_transfer_busy');
+    await safeAssetTransferDirectory(transfer.directory);
+    await rm(transfer.directory, { recursive: true });
+    return { cancelled: true };
+});

package/dist/workspace-runtime/workspaces/directory-mutations.js

@@ -0,0 +1,238 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, realpath, rename, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { directoryDeletePayloadSchema, directoryRenamePayloadSchema, hashOperationPayload, isMutableWorkspaceDirectoryPath, } from '@playcraft/common/cloud-workspace/runtime';
+import { safeAssetTransferDirectory, syncAssetTransferDirectory } from './asset-transfer-storage.js';
+export class DirectoryMutationError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const fail = (code) => { throw new DirectoryMutationError(code); };
+const missing = (error) => error?.code === 'ENOENT';
+const identitySchema = z.object({ dev: z.number().nonnegative(), ino: z.number().nonnegative() }).strict();
+const receiptSchema = z.object({ operationId: z.string().min(1).max(128), kind: z.enum(['directory.rename', 'directory.delete']),
+    path: z.string(), newPath: z.string().optional(), revision: z.number().int().nonnegative(), recoveryPath: z.string().optional() }).strict();
+const recordSchema = z.object({ version: z.literal(1), scope: z.string(), operationId: z.string().min(1).max(128),
+    payloadHash: z.string().regex(/^[a-f0-9]{64}$/), kind: z.enum(['directory.rename', 'directory.delete']),
+    operationPayloadHash: z.string().regex(/^[a-f0-9]{64}$/), payload: z.unknown(),
+    path: z.string(), newPath: z.string().optional(), source: identitySchema, reservation: identitySchema.optional(),
+    revision: z.number().int().nonnegative(), phase: z.enum(['prepared', 'completed']), receipt: receiptSchema.optional() }).strict();
+async function identity(path) {
+    const stat = await lstat(path).catch(error => { if (!missing(error))
+        throw error; return undefined; });
+    if (!stat)
+        return undefined;
+    if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(path) !== path)
+        fail('invalid_workspace_path');
+    return { dev: stat.dev, ino: stat.ino };
+}
+function same(left, right) { return Boolean(left && right && left.dev === right.dev && left.ino === right.ino); }
+/** Reject redirected entries and managed descendants too: renaming their parent must not bypass path protection. */
+async function validateTree(root, path) {
+    await safeAssetTransferDirectory(root, path);
+    const target = join(root, ...path.split('/'));
+    const original = await identity(target);
+    if (!original)
+        return fail('directory_not_found');
+    const visit = async (current, relative) => {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            const child = join(current, entry.name), childPath = `${relative}/${entry.name}`;
+            const stat = await lstat(child);
+            if (stat.isSymbolicLink() || !stat.isDirectory() && !stat.isFile()
+                || stat.isDirectory() && !isMutableWorkspaceDirectoryPath(childPath))
+                fail('invalid_workspace_path');
+            if (stat.isDirectory()) {
+                await safeAssetTransferDirectory(root, childPath);
+                await visit(child, childPath);
+            }
+        }
+    };
+    await visit(target, path);
+    if (!same(original, await identity(target)))
+        fail('directory_conflict');
+    return original;
+}
+async function saveRecord(directory, record) {
+    await safeAssetTransferDirectory(directory);
+    const temporary = join(directory, `${randomUUID()}.tmp`);
+    const file = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+    try {
+        await file.writeFile(JSON.stringify(record));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    await safeAssetTransferDirectory(directory);
+    await rename(temporary, join(directory, 'record.json'));
+    await syncAssetTransferDirectory(directory);
+}
+async function readRecord(directory) {
+    let handle;
+    try {
+        handle = await open(join(directory, 'record.json'), constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (missing(error))
+            return undefined;
+        throw error;
+    }
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 64 * 1024)
+            fail('directory_recovery_required');
+        return recordSchema.parse(JSON.parse(await handle.readFile('utf8')));
+    }
+    catch {
+        return fail('directory_recovery_required');
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function cleanupRemoved(directory, record) {
+    if (record.kind !== 'directory.delete' || !record.receipt?.recoveryPath)
+        return;
+    try {
+        await safeAssetTransferDirectory(directory);
+        const destination = join(directory, 'removed'), stored = await identity(destination);
+        if (stored) {
+            if (!same(stored, record.source))
+                return;
+            await rm(destination, { recursive: true, force: false });
+            await syncAssetTransferDirectory(directory);
+        }
+        delete record.receipt.recoveryPath;
+        await saveRecord(directory, record);
+    }
+    catch { /* A retained private backup is disclosed in the receipt, never mistaken for a fresh source. */ }
+}
+/** A durable identity-bound intent makes a retry independent of any directory recreated at the old path. */
+export async function mutateWorkspaceDirectory(root, kind, input, options) {
+    const parsed = kind === 'directory.rename' ? directoryRenamePayloadSchema.safeParse(input) : directoryDeletePayloadSchema.safeParse(input);
+    if (!parsed.success || !options.operationId || options.operationId.length > 128)
+        return fail('invalid_workspace_path');
+    const payload = parsed.data, newPath = 'newName' in payload
+        ? [...payload.path.split('/').slice(0, -1), payload.newName].join('/') : undefined;
+    if (newPath === payload.path)
+        return fail('directory_exists');
+    if ((await lstat(root)).isSymbolicLink())
+        return fail('invalid_workspace_path');
+    root = await realpath(root);
+    await safeAssetTransferDirectory(root);
+    const key = createHash('sha256').update(`${options.scope}\0${options.operationId}`).digest('hex');
+    const relativeDirectory = `.playcraft-temp/directory-mutations/${key}`;
+    const directory = options.recoverOnly
+        ? await safeAssetTransferDirectory(root, relativeDirectory).catch(error => { if (missing(error))
+            return undefined; throw error; })
+        : await safeAssetTransferDirectory(root, relativeDirectory, true);
+    if (!directory)
+        return undefined;
+    let record = await readRecord(directory);
+    const payloadHash = hashOperationPayload({ kind, payload });
+    if (record && (record.operationId !== options.operationId || record.scope !== options.scope || record.payloadHash !== payloadHash
+        || record.operationPayloadHash !== (options.operationPayloadHash ?? hashOperationPayload(input))
+        || record.path !== payload.path || record.kind !== kind || record.newPath !== newPath))
+        return fail('directory_recovery_required');
+    if (record?.phase === 'completed') {
+        const expected = { operationId: options.operationId, kind, path: payload.path, ...(newPath ? { newPath } : {}), revision: record.revision };
+        if (!record.receipt || Object.entries(expected).some(([key, value]) => record.receipt[key] !== value)
+            || record.receipt.recoveryPath && record.receipt.recoveryPath !== `${relativeDirectory}/removed`)
+            return fail('directory_recovery_required');
+        await cleanupRemoved(directory, record);
+        return record.receipt;
+    }
+    if (!record) {
+        if (options.recoverOnly)
+            return undefined;
+        let source;
+        try {
+            source = await validateTree(root, payload.path);
+        }
+        catch (error) {
+            if (missing(error))
+                return fail('directory_not_found');
+            throw error;
+        }
+        const revision = await options.observeRevision();
+        if (revision === undefined)
+            return fail('directory_revision_unavailable');
+        if (payload.expectedRevision !== undefined && payload.expectedRevision !== revision)
+            return fail('revision_conflict');
+        if (newPath && await lstat(join(root, ...newPath.split('/'))).then(() => true, error => { if (missing(error))
+            return false; throw error; }))
+            return fail('directory_exists');
+        record = { version: 1, scope: options.scope, operationId: options.operationId, payloadHash,
+            operationPayloadHash: options.operationPayloadHash ?? hashOperationPayload(input), payload, kind, path: payload.path,
+            ...(newPath ? { newPath } : {}), source, revision: revision + 1, phase: 'prepared' };
+        await saveRecord(directory, record);
+    }
+    const source = join(root, ...record.path.split('/'));
+    const destination = newPath ? join(root, ...newPath.split('/')) : join(directory, 'removed');
+    await safeAssetTransferDirectory(root, record.path.split('/').slice(0, -1).join('/'));
+    let destinationIdentity = await identity(destination);
+    if (!same(destinationIdentity, record.source)) {
+        if (!same(await identity(source), record.source))
+            return fail('directory_recovery_required');
+        await validateTree(root, record.path);
+        if (newPath) {
+            // Reserve an absent destination atomically; only our recorded empty placeholder may be replaced.
+            if (!destinationIdentity) {
+                await mkdir(destination, { mode: 0o700 }).catch(error => { if (error.code === 'EEXIST')
+                    return fail('directory_exists'); throw error; });
+                record.reservation = await identity(destination);
+                await saveRecord(directory, record);
+            }
+            else if (!same(destinationIdentity, record.reservation))
+                return fail('directory_exists');
+            destinationIdentity = await identity(destination);
+            if (!same(destinationIdentity, record.reservation) || (await readdir(destination)).length)
+                return fail('directory_exists');
+        }
+        else if (destinationIdentity)
+            return fail('directory_recovery_required');
+        await options.assertCurrent?.();
+        if (!same(await identity(source), record.source))
+            return fail('directory_conflict');
+        if (newPath && !same(await identity(destination), record.reservation))
+            return fail('directory_exists');
+        await rename(source, destination);
+        await syncAssetTransferDirectory(dirname(source));
+        await syncAssetTransferDirectory(dirname(destination));
+    }
+    await options.onDetached?.();
+    const receipt = { operationId: options.operationId, kind, path: record.path,
+        ...(newPath ? { newPath } : {}), revision: record.revision };
+    if (!newPath) {
+        // Mark the detach durably before recursive cleanup; a crash during cleanup cannot revive the old path.
+        receipt.recoveryPath = `${relativeDirectory}/removed`;
+    }
+    record = { ...record, phase: 'completed', receipt };
+    await saveRecord(directory, record);
+    await cleanupRemoved(directory, record);
+    return receipt;
+}
+/** Recover only an existing intent whose scope and original operation payload still agree. Never start new work. */
+export async function recoverWorkspaceDirectoryMutation(root, kind, options) {
+    if ((await lstat(root)).isSymbolicLink())
+        return fail('invalid_workspace_path');
+    root = await realpath(root);
+    const key = createHash('sha256').update(`${options.scope}\0${options.operationId}`).digest('hex');
+    const directory = await safeAssetTransferDirectory(root, `.playcraft-temp/directory-mutations/${key}`)
+        .catch(error => { if (missing(error))
+        return undefined; throw error; });
+    if (!directory)
+        return undefined;
+    const record = await readRecord(directory);
+    if (!record)
+        return undefined;
+    const payload = kind === 'directory.rename' ? directoryRenamePayloadSchema.safeParse(record.payload) : directoryDeletePayloadSchema.safeParse(record.payload);
+    if (!payload.success)
+        return fail('directory_recovery_required');
+    return mutateWorkspaceDirectory(root, kind, payload.data, { ...options, recoverOnly: true, observeRevision: async () => undefined });
+}