@playcraft/cli 0.1.57-beta → 0.1.58-beta

package/dist/workspace-runtime/workspaces/parameter-initialization-skill-transaction.js

@@ -0,0 +1,141 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+const ownerSchema = z.object({ kind: z.literal('playcraft.parameter-skill.v1'), pid: z.number().int().positive(), token: z.string().uuid() }).strict();
+export const PARAMETER_SKILL_TRANSACTION = 'parameter-initialization-skill.transaction.json';
+const transactionSchema = z.object({ version: z.literal(1), owner: ownerSchema,
+    templateHash: z.string().regex(/^[a-f0-9]{64}$/), artifactHash: z.string().regex(/^[a-f0-9]{64}$/), sourceAdded: z.boolean(),
+    originalDeclaration: z.string().nullable(), originalLock: z.string().nullable(),
+    nextDeclaration: z.string(), nextLock: z.string(),
+}).strict();
+export async function readParameterSkillTransactionFile(path, maximum = 8 * 1024 * 1024) {
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > maximum)
+            throw new Error('workspace_skills_parameter_recovery_conflict');
+        return await readFile(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function parseOwner(bytes) {
+    try {
+        return ownerSchema.parse(JSON.parse(bytes.toString('utf8')));
+    }
+    catch {
+        throw Object.assign(new Error('workspace_skills_parameter_recovery_conflict'), { code: 'EEXIST' });
+    }
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+async function removeExact(path, expected) {
+    const current = await readParameterSkillTransactionFile(path);
+    if (current === undefined || !current.equals(expected))
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    await rm(path);
+}
+/** Each dead recovery owner has its own exclusive successor, avoiding an unchecked lease takeover. */
+async function recoveryClaim(management, previous, claims, depth = 0) {
+    if (depth > 32)
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    const path = join(management, `parameter-initialization-${previous.token}.recovery.lock`);
+    const owner = { kind: 'playcraft.parameter-skill.v1', pid: process.pid, token: randomUUID() };
+    const bytes = Buffer.from(JSON.stringify(owner));
+    // private: lease identities and crash recovery records belong to the controller.
+    try {
+        await writeFile(path, bytes, { flag: 'wx', mode: 0o600 });
+        claims.push({ path, bytes });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const existing = await readParameterSkillTransactionFile(path, 4096);
+        if (!existing)
+            throw error;
+        const held = parseOwner(existing);
+        if (alive(held.pid))
+            throw error;
+        claims.push({ path, bytes: existing });
+        await recoveryClaim(management, held, claims, depth + 1);
+    }
+}
+export async function acquireParameterSkillLease(management, recover) {
+    const path = join(management, 'skills-write.lock');
+    const owner = { kind: 'playcraft.parameter-skill.v1', pid: process.pid, token: randomUUID() };
+    const bytes = Buffer.from(JSON.stringify(owner));
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            // private
+            await writeFile(path, bytes, { flag: 'wx', mode: 0o600 });
+            return { owner, release: () => removeExact(path, bytes) };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const previousBytes = await readParameterSkillTransactionFile(path, 4096);
+            if (!previousBytes)
+                throw error;
+            const previous = parseOwner(previousBytes);
+            if (alive(previous.pid))
+                throw error;
+            const claims = [];
+            let claimed = false;
+            try {
+                await recoveryClaim(management, previous, claims);
+                claimed = true;
+                const current = await readParameterSkillTransactionFile(path, 4096);
+                if (!current?.equals(previousBytes) || alive(previous.pid))
+                    throw new Error('workspace_skills_parameter_recovery_conflict');
+                const marker = join(management, PARAMETER_SKILL_TRANSACTION);
+                const transactionBytes = await readParameterSkillTransactionFile(marker);
+                if (transactionBytes) {
+                    let transaction;
+                    try {
+                        transaction = transactionSchema.parse(JSON.parse(transactionBytes.toString('utf8')));
+                    }
+                    catch {
+                        throw new Error('workspace_skills_parameter_recovery_conflict');
+                    }
+                    if (transaction.owner.pid !== previous.pid || transaction.owner.token !== previous.token)
+                        throw new Error('workspace_skills_parameter_recovery_conflict');
+                    await recover(transaction);
+                    await removeExact(marker, transactionBytes);
+                }
+                await removeExact(path, previousBytes);
+            }
+            finally {
+                if (claimed)
+                    for (const claim of claims.reverse())
+                        await removeExact(claim.path, claim.bytes);
+            }
+        }
+    }
+    throw new Error('workspace_skills_parameter_recovery_conflict');
+}
+export async function writeParameterSkillTransaction(management, transaction) {
+    const path = join(management, PARAMETER_SKILL_TRANSACTION);
+    const bytes = Buffer.from(JSON.stringify(transactionSchema.parse(transaction)));
+    if (await readParameterSkillTransactionFile(path))
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    const temporary = `${path}.${transaction.owner.token}.tmp`;
+    try {
+        // private
+        await writeFile(temporary, bytes, { flag: 'wx', mode: 0o600 });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return () => removeExact(path, bytes);
+}

package/dist/workspace-runtime/workspaces/parameter-initialization-skill.js

@@ -0,0 +1,329 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, readFile, readdir, rename, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { canonicalProjectSkillsJson, createCanonicalBundleArchive, declarationDigest, dependencyDigest, PROJECT_SKILL_SOURCE_ROOTS, readProjectSkillSource, readProjectSkillsLockFile, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
+import { resolveCliPackageRoot } from '../../scaffold/compose.js';
+import { excludeFromGit } from './dependencies.js';
+import { ensureSharedDirectory, openSharedFile, shareIfNeeded } from './shared-write.js';
+import { acquireParameterSkillLease, readParameterSkillTransactionFile, writeParameterSkillTransaction } from './parameter-initialization-skill-transaction.js';
+export const PARAMETER_INITIALIZATION_SKILL = 'playcraft-runtime-parameters';
+const sourceRoot = `.agents/skills/${PARAMETER_INITIALIZATION_SKILL}`;
+const skillRef = `builtin/${PARAMETER_INITIALIZATION_SKILL}`;
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+async function safeDirectory(root, path) {
+    let current = root;
+    for (const segment of path.split('/')) {
+        current = join(current, segment);
+        const stat = await lstat(current).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
+            throw new Error('workspace_skills_invalid');
+    }
+    await ensureSharedDirectory(root, current);
+    return current;
+}
+async function writeExclusiveShared(root, path, data) {
+    const handle = await openSharedFile(root, path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW);
+    try {
+        await handle.writeFile(data);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function optionalFile(path) {
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+            throw new Error('workspace_skills_invalid');
+        return await readFile(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+async function installSource(root, files, token) {
+    const directory = join(root, sourceRoot);
+    const staging = await safeDirectory(root, `.playcraft/parameter-initialization-${token}`);
+    const temporary = join(staging, 'source');
+    await ensureSharedDirectory(root, temporary);
+    await safeDirectory(root, '.agents/skills');
+    try {
+        for (const file of files) {
+            if (dirname(file.path) !== '.')
+                await safeDirectory(temporary, dirname(file.path));
+            await writeExclusiveShared(root, join(temporary, file.path), file.content);
+        }
+        if (await lstat(directory).then(() => true, error => { if (error.code === 'ENOENT')
+            return false; throw error; }))
+            throw new Error('workspace_skills_parameter_conflict');
+        await rename(temporary, directory);
+    }
+    catch (error) {
+        await rm(staging, { recursive: true, force: true });
+        throw error;
+    }
+    await rm(staging, { recursive: true, force: true }).catch(() => undefined);
+}
+async function preserveArtifact(root, artifactHash, archive, token) {
+    const directory = await safeDirectory(root, '.playcraft/skill-artifacts');
+    const path = join(directory, `${artifactHash}.tar.gz`);
+    const existing = await readParameterSkillTransactionFile(path);
+    if (existing) {
+        if (!existing.equals(archive))
+            throw new Error('workspace_skills_digest_mismatch');
+        await shareIfNeeded(root, path);
+        return;
+    }
+    const temporary = `${path}.${token}.tmp`;
+    try {
+        await writeExclusiveShared(root, temporary, archive);
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+function snapshot(originalDeclaration, originalLock) {
+    if ((originalDeclaration === undefined) !== (originalLock === null))
+        throw new Error('workspace_skills_invalid');
+    if (originalDeclaration !== undefined)
+        return validateProjectSkillsSnapshot(originalDeclaration.toString('utf8'), originalLock);
+    const declaration = { schemaVersion: 1, entries: [] };
+    return { declaration, lock: { lockVersion: 3, declarationHash: declarationDigest(declaration), entries: [] } };
+}
+function selectedSnapshot(previous, templateHash, artifactHash) {
+    const next = structuredClone(previous);
+    const matches = next.declaration.entries.filter(entry => entry.entryKey === PARAMETER_INITIALIZATION_SKILL
+        || entry.source.skillRef === skillRef || entry.source.kind === 'repository' && entry.source.root === sourceRoot);
+    if (matches.length > 1)
+        throw new Error('workspace_skills_parameter_conflict');
+    const existing = matches[0];
+    let selected;
+    if (existing) {
+        const locked = next.lock.entries.find(entry => entry.entryKey === existing.entryKey);
+        if (existing.source.kind !== 'repository' || existing.source.root !== sourceRoot
+            || existing.source.skillRef !== skillRef || existing.surface !== 'sandbox-agent' || existing.projectFiles?.length
+            || locked.dependencies.length || locked.revision.kind !== 'source' || locked.sourceTreeHash !== templateHash
+            || locked.revision.artifactHash !== artifactHash)
+            throw new Error('workspace_skills_parameter_conflict');
+        selected = existing;
+        selected.enabled = true;
+    }
+    else {
+        selected = { entryKey: PARAMETER_INITIALIZATION_SKILL, source: { kind: 'repository', root: sourceRoot, skillRef },
+            enabled: true, surface: 'sandbox-agent' };
+        const locked = { entryKey: selected.entryKey, sourceTreeHash: templateHash,
+            revision: { kind: 'source', skillRef, sourceRevision: `src-v1-sha256:${templateHash}`, artifactHash },
+            dependencies: [], dependencyLockHash: dependencyDigest([], []) };
+        next.declaration.entries.push(selected);
+        next.lock.entries.push(locked);
+    }
+    next.lock.declarationHash = declarationDigest(next.declaration);
+    validateProjectSkillsSnapshot(next.declaration, next.lock);
+    return { next, selected, sourceAdded: !existing };
+}
+async function cleanStaging(root, transaction, files, archive) {
+    const directory = join(root, '.playcraft', `parameter-initialization-${transaction.owner.token}`);
+    const expected = new Map(files.map(file => [`source/${file.path}`, Buffer.from(file.content)]));
+    const visit = async (path, relative = '') => {
+        const stat = await lstat(path);
+        if (stat.isSymbolicLink())
+            throw new Error('workspace_skills_parameter_recovery_conflict');
+        if (stat.isDirectory()) {
+            if (relative && ![...expected.keys()].some(file => file.startsWith(`${relative}/`)))
+                throw new Error('workspace_skills_parameter_recovery_conflict');
+            for (const name of await readdir(path))
+                await visit(join(path, name), relative ? `${relative}/${name}` : name);
+        }
+        else {
+            const bytes = await readParameterSkillTransactionFile(path);
+            const wanted = expected.get(relative);
+            if (!bytes || !wanted || !wanted.subarray(0, bytes.length).equals(bytes))
+                throw new Error('workspace_skills_parameter_recovery_conflict');
+        }
+    };
+    if (await lstat(directory).then(() => true, error => { if (error.code === 'ENOENT')
+        return false; throw error; })) {
+        await visit(directory);
+        await rm(directory, { recursive: true });
+    }
+    const temporaryFiles = [
+        ['skills.json', Buffer.from(transaction.nextDeclaration)], ['skills.lock.json', Buffer.from(transaction.nextLock)],
+        [`skill-artifacts/${transaction.artifactHash}.tar.gz`, archive],
+    ];
+    for (const [name, expectedBytes] of temporaryFiles) {
+        const path = join(root, '.playcraft', `${name}.${transaction.owner.token}.tmp`);
+        const bytes = await readParameterSkillTransactionFile(path);
+        if (bytes) {
+            if (!expectedBytes.subarray(0, bytes.length).equals(bytes))
+                throw new Error('workspace_skills_parameter_recovery_conflict');
+            await rm(path);
+        }
+    }
+}
+async function recoverTransaction(root, transaction, template, artifactHash, archive) {
+    if (transaction.templateHash !== template.sourceTreeHash || transaction.artifactHash !== artifactHash)
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    const originalDeclaration = transaction.originalDeclaration === null ? undefined : Buffer.from(transaction.originalDeclaration, 'base64');
+    if (originalDeclaration && originalDeclaration.toString('base64') !== transaction.originalDeclaration)
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    const previous = snapshot(originalDeclaration, transaction.originalLock);
+    const { next, selected, sourceAdded } = selectedSnapshot(previous, template.sourceTreeHash, artifactHash);
+    if (sourceAdded !== transaction.sourceAdded || `${canonicalProjectSkillsJson(next.declaration)}\n` !== transaction.nextDeclaration
+        || `${canonicalProjectSkillsJson(next.lock)}\n` !== transaction.nextLock)
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    const declarationPath = join(root, '.playcraft/skills.json'), lockPath = join(root, '.playcraft/skills.lock.json');
+    const declaration = await optionalFile(declarationPath), lock = await readProjectSkillsLockFile(root);
+    const oldDeclaration = declaration === undefined ? originalDeclaration === undefined : !!originalDeclaration?.equals(declaration);
+    const newDeclaration = declaration?.equals(Buffer.from(transaction.nextDeclaration));
+    const oldLock = lock === transaction.originalLock, newLock = lock === transaction.nextLock;
+    if (!(oldDeclaration && oldLock || newDeclaration && (oldLock || newLock)))
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    const sourceExists = await lstat(join(root, sourceRoot)).then(() => true, error => { if (error.code === 'ENOENT')
+        return false; throw error; });
+    if (!sourceExists) {
+        if (!sourceAdded || !oldDeclaration || !oldLock)
+            throw new Error('workspace_skills_parameter_recovery_conflict');
+    }
+    else {
+        if ((await readProjectSkillSource(root, selected)).sourceTreeHash !== template.sourceTreeHash)
+            throw new Error('workspace_skills_source_changed');
+        // The exact source and pair identify the interrupted import; finish only its recorded transition.
+        for (const [path, content] of [[declarationPath, transaction.nextDeclaration], [lockPath, transaction.nextLock]]) {
+            if ((await optionalFile(path))?.equals(Buffer.from(content)))
+                continue;
+            const temporary = `${path}.${randomUUID()}.tmp`;
+            try {
+                await writeExclusiveShared(root, temporary, content);
+                await rename(temporary, path);
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+        }
+    }
+    await cleanStaging(root, transaction, template.files, archive);
+}
+/** A deliberate initialization selects one versioned project skill without synchronizing other sources. */
+export async function ensureParameterInitializationSkill(root) {
+    const rootStat = await lstat(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error('workspace_skills_invalid');
+    const templateEntry = { entryKey: PARAMETER_INITIALIZATION_SKILL,
+        source: { kind: 'repository', root: `project-template/.claude/skills/${PARAMETER_INITIALIZATION_SKILL}`, skillRef },
+        enabled: true, surface: 'sandbox-agent' };
+    const template = await readProjectSkillSource(resolveCliPackageRoot(), templateEntry);
+    const archive = createCanonicalBundleArchive(template.files.map(file => ({ path: file.path, data: Buffer.from(file.content) })));
+    const artifactHash = digest(archive);
+    await excludeFromGit(root, '/.playcraft/skills/');
+    await excludeFromGit(root, '/.playcraft/skill-artifacts/');
+    await excludeFromGit(root, '/.playcraft/skills-write.lock');
+    await excludeFromGit(root, '/.playcraft/parameter-initialization-*');
+    const management = await safeDirectory(root, '.playcraft');
+    const lease = await acquireParameterSkillLease(management, transaction => recoverTransaction(root, transaction, template, artifactHash, archive));
+    const staged = [];
+    let ownedSource = false, committed = false, cleanupAllowed = true;
+    let removeTransaction;
+    try {
+        const declarationPath = join(management, 'skills.json'), lockPath = join(management, 'skills.lock.json');
+        const originalDeclaration = await optionalFile(declarationPath);
+        const originalLock = await readProjectSkillsLockFile(root);
+        const previous = snapshot(originalDeclaration, originalLock);
+        const { next, selected, sourceAdded } = selectedSnapshot(previous, template.sourceTreeHash, artifactHash);
+        if (!sourceAdded) {
+            if ((await readProjectSkillSource(root, selected)).sourceTreeHash !== template.sourceTreeHash)
+                throw new Error('workspace_skills_source_changed');
+            await safeDirectory(root, sourceRoot);
+            for (const file of template.files) {
+                if (dirname(file.path) !== '.')
+                    await safeDirectory(root, `${sourceRoot}/${dirname(file.path)}`);
+                await shareIfNeeded(root, join(root, sourceRoot, file.path));
+            }
+        }
+        else {
+            for (const source of PROJECT_SKILL_SOURCE_ROOTS) {
+                const path = join(root, source, PARAMETER_INITIALIZATION_SKILL);
+                const exists = await lstat(path).then(() => true, error => {
+                    if (error.code === 'ENOENT')
+                        return false;
+                    throw error;
+                });
+                if (exists)
+                    throw new Error('workspace_skills_parameter_conflict');
+            }
+        }
+        if (canonicalProjectSkillsJson(previous) !== canonicalProjectSkillsJson(next)) {
+            removeTransaction = await writeParameterSkillTransaction(management, { version: 1, owner: lease.owner,
+                templateHash: template.sourceTreeHash, artifactHash, sourceAdded,
+                originalDeclaration: originalDeclaration?.toString('base64') ?? null, originalLock,
+                nextDeclaration: `${canonicalProjectSkillsJson(next.declaration)}\n`, nextLock: `${canonicalProjectSkillsJson(next.lock)}\n` });
+            if (sourceAdded) {
+                await installSource(root, template.files, lease.owner.token);
+                ownedSource = true;
+            }
+            await preserveArtifact(root, artifactHash, archive, lease.owner.token);
+            const pending = [];
+            for (const [path, value] of [[declarationPath, next.declaration], [lockPath, next.lock]]) {
+                const temporary = `${path}.${lease.owner.token}.tmp`;
+                staged.push(temporary);
+                await writeExclusiveShared(root, temporary, `${canonicalProjectSkillsJson(value)}\n`);
+                pending.push(temporary);
+            }
+            const currentDeclaration = await optionalFile(declarationPath);
+            if (currentDeclaration === undefined ? originalDeclaration !== undefined
+                : originalDeclaration === undefined || !currentDeclaration.equals(originalDeclaration))
+                throw new Error('skills_revision_conflict');
+            if (await readProjectSkillsLockFile(root) !== originalLock)
+                throw new Error('skills_revision_conflict');
+            await rename(pending[0], declarationPath);
+            try {
+                await rename(pending[1], lockPath);
+            }
+            catch (error) {
+                try {
+                    if (originalDeclaration === undefined)
+                        await rm(declarationPath, { force: true });
+                    else {
+                        const restore = `${declarationPath}.${randomUUID()}.tmp`;
+                        staged.push(restore);
+                        await writeExclusiveShared(root, restore, originalDeclaration);
+                        await rename(restore, declarationPath);
+                    }
+                }
+                catch (restoreError) {
+                    cleanupAllowed = false;
+                    throw restoreError;
+                }
+                throw error;
+            }
+        }
+        else
+            await preserveArtifact(root, artifactHash, archive, lease.owner.token);
+        committed = true;
+        await shareIfNeeded(root, declarationPath);
+        await shareIfNeeded(root, lockPath);
+        return { entryKey: selected.entryKey, lockHash: digest(canonicalProjectSkillsJson(next.lock)) };
+    }
+    finally {
+        if (cleanupAllowed && ownedSource && !committed) {
+            const entry = { entryKey: PARAMETER_INITIALIZATION_SKILL,
+                source: { kind: 'repository', root: sourceRoot }, enabled: true, surface: 'sandbox-agent' };
+            if ((await readProjectSkillSource(root, entry)).sourceTreeHash !== template.sourceTreeHash)
+                throw new Error('workspace_skills_source_changed');
+            await rm(join(root, sourceRoot), { recursive: true });
+        }
+        if (cleanupAllowed) {
+            for (const path of staged)
+                await rm(path, { force: true });
+            await removeTransaction?.();
+            await lease.release();
+        }
+    }
+}

package/dist/workspace-runtime/workspaces/parameter-initialization.js

@@ -0,0 +1,63 @@
+import JSON5 from 'json5';
+import { workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { PREVIEW_RUNTIME_DIRECTORY, readPreviewRuntimeDistribution } from '../../preview-runtime/distribution.js';
+import { ParameterAgentError, parameterDigest, readParameterAgentFile } from './parameter-agent-inputs.js';
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+const path = (value) => workspaceRelativePathSchema.safeParse(value).success;
+async function input(root, file) {
+    try {
+        return await readParameterAgentFile(root, file);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new ParameterAgentError('parameter_agent_preview_inputs_not_ready');
+        throw error;
+    }
+}
+/** Check admission inputs without building a preview, deleting outputs or declaring fields live. */
+export async function inspectParameterInitialization(root, document, report) {
+    const manifestBytes = await input(root, '.playcraft/workspace.json');
+    let manifest;
+    try {
+        manifest = record(JSON5.parse(manifestBytes.toString('utf8')));
+    }
+    catch {
+        throw new ParameterAgentError('parameter_agent_preview_manifest_not_ready');
+    }
+    const parameters = record(manifest?.parameters);
+    const preview = record(manifest?.previewRuntime);
+    const allowed = new Set(['version', 'buildScript', 'outputPath', 'reportPath', 'configContractVersion', 'entryPath', 'viteConfigPath', 'mountId', 'gameFilePaths']);
+    if (!parameters || parameters.schemaPath !== document.schemaPath || parameters.dataPath !== document.dataPath ||
+        !document.platformI18nPath || !preview || Object.keys(preview).some(key => !allowed.has(key)) || preview.version !== 1 ||
+        typeof preview.buildScript !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9:_-]{0,63}$/.test(preview.buildScript) ||
+        !path(preview.outputPath) || !preview.outputPath.startsWith('.playcraft-editor-preview/') || !preview.outputPath.endsWith('.html') ||
+        !path(preview.reportPath) || !preview.reportPath.startsWith('.playcraft-editor-preview/') || !preview.reportPath.endsWith('.json') ||
+        typeof preview.configContractVersion !== 'string' || !preview.configContractVersion.length || preview.configContractVersion.length > 128 ||
+        !path(preview.entryPath) || (preview.viteConfigPath !== undefined && !path(preview.viteConfigPath)) ||
+        (preview.mountId !== undefined && (typeof preview.mountId !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(preview.mountId))) ||
+        !Array.isArray(preview.gameFilePaths) || preview.gameFilePaths.length > 256 || !preview.gameFilePaths.every(path))
+        throw new ParameterAgentError('parameter_agent_preview_manifest_not_ready');
+    const files = new Set(preview.gameFilePaths);
+    if (!files.has(preview.entryPath) || report.candidates.some(candidate => candidate.status === 'implemented' && !candidate.consumers.some(consumer => files.has(consumer.path))))
+        throw new ParameterAgentError('parameter_agent_preview_inputs_not_ready');
+    const packageData = JSON.parse((await input(root, 'package.json')).toString('utf8'));
+    if (typeof packageData.scripts?.[preview.buildScript] !== 'string' || !packageData.scripts[preview.buildScript].trim())
+        throw new ParameterAgentError('parameter_agent_preview_script_not_ready');
+    const hashes = [['.playcraft/workspace.json', parameterDigest(manifestBytes)]];
+    for (const file of [...files, preview.entryPath, ...(preview.viteConfigPath ? [preview.viteConfigPath] : [])])
+        hashes.push([file, parameterDigest(await input(root, file))]);
+    const trusted = await readPreviewRuntimeDistribution();
+    const copiedManifest = await input(root, `${PREVIEW_RUNTIME_DIRECTORY}/manifest.json`);
+    if (!copiedManifest.equals(trusted.manifestBytes))
+        throw new ParameterAgentError('parameter_agent_preview_sdk_not_ready');
+    hashes.push([`${PREVIEW_RUNTIME_DIRECTORY}/manifest.json`, parameterDigest(copiedManifest)]);
+    for (const [name, expected] of Object.entries(trusted.manifest.files)) {
+        const file = `${PREVIEW_RUNTIME_DIRECTORY}/${name}`;
+        const bytes = await input(root, file);
+        const actual = parameterDigest(bytes);
+        if (actual !== expected)
+            throw new ParameterAgentError('parameter_agent_preview_sdk_not_ready');
+        hashes.push([file, actual]);
+    }
+    return parameterDigest(JSON.stringify(hashes));
+}

package/dist/workspace-runtime/workspaces/parameter-production.js

@@ -0,0 +1,124 @@
+import { lstat, readdir, realpath, unlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import JSON5 from 'json5';
+import { z } from 'zod';
+import { workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { ParameterAgentError, parameterDigest, readParameterAgentFile } from './parameter-agent-inputs.js';
+const reportPath = '.playcraft-editor-preview/release-report.json';
+const marker = /runtime\.parameters\.|playcraft-preview-storage:|__playcraft_preview_context__/i;
+const slash = (value) => value.replaceAll('\\', '/').replaceAll('\0', '').split('?')[0];
+const relativePath = z.string().refine(value => workspaceRelativePathSchema.safeParse(value).success);
+const reportSchema = z.object({
+    version: z.literal(1), target: z.literal('playable-release'), previewRuntimeExcluded: z.literal(true),
+    moduleIds: z.array(z.string().min(1).max(4096)).min(1).max(10000),
+    artifacts: z.array(z.object({ path: relativePath, sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict()).min(1).max(4096),
+}).strict();
+async function safePath(root, path, missing = false) {
+    let current = root;
+    const segments = path.split('/');
+    for (let index = 0; index < segments.length; index++) {
+        current = resolve(current, segments[index]);
+        const stat = await lstat(current).catch(error => {
+            if (missing && error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (!stat)
+            continue;
+        if (stat.isSymbolicLink() || (index < segments.length - 1 && !stat.isDirectory()))
+            throw new ParameterAgentError('parameter_agent_production_path_not_ready');
+    }
+    return current;
+}
+/** Remove only the old fixed guard report; never follow its parents into source or delivery files. */
+export async function prepareParameterProductionCheck(root) {
+    try {
+        const base = await realpath(root);
+        const manifest = JSON5.parse((await readParameterAgentFile(base, '.playcraft/workspace.json')).toString('utf8'));
+        const entry = manifest.previewRuntime?.entryPath;
+        if (!workspaceRelativePathSchema.safeParse(entry).success)
+            throw new ParameterAgentError('parameter_agent_production_entry_not_ready');
+        const file = await safePath(base, reportPath, true);
+        const stat = await lstat(file).catch(error => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (stat && (!stat.isFile() || stat.nlink !== 1))
+            throw new ParameterAgentError('parameter_agent_production_path_not_ready');
+        if (stat)
+            await unlink(file);
+        return { root: base, startedAt: Date.now(), previewEntry: slash(resolve(base, entry)), requestedPreviewEntry: slash(resolve(root, entry)) };
+    }
+    catch (error) {
+        if (error instanceof ParameterAgentError)
+            throw error;
+        throw new ParameterAgentError('parameter_agent_production_report_not_ready');
+    }
+}
+/** Inspect the reported module boundary and every actual delivery file, not a claimed success flag. */
+export async function inspectParameterProductionCheck(plan, assertActive = () => { }) {
+    try {
+        assertActive();
+        const file = await safePath(plan.root, reportPath);
+        const stat = await lstat(file);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.mtimeMs + 1 < plan.startedAt)
+            throw new ParameterAgentError('parameter_agent_production_report_not_ready');
+        const bytes = await readParameterAgentFile(plan.root, reportPath);
+        const parsed = reportSchema.safeParse(JSON.parse(bytes.toString('utf8')));
+        if (!parsed.success)
+            throw new ParameterAgentError('parameter_agent_production_report_not_ready');
+        const report = parsed.data;
+        const sdkRoot = slash(resolve(plan.root, '.playcraft/preview-runtime')) + '/';
+        for (const moduleId of report.moduleIds) {
+            const id = slash(moduleId);
+            if (id === plan.previewEntry || id === plan.requestedPreviewEntry || id.startsWith(sdkRoot) ||
+                /(?:^|\/)(?:@playcraft\/)?preview-runtime(?:\/|@|$)/.test(id) || /@playcraft\+preview-runtime@/.test(id))
+                throw new ParameterAgentError('parameter_agent_production_modules_not_ready');
+        }
+        const declared = new Map(report.artifacts.map(artifact => [artifact.path, artifact.sha256]));
+        if (declared.size !== report.artifacts.length || new Set(report.moduleIds).size !== report.moduleIds.length)
+            throw new ParameterAgentError('parameter_agent_production_report_not_ready');
+        const output = await safePath(plan.root, 'dist');
+        if (!(await lstat(output)).isDirectory())
+            throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+        let count = 0;
+        let total = 0;
+        let directories = 0;
+        const walk = async (directory, prefix = '', depth = 0) => {
+            assertActive();
+            if (depth > 24 || ++directories > 4096)
+                throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+            const entries = await readdir(directory, { withFileTypes: true });
+            if (entries.length > 4096)
+                throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+            for (const entry of entries) {
+                assertActive();
+                const relative = prefix + entry.name;
+                if (!workspaceRelativePathSchema.safeParse(relative).success || entry.isSymbolicLink())
+                    throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+                if (entry.isDirectory())
+                    await walk(resolve(directory, entry.name), relative + '/', depth + 1);
+                else if (entry.isFile()) {
+                    if (++count > 4096)
+                        throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+                    const content = await readParameterAgentFile(plan.root, `dist/${relative}`, 50 * 1024 * 1024);
+                    total += content.byteLength;
+                    if (total > 128 * 1024 * 1024 || declared.get(relative) !== parameterDigest(content) || marker.test(content.toString()))
+                        throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+                }
+                else
+                    throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+            }
+        };
+        await walk(output);
+        if (count !== declared.size || parameterDigest(await readParameterAgentFile(plan.root, reportPath)) !== parameterDigest(bytes))
+            throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+        return { reportHash: parameterDigest(bytes), artifactCount: count, moduleCount: report.moduleIds.length };
+    }
+    catch (error) {
+        if (error instanceof ParameterAgentError || (error instanceof Error && error.name === 'AbortError'))
+            throw error;
+        throw new ParameterAgentError('parameter_agent_production_report_not_ready');
+    }
+}