@playcraft/cli 0.1.42 → 0.1.44-beta

package/dist/workspace-runtime/workspaces/artifacts.js

@@ -0,0 +1,282 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, rename, unlink } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import sharp from 'sharp';
+import { WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, isWorkspaceArtifactOutputPath, isWorkspaceArtifactOutputVersion, workspaceArtifactContentQuerySchema, workspaceArtifactListSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { artifactBundleDigest, artifactDirectory, artifactFormat, artifactPath, artifactResources, snapshotArtifactBundle, snapshotArtifactFile } from './artifact-files.js';
+import { ARTIFACT_RECEIPTS_DIRECTORY, readArtifactReceipt } from './artifact-receipts.js';
+const serial = new Map();
+function digest(text) { return createHash('sha256').update(text).digest('hex'); }
+function artifactId(workspaceId, path) { return `artifact_${digest(`${workspaceId}\0${path}`).slice(0, 40)}`; }
+function outputArtifacts(artifacts) {
+    return artifacts.flatMap(artifact => {
+        const versions = artifact.versions.filter(isWorkspaceArtifactOutputVersion);
+        if (!versions.length)
+            return [];
+        const current = versions.find(version => version.id === artifact.currentVersionId)
+            ?? versions.reduce((latest, version) => version.createdAt > latest.createdAt ? version : latest);
+        return [{ ...artifact, versions, currentVersionId: current.id, updatedAt: current.createdAt }];
+    }).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id));
+}
+/** Catalogs and immutable bytes are control-owned, outside the mutable checkout. */
+export class WorkspaceArtifactStore {
+    stateDir;
+    workspaceId;
+    constructor(stateDir, workspaceId) {
+        this.stateDir = stateDir;
+        this.workspaceId = workspaceId;
+    }
+    async directory() {
+        await mkdir(this.stateDir, { recursive: true, mode: 0o700 });
+        return artifactDirectory(this.stateDir, `artifacts/${digest(this.workspaceId)}`);
+    }
+    async read(directory) {
+        const handle = await open(join(directory, 'catalog.json'), constants.O_RDONLY | constants.O_NOFOLLOW).catch(error => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (!handle)
+            return { artifacts: [], scannedAt: new Date().toISOString(), receipts: [], observations: {} };
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.size > 32 * 1024 * 1024)
+                throw new Error('artifact_catalog_invalid');
+            const { receipts, observations = {}, ...body } = JSON.parse(await handle.readFile('utf8'));
+            if (!Array.isArray(receipts) || receipts.some(id => typeof id !== 'string'))
+                throw new Error('artifact_catalog_invalid');
+            return { ...workspaceArtifactListSchema.parse(body), receipts, observations };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async write(directory, catalog) {
+        const temporary = join(directory, `${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(catalog));
+            await handle.sync();
+            await handle.close();
+            await rename(temporary, join(directory, 'catalog.json'));
+        }
+        finally {
+            await handle.close();
+            await unlink(temporary).catch(error => { if (error.code !== 'ENOENT')
+                throw error; });
+        }
+    }
+    async discover(root, source = { kind: 'discovered' }, sourcePaths = []) {
+        const key = `${this.stateDir}\0${this.workspaceId}`;
+        const previous = serial.get(key) ?? Promise.resolve();
+        const task = previous.catch(() => undefined).then(() => this.scan(root, source, sourcePaths));
+        serial.set(key, task);
+        try {
+            return await task;
+        }
+        finally {
+            if (serial.get(key) === task)
+                serial.delete(key);
+        }
+    }
+    async list() {
+        const catalog = await this.read(await this.directory());
+        return workspaceArtifactListSchema.parse({ artifacts: outputArtifacts(catalog.artifacts), scannedAt: catalog.scannedAt });
+    }
+    async scan(root, source, sourcePaths) {
+        const directory = await this.directory();
+        const objects = await artifactDirectory(directory, 'objects');
+        const catalog = await this.read(directory);
+        const original = JSON.stringify(outputArtifacts(catalog.artifacts));
+        const receipts = await this.receipts(root, catalog);
+        for (const receipt of receipts) {
+            try {
+                for (const file of receipt.files) {
+                    const copied = await snapshotArtifactFile(root, `${ARTIFACT_RECEIPTS_DIRECTORY}/objects/${file.sha256}`, objects);
+                    if (copied.sha256 !== file.sha256 || copied.size !== file.size)
+                        throw new Error('artifact_receipt_digest_mismatch');
+                }
+                const primary = receipt.files.find(file => file.role === 'primary' && file.path === receipt.path);
+                if (!primary || !artifactFormat(receipt.path))
+                    continue;
+                const version = {
+                    id: `version_${receipt.id}`, createdAt: receipt.source.generatedAt ?? new Date().toISOString(),
+                    path: receipt.path, mimeType: primary.mimeType, size: primary.size, sha256: primary.sha256,
+                    files: receipt.files, source: receipt.source,
+                    ...(receipt.width ? { width: receipt.width } : {}), ...(receipt.height ? { height: receipt.height } : {}),
+                    ...(receipt.duration !== undefined ? { duration: receipt.duration } : {}),
+                };
+                this.add(catalog, version);
+                catalog.receipts.push(receipt.id);
+            }
+            catch { /* An incomplete receipt stays pending; the next scan retries its original bytes. */ }
+        }
+        const candidates = await discoverPaths(root);
+        // Models are inspected before images so their explicitly referenced textures stay under the model.
+        candidates.sort((a, b) => Number(artifactFormat(b)?.[0] === 'model') - Number(artifactFormat(a)?.[0] === 'model') || a.localeCompare(b));
+        const visible = outputArtifacts(catalog.artifacts);
+        const members = new Set(visible.flatMap(artifact => artifact.versions.flatMap(version => version.files.filter(file => file.role !== 'primary').map(file => file.path))));
+        for (const path of candidates) {
+            if (members.has(path))
+                continue;
+            try {
+                const current = visible.find(artifact => artifact.id === artifactId(this.workspaceId, path));
+                const version = current?.versions.find(entry => entry.id === current.currentVersionId);
+                const knownWrite = sourcePaths.includes(path) && Boolean(source.operationId) && version?.source.operationId !== source.operationId;
+                const observation = catalog.observations[path];
+                if (!knownWrite && version && observation?.versionId === version.id && observation.signature === await fileSignature(root, version.files.map(file => file.path)))
+                    continue;
+                const thumbnail = version?.files.find(file => file.role === 'thumbnail');
+                const thumbnailPath = thumbnail && await lstat(join(root, thumbnail.path)).then(stat => stat.isFile(), () => false) ? thumbnail.path : undefined;
+                const paths = [path, ...await artifactResources(root, path), ...(thumbnailPath ? [thumbnailPath] : [])];
+                const signature = await fileSignature(root, paths);
+                const files = await snapshotArtifactBundle(root, path, objects, thumbnailPath);
+                if (signature !== await fileSignature(root, files.map(file => file.path)))
+                    continue;
+                for (const file of files)
+                    if (file.role !== 'primary')
+                        members.add(file.path);
+                if (!knownWrite && version && artifactBundleDigest(version.files) === artifactBundleDigest(files)) {
+                    catalog.observations[path] = { signature, versionId: version.id };
+                    continue;
+                }
+                const primary = files[0];
+                const next = {
+                    id: `version_${knownWrite ? source.operationId : randomUUID()}`, createdAt: new Date().toISOString(),
+                    path, mimeType: primary.mimeType, size: primary.size, sha256: primary.sha256, files,
+                    source: sourcePaths.includes(path) ? source : { kind: 'discovered' },
+                    ...await this.dimensions(objects, primary),
+                };
+                this.add(catalog, next);
+                catalog.observations[path] = { signature, versionId: next.id };
+            }
+            catch { /* Files being written or temporarily missing are retried, never published as complete. */ }
+        }
+        catalog.artifacts = catalog.artifacts.filter(artifact => {
+            const current = artifact.versions.find(version => version.id === artifact.currentVersionId);
+            return !isWorkspaceArtifactOutputVersion(current) || current.source.kind !== 'discovered' || !members.has(current.path);
+        });
+        catalog.artifacts.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id));
+        catalog.scannedAt = new Date().toISOString();
+        const list = workspaceArtifactListSchema.parse({ artifacts: outputArtifacts(catalog.artifacts), scannedAt: catalog.scannedAt });
+        await this.write(directory, catalog);
+        return { list, changed: original !== JSON.stringify(list.artifacts) };
+    }
+    add(catalog, version) {
+        const id = artifactId(this.workspaceId, version.path);
+        let artifact = catalog.artifacts.find(item => item.id === id);
+        if (!artifact) {
+            artifact = { id, kind: artifactFormat(version.path)[0], name: basename(version.path), currentVersionId: version.id, updatedAt: version.createdAt, versions: [] };
+            catalog.artifacts.push(artifact);
+        }
+        if (!artifact.versions.some(item => item.id === version.id)) {
+            // Display ordering is monotonic; the original generation time stays in source.generatedAt.
+            const latest = Math.max(0, ...artifact.versions.map(item => Date.parse(item.createdAt)));
+            version.createdAt = new Date(Math.max(Date.parse(version.createdAt), latest + 1)).toISOString();
+            artifact.versions.unshift(version);
+        }
+        artifact.currentVersionId = version.id;
+        artifact.updatedAt = version.createdAt;
+    }
+    async receipts(root, catalog) {
+        let directory;
+        try {
+            const target = join(root, ARTIFACT_RECEIPTS_DIRECTORY);
+            if (!(await lstat(target)).isDirectory())
+                return [];
+            directory = await artifactDirectory(root, ARTIFACT_RECEIPTS_DIRECTORY);
+        }
+        catch {
+            return [];
+        }
+        const seen = new Set(catalog.receipts), receipts = [];
+        for (const name of await readdir(directory)) {
+            if (!/^[a-f0-9-]{36}\.json$/.test(name) || seen.has(name.slice(0, -5)))
+                continue;
+            try {
+                const receipt = await readArtifactReceipt(join(directory, name));
+                if (receipt.workspaceId === this.workspaceId && `${receipt.id}.json` === name && isWorkspaceArtifactOutputVersion(receipt))
+                    receipts.push(receipt);
+            }
+            catch { /* Malformed output metadata is never trusted as a completed artifact. */ }
+        }
+        return receipts.sort((a, b) => (a.source.generatedAt ?? '').localeCompare(b.source.generatedAt ?? '') || a.id.localeCompare(b.id));
+    }
+    async dimensions(objects, file) {
+        if (!file.mimeType.startsWith('image/') || file.mimeType === 'image/svg+xml')
+            return {};
+        try {
+            const metadata = await sharp(join(objects, file.sha256), { limitInputPixels: 100_000_000 }).metadata();
+            return { ...(metadata.width ? { width: metadata.width } : {}), ...(metadata.height ? { height: metadata.height } : {}) };
+        }
+        catch {
+            return {};
+        }
+    }
+    async content(input) {
+        const query = workspaceArtifactContentQuerySchema.parse(input);
+        const directory = await this.directory(), catalog = await this.read(directory);
+        const artifact = catalog.artifacts.find(item => item.id === query.artifactId);
+        const version = artifact?.versions.find(item => item.id === query.versionId && isWorkspaceArtifactOutputVersion(item));
+        const file = version?.files.find(item => item.path === (query.path ?? version.path));
+        if (!file)
+            throw new Error('artifact_not_found');
+        if (query.offset > file.size)
+            throw new Error('artifact_range_invalid');
+        const handle = await open(join(directory, 'objects', file.sha256), 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('artifact_snapshot_invalid');
+            const bytes = Buffer.alloc(Math.min(query.length, file.size - query.offset));
+            let read = 0;
+            while (read < bytes.length) {
+                const part = await handle.read(bytes, read, bytes.length - read, query.offset + read);
+                if (!part.bytesRead)
+                    throw new Error('artifact_snapshot_invalid');
+                read += part.bytesRead;
+            }
+            return { content: bytes.toString('base64'), mimeType: file.mimeType, totalBytes: file.size, offset: query.offset, sha256: file.sha256 };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+async function fileSignature(root, paths) {
+    const records = [];
+    for (const path of [...new Set(paths)].sort()) {
+        const stat = await lstat(await artifactPath(root, path));
+        if (!stat.isFile() || stat.nlink !== 1)
+            throw new Error('artifact_file_unavailable');
+        records.push([path, stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs]);
+    }
+    return JSON.stringify(records);
+}
+async function discoverPaths(root, directory = WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, result = []) {
+    if (directory !== WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY && !isWorkspaceArtifactOutputPath(directory))
+        throw new Error('invalid_artifact_path');
+    let target;
+    try {
+        target = await artifactPath(root, directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return result;
+        throw error;
+    }
+    if (!(await lstat(target)).isDirectory())
+        throw new Error('invalid_artifact_directory');
+    for (const entry of await readdir(target, { withFileTypes: true })) {
+        if (entry.name.startsWith('.') || entry.isSymbolicLink())
+            continue;
+        const path = `${directory}/${entry.name}`;
+        if (entry.isDirectory()) {
+            await discoverPaths(root, path, result);
+        }
+        else if (entry.isFile() && artifactFormat(path))
+            result.push(path);
+    }
+    return result;
+}

package/dist/workspace-runtime/workspaces/asset-library-import.js

@@ -0,0 +1,366 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, mkdtemp, open, readdir, realpath, rename, rm, rmdir } from 'node:fs/promises';
+import { basename, dirname, extname, join, relative } from 'node:path';
+import { BINARY_WORKSPACE_FILE_MAX_BYTES, WORKSPACE_LIBRARY_ATTACHMENT_MAX_BYTES, WORKSPACE_LIBRARY_ATTACHMENT_MAX_FILES, workspaceAssetLibraryImportPayloadSchema, workspaceAssetLibraryImportResultSchema, workspaceAssetLibraryImportTransportSchema, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { observeWorkspaceBinaryFile, writeWorkspaceBinaryFile } from './binary-write.js';
+const RESERVED = new Set(['.git', 'node_modules', '.playcraft-temp', '.tmp']);
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const missing = (error) => error?.code === 'ENOENT';
+export class AssetLibraryImportError extends Error {
+    constructor(code) { super(code); this.name = 'AssetLibraryImportError'; }
+}
+function validPath(path) {
+    if (!workspaceRelativePathSchema.safeParse(path).success || path.split('/').some(part => RESERVED.has(part)))
+        throw new AssetLibraryImportError('invalid_library_import_path');
+    return path;
+}
+async function safeDirectory(root, path, create = false) {
+    const rootStat = await lstat(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || await realpath(root) !== root)
+        throw new AssetLibraryImportError('invalid_library_import_path');
+    let current = root;
+    for (const part of path.split('/').filter(Boolean)) {
+        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)
+            throw new AssetLibraryImportError('invalid_library_import_path');
+    }
+    return current;
+}
+async function statTarget(root, path) {
+    try {
+        await safeDirectory(root, dirname(path) === '.' ? '' : dirname(path));
+        return await lstat(join(root, path));
+    }
+    catch (error) {
+        if (missing(error))
+            return undefined;
+        throw error;
+    }
+}
+function validateAsset(asset) {
+    let size = 0;
+    for (const file of asset.files) {
+        validPath(file.path);
+        const bytes = Buffer.from(file.content, 'base64');
+        if (bytes.toString('base64') !== file.content || digest(bytes) !== file.sha256)
+            throw new AssetLibraryImportError('library_asset_changed');
+        if (bytes.length > BINARY_WORKSPACE_FILE_MAX_BYTES)
+            throw new AssetLibraryImportError('binary_file_too_large');
+        size += bytes.length;
+    }
+    if (size > WORKSPACE_LIBRARY_ATTACHMENT_MAX_BYTES)
+        throw new AssetLibraryImportError('library_asset_too_large');
+    const files = asset.files.map(file => [file.path, file.sha256]).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    if (digest(JSON.stringify(files)) !== asset.contentHash)
+        throw new AssetLibraryImportError('library_asset_changed');
+}
+async function directorySnapshot(root) {
+    const rootStat = await lstat(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new AssetLibraryImportError('invalid_library_import_path');
+    const contents = [];
+    let bytes = 0;
+    const visit = async (relative = '') => {
+        for (const entry of await readdir(join(root, relative), { withFileTypes: true })) {
+            const path = relative ? `${relative}/${entry.name}` : entry.name;
+            validPath(path);
+            if (entry.isSymbolicLink())
+                throw new AssetLibraryImportError('invalid_library_import_path');
+            if (entry.isDirectory()) {
+                contents.push([`${path}/`, '']);
+                await safeDirectory(root, path);
+                await visit(path);
+            }
+            else if (entry.isFile()) {
+                const file = await observeWorkspaceBinaryFile(root, path);
+                if (!file)
+                    throw new AssetLibraryImportError('content_conflict');
+                bytes += file.size;
+                contents.push([path, file.contentHash]);
+            }
+            else
+                throw new AssetLibraryImportError('invalid_library_import_path');
+            if (contents.length > WORKSPACE_LIBRARY_ATTACHMENT_MAX_FILES * 2 || bytes > WORKSPACE_LIBRARY_ATTACHMENT_MAX_BYTES)
+                throw new AssetLibraryImportError('library_asset_too_large');
+        }
+    };
+    await safeDirectory(root, '');
+    await visit();
+    return digest(JSON.stringify(contents.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)));
+}
+async function syncDirectory(path) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function saveTransaction(root, transaction, value) {
+    await safeDirectory(root, relative(root, transaction));
+    const temporary = join(transaction, 'manifest.next');
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(value));
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await rename(temporary, join(transaction, 'manifest.json'));
+    await syncDirectory(transaction);
+}
+async function removeTransaction(root, transaction) {
+    await safeDirectory(root, relative(root, transaction));
+    await rm(transaction, { recursive: true, force: true });
+}
+async function readTransaction(root, transaction) {
+    await safeDirectory(root, relative(root, transaction));
+    const handle = await open(join(transaction, '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 AssetLibraryImportError('invalid_library_import');
+        const value = JSON.parse(await handle.readFile('utf8'));
+        if (!value || value.version !== 1 || typeof value.target !== 'string'
+            || !['prepared', 'backed_up', 'reserved', 'published'].includes(value.phase)
+            || !(value.originalHash === null || /^[a-f0-9]{64}$/.test(value.originalHash))
+            || !/^[a-f0-9]{64}$/.test(value.incomingHash))
+            throw new AssetLibraryImportError('invalid_library_import');
+        validPath(value.target);
+        if ((value.operationId !== undefined || value.assetId !== undefined || value.paths !== undefined)
+            && (typeof value.operationId !== 'string' || !value.operationId || value.operationId.length > 128
+                || typeof value.assetId !== 'string' || !value.assetId || value.assetId.length > 128
+                || !Array.isArray(value.paths) || !value.paths.length || value.paths.length > WORKSPACE_LIBRARY_ATTACHMENT_MAX_FILES
+                || value.paths.some(path => typeof path !== 'string' || !path.startsWith(`${value.target}/`) || !workspaceRelativePathSchema.safeParse(path).success)))
+            throw new AssetLibraryImportError('invalid_library_import');
+        return value;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Restore interrupted replacements before serving files; ambiguous states retain every backup. */
+export async function recoverInterruptedLibraryImports(root) {
+    const rootReal = await realpath(root);
+    const result = { recovered: [], pending: [], published: [] };
+    let scratch;
+    try {
+        scratch = await safeDirectory(rootReal, '.playcraft-temp');
+    }
+    catch (error) {
+        if (missing(error))
+            return result;
+        throw error;
+    }
+    for (const entry of await readdir(scratch, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !entry.name.startsWith('library-import-'))
+            continue;
+        const transaction = join(scratch, entry.name);
+        try {
+            const manifest = await readTransaction(rootReal, transaction);
+            const target = join(rootReal, manifest.target);
+            const parent = dirname(manifest.target) === '.' ? '' : dirname(manifest.target);
+            await safeDirectory(rootReal, parent, true);
+            const current = await statTarget(rootReal, manifest.target);
+            const backup = await lstat(join(transaction, 'previous')).catch(error => { if (missing(error))
+                return undefined; throw error; });
+            const incoming = await lstat(join(transaction, 'incoming')).catch(error => { if (missing(error))
+                return undefined; throw error; });
+            if (backup && (!backup.isDirectory() || backup.isSymbolicLink()))
+                throw new AssetLibraryImportError('invalid_library_import_path');
+            if (current?.isDirectory() && !current.isSymbolicLink() && !incoming
+                && await directorySnapshot(target) === manifest.incomingHash) {
+                if (manifest.operationId && manifest.assetId && manifest.paths)
+                    result.published.push({ operationId: manifest.operationId, assetId: manifest.assetId, paths: manifest.paths });
+                await removeTransaction(rootReal, transaction);
+                result.recovered.push(manifest.target);
+                continue;
+            }
+            if (backup) {
+                if (current) {
+                    if (!current.isDirectory() || current.isSymbolicLink() || (await readdir(target)).length)
+                        throw new AssetLibraryImportError('content_conflict');
+                    if (manifest.reservation && (current.ino !== manifest.reservation.ino || current.dev !== manifest.reservation.dev))
+                        throw new AssetLibraryImportError('content_conflict');
+                    await safeDirectory(rootReal, parent);
+                    await rmdir(target);
+                }
+                await safeDirectory(rootReal, parent);
+                await safeDirectory(rootReal, relative(rootReal, transaction));
+                await rename(join(transaction, 'previous'), target);
+                await syncDirectory(dirname(target));
+                await removeTransaction(rootReal, transaction);
+                result.recovered.push(manifest.target);
+                continue;
+            }
+            if (manifest.originalHash !== null && !current)
+                throw new AssetLibraryImportError('content_conflict');
+            await removeTransaction(rootReal, transaction);
+        }
+        catch {
+            result.pending.push(relative(rootReal, transaction));
+        }
+    }
+    return result;
+}
+async function publishBundle(root, target, asset, replace, assertCurrent, operationId) {
+    const parent = dirname(target) === '.' ? '' : dirname(target);
+    await safeDirectory(root, parent, true);
+    const previous = await statTarget(root, target);
+    if (previous && (!replace || !previous.isDirectory() || previous.isSymbolicLink()))
+        throw new AssetLibraryImportError('content_conflict');
+    const originalHash = previous ? await directorySnapshot(join(root, target)) : undefined;
+    const scratch = await safeDirectory(root, '.playcraft-temp', true);
+    const transaction = await mkdtemp(join(scratch, 'library-import-'));
+    const staged = join(transaction, 'incoming'), backup = join(transaction, 'previous');
+    await mkdir(staged, { mode: 0o700 });
+    let moved = false, published = false, preserve = false;
+    let reservation;
+    try {
+        for (const file of asset.files) {
+            await writeWorkspaceBinaryFile(staged, { path: file.path, contentBase64: file.content, expectedContentHash: null });
+        }
+        const manifest = { version: 1, target, phase: 'prepared', originalHash: originalHash ?? null,
+            incomingHash: await directorySnapshot(staged), ...(operationId ? { operationId, assetId: asset.assetId,
+                paths: asset.files.map(file => `${target}/${file.path}`) } : {}) };
+        await saveTransaction(root, transaction, manifest);
+        await assertCurrent();
+        await safeDirectory(root, parent);
+        const current = await statTarget(root, target);
+        if (previous) {
+            if (!current || current.ino !== previous.ino || current.dev !== previous.dev || !current.isDirectory()
+                || await directorySnapshot(join(root, target)) !== originalHash)
+                throw new AssetLibraryImportError('content_conflict');
+            await rename(join(root, target), backup);
+            moved = true;
+            preserve = true;
+            await syncDirectory(join(root, parent));
+            await saveTransaction(root, transaction, { ...manifest, phase: 'backed_up' });
+            if (await directorySnapshot(backup) !== originalHash)
+                throw new AssetLibraryImportError('content_conflict');
+        }
+        else if (current)
+            throw new AssetLibraryImportError('content_conflict');
+        await mkdir(join(root, target), { mode: 0o700 });
+        reservation = await lstat(join(root, target));
+        await saveTransaction(root, transaction, { ...manifest, phase: 'reserved', reservation: { dev: reservation.dev, ino: reservation.ino } });
+        await assertCurrent();
+        await safeDirectory(root, parent);
+        await safeDirectory(root, relative(root, transaction));
+        const verified = await lstat(join(root, target));
+        if (!verified.isDirectory() || verified.isSymbolicLink() || verified.ino !== reservation.ino || verified.dev !== reservation.dev)
+            throw new AssetLibraryImportError('content_conflict');
+        await rename(staged, join(root, target));
+        published = true;
+        preserve = Boolean(operationId);
+        await syncDirectory(join(root, parent));
+        await saveTransaction(root, transaction, { ...manifest, phase: 'published' });
+        return operationId ? transaction : undefined;
+    }
+    catch (error) {
+        if (!published && reservation) {
+            const current = await statTarget(root, target);
+            if (current?.ino === reservation.ino && current.dev === reservation.dev)
+                await rmdir(join(root, target)).catch(() => undefined);
+        }
+        if (moved && !published) {
+            preserve = true;
+            if (!await statTarget(root, target)) {
+                await rename(backup, join(root, target));
+                preserve = false;
+            }
+        }
+        throw error;
+    }
+    finally {
+        // A concurrent replacement can prevent rollback; keep the original bytes for recovery.
+        if (!preserve)
+            await removeTransaction(root, transaction).catch(() => undefined);
+    }
+}
+export async function importWorkspaceLibraryAssets(root, selection, snapshot, assertCurrent = async () => undefined, options = {}) {
+    const payload = workspaceAssetLibraryImportPayloadSchema.parse(selection);
+    const transport = workspaceAssetLibraryImportTransportSchema.parse(snapshot);
+    const exported = new Map(transport.assets.map(asset => [asset.assetId, asset]));
+    const received = new Set([...exported.keys(), ...transport.failures.map(failure => failure.assetId)]);
+    if (payload.assetIds.length !== received.size || payload.assetIds.some(id => !received.has(id)))
+        throw new AssetLibraryImportError('invalid_library_import');
+    if (payload.targetDirectory)
+        validPath(payload.targetDirectory);
+    const rootReal = await realpath(root);
+    await safeDirectory(rootReal, payload.targetDirectory, true);
+    const result = { paths: [], skippedPaths: [], failures: [...transport.failures] };
+    const processed = new Set(transport.failures.map(failure => failure.assetId));
+    const progress = () => options.onProgress?.({ ...result, failures: [...result.failures,
+            ...payload.assetIds.filter(id => !processed.has(id)).map(assetId => ({ assetId, error: 'asset_library_import_interrupted' }))] });
+    await progress();
+    for (const assetId of payload.assetIds) {
+        const asset = exported.get(assetId);
+        if (!asset)
+            continue;
+        let publishedTransaction;
+        try {
+            validateAsset(asset);
+            await assertCurrent();
+            const originalName = asset.kind === 'bundle'
+                ? asset.name.replace(/\.(?:prefab|aiaudio|aiimage|aiconfig|aigameplay)$/i, '')
+                : basename(asset.files[0].path);
+            validPath(originalName);
+            if (originalName.includes('/'))
+                throw new AssetLibraryImportError('invalid_library_import_path');
+            let name = originalName;
+            let target = validPath([payload.targetDirectory, name].filter(Boolean).join('/'));
+            let existing = await statTarget(rootReal, target);
+            if (existing && payload.collision === 'skip') {
+                result.skippedPaths.push(target);
+                processed.add(assetId);
+                await progress();
+                continue;
+            }
+            if (payload.collision === 'rename') {
+                const extension = asset.kind === 'bundle' ? '' : extname(originalName);
+                const stem = originalName.slice(0, originalName.length - extension.length);
+                for (let suffix = 1; existing; suffix++) {
+                    if (suffix > 10_000)
+                        throw new AssetLibraryImportError('content_conflict');
+                    name = `${stem} (${suffix})${extension}`;
+                    target = validPath([payload.targetDirectory, name].filter(Boolean).join('/'));
+                    existing = await statTarget(rootReal, target);
+                }
+            }
+            if (asset.kind === 'bundle') {
+                const paths = asset.files.map(file => validPath(`${target}/${file.path}`));
+                publishedTransaction = await publishBundle(rootReal, target, asset, payload.collision === 'replace', assertCurrent, options.operationId);
+                result.paths.push(...paths);
+            }
+            else {
+                const observed = existing ? await observeWorkspaceBinaryFile(rootReal, target) : undefined;
+                await assertCurrent();
+                await writeWorkspaceBinaryFile(rootReal, { path: target, contentBase64: asset.files[0].content,
+                    expectedContentHash: observed?.contentHash ?? null });
+                result.paths.push(target);
+            }
+        }
+        catch (error) {
+            const code = error instanceof AssetLibraryImportError ? error.message
+                : error?.code === 'content_conflict' ? 'content_conflict'
+                    : ['EACCES', 'EPERM'].includes(String(error?.code)) ? 'workspace_permission_denied'
+                        : 'asset_library_import_failed';
+            result.failures.push({ assetId, error: code });
+        }
+        processed.add(assetId);
+        await progress();
+        if (publishedTransaction)
+            await removeTransaction(rootReal, publishedTransaction).catch(() => undefined);
+    }
+    return workspaceAssetLibraryImportResultSchema.parse(result);
+}