@playcraft/cli 0.1.64 → 0.1.66

package/dist/workspace-runtime/workspaces/build-isolation.js

@@ -0,0 +1,75 @@
+import { constants } from 'node:fs';
+import { copyFile, cp, lstat, mkdir, readdir, readlink, symlink } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { listWorkspaceBuildInputs } from './git.js';
+import { ensureSharedDirectory } from './shared-write.js';
+/** Staging under the workspace from earlier runtimes' sandbox delivery builds; never a build input. */
+const STAGING_DIRECTORY = '.playcraft-delivery';
+/** Never copied into the build copy: history, outputs and caches that the build neither reads nor owns. */
+const ISOLATE_SKIP = new Set(['.git', 'dist', '.turbo', STAGING_DIRECTORY]);
+/** Copy-on-write clone where the filesystem supports it (APFS, btrfs, XFS); a plain copy elsewhere. */
+const CLONE = constants.COPYFILE_FICLONE;
+const COPY_CONCURRENCY = 16;
+function skipped(path) {
+    const parts = path.split(/[\\/]/);
+    return ISOLATE_SKIP.has(parts[0]) || parts.includes('node_modules');
+}
+async function copyInput(root, destination, path) {
+    const source = join(root, path);
+    const target = join(destination, path);
+    let entry;
+    try {
+        entry = await lstat(source);
+    }
+    catch (error) {
+        // A tracked file deleted in the work tree is not a build input.
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    await mkdir(dirname(target), { recursive: true });
+    if (entry.isSymbolicLink())
+        await symlink(await readlink(source), target);
+    else if (entry.isDirectory())
+        await cp(source, target, { recursive: true, verbatimSymlinks: true, mode: CLONE });
+    else
+        await copyFile(source, target, CLONE);
+}
+/**
+ * Copies the workspace into `destination` for one build, like the platform export runner, with the
+ * top-level `node_modules` linked (the build only reads it). Builders rewrite project files in place
+ * (`builds.config.js` and its `.bak`, `package.json` scripts, migrated imports), so the build must
+ * never run in the workspace itself, where autosave would commit those rewrites.
+ *
+ * Only the files Git would carry are copied: tracked ones and untracked ones `.gitignore` keeps, so
+ * caches, logs and local outputs stay behind. Without a repository the whole tree is copied.
+ */
+export async function isolateWorkspaceForBuild(root, destination) {
+    // The build runs as the development identity and writes its scratch folder inside this copy.
+    await ensureSharedDirectory(root, destination);
+    const modules = join(root, 'node_modules');
+    const modulesEntry = await lstat(modules).catch(() => undefined);
+    if (modulesEntry?.isDirectory() || modulesEntry?.isSymbolicLink()) {
+        await symlink(modulesEntry.isSymbolicLink() ? await readlink(modules) : modules, join(destination, 'node_modules'), 'dir');
+    }
+    const inputs = await listWorkspaceBuildInputs(root).catch(() => undefined);
+    const paths = inputs
+        ?? (await readdir(root)).filter((name) => name !== 'node_modules');
+    const queue = paths.filter((path) => !skipped(path));
+    const workers = Array.from({ length: Math.min(COPY_CONCURRENCY, queue.length) }, async () => {
+        for (let path = queue.shift(); path !== undefined; path = queue.shift()) {
+            if (inputs)
+                await copyInput(root, destination, path);
+            else {
+                await cp(join(root, path), join(destination, path), {
+                    recursive: true,
+                    verbatimSymlinks: true,
+                    mode: CLONE,
+                    // Nested dependency folders stay out as well; the build resolves through the linked root.
+                    filter: (source) => !relative(join(root, path), source).split(sep).includes('node_modules'),
+                });
+            }
+        }
+    });
+    await Promise.all(workers);
+}

package/dist/workspace-runtime/workspaces/model-build-inputs.js

@@ -118,6 +118,16 @@ export async function readWorkspaceModelBuildInputs(root, stateDir) {
                 throw new Error('model_build_resource_manifest_mismatch');
             for (const file of source.files)
                 inputs.push((await read(file.path, file.contentHash)).file);
+            // Resolve the actual installed dependency inputs even when a generated declaration predates installation.
+            for (const path of ['package.json', 'pnpm-lock.yaml', 'package-lock.json', 'yarn.lock']) {
+                try {
+                    inputs.push((await read(path)).file);
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+            }
         }
         else {
             const candidate = candidates?.candidates.find(item => item.runId === source.runId && item.candidateId === source.candidateId);
@@ -174,6 +184,23 @@ export async function verifyWorkspaceModelBuildInputs(root, snapshot) {
         if (model.source.kind === 'procedural' &&
             await dependencyHash(root) !== model.source.dependencyHash)
             throw new Error('model_build_input_changed');
+    for (const model of snapshot.models)
+        if (model.source.kind === 'resource') {
+            for (const path of ['package.json', 'pnpm-lock.yaml', 'package-lock.json', 'yarn.lock']) {
+                const frozen = model.inputs.find(file => file.path === path);
+                try {
+                    const bytes = await checkedFile(root, path, 64 * 1024 * 1024);
+                    if (!frozen || digest(bytes) !== frozen.contentHash)
+                        throw new Error('model_build_input_changed');
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                    if (frozen)
+                        throw new Error('model_build_input_changed');
+                }
+            }
+        }
 }
 /** The marker makes otherwise identical HTML from different input declarations distinct artifacts. */
 export function markWorkspaceModelBuild(bytes, snapshot) {

package/dist/workspace-runtime/workspaces/model-preparation-store.js

@@ -0,0 +1,134 @@
+import { lstat, mkdir, readdir, realpath, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { modelPreparationReceiptSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { hash, hashData, preparationPath, readPreparationFile, readPreparationJson, writePreparationJson } from '../../model-preparation/pipeline-files.js';
+import { observeWorkspaceBinaryFile, writeWorkspaceBinaryFile } from './binary-write.js';
+/** Control-owned step truth. Workspace metadata is never accepted as an execution receipt. */
+export class ModelPreparationStore {
+    workspaceId;
+    directoryName;
+    pipelineId;
+    stepId;
+    root;
+    constructor(stateDir, workspaceId, directoryName, pipelineId, stepId) {
+        this.workspaceId = workspaceId;
+        this.directoryName = directoryName;
+        this.pipelineId = pipelineId;
+        this.stepId = stepId;
+        if (!/^[a-f0-9-]{36}$/.test(workspaceId) || !/^[a-f0-9-]{36}$/.test(pipelineId) || stepId.length < 1 || stepId.length > 128)
+            throw Error('model_prepare_scope_invalid');
+        this.root = join(stateDir, 'model-preparations', hashData({ workspaceId, directoryName }), pipelineId, hash(stepId));
+    }
+    async read() {
+        const value = await readPreparationJson(this.root, 'record.json');
+        if (value && (value.schemaVersion !== 1 || value.workspaceId !== this.workspaceId || value.directoryName !== this.directoryName ||
+            value.pipelineId !== this.pipelineId || value.stepId !== this.stepId))
+            throw Error('model_prepare_scope_mismatch');
+        if (value?.receipt) {
+            const parsed = modelPreparationReceiptSchema.parse(value.receipt), { receiptHash, ...body } = parsed;
+            if (hashData(body) !== receiptHash)
+                throw Error('model_prepare_receipt_changed');
+        }
+        return value;
+    }
+    async write(value) {
+        if (value.workspaceId !== this.workspaceId || value.directoryName !== this.directoryName || value.pipelineId !== this.pipelineId || value.stepId !== this.stepId)
+            throw Error('model_prepare_scope_mismatch');
+        if (value.receipt)
+            modelPreparationReceiptSchema.parse(value.receipt);
+        await writePreparationJson(join(this.root, 'record.json'), value);
+    }
+}
+/** New standalone template baseline, including preserved instructions; never traverse repository internals. */
+export async function targetPreparationSnapshot(root) {
+    const result = [];
+    let size = 0;
+    async function walk(prefix = '') {
+        for (const entry of await readdir(join(root, prefix), { withFileTypes: true })) {
+            if (['.git', 'node_modules'].includes(entry.name))
+                continue;
+            const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+            preparationPath(path);
+            if (entry.isSymbolicLink())
+                throw Error('model_prepare_target_unsafe');
+            if (entry.isDirectory())
+                await walk(path);
+            else {
+                const file = await readPreparationFile(root, path);
+                size += file.bytes.length;
+                if (result.length >= 1024 || size > 256 * 1024 * 1024)
+                    throw Error('model_prepare_target_bound');
+                result.push({ path, contentHash: file.contentHash, bytes: file.bytes.length });
+            }
+        }
+    }
+    await walk();
+    return result.sort((a, b) => a.path.localeCompare(b.path, 'en'));
+}
+export function preparationWriteFiles(result) {
+    return result.files.filter(file => !['AGENTS.md', 'README.md'].includes(file.path));
+}
+/** Every output is either its frozen preimage or this exact transaction's postimage. */
+export async function promotePreparationProject(store, target, record, options) {
+    if (!record.result || !record.targetSnapshot)
+        throw Error('model_prepare_transaction_missing');
+    if (await realpath(target) !== target || !(await lstat(target)).isDirectory())
+        throw Error('model_prepare_target_unsafe');
+    const expected = new Map(record.targetSnapshot.map(file => [file.path, file.contentHash]));
+    if (!record.transaction) {
+        const actual = await targetPreparationSnapshot(target);
+        if (hashData(actual) !== hashData(record.targetSnapshot))
+            throw Error('model_prepare_target_changed');
+        record.transaction = { files: preparationWriteFiles(record.result).map(file => ({ ...file, before: expected.get(file.path) ?? null })), published: [] };
+        record.phase = 'promoting';
+        await store.write(record);
+    }
+    const transaction = record.transaction;
+    const expectedPaths = new Set([...record.targetSnapshot.map(file => file.path), ...transaction.files.map(file => file.path)]);
+    for (const file of await targetPreparationSnapshot(target)) {
+        if (!expectedPaths.has(file.path))
+            throw Error('model_prepare_target_changed');
+        const write = transaction.files.find(item => item.path === file.path);
+        if (file.contentHash !== (expected.get(file.path) ?? null) && (!write || file.contentHash !== write.contentHash))
+            throw Error('model_prepare_target_changed');
+    }
+    // A removed non-output instruction is also a conflict, rather than a reason to recreate it.
+    for (const file of record.targetSnapshot)
+        if (!transaction.files.some(item => item.path === file.path) &&
+            (await observeWorkspaceBinaryFile(target, file.path))?.contentHash !== file.contentHash)
+            throw Error('model_prepare_target_changed');
+    for (const file of transaction.files) {
+        options.signal?.throwIfAborted();
+        await options.assertCurrent();
+        const current = await observeWorkspaceBinaryFile(target, file.path);
+        if (current?.contentHash !== file.contentHash) {
+            if ((current?.contentHash ?? null) !== file.before)
+                throw Error('model_prepare_target_changed');
+            const source = await readPreparationFile(record.result.projectRoot, file.path);
+            if (source.contentHash !== file.contentHash || source.bytes.length !== file.bytes)
+                throw Error('model_prepare_worker_output_changed');
+            if (current) {
+                const backup = join(store.root, 'preimages', file.path);
+                await mkdir(dirname(backup), { recursive: true, mode: 0o700 }); // private: controller-only preparation state
+                const old = await readPreparationFile(target, file.path);
+                if (old.contentHash !== file.before)
+                    throw Error('model_prepare_target_changed');
+                const { writeFile } = await import('node:fs/promises');
+                await writeFile(backup, old.bytes, { flag: 'wx', mode: 0o600 }).catch(async (error) => {
+                    if (error.code !== 'EEXIST' || hash(await readFile(backup)) !== file.before)
+                        throw error;
+                });
+            }
+            await writeWorkspaceBinaryFile(target, { path: file.path, contentBase64: source.bytes.toString('base64'), expectedContentHash: file.before });
+        }
+        if (!transaction.published.includes(file.path)) {
+            const actual = await observeWorkspaceBinaryFile(target, file.path);
+            if (!actual || actual.contentHash !== file.contentHash)
+                throw Error('model_prepare_target_changed');
+            await options.onFile({ path: file.path, ...actual });
+            transaction.published.push(file.path);
+            await store.write(record);
+        }
+    }
+    await options.assertCurrent();
+}

package/dist/workspace-runtime/workspaces/model-preparation.js

@@ -0,0 +1,357 @@
+import { chmod, chown, lstat, mkdir, mkdtemp, readFile, readdir, realpath, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { canonicalModelAdaptation, hashOperationPayload, modelPreparationPayloadSchema, modelPreparationReceiptSchema, transitionOperation, } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceRoot, revisionScope } from './registry.js';
+import { runDeveloperCommand } from './developer-command.js';
+import { openScratchToDevelopment } from './directory-access.js';
+import { stopLauncherExecution } from '../codex/launcher-client.js';
+import { assertOperationDirectoryAccess } from '../server/directory-access.js';
+import { ModelPreparationStore, promotePreparationProject, targetPreparationSnapshot } from './model-preparation-store.js';
+import { hash, hashData, preparationInventory, readPreparationFile, readPreparationJson, writePreparationJson } from '../../model-preparation/pipeline-files.js';
+const active = new WeakMap();
+const tasks = new WeakMap();
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+const identity = (payload) => { const { resumeFromReceiptHash: _resume, ...value } = payload; return hashData(value); };
+const requestKey = (workspaceId, payload) => hashData({ workspaceId, pipelineId: payload.pipelineId, stepId: payload.stepId });
+export async function preparationToolManifest() {
+    const files = ['model-preparation/pipeline-worker.js', 'model-preparation/pipeline-engine.js', 'model-preparation/pipeline-files.js',
+        'model-preparation/glb.js', 'model-preparation/geometry.js', 'model-preparation/split-rigid.js', 'model-preparation/vertex-repairs.js',
+        'model-adaptation/node-inspection.js', 'model-adaptation/source.js', 'model-adaptation/project.js', 'model-adaptation/project-template.js',
+        'model-optimization/optimize.js', 'workspace-runtime/workspaces/model-preparation.js', 'workspace-runtime/workspaces/model-preparation-store.js'];
+    const common = createRequire(import.meta.url).resolve('@playcraft/common/cloud-workspace/runtime');
+    const manifest = await Promise.all(files.map(async (path) => ({ path, contentHash: hash(await readFile(new URL(`../../../dist/${path}`, import.meta.url))) })));
+    const visitCommon = async (path, prefix = '') => {
+        for (const entry of await readdir(path, { withFileTypes: true })) {
+            if (entry.isSymbolicLink())
+                throw Error('model_prepare_tool_path_unsafe');
+            const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                await visitCommon(join(path, entry.name), name);
+            else if (entry.name.endsWith('.js'))
+                manifest.push({ path: `common/${name}`, contentHash: hash(await readFile(join(path, entry.name))) });
+        }
+    };
+    await visitCommon(dirname(common));
+    const require = createRequire(import.meta.url), threeRoot = dirname(dirname(require.resolve('three')));
+    for (const [name, path] of [['three-module', join(threeRoot, 'build/three.module.js')], ['three-core', join(threeRoot, 'build/three.core.js')],
+        ['three-loader', require.resolve('three/examples/jsm/loaders/GLTFLoader.js')], ['earcut', require.resolve('earcut')],
+        ...Object.keys(require.cache).filter(path => /sharp.*\.node$/.test(path)).sort().map((path, index) => [`sharp-native-${index}`, path])])
+        manifest.push({ path: `dependency/${name}`, contentHash: hash(await readFile(path)) });
+    manifest.push({ path: 'cli/package.json', contentHash: hash(await readFile(new URL('../../../package.json', import.meta.url))) });
+    manifest.sort((a, b) => a.path.localeCompare(b.path, 'en'));
+    return { schemaVersion: 1, files: manifest, toolHash: hashData(manifest) };
+}
+async function seal(path, groupId) {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink())
+        throw Error('model_prepare_path_unsafe');
+    if (stat.gid !== groupId)
+        await chown(path, stat.uid, groupId);
+    if (stat.isDirectory()) {
+        for (const entry of await readdir(path))
+            await seal(join(path, entry), groupId);
+        await chmod(path, 0o550);
+    }
+    else
+        await chmod(path, 0o440);
+}
+async function verifyOriginalSource(root, record) {
+    for (const file of record.sourceSnapshot ?? []) {
+        const actual = await readPreparationFile(root, file.path), before = record.sourceStats?.find(item => item.path === file.path);
+        if (actual.contentHash !== file.contentHash || actual.bytes.length !== file.bytes || before &&
+            ['ino', 'dev', 'size', 'mtimeMs', 'ctimeMs'].some(key => actual.stat[key] !== before[key]))
+            throw Error('model_prepare_source_changed');
+    }
+}
+async function snapshotSource(root, store, record) {
+    const files = [], stats = [];
+    let total = 0;
+    for (const file of record.payload.source.files) {
+        if (file.path.split('/').includes('.playcraft'))
+            throw Error('model_prepare_source_path_unsafe');
+        const actual = await readPreparationFile(root, file.path);
+        total += actual.bytes.length;
+        if (actual.contentHash !== file.contentHash || total > 128 * 1024 * 1024)
+            throw Error('model_prepare_source_identity_mismatch');
+        const path = join(store.root, 'source', file.path);
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 }); // private: controller-only preparation state
+        await writeFile(path, actual.bytes, { flag: 'wx', mode: 0o600 }).catch(async (error) => { if (error.code !== 'EEXIST' || hash(await readFile(path)) !== file.contentHash)
+            throw error; }); // private: controller-only preparation state
+        files.push({ ...file, bytes: actual.bytes.length });
+        const { ino, dev, size, mtimeMs, ctimeMs } = actual.stat;
+        stats.push({ path: file.path, ino, dev, size, mtimeMs, ctimeMs });
+    }
+    record.sourceSnapshot = files;
+    record.sourceStats = stats;
+    await verifyOriginalSource(root, record);
+    record.phase = 'snapshotted';
+    await store.write(record);
+}
+function receipt(record, status, reasonCode) {
+    const result = record.result;
+    const base = { kind: 'model-preparation', schemaVersion: 1, pipelineId: record.pipelineId, stepId: record.stepId,
+        status, ...(reasonCode ? { reasonCode } : {}), inputHash: record.inputHash, sourceScope: record.payload.sourceScope, source: record.payload.source,
+        ...(status === 'prepared' && result ? { model: result.model, adaptationPath: result.adaptationPath, adaptationHash: result.adaptationHash,
+            manifestPath: '.playcraft/model-build-inputs.json', modelBytes: result.modelBytes, triangles: result.triangles,
+            lineageFiles: result.lineageFiles, writePaths: record.transaction?.files.map(file => file.path) ?? [] } : { lineageFiles: [], writePaths: record.transaction?.published ?? [] }),
+        toolHash: record.toolHash, browserValidation: 'pending', modelAcceptance: false };
+    return modelPreparationReceiptSchema.parse({ ...base, receiptHash: hashData(base) });
+}
+export async function readModelPreparation(state, workspaceId, directoryName, pipelineId, stepId) {
+    await workspaceRoot(state, workspaceId, directoryName);
+    const record = await new ModelPreparationStore(state.config.stateDir, workspaceId, directoryName, pipelineId, stepId).read();
+    return record?.receipt ?? null;
+}
+export function trackModelPreparation(state, task) {
+    const known = tasks.get(state) ?? new Set();
+    tasks.set(state, known);
+    known.add(task);
+    void task.finally(() => known.delete(task)).catch(() => undefined);
+}
+export async function stopModelPreparations(state) {
+    for (const controller of active.get(state)?.values() ?? [])
+        controller.abort();
+    await Promise.allSettled([...(tasks.get(state) ?? [])]);
+}
+/** A controlled local step creates source and receipts; it never installs, builds, infers or validates a game. */
+export async function runModelPreparation(state, operation, value, options) {
+    const payload = modelPreparationPayloadSchema.parse(value);
+    if (!operation.workspaceId || operation.directoryName !== 'basic' || payload.targetDirectoryName !== 'basic' ||
+        state.journal.getWorkspace(operation.workspaceId)?.targetKind !== 'standalone')
+        throw Error('model_prepare_target_scope_invalid');
+    const target = await workspaceRoot(state, operation.workspaceId, 'basic'), source = await workspaceRoot(state, payload.sourceScope.workspaceId, payload.sourceScope.directoryName);
+    const store = new ModelPreparationStore(state.config.stateDir, operation.workspaceId, 'basic', payload.pipelineId, payload.stepId);
+    const tools = await preparationToolManifest(), inputHash = hashOperationPayload(payload), semanticInputHash = identity(payload), key = requestKey(operation.workspaceId, payload);
+    const known = active.get(state) ?? new Map();
+    active.set(state, known);
+    if (known.has(key))
+        throw Error('model_prepare_already_running');
+    let record = await store.read();
+    if (record && (record.semanticInputHash !== semanticInputHash || record.toolHash !== tools.toolHash))
+        throw Error('model_prepare_resume_identity_mismatch');
+    if (payload.resumeFromReceiptHash && record?.receipt?.receiptHash !== payload.resumeFromReceiptHash)
+        throw Error('model_prepare_resume_receipt_mismatch');
+    if (record?.phase === 'uncertain' || record?.phase === 'running')
+        throw Error('model_prepare_recovery_required');
+    if (record?.receipt) {
+        if (record.inputHash !== inputHash) {
+            await writePreparationJson(join(store.root, 'receipts', `${record.receipt.receiptHash}.json`), record.receipt);
+            record.inputHash = inputHash;
+            record.payload = payload;
+            record.receipt = receipt(record, record.receipt.status, record.receipt.reasonCode);
+            await store.write(record);
+        }
+        return record.receipt;
+    }
+    const assertCurrent = async () => {
+        if (state.journal.destroyed() || (operation.leaseFence ?? 0) < state.acceptedLeaseFence || operation.generation !== state.config.generation || operation.runtimeEpoch !== state.runtimeEpoch)
+            throw Error('model_prepare_stale_operation');
+        await assertOperationDirectoryAccess(state, operation, 'exclusive');
+    };
+    await assertCurrent();
+    const controller = new AbortController();
+    known.set(key, controller);
+    const writeId = `model-prepare-${operation.gatewayOperationId ?? operation.operationId}`;
+    let stopped = true;
+    try {
+        const ownerPath = join(dirname(dirname(store.root)), 'target-owner.json');
+        const owner = await readPreparationJson(dirname(ownerPath), 'target-owner.json');
+        if (owner && owner.pipelineId !== payload.pipelineId)
+            throw Error('model_prepare_target_owned');
+        if (!owner)
+            await writePreparationJson(ownerPath, { pipelineId: payload.pipelineId, workspaceId: operation.workspaceId, directoryName: 'basic' });
+        if (!record) {
+            const targetSnapshot = await targetPreparationSnapshot(target);
+            if (payload.expectedTargetSnapshotHash && hashData(targetSnapshot) !== payload.expectedTargetSnapshotHash)
+                throw Error('model_prepare_target_changed');
+            record = { schemaVersion: 1, pipelineId: payload.pipelineId, stepId: payload.stepId, workspaceId: operation.workspaceId, directoryName: 'basic',
+                inputHash, semanticInputHash, toolHash: tools.toolHash, payload, phase: 'planned', createdAt: new Date().toISOString(), targetSnapshot };
+            await store.write(record);
+            await writePreparationJson(join(store.root, 'tools.json'), tools);
+        }
+        record.inputHash = inputHash;
+        record.payload = payload;
+        await store.write(record);
+        await writePreparationJson(join(state.config.stateDir, 'model-preparations', 'operations', `${operation.operationId}.json`), {
+            workspaceId: operation.workspaceId, directoryName: 'basic', pipelineId: payload.pipelineId, stepId: payload.stepId,
+        });
+        if (!record.sourceSnapshot)
+            await snapshotSource(source, store, record);
+        else
+            await verifyOriginalSource(source, record);
+        if (!record.result) {
+            let scratch = record.scratch;
+            if (scratch && !await lstat(scratch).then(value => value.isDirectory() && !value.isSymbolicLink(), () => false)) {
+                await writePreparationJson(join(store.root, 'lost-scratch', `${Date.now()}.json`), { path: scratch, reason: 'worker-scratch-unavailable', stagesRecomputedOnExplicitResume: true });
+                scratch = undefined;
+            }
+            if (!scratch) {
+                scratch = await realpath(await mkdtemp(join(tmpdir(), 'playcraft-model-prepare-')));
+                const groupId = (await lstat(target)).gid;
+                await openScratchToDevelopment(scratch, groupId);
+                await chmod(scratch, 0o750);
+                const inputRoot = join(scratch, 'input');
+                await mkdir(inputRoot);
+                for (const file of record.sourceSnapshot ?? []) {
+                    const bytes = (await readPreparationFile(join(store.root, 'source'), file.path)).bytes, destination = join(inputRoot, file.path);
+                    await mkdir(dirname(destination), { recursive: true });
+                    await writeFile(destination, bytes, { flag: 'wx' });
+                }
+                await seal(inputRoot, groupId);
+                await mkdir(join(scratch, 'output'));
+                await openScratchToDevelopment(join(scratch, 'output'), groupId);
+                const configPath = join(scratch, 'input.json');
+                await writePreparationJson(configPath, { payload, sourceRoot: inputRoot, outputRoot: join(scratch, 'output'), toolHash: tools.toolHash, tools });
+                await seal(configPath, groupId);
+                record.scratch = scratch;
+                await store.write(record);
+            }
+            const configPath = join(scratch, 'input.json'), configHash = hash(await readFile(configPath));
+            const config = JSON.parse(await readFile(configPath, 'utf8'));
+            if (identity(modelPreparationPayloadSchema.parse(config.payload)) !== semanticInputHash || config.toolHash !== tools.toolHash || hashData(config.tools) !== hashData(tools) ||
+                config.sourceRoot !== join(scratch, 'input') || config.outputRoot !== join(scratch, 'output'))
+                throw Error('model_prepare_worker_input_changed');
+            record.phase = 'running';
+            await store.write(record);
+            const outcome = await runDeveloperCommand(state, { processId: writeId, cwd: scratch,
+                command: `${quote(process.execPath)} --max-old-space-size=768 ${quote(options.workerPath ?? fileURLToPath(new URL('../../../dist/model-preparation/pipeline-worker.js', import.meta.url)))} ${quote(configPath)} ${quote(configHash)}`,
+                timeoutMs: 600_000, signal: controller.signal, onOutput: () => undefined,
+                onStarted: async (process) => {
+                    stopped = false;
+                    await state.journal.putManagedWrite({ writeId,
+                        workspaceId: revisionScope(state, operation.workspaceId, 'basic') ?? 'single', source: 'manual', directoryAccessMode: 'exclusive',
+                        startedAt: new Date().toISOString(), pid: process.pid,
+                        ...(process.launcher ? { executionMode: 'launcher', launcher: process.launcher, runtimeEpoch: state.runtimeEpoch } : { executionMode: 'local' }) });
+                } });
+            stopped = outcome.code !== undefined;
+            if (!stopped)
+                throw Error('model_prepare_process_unknown');
+            const writer = state.journal.listManagedWrites().find(item => item.writeId === writeId);
+            if (writer)
+                await state.journal.putManagedWrite({ ...writer, stoppedAt: new Date().toISOString() });
+            if (outcome.canceled)
+                throw Error('model_prepare_cancelled');
+            if (outcome.timedOut)
+                throw Error('model_prepare_timeout');
+            if (outcome.code !== 0)
+                throw Error('model_prepare_worker_failed');
+            const result = await readPreparationJson(join(scratch, 'output'), 'result.json', 8 * 1024 * 1024);
+            if (!result)
+                throw Error('model_prepare_worker_receipt_missing');
+            if (result.status === 'blocked') {
+                if (!/^([a-z]+_)+[a-z]+$/.test(result.reasonCode))
+                    throw Error('model_prepare_worker_receipt_invalid');
+                record.phase = 'blocked';
+                record.receipt = receipt(record, 'blocked', result.reasonCode);
+                await store.write(record);
+                return record.receipt;
+            }
+            if (result.status !== 'prepared' || !/^adapt-[a-f0-9-]{36}\/project$/.test(relative(join(scratch, 'output'), result.projectRoot)) ||
+                await realpath(result.projectRoot) !== result.projectRoot)
+                throw Error('model_prepare_worker_receipt_invalid');
+            const actual = await preparationInventory(result.projectRoot);
+            if (canonicalModelAdaptation(actual) !== canonicalModelAdaptation(result.files))
+                throw Error('model_prepare_worker_output_changed');
+            const produced = join(store.root, 'produced');
+            await mkdir(produced, { recursive: true, mode: 0o700 }); // private: controller-only preparation state
+            for (const file of actual) {
+                const bytes = (await readPreparationFile(result.projectRoot, file.path)).bytes, path = join(produced, file.path);
+                if (hash(bytes) !== file.contentHash)
+                    throw Error('model_prepare_worker_output_changed');
+                await mkdir(dirname(path), { recursive: true, mode: 0o700 }); // private: controller-only preparation state
+                await writeFile(path, bytes, { flag: 'wx', mode: 0o600 }).catch(async (error) => { if (error.code !== 'EEXIST' || hash(await readFile(path)) !== file.contentHash)
+                    throw error; }); // private: controller-only preparation state
+            }
+            if (canonicalModelAdaptation(await preparationInventory(produced)) !== canonicalModelAdaptation(actual))
+                throw Error('model_prepare_worker_output_changed');
+            record.result = { ...result, projectRoot: produced };
+            record.phase = 'produced';
+            await store.write(record);
+        }
+        if ((await preparationToolManifest()).toolHash !== tools.toolHash)
+            throw Error('model_prepare_tool_changed');
+        await verifyOriginalSource(source, record);
+        await assertCurrent();
+        if (payload.sourceScope.workspaceId === operation.workspaceId && payload.sourceScope.directoryName === 'basic') {
+            const writePaths = new Set(record.result.files.filter(file => !['AGENTS.md', 'README.md'].includes(file.path)).map(file => file.path));
+            if (payload.source.files.some(file => writePaths.has(file.path)))
+                throw Error('model_prepare_source_output_overlap');
+        }
+        await promotePreparationProject(store, target, record, { assertCurrent, onFile: options.onFile, signal: controller.signal });
+        await verifyOriginalSource(source, record);
+        record.phase = 'prepared';
+        record.receipt = receipt(record, 'prepared');
+        await store.write(record);
+        return record.receipt;
+    }
+    catch (error) {
+        if (record && stopped && error instanceof Error && /^model_prepare_(target_changed|source_changed|source_identity_mismatch|target_unsafe|source_output_overlap)$/.test(error.message)) {
+            record.phase = 'blocked';
+            record.receipt = receipt(record, 'blocked', error.message);
+            await store.write(record);
+            return record.receipt;
+        }
+        if (record) {
+            record.phase = stopped ? 'interrupted' : 'uncertain';
+            await store.write(record);
+        }
+        throw error;
+    }
+    finally {
+        known.delete(key);
+    }
+}
+/** Startup never relaunches a partial worker; it only confirms process termination and retains stages. */
+export async function recoverModelPreparationOperations(state, recovery) {
+    for (const { operation, scopeKey } of state.journal.listOperations()) {
+        if (operation.kind !== 'model.prepare' || !operation.workspaceId || !['dispatched', 'accepted', 'uncertain'].includes(operation.status))
+            continue;
+        const id = operation.gatewayOperationId ?? operation.operationId, writer = state.journal.listManagedWrites().find(item => item.writeId === `model-prepare-${id}`);
+        let stopped = Boolean(writer?.stoppedAt);
+        if (writer && !stopped) {
+            if (recovery.confirmStopped)
+                stopped = await recovery.confirmStopped(writer);
+            else if (writer.executionMode === 'launcher' && recovery.identityMatches && recovery.launcherSocket && writer.launcher && writer.launcher.processId === writer.writeId) {
+                if (recovery.previousRuntimeEpoch !== undefined && recovery.runtimeEpoch !== undefined && recovery.runtimeEpoch > recovery.previousRuntimeEpoch && writer.launcher.runtimeEpoch < recovery.runtimeEpoch)
+                    stopped = true;
+                else
+                    try {
+                        await stopLauncherExecution(recovery.launcherSocket, writer.launcher);
+                        stopped = true;
+                    }
+                    catch { /* retain uncertain */ }
+            }
+            else if (writer.executionMode === 'local' && writer.pid) {
+                const absent = (pid) => { try {
+                    process.kill(pid, 0);
+                    return false;
+                }
+                catch (error) {
+                    return error.code === 'ESRCH';
+                } };
+                stopped = absent(writer.pid) && absent(-writer.pid);
+            }
+        }
+        const binding = await readPreparationJson(state.config.stateDir, `model-preparations/operations/${operation.operationId}.json`);
+        const store = binding?.workspaceId === operation.workspaceId && binding.directoryName === 'basic'
+            ? new ModelPreparationStore(state.config.stateDir, binding.workspaceId, binding.directoryName, binding.pipelineId, binding.stepId) : undefined;
+        const record = await store?.read();
+        // onStarted persists the writer before opening its stdin gate; absent writer means it never ran.
+        if (!writer)
+            stopped = true;
+        if (writer && stopped && !writer.stoppedAt)
+            await state.journal.putManagedWrite({ ...writer, stoppedAt: new Date().toISOString() });
+        if (record?.receipt && stopped) {
+            await state.journal.putOperation(scopeKey, transitionOperation(operation, 'completed', { result: record.receipt }));
+            continue;
+        }
+        if (record && store) {
+            record.phase = stopped ? 'interrupted' : 'uncertain';
+            await store.write(record);
+        }
+        await state.journal.putOperation(scopeKey, transitionOperation(operation, stopped ? 'interrupted' : 'uncertain', { error: stopped ? 'model_prepare_interrupted' : 'model_prepare_process_unknown' }));
+    }
+}

package/dist/workspace-runtime/workspaces/platform-export.js

@@ -123,6 +123,7 @@ export async function startPlatformExport(state, input) {
             commitHash: commit,
             platforms: input.channels,
             clientRequestId: input.clientRequestId,
+            ...(input.options && Object.keys(input.options).length ? { options: input.options } : {}),
         },
     });
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.64",
+  "version": "0.1.66",
   "private": false,
   "type": "module",
   "engines": {
@@ -53,8 +53,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.64",
-    "@playcraft/common": "0.1.64",
+    "@playcraft/build": "0.1.66",
+    "@playcraft/common": "0.1.66",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
@@ -77,6 +77,7 @@
     "picocolors": "^1.1.1",
     "playwright-core": "1.52.0",
     "sharp": "^0.34.5",
+    "three": "0.183.2",
     "update-notifier": "^7.3.1",
     "ws": "^8.19.0",
     "zod": "^3.25.76"
@@ -93,7 +94,6 @@
     "@types/update-notifier": "^6.0.8",
     "@types/ws": "^8.18.1",
     "esbuild": "^0.28.1",
-    "three": "^0.183.2",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   }