@playcraft/cli 0.1.63 → 0.1.65

package/dist/model-preparation/glb.js

@@ -0,0 +1,176 @@
+import { readModelSourceDocument } from '@playcraft/common/cloud-workspace/runtime';
+import { createHash } from 'node:crypto';
+import { add, cross, dot, f32, length, mul, unit } from './geometry.js';
+export const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const identity = () => [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+function matrixMultiply(a, b) {
+    return Array.from({ length: 16 }, (_, i) => { const r = i % 4, c = Math.floor(i / 4); return [0, 1, 2, 3].reduce((sum, k) => sum + a[k * 4 + r] * b[c * 4 + k], 0); });
+}
+function nodeMatrix(node) {
+    if (node.matrix) {
+        if (!Array.isArray(node.matrix) || node.matrix.length !== 16 || !node.matrix.every(Number.isFinite))
+            throw Error('model_preparation_transform_invalid');
+        return node.matrix;
+    }
+    const t = node.translation ?? [0, 0, 0], s = node.scale ?? [1, 1, 1], q = node.rotation ?? [0, 0, 0, 1];
+    if (t.length !== 3 || s.length !== 3 || q.length !== 4 || ![...t, ...s, ...q].every(Number.isFinite) || Math.abs(Math.hypot(...q) - 1) > 1e-4)
+        throw Error('model_preparation_transform_invalid');
+    const [x, y, z, w] = q;
+    return [(1 - 2 * (y * y + z * z)) * s[0], 2 * (x * y + z * w) * s[0], 2 * (x * z - y * w) * s[0], 0,
+        2 * (x * y - z * w) * s[1], (1 - 2 * (x * x + z * z)) * s[1], 2 * (y * z + x * w) * s[1], 0,
+        2 * (x * z + y * w) * s[2], 2 * (y * z - x * w) * s[2], (1 - 2 * (x * x + y * y)) * s[2], 0,
+        t[0], t[1], t[2], 1];
+}
+export function readRigidGlb(bytes) {
+    const parsed = readModelSourceDocument(bytes), d = parsed.document, binary = parsed.binary;
+    if (!binary || parsed.extraChunks?.length || d.asset?.version !== '2.0' || d.buffers?.length !== 1 || d.buffers.some((b) => b.uri) ||
+        d.animations?.length || d.skins?.length || d.meshes?.length !== 1 || !Array.isArray(d.nodes) || d.nodes.length > 256)
+        throw Error('model_preparation_single_rigid_glb_required');
+    const primitive = d.meshes[0].primitives?.[0];
+    if (d.meshes[0].primitives?.length !== 1 || !primitive || primitive.targets || primitive.extensions || (primitive.mode ?? 4) !== 4 ||
+        Object.keys(primitive.attributes ?? {}).some(key => !['POSITION', 'NORMAL', 'TEXCOORD_0'].includes(key)))
+        throw Error('model_preparation_attributes_unsupported');
+    let world;
+    const visited = new Set();
+    const walk = (id, parent) => {
+        if (!Number.isSafeInteger(id) || visited.has(id) || !d.nodes[id])
+            throw Error('model_preparation_node_graph_invalid');
+        visited.add(id);
+        const node = d.nodes[id];
+        if (node.skin !== undefined || node.extensions)
+            throw Error('model_preparation_node_unsupported');
+        const matrix = matrixMultiply(parent, nodeMatrix(node));
+        if (node.mesh !== undefined) {
+            if (world || node.mesh !== 0)
+                throw Error('model_preparation_single_instance_required');
+            world = matrix;
+        }
+        for (const child of node.children ?? [])
+            walk(child, matrix);
+    };
+    for (const node of d.scenes?.[d.scene ?? 0]?.nodes ?? [])
+        walk(node, identity());
+    if (!world)
+        throw Error('model_preparation_empty_scene');
+    const m = world, axes = [[m[0], m[1], m[2]], [m[4], m[5], m[6]], [m[8], m[9], m[10]]], sizes = axes.map(length);
+    const determinant = dot(axes[0], cross(axes[1], axes[2]));
+    if (!m.every(Number.isFinite) || Math.abs(m[3]) + Math.abs(m[7]) + Math.abs(m[11]) + Math.abs(m[15] - 1) > 1e-9 || determinant <= 0 ||
+        Math.min(...sizes) < 1e-12 || Math.max(...sizes) / Math.min(...sizes) > 1.00001 ||
+        Math.abs(dot(axes[0], axes[1])) + Math.abs(dot(axes[1], axes[2])) + Math.abs(dot(axes[2], axes[0])) > sizes[0] ** 2 * 1e-5)
+        throw Error('model_preparation_positive_rigid_transform_required');
+    function accessor(id, components, allowed) {
+        const a = d.accessors?.[id], v = d.bufferViews?.[a?.bufferView], bytesPer = a?.componentType === 5126 || a?.componentType === 5125 ? 4 : 2;
+        if (!a || a.sparse || a.normalized || !allowed.includes(a.componentType) || a.type !== (components === 3 ? 'VEC3' : components === 2 ? 'VEC2' : 'SCALAR') ||
+            !Number.isSafeInteger(a.count) || a.count < 1 || a.count > 600000 || !v || v.buffer !== 0 || v.extensions)
+            throw Error('model_preparation_accessor_unsupported');
+        const start = (v.byteOffset ?? 0) + (a.byteOffset ?? 0), stride = v.byteStride ?? components * bytesPer;
+        if (![start, stride, v.byteLength].every(Number.isSafeInteger) || start < 0 || stride < components * bytesPer ||
+            start + (a.count - 1) * stride + components * bytesPer > (v.byteOffset ?? 0) + v.byteLength || (v.byteOffset ?? 0) + v.byteLength > binary.length)
+            throw Error('model_preparation_accessor_bound');
+        const view = new DataView(binary.buffer, binary.byteOffset, binary.byteLength);
+        return Array.from({ length: a.count }, (_, i) => Array.from({ length: components }, (_, k) => {
+            const offset = start + i * stride + k * bytesPer, value = a.componentType === 5126 ? view.getFloat32(offset, true) : bytesPer === 4 ? view.getUint32(offset, true) : view.getUint16(offset, true);
+            if (!Number.isFinite(value))
+                throw Error('model_preparation_nonfinite_accessor');
+            return value;
+        }));
+    }
+    const p = accessor(primitive.attributes.POSITION, 3, [5126]), n = accessor(primitive.attributes.NORMAL, 3, [5126]), uv = accessor(primitive.attributes.TEXCOORD_0, 2, [5126]);
+    const indices = accessor(primitive.indices, 1, [5123, 5125]).flat();
+    if (p.length !== n.length || p.length !== uv.length || indices.length % 3 || indices.length / 3 > 100000 || indices.some(i => i >= p.length))
+        throw Error('model_preparation_primitive_bound');
+    const transformVector = (v) => add(add(mul(axes[0], v[0]), mul(axes[1], v[1])), mul(axes[2], v[2]));
+    const faces = [];
+    for (let i = 0; i < indices.length; i += 3)
+        faces.push({ sourceTriangle: i / 3, kind: 'exterior', v: [0, 1, 2].map(k => {
+                const id = indices[i + k];
+                return { p: f32(add(transformVector(p[id]), [m[12], m[13], m[14]])), n: unit(transformVector(n[id])), uv: uv[id],
+                    bary: [+(k === 0), +(k === 1), +(k === 2)] };
+            }) });
+    const textures = (d.images ?? []).map((image) => {
+        const v = d.bufferViews?.[image.bufferView];
+        if (image.uri || !v || v.buffer !== 0 || !['image/png', 'image/jpeg', 'image/webp'].includes(image.mimeType) || v.byteOffset < 0 || v.byteOffset + v.byteLength > binary.length)
+            throw Error('model_preparation_embedded_image_required');
+        const data = binary.slice(v.byteOffset ?? 0, (v.byteOffset ?? 0) + v.byteLength);
+        return { image, bytes: data, contentHash: digest(data) };
+    });
+    if (!d.materials?.[primitive.material])
+        throw Error('model_preparation_material_required');
+    const positionAccessor = d.accessors[primitive.attributes.POSITION], positionView = d.bufferViews[positionAccessor.bufferView];
+    const binaryOffset = 28 + new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(12, true);
+    const positionByteOffsets = p.map((_, i) => binaryOffset + (positionView.byteOffset ?? 0) + (positionAccessor.byteOffset ?? 0) + i * (positionView.byteStride ?? 12));
+    return { faces, document: d, textures, materialIndex: primitive.material, sourceWorldMatrix: m,
+        localPositions: p, sourceIndices: indices, positionByteOffsets };
+}
+export function encodeSplitGlb(source, parts, parentHash) {
+    const chunks = [], bufferViews = [], accessors = [];
+    let byteOffset = 0;
+    const append = (bytes, target) => {
+        const id = bufferViews.length;
+        bufferViews.push({ buffer: 0, byteOffset, byteLength: bytes.length, ...(target ? { target } : {}) });
+        const padded = new Uint8Array(Math.ceil(bytes.length / 4) * 4);
+        padded.set(bytes);
+        chunks.push(padded);
+        byteOffset += padded.length;
+        return id;
+    };
+    const images = source.textures.map(t => ({ ...t.image, bufferView: append(t.bytes) }));
+    const materials = [...source.document.materials, { name: 'authored_untextured_wood_interior', doubleSided: false,
+            pbrMetallicRoughness: { baseColorFactor: [.18, .095, .035, 1], metallicFactor: 0, roughnessFactor: .9 } }];
+    const attribute = (array, type, components, target) => {
+        const id = accessors.length, view = append(new Uint8Array(array.buffer), target), count = array.length / components;
+        const min = Array.from({ length: components }, () => Infinity), max = min.map(() => -Infinity);
+        for (let i = 0; i < array.length; i++) {
+            const k = i % components;
+            min[k] = Math.min(min[k], array[i]);
+            max[k] = Math.max(max[k], array[i]);
+        }
+        accessors.push({ bufferView: view, componentType: array instanceof Float32Array ? 5126 : 5125, count, type, min, max });
+        return id;
+    };
+    const primitiveFaceCounts = [];
+    const meshes = parts.map(part => {
+        const groups = [part.faces.filter(f => ['exterior', 'auxiliary'].includes(f.kind)), part.faces.filter(f => ['interior', 'rim'].includes(f.kind))];
+        primitiveFaceCounts.push({ exterior: groups[0].length, interiorAndRim: groups[1].length });
+        return { name: `split_${part.role}_mesh`, primitives: groups.filter(fs => fs.length).map((fs, group) => {
+                const positions = [], normals = [], uvs = [], indices = [], seen = new Map();
+                for (const face of fs)
+                    for (const v of face.v) {
+                        const p = f32(v.p), n = f32(v.n), uv = v.uv.map(Math.fround), key = [...p, ...n, ...uv].join(',');
+                        let id = seen.get(key);
+                        if (id === undefined) {
+                            id = positions.length / 3;
+                            seen.set(key, id);
+                            positions.push(...p);
+                            normals.push(...n);
+                            uvs.push(...uv);
+                        }
+                        indices.push(id);
+                    }
+                return { attributes: { POSITION: attribute(new Float32Array(positions), 'VEC3', 3, 34962), NORMAL: attribute(new Float32Array(normals), 'VEC3', 3, 34962),
+                        TEXCOORD_0: attribute(new Float32Array(uvs), 'VEC2', 2, 34962) }, indices: attribute(new Uint32Array(indices), 'SCALAR', 1, 34963), material: group ? materials.length - 1 : source.materialIndex };
+            }) };
+    });
+    const document = { asset: { ...source.document.asset, generator: 'PlayCraft restricted rigid shell preparation' }, buffers: [{ byteLength: byteOffset }], bufferViews, accessors,
+        images, textures: source.document.textures ?? [], samplers: source.document.samplers ?? [], materials, meshes,
+        nodes: parts.map((part, mesh) => ({ name: `split_${part.role}`, mesh, extras: { playcraftPart: part.role } })), scenes: [{ nodes: parts.map((_, i) => i) }], scene: 0,
+        ...(source.document.extensionsUsed ? { extensionsUsed: source.document.extensionsUsed } : {}),
+        ...(source.document.extensionsRequired ? { extensionsRequired: source.document.extensionsRequired } : {}), extras: { playcraftParentSourceHash: parentHash, preparation: 'restricted-rigid-shell-v1' } };
+    const json = new TextEncoder().encode(JSON.stringify(document)), jsonLength = Math.ceil(json.length / 4) * 4;
+    const output = new Uint8Array(12 + 8 + jsonLength + 8 + byteOffset), view = new DataView(output.buffer);
+    view.setUint32(0, 0x46546c67, true);
+    view.setUint32(4, 2, true);
+    view.setUint32(8, output.length, true);
+    view.setUint32(12, jsonLength, true);
+    view.setUint32(16, 0x4e4f534a, true);
+    output.fill(32, 20, 20 + jsonLength);
+    output.set(json, 20);
+    view.setUint32(20 + jsonLength, byteOffset, true);
+    view.setUint32(24 + jsonLength, 0x004e4942, true);
+    let offset = 28 + jsonLength;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return { bytes: output, document, primitiveFaceCounts };
+}

package/dist/model-preparation/pipeline-engine.js

@@ -0,0 +1,157 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { modelPreparationPayloadSchema, workspaceModelAdaptationSchema, canonicalModelAdaptation } from '@playcraft/common/cloud-workspace/runtime';
+import { inspectModelSourceFiles } from '../model-adaptation/source.js';
+import { generateModelAdaptationProject } from '../model-adaptation/project.js';
+import { inspectRigidModel } from '../model-adaptation/node-inspection.js';
+import { applyRigidVertexRepairs } from './vertex-repairs.js';
+import { prepareRigidSplit } from './split-rigid.js';
+import { optimizeModel } from '../model-optimization/optimize.js';
+import { hash, hashData, preparationInventory, readPreparationFile, readPreparationJson, writePreparationJson } from './pipeline-files.js';
+/** Deterministic stages only. All destinations are fresh; prior incomplete attempts remain available. */
+export async function runPreparationEngine(input) {
+    const payload = modelPreparationPayloadSchema.parse(input.payload), { resumeFromReceiptHash: _resume, ...request } = payload;
+    const inputHash = hashData(request);
+    await mkdir(input.outputRoot, { recursive: true });
+    const checkpoint = await readPreparationJson(input.outputRoot, 'checkpoint.json') ?? {
+        schemaVersion: 1, inputHash, toolHash: input.toolHash, stages: {},
+    };
+    if (checkpoint.schemaVersion !== 1 || checkpoint.inputHash !== inputHash || checkpoint.toolHash !== input.toolHash)
+        throw Error('model_prepare_checkpoint_identity_changed');
+    const stage = async (name, identity, action) => {
+        input.signal?.throwIfAborted();
+        const stageHash = hashData({ inputHash, toolHash: input.toolHash, identity });
+        const prior = checkpoint.stages[name];
+        if (prior) {
+            if (prior.inputHash !== stageHash || !new RegExp(`^${name}-[a-f0-9-]{36}$`).test(prior.directory))
+                throw Error('model_prepare_checkpoint_identity_changed');
+            const actual = await preparationInventory(join(input.outputRoot, prior.directory));
+            if (canonicalModelAdaptation(actual) !== canonicalModelAdaptation(prior.files))
+                throw Error('model_prepare_checkpoint_output_changed');
+            return join(input.outputRoot, prior.directory);
+        }
+        const relative = `${name}-${randomUUID()}`, directory = join(input.outputRoot, relative);
+        await mkdir(directory);
+        await action(directory);
+        input.signal?.throwIfAborted();
+        const files = await preparationInventory(directory);
+        checkpoint.stages[name] = { inputHash: stageHash, directory: relative, files };
+        await writePreparationJson(join(input.outputRoot, 'checkpoint.json'), checkpoint, true);
+        return directory;
+    };
+    const observed = await inspectModelSourceFiles({ projectRoot: input.sourceRoot, modelPath: payload.source.path, signal: input.signal });
+    if (canonicalModelAdaptation({ ...observed.source, files: [...observed.source.files].sort((a, b) => a.path.localeCompare(b.path)) }) !==
+        canonicalModelAdaptation({ ...payload.source, files: [...payload.source.files].sort((a, b) => a.path.localeCompare(b.path)) }))
+        throw Error('model_prepare_source_identity_mismatch');
+    if (observed.metadata.unsupported.length)
+        throw Error('model_prepare_rigid_source_required');
+    if (payload.recipe.adaptation && canonicalModelAdaptation(payload.recipe.adaptation.source) !== canonicalModelAdaptation(payload.source))
+        throw Error('model_prepare_adaptation_source_mismatch');
+    if (payload.recipe.repair && (!/\.glb$/i.test(payload.source.path) || payload.source.files.length !== 1))
+        throw Error('model_prepare_repair_glb_required');
+    const initial = await stage('inspect', payload.source, async (directory) => {
+        await writeFile(join(directory, 'model.glb'), observed.packed, { flag: 'wx' });
+        await writeFile(join(directory, 'source-inspection.json'), JSON.stringify({ source: observed.source, packedHash: observed.packedHash, metadata: observed.metadata }) + '\n', { flag: 'wx' });
+    });
+    let current = join(initial, 'model.glb');
+    const lineage = [{ name: 'inspect', directory: initial }];
+    if (payload.recipe.repair) {
+        const bytes = new Uint8Array(await readFile(current)), recipe = { ...payload.recipe.repair, weldedPositionIdentity: 'exact-local-float32-lexicographic-v1' };
+        const repaired = await stage('repair', { parentHash: hash(bytes), recipe }, async (directory) => {
+            const result = applyRigidVertexRepairs(bytes, recipe);
+            await writeFile(join(directory, 'model.glb'), result.bytes, { flag: 'wx' });
+            await writeFile(join(directory, 'repair-manifest.json'), JSON.stringify(result.manifest) + '\n', { flag: 'wx' });
+        });
+        current = join(repaired, 'model.glb');
+        lineage.push({ name: 'repair', directory: repaired });
+    }
+    let splitManifest;
+    if (payload.recipe.split) {
+        const bytes = new Uint8Array(await readFile(current));
+        const split = await stage('split', { parentHash: hash(bytes), recipe: payload.recipe.split }, async (directory) => {
+            const result = prepareRigidSplit(bytes, payload.recipe.split, input.signal);
+            await writeFile(join(directory, 'model.glb'), result.bytes, { flag: 'wx' });
+            await writeFile(join(directory, 'split-manifest.json'), JSON.stringify(result.manifest) + '\n', { flag: 'wx' });
+            await writeFile(join(directory, 'exterior-trace.json'), JSON.stringify(result.trace) + '\n', { flag: 'wx' });
+        });
+        current = join(split, 'model.glb');
+        splitManifest = JSON.parse(await readFile(join(split, 'split-manifest.json'), 'utf8'));
+        lineage.push({ name: 'split', directory: split });
+    }
+    // Verify exact runtime fingerprints across texture-only optimization, including grouped meshes.
+    const beforeBytes = new Uint8Array(await readFile(current));
+    const beforeSource = { kind: 'resource', path: 'prepared/model.glb', contentHash: hash(beforeBytes), files: [{ path: 'prepared/model.glb', contentHash: hash(beforeBytes) }] };
+    const before = await inspectRigidModel({ bytes: beforeBytes, source: beforeSource,
+        adaptation: payload.recipe.adaptation, split: splitManifest, requiredCapability: payload.requiredCapability, signal: input.signal });
+    if (payload.recipe.optimize) {
+        const optimized = await stage('optimize', { parentHash: hash(beforeBytes), recipe: payload.recipe.optimize }, async (directory) => {
+            await optimizeModel({ input: current, output: join(directory, 'model.glb'), lineagePath: join(directory, 'optimization.json'),
+                ...payload.recipe.optimize, texturesOnly: true, maxOutputBytes: payload.maxModelBytes });
+        });
+        current = join(optimized, 'model.glb');
+        lineage.push({ name: 'optimize', directory: optimized });
+    }
+    const finalBytes = new Uint8Array(await readFile(current));
+    if (finalBytes.length > payload.maxModelBytes)
+        throw Error('model_prepare_model_budget_exceeded');
+    const derived = Boolean(payload.recipe.repair || payload.recipe.split || payload.recipe.optimize);
+    const source = derived ? { ...beforeSource, contentHash: hash(finalBytes), files: [{ path: beforeSource.path, contentHash: hash(finalBytes) }] } : payload.source;
+    const inspection = await inspectRigidModel({ bytes: finalBytes, source, adaptation: payload.recipe.adaptation, split: splitManifest,
+        requiredCapability: payload.requiredCapability, signal: input.signal });
+    if (inspection.triangles > payload.maxTriangles)
+        throw Error('model_prepare_triangle_budget_exceeded');
+    const geometry = (value) => value.inventory.nodes.map(({ sourceNodeId, geometryHash }) => ({ sourceNodeId, geometryHash }));
+    if (canonicalModelAdaptation(geometry(before)) !== canonicalModelAdaptation(geometry(inspection)))
+        throw Error('model_prepare_optimized_geometry_changed');
+    const adapted = await stage('adapt', { source, plan: inspection.plan }, async (directory) => {
+        const inputRoot = join(directory, 'input');
+        await mkdir(inputRoot);
+        if (derived) {
+            await mkdir(join(inputRoot, 'prepared'));
+            await writeFile(join(inputRoot, source.path), finalBytes, { flag: 'wx' });
+        }
+        else
+            for (const [path, bytes] of observed.originalFiles) {
+                await mkdir(dirname(join(inputRoot, path)), { recursive: true });
+                await writeFile(join(inputRoot, path), bytes, { flag: 'wx' });
+            }
+        await mkdir(join(inputRoot, '.playcraft'));
+        await writeFile(join(inputRoot, '.playcraft/model-adaptation.json'), JSON.stringify(inspection.plan, null, 2) + '\n', { flag: 'wx' });
+        const generated = await generateModelAdaptationProject({ projectRoot: inputRoot, planPath: '.playcraft/model-adaptation.json',
+            outputRoot: join(directory, 'project'), candidateId: payload.pipelineId, signal: input.signal });
+        const project = generated.outputRoot, proofPrefix = `.playcraft/model-production/${payload.pipelineId}`, proofRoot = join(project, proofPrefix);
+        await mkdir(proofRoot, { recursive: true });
+        const proof = { schemaVersion: 1, pipelineId: payload.pipelineId, stepId: payload.stepId, inputHash,
+            sourceScope: payload.sourceScope, parentSource: payload.source, recipe: payload.recipe, toolHash: input.toolHash,
+            outputSource: generated.manifest.derivedSource, actualInspection: inspection, modelAcceptance: false, browserValidation: 'pending' };
+        await writeFile(join(proofRoot, 'lineage.json'), JSON.stringify(proof, null, 2) + '\n', { flag: 'wx' });
+        await writeFile(join(proofRoot, 'recipe.json'), JSON.stringify(payload.recipe, null, 2) + '\n', { flag: 'wx' });
+        await writeFile(join(proofRoot, 'tool.json'), JSON.stringify({ toolHash: input.toolHash, manifest: input.toolManifest, actualInspector: inspection.tool }, null, 2) + '\n', { flag: 'wx' });
+        for (const [path, bytes] of observed.originalFiles) {
+            await mkdir(dirname(join(proofRoot, 'original', path)), { recursive: true });
+            await writeFile(join(proofRoot, 'original', path), bytes, { flag: 'wx' });
+        }
+        for (const item of lineage)
+            for (const file of await preparationInventory(item.directory)) {
+                await writeFile(join(proofRoot, `${item.name}-${file.path.replaceAll('/', '-')}`), (await readPreparationFile(item.directory, file.path)).bytes, { flag: 'wx' });
+            }
+        const buildPath = join(project, '.playcraft/model-build-inputs.json'), build = JSON.parse(await readFile(buildPath, 'utf8'));
+        for (const file of await preparationInventory(proofRoot))
+            build.models[0].adaptationFiles.push({ path: `${proofPrefix}/${file.path}`, contentHash: file.contentHash });
+        if (build.models[0].adaptationFiles.length > 64)
+            throw Error('model_prepare_lineage_limit');
+        await writeFile(buildPath, JSON.stringify(build, null, 2) + '\n');
+        const sourceManifestPath = join(project, 'model-adaptation-source-manifest.json');
+        const sourceManifest = JSON.parse(await readFile(sourceManifestPath, 'utf8'));
+        sourceManifest.files = (await preparationInventory(project)).filter(file => !['AGENTS.md', 'README.md', 'model-adaptation-source-manifest.json'].includes(file.path));
+        sourceManifest.preservedWorkspaceInstructions = true;
+        await writeFile(sourceManifestPath, JSON.stringify(sourceManifest, null, 2) + '\n');
+    });
+    const projectRoot = join(adapted, 'project'), config = await readPreparationFile(projectRoot, '.playcraft/model-adaptation.json');
+    const plan = workspaceModelAdaptationSchema.parse(JSON.parse(config.bytes.toString('utf8')));
+    const files = await preparationInventory(projectRoot);
+    return { status: 'prepared', projectRoot, model: plan.source, adaptationPath: '.playcraft/model-adaptation.json', adaptationHash: config.contentHash,
+        modelBytes: finalBytes.length, triangles: inspection.triangles, files,
+        lineageFiles: files.filter(file => file.path.startsWith(`.playcraft/model-production/${payload.pipelineId}/`)).map(({ path, contentHash }) => ({ path, contentHash })) };
+}

package/dist/model-preparation/pipeline-files.js

@@ -0,0 +1,108 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, realpath, rename, rm } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { workspaceRelativePathSchema, canonicalModelAdaptation } from '@playcraft/common/cloud-workspace/runtime';
+import { modelSourceDigest as hash } from '../model-adaptation/source.js';
+export const hashData = (value) => hash(canonicalModelAdaptation(value));
+export function preparationPath(value) {
+    workspaceRelativePathSchema.parse(value);
+    if (value.split('/').some(part => ['.git', '.ssh', 'node_modules'].includes(part) || part === '.env' || part.startsWith('.env.')))
+        throw Error('model_prepare_path_unsafe');
+    return value;
+}
+const same = (a, b) => a.ino === b.ino && a.dev === b.dev && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+/** Safe byte reads include inode/parent identity checks before and after reading, not only a digest. */
+export async function readPreparationFile(root, relative, maximum = 64 * 1024 * 1024) {
+    preparationPath(relative);
+    const base = resolve(root);
+    if (await realpath(base) !== base || !(await lstat(base)).isDirectory())
+        throw Error('model_prepare_root_unsafe');
+    const parents = [];
+    let path = base;
+    for (const part of relative.split('/').slice(0, -1)) {
+        path = join(path, part);
+        const stat = await lstat(path);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw Error('model_prepare_path_unsafe');
+        parents.push({ path, stat });
+    }
+    path = join(base, relative);
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > maximum)
+            throw Error('model_prepare_file_bound');
+        const bytes = await handle.readFile();
+        if (!same(stat, await handle.stat()) || !same(stat, await lstat(path)) || await realpath(path) !== path)
+            throw Error('model_prepare_source_changed');
+        for (const parent of parents) {
+            const now = await lstat(parent.path);
+            if (!now.isDirectory() || now.isSymbolicLink() || now.ino !== parent.stat.ino || now.dev !== parent.stat.dev)
+                throw Error('model_prepare_source_changed');
+        }
+        return { bytes, stat, contentHash: hash(bytes) };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function writePreparationJson(path, value, shared = false) {
+    await mkdir(dirname(path), { recursive: true, mode: shared ? 0o2770 : 0o700 });
+    const temporary = `${path}.${randomUUID()}.pending`;
+    try {
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, shared ? 0o660 : 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(value, null, 2) + '\n');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, path);
+        const directory = await open(dirname(path), constants.O_RDONLY);
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export async function preparationInventory(root) {
+    const files = [];
+    let total = 0;
+    async function walk(prefix = '') {
+        for (const entry of await readdir(join(root, prefix), { withFileTypes: true })) {
+            const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+            preparationPath(path);
+            if (entry.isSymbolicLink())
+                throw Error('model_prepare_path_unsafe');
+            if (entry.isDirectory())
+                await walk(path);
+            else {
+                const file = await readPreparationFile(root, path);
+                total += file.bytes.length;
+                if (files.length >= 256 || total > 256 * 1024 * 1024)
+                    throw Error('model_prepare_inventory_bound');
+                files.push({ path, contentHash: file.contentHash, bytes: file.bytes.length });
+            }
+        }
+    }
+    await walk();
+    return files.sort((a, b) => a.path.localeCompare(b.path, 'en'));
+}
+export async function readPreparationJson(root, path, maximum = 4 * 1024 * 1024) {
+    try {
+        return JSON.parse((await readPreparationFile(root, path, maximum)).bytes.toString('utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+export { hash };

package/dist/model-preparation/pipeline-worker.js

@@ -0,0 +1,32 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { modelPreparationPayloadSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { runPreparationEngine } from './pipeline-engine.js';
+import { hash, writePreparationJson } from './pipeline-files.js';
+/** Internal frozen CLI worker; accepts neither a project module nor executable recipe strings. */
+export async function modelPrepareWorker(configPath, expectedHash) {
+    const bytes = await readFile(configPath);
+    if (hash(bytes) !== expectedHash)
+        throw Error('model_prepare_worker_input_changed');
+    const config = JSON.parse(bytes.toString('utf8'));
+    const payload = modelPreparationPayloadSchema.parse(config.payload);
+    try {
+        const result = await runPreparationEngine({ payload, sourceRoot: config.sourceRoot, outputRoot: config.outputRoot, toolHash: config.toolHash, toolManifest: config.tools });
+        await writePreparationJson(join(config.outputRoot, 'result.json'), result, true);
+    }
+    catch (error) {
+        const safeCode = error && typeof error === 'object' && 'code' in error && typeof error.code === 'string'
+            && /^model_adaptation_[a-z_]+$/.test(error.code) ? error.code : undefined;
+        const message = safeCode ?? (error instanceof Error ? error.message : '');
+        let code = message.split(':')[0];
+        if (['invalid_model', 'invalid_model_resource', 'invalid_model_image', 'asset_too_large'].includes(code))
+            code = `model_prepare_${code}`;
+        if (!/^(model_prepare_|model_preparation_|model_adaptation_|model_source_|optimization_)[a-z_]+$/.test(code))
+            throw error;
+        await writePreparationJson(join(config.outputRoot, 'result.json'), { status: 'blocked', reasonCode: code }, true);
+    }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    modelPrepareWorker(process.argv[2] ?? '', process.argv[3] ?? '').catch(() => { process.stderr.write('model_prepare_worker_failed\n'); process.exitCode = 1; });
+}