@playcraft/cli 0.1.51 → 0.1.53-beta

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

@@ -0,0 +1,245 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { attachmentIdsSchema, WORKSPACE_USER_UPLOADS_DIRECTORY, WORKSPACE_ATTACHMENT_MAX_BYTES, WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES, WORKSPACE_DIRECTORY_ATTACHMENT_MAX_BYTES, workspaceAttachmentSchema, workspaceDirectoryAttachmentUploadSchema, workspaceDirectoryAttachmentFilePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { artifactMime } from './artifact-files.js';
+import { excludeFromGit } from './dependencies.js';
+import { hashAttachment, probeAttachmentVideo } from './video-attachments.js';
+const stagingPath = `${WORKSPACE_USER_UPLOADS_DIRECTORY}/.directory-uploads`;
+const locks = new Map();
+async function withUploadLock(root, id, action) {
+    const key = `${root}\0${id}`;
+    const previous = locks.get(key) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(action);
+    locks.set(key, current);
+    try {
+        return await current;
+    }
+    finally {
+        if (locks.get(key) === current)
+            locks.delete(key);
+    }
+}
+async function safeDirectory(root, relative, create = false) {
+    let directory = root;
+    for (const part of relative.split('/')) {
+        directory = join(directory, part);
+        if (create)
+            await mkdir(directory, { mode: 0o755 }).catch((error) => {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            });
+        if (!(await lstat(directory)).isDirectory())
+            throw new Error('invalid_attachment');
+    }
+    return directory;
+}
+function validId(id) {
+    if (!attachmentIdsSchema.safeParse([id]).success)
+        throw new Error('invalid_attachment');
+}
+async function readManifest(root, id) {
+    validId(id);
+    const stage = await safeDirectory(root, `${stagingPath}/${id}`);
+    const handle = await open(join(stage, 'manifest.json'), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+            throw new Error('invalid_attachment');
+        return workspaceDirectoryAttachmentUploadSchema.parse(JSON.parse(await handle.readFile('utf8')));
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function beginWorkspaceDirectoryAttachment(root, body) {
+    const manifest = workspaceDirectoryAttachmentUploadSchema.parse(body);
+    await excludeFromGit(root, `/${WORKSPACE_USER_UPLOADS_DIRECTORY}/`);
+    const staging = await safeDirectory(root, stagingPath, true);
+    const id = randomUUID();
+    const stage = join(staging, id);
+    await mkdir(stage, { mode: 0o755 });
+    try {
+        await mkdir(join(stage, 'data'), { mode: 0o755 });
+        await mkdir(join(stage, 'data', manifest.name), { mode: 0o755 });
+        await writeFile(join(stage, 'manifest.json'), JSON.stringify(manifest), { flag: 'wx', mode: 0o644 });
+        return { uploadId: id };
+    }
+    catch (error) {
+        await rm(stage, { recursive: true, force: true });
+        throw error;
+    }
+}
+/** Each member is streamed and created exclusively; no completed member can be overwritten. */
+export async function uploadWorkspaceDirectoryFile(root, id, path, request) {
+    return withUploadLock(root, id, async () => {
+        workspaceDirectoryAttachmentFilePathSchema.parse(path);
+        const manifest = await readManifest(root, id);
+        const member = manifest.files.find(file => file.path === path);
+        if (!member)
+            throw new Error('invalid_attachment');
+        const length = request.headers['content-length'];
+        if (length !== undefined && (!/^\d+$/.test(length) || Number(length) !== member.size))
+            throw new Error('invalid_attachment');
+        const relative = `${stagingPath}/${id}/data/${manifest.name}/${path}`;
+        await safeDirectory(root, dirname(relative), true);
+        const handle = await open(join(root, relative), constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, 0o644);
+        try {
+            let size = 0;
+            for await (const chunk of request) {
+                const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                if (size + bytes.length > member.size)
+                    throw new Error('invalid_attachment');
+                let offset = 0;
+                while (offset < bytes.length)
+                    offset += (await handle.write(bytes, offset, bytes.length - offset, size + offset)).bytesWritten;
+                size += bytes.length;
+            }
+            if (size !== member.size)
+                throw new Error('invalid_attachment');
+            await handle.sync();
+            if (member.mimeType.startsWith('video/')) {
+                const media = await probeAttachmentVideo(handle);
+                if (media.mimeType !== member.mimeType && !(member.mimeType === 'video/quicktime' && media.mimeType === 'video/mp4'))
+                    throw new Error('invalid_attachment');
+            }
+            return { path, size };
+        }
+        catch (error) {
+            await rm(join(root, relative), { force: true });
+            throw error;
+        }
+        finally {
+            await handle.close();
+        }
+    });
+}
+async function assertExactFiles(directory, expected, prefix = '') {
+    for (const name of await readdir(directory)) {
+        const relative = prefix ? `${prefix}/${name}` : name;
+        const path = join(directory, name);
+        const stat = await lstat(path);
+        if (stat.isDirectory())
+            await assertExactFiles(path, expected, relative);
+        else if (!stat.isFile() || stat.nlink !== 1 || !expected.delete(relative))
+            throw new Error('invalid_attachment');
+    }
+    if (!prefix && expected.size)
+        throw new Error('invalid_attachment');
+}
+async function directoryFiles(root, relative, manifest) {
+    const directory = await safeDirectory(root, relative);
+    await assertExactFiles(directory, new Set(manifest.files.map(file => file.path)));
+    const files = [];
+    for (const file of manifest.files) {
+        await safeDirectory(directory, dirname(file.path) === '.' ? '' : dirname(file.path));
+        const handle = await open(join(directory, file.path), constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.nlink !== 1 || stat.size !== file.size)
+                throw new Error('invalid_attachment');
+            const media = file.mimeType.startsWith('video/') ? await probeAttachmentVideo(handle) : undefined;
+            if (media && media.mimeType !== file.mimeType && !(file.mimeType === 'video/quicktime' && media.mimeType === 'video/mp4'))
+                throw new Error('invalid_attachment');
+            const inferred = artifactMime(file.path);
+            files.push({ path: file.path, size: stat.size, sha256: await hashAttachment(handle),
+                mimeType: media?.mimeType ?? (inferred === 'application/octet-stream' ? file.mimeType : inferred) });
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    return files;
+}
+export async function completeWorkspaceDirectoryAttachment(root, id) {
+    return withUploadLock(root, id, async () => {
+        const manifest = await readManifest(root, id);
+        const stage = await safeDirectory(root, `${stagingPath}/${id}`);
+        const files = await directoryFiles(root, `${stagingPath}/${id}/data/${manifest.name}`, manifest);
+        const metadata = await safeDirectory(root, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/.metadata`, true);
+        const uploads = await safeDirectory(root, WORKSPACE_USER_UPLOADS_DIRECTORY);
+        const attachment = { id, name: manifest.name, kind: 'directory',
+            size: files.reduce((size, file) => size + file.size, 0), mimeType: 'application/vnd.playcraft.directory',
+            path: `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${id}/${manifest.name}`, files };
+        workspaceAttachmentSchema.parse(attachment);
+        const target = join(uploads, id);
+        await mkdir(target, { mode: 0o755 });
+        try {
+            await rename(join(stage, 'data', manifest.name), join(target, manifest.name));
+            await writeFile(join(metadata, `${id}.json`), JSON.stringify(attachment), { flag: 'wx', mode: 0o644 });
+        }
+        catch (error) {
+            await rm(target, { recursive: true, force: true });
+            throw error;
+        }
+        await rm(stage, { recursive: true, force: true });
+        return attachment;
+    });
+}
+export async function cancelWorkspaceDirectoryAttachment(root, id) {
+    validId(id);
+    return withUploadLock(root, id, async () => {
+        const parent = await safeDirectory(root, stagingPath);
+        const stage = join(parent, id);
+        try {
+            if (!(await lstat(stage)).isDirectory())
+                throw new Error('invalid_attachment');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await rm(stage, { recursive: true, force: true });
+        return { uploadId: id, cancelled: true };
+    });
+}
+export async function readWorkspaceDirectoryMetadata(root, id) {
+    validId(id);
+    const metadata = await safeDirectory(root, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/.metadata`);
+    const handle = await open(join(metadata, `${id}.json`), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+            throw new Error('invalid_attachment');
+        const attachment = workspaceAttachmentSchema.parse(JSON.parse(await handle.readFile('utf8')));
+        if (attachment.id !== id || attachment.kind !== 'directory' || attachment.origin || !attachment.files ||
+            attachment.path !== `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${id}/${attachment.name}` || attachment.mimeType !== 'application/vnd.playcraft.directory')
+            throw new Error('invalid_attachment');
+        workspaceDirectoryAttachmentUploadSchema.parse({ name: attachment.name, files: attachment.files.map(({ sha256: _digest, ...file }) => file) });
+        if (attachment.size !== attachment.files.reduce((size, file) => size + file.size, 0) || attachment.size > WORKSPACE_DIRECTORY_ATTACHMENT_MAX_BYTES)
+            throw new Error('invalid_attachment');
+        return attachment;
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function openWorkspaceDirectoryFile(root, attachment, path) {
+    workspaceDirectoryAttachmentFilePathSchema.parse(path);
+    const file = attachment.files?.find(file => file.path === path);
+    if (!file || !attachment.path)
+        throw new Error('attachment_unavailable');
+    const directory = await safeDirectory(root, attachment.path);
+    if (dirname(file.path) !== '.')
+        await safeDirectory(directory, dirname(file.path));
+    const handle = await open(join(directory, file.path), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        const limit = file.mimeType.startsWith('video/') ? WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES : WORKSPACE_ATTACHMENT_MAX_BYTES;
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size !== file.size || stat.size > limit || await hashAttachment(handle) !== file.sha256)
+            throw new Error('attachment_unavailable');
+        return { handle, name: file.path.split('/').at(-1), mimeType: file.mimeType, size: file.size };
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+export async function resolveWorkspaceDirectoryAttachment(root, id) {
+    const attachment = await readWorkspaceDirectoryMetadata(root, id);
+    const files = await directoryFiles(root, attachment.path, { name: attachment.name, files: attachment.files.map(({ sha256: _digest, ...file }) => file) });
+    if (files.some((file, index) => file.sha256 !== attachment.files[index].sha256 || file.mimeType !== attachment.files[index].mimeType))
+        throw new Error('attachment_unavailable');
+    return { ...attachment, path: join(root, attachment.path) };
+}

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

@@ -0,0 +1,57 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath, rmdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { directoryCreatePayloadSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { ensureWorkspaceRoot, InvalidWorkspacePathError } from './files.js';
+const RESERVED_DIRECTORIES = new Set(['.git', 'node_modules', '.playcraft-temp']);
+export class WorkspaceDirectoryCreateError extends Error {
+    code = 'directory_exists';
+    constructor() { super('directory_exists'); }
+}
+/** Keep the new directory in saved workspaces without showing its marker as an asset. */
+export async function createWorkspaceDirectory(root, input) {
+    const parsed = directoryCreatePayloadSchema.safeParse(input);
+    if (!parsed.success)
+        throw new InvalidWorkspacePathError(input.path);
+    const path = parsed.data.path;
+    const parts = path.split('/');
+    if (parts.some(part => RESERVED_DIRECTORIES.has(part)))
+        throw new InvalidWorkspacePathError(path);
+    const rootReal = await ensureWorkspaceRoot(root);
+    let parent = rootReal;
+    for (const part of parts.slice(0, -1)) {
+        parent = join(parent, part);
+        await mkdir(parent, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+            throw error; });
+        const stat = await lstat(parent);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(parent) !== parent)
+            throw new InvalidWorkspacePathError(path);
+    }
+    const target = join(parent, parts.at(-1));
+    try {
+        await mkdir(target, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        if ((await lstat(target)).isSymbolicLink())
+            throw new InvalidWorkspacePathError(path);
+        throw new WorkspaceDirectoryCreateError();
+    }
+    try {
+        if (!(await lstat(target)).isDirectory() || await realpath(target) !== target)
+            throw new InvalidWorkspacePathError(path);
+        const marker = await open(join(target, '.gitkeep'), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        try {
+            await marker.sync();
+        }
+        finally {
+            await marker.close();
+        }
+        return { path };
+    }
+    catch (error) {
+        await rmdir(target).catch(() => undefined);
+        throw error;
+    }
+}

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

@@ -0,0 +1,111 @@
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { promisify } from 'node:util';
+import { workspaceDirectoryNameSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { batchDirectoryHeld } from '../batch/occupancy.js';
+import { workspaceRoot, workspaceSessions } from './registry.js';
+const execute = promisify(execFile);
+const git = async (state, root, ...args) => (await execute('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-C', root, ...args], {
+    timeout: 30_000, maxBuffer: 1024 * 1024, env: { PATH: process.env.PATH, HOME: state.config.stateDir, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' },
+})).stdout.trim();
+export async function workspaceDirectoryOccupied(state, workspaceId, directoryName) {
+    if (await batchDirectoryHeld(state, workspaceId, directoryName))
+        return true;
+    if (state.journal.listOperations().some(({ operation }) => operation.workspaceId === workspaceId
+        && (operation.directoryName ?? 'basic') === directoryName && ['queued', 'dispatched', 'accepted', 'uncertain'].includes(operation.status)))
+        return true;
+    if (workspaceSessions(state, workspaceId, directoryName).some(session => session.turnBlock === 'uncertain' || ['starting', 'running', 'waiting_for_user'].includes(session.turnStatus ?? '')))
+        return true;
+    if (state.journal.listTerminals().some(terminal => terminal.workspaceId === workspaceId && (terminal.directoryName ?? 'basic') === directoryName && terminal.status !== 'destroyed'))
+        return true;
+    return [workspaceId, `${workspaceId}:${directoryName}`].some(scope => state.journal.listManagedWrites(scope).some(write => !write.stoppedAt));
+}
+async function assertCleanAndPushed(state, root, allowedHead) {
+    if (await git(state, root, 'status', '--porcelain', '--untracked-files=all'))
+        throw new Error('workspace_directory_uncommitted');
+    const upstream = await git(state, root, 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}').catch(() => '');
+    if (!upstream || (Number(await git(state, root, 'rev-list', '--count', `${upstream}..HEAD`)) > 0 && await git(state, root, 'rev-parse', 'HEAD') !== allowedHead))
+        throw new Error('workspace_directory_unpushed');
+}
+/** Keep remote branches, published previews and all journal identities; only local checkouts are reclaimed. */
+export async function cleanupWorkspaceDirectories(state, workspaceId, directoryNames) {
+    if (!Array.isArray(directoryNames) || directoryNames.length === 0 || directoryNames.length > 64)
+        throw new Error('workspace_directories_invalid');
+    const names = [...new Set(directoryNames.map(name => workspaceDirectoryNameSchema.parse(name)))];
+    return state.journal.exclusive(`maintenance:${workspaceId}`, async () => {
+        const cleaned = [];
+        const blocked = [];
+        for (const directoryName of names) {
+            try {
+                await state.journal.exclusive(`directory:${workspaceId}:${directoryName}`, async () => {
+                    if (await workspaceDirectoryOccupied(state, workspaceId, directoryName))
+                        throw new Error('workspace_directory_occupied');
+                    const root = await workspaceRoot(state, workspaceId, directoryName);
+                    await assertCleanAndPushed(state, root);
+                    const binding = state.journal.getWorkspace(workspaceId);
+                    // Persist recoverable identity before removing the checkout; a retry cannot silently adopt another branch.
+                    const existing = binding.directories?.find(item => item.directoryName === directoryName);
+                    const directory = existing ?? { workspaceId, directoryName, remixId: binding.remixId, branchName: binding.branchName };
+                    await state.journal.putWorkspace({ ...binding, directories: [...(binding.directories ?? []).filter(item => item.directoryName !== directoryName), { ...directory, status: 'reclaimed' }] });
+                    await rm(root, { recursive: true });
+                    cleaned.push(directoryName);
+                });
+            }
+            catch (error) {
+                blocked.push({ directoryName, reason: error instanceof Error && /^[a-z0-9_]+$/.test(error.message) ? error.message : 'workspace_cleanup_failed' });
+            }
+        }
+        return { cleaned, blocked };
+    });
+}
+/** Conflicts remain isolated to their own engineering directory. Busy directories are skipped without deferred work. */
+export async function syncWorkspaceDirectories(state, workspaceId, commitHash, targetDirectoryNames) {
+    if (typeof commitHash !== 'string' || !/^[a-f0-9]{40,64}$/.test(commitHash) || !Array.isArray(targetDirectoryNames) || targetDirectoryNames.length === 0 || targetDirectoryNames.length > 64)
+        throw new Error('workspace_sync_invalid');
+    const basic = await workspaceRoot(state, workspaceId, 'basic');
+    await git(state, basic, 'merge-base', '--is-ancestor', commitHash, 'HEAD');
+    const synced = [], skipped = [], conflicts = [];
+    for (const directoryName of [...new Set(targetDirectoryNames.map(name => workspaceDirectoryNameSchema.parse(name)))]) {
+        if (directoryName === 'basic')
+            throw new Error('workspace_sync_target_invalid');
+        await state.journal.exclusive(`directory:${workspaceId}:${directoryName}`, async () => {
+            if (await workspaceDirectoryOccupied(state, workspaceId, directoryName)) {
+                skipped.push({ directoryName, reason: 'directory_busy' });
+                return;
+            }
+            const root = await workspaceRoot(state, workspaceId, directoryName);
+            const ledger = join(state.config.stateDir, 'directory-sync', workspaceId, `${directoryName}.json`);
+            const applied = await readFile(ledger, 'utf8').then(value => JSON.parse(value), () => undefined);
+            await assertCleanAndPushed(state, root, applied?.sourceCommit === commitHash ? applied.targetCommit : undefined);
+            if (applied?.sourceCommit === commitHash && await git(state, root, 'rev-parse', 'HEAD') === applied.targetCommit) {
+                synced.push(directoryName);
+                return;
+            }
+            const containing = await git(state, root, 'merge-base', '--is-ancestor', commitHash, 'HEAD').then(() => true, () => false);
+            if (containing) {
+                synced.push(directoryName);
+                return;
+            }
+            // Import the exact preserved basic commit, without fetching a moving remote branch.
+            await execute('git', ['-c', 'core.hooksPath=/dev/null', '-C', root, 'fetch', '--no-tags', '--', basic, commitHash], { timeout: 30_000, maxBuffer: 1024 * 1024 });
+            const equivalent = (await git(state, root, 'cherry', 'HEAD', commitHash)).split('\n').some(line => line === `- ${commitHash}`);
+            if (!equivalent) {
+                try {
+                    await git(state, root, '-c', 'user.name=PlayCraft', '-c', 'user.email=playcraft@localhost', 'cherry-pick', commitHash);
+                }
+                catch {
+                    conflicts.push(directoryName);
+                    return;
+                }
+            }
+            await mkdir(join(state.config.stateDir, 'directory-sync', workspaceId), { recursive: true, mode: 0o700 });
+            const temporary = `${ledger}.${randomUUID()}.tmp`;
+            await writeFile(temporary, JSON.stringify({ sourceCommit: commitHash, targetCommit: await git(state, root, 'rev-parse', 'HEAD') }), { mode: 0o600 });
+            await rename(temporary, ledger);
+            synced.push(directoryName);
+        });
+    }
+    return { synced, skipped, conflicts, previewStale: 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 });
+}