@playcraft/cli 0.1.67 → 0.1.68

package/dist/workspace-runtime/workspaces/audio-assets/program-variant-build.js

@@ -0,0 +1,217 @@
+import { constants } from 'node:fs';
+import { lstat, open, opendir, realpath } from 'node:fs/promises';
+import { posix, relative, resolve, sep } from 'node:path';
+import { init, parse } from 'es-module-lexer';
+import { audioError, audioProjectPath, digest } from './storage.js';
+import { writeSharedFile } from '../shared-write.js';
+import { auditAudioProgramArtifact } from './program-artifact-audit.js';
+import { assertAudioProgramBuildClone, readAudioProgramBuildInputs, verifyAudioProgramBuildInputs } from './program-build-inputs.js';
+const SKIP = new Set(['dist', 'node_modules', '.git', '.playcraft', '.playcraft-delivery', '.turbo', 'coverage']);
+const SOURCE = /\.(?:[cm]?[jt]s|[jt]sx)$/i;
+const MAX_SOURCE_BYTES = 16 * 1024 * 1024, MAX_SOURCE_FILE_BYTES = 2 * 1024 * 1024, MAX_FILES = 2048, MAX_ENTRIES = 8192;
+async function sourceFiles(root) {
+    const files = [], unresolved = [];
+    let count = 0;
+    const visit = async (directory, depth) => {
+        if (depth > 32)
+            throw audioError('audio_build_budget_exceeded', 422);
+        const handle = await opendir(directory ? await audioProjectPath(root, directory) : await realpath(root), { bufferSize: 32 });
+        for await (const entry of handle) {
+            if (++count > MAX_ENTRIES)
+                throw audioError('audio_build_budget_exceeded', 422);
+            if (SKIP.has(entry.name))
+                continue;
+            const path = directory ? `${directory}/${entry.name}` : entry.name;
+            if (entry.isSymbolicLink()) {
+                unresolved.push({ file: path, offset: 0, reason: 'symlink_source_skipped' });
+                continue;
+            }
+            if (entry.isDirectory())
+                await visit(path, depth + 1);
+            else if (entry.isFile() && SOURCE.test(entry.name)) {
+                if (files.length >= MAX_FILES)
+                    throw audioError('audio_build_budget_exceeded', 422);
+                files.push(path);
+            }
+        }
+    };
+    await visit('', 0);
+    return { files: files.sort(), unresolved };
+}
+async function stableBytes(root, path, maximum) {
+    const handle = await open(await audioProjectPath(root, path), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size > maximum)
+            throw audioError('audio_build_budget_exceeded', 422);
+        const bytes = await handle.readFile(), after = await handle.stat();
+        if (bytes.length !== before.size || before.ino !== after.ino || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+            throw audioError('audio_build_input_changed');
+        return bytes;
+    }
+    finally {
+        await handle.close();
+    }
+}
+function importedPath(file, specifier) {
+    if (specifier.includes('\\') || specifier.includes('\0'))
+        return undefined;
+    if (specifier.startsWith('/'))
+        return posix.normalize(specifier.slice(1));
+    if (!specifier.startsWith('.'))
+        return undefined;
+    const path = posix.normalize(posix.join(posix.dirname(file), specifier));
+    return path === '..' || path.startsWith('../') ? undefined : path;
+}
+/** Only lexer-confirmed literals in ordinary clone source are changed; immutable packages are never rewritten. */
+export async function rewriteAudioProgramVariantImports(input) {
+    if (!['runtime', 'prerender'].includes(input.variant))
+        throw audioError('invalid_audio_variant', 400);
+    await assertAudioProgramBuildClone(input.sourceRoot, input.cloneRoot);
+    await verifyAudioProgramBuildInputs(input.sourceRoot, input.snapshot);
+    await verifyAudioProgramBuildInputs(input.cloneRoot, input.snapshot);
+    const routes = new Map();
+    for (const bundle of input.snapshot.packages)
+        for (const path of [bundle.runtimeModulePath, bundle.prerenderModulePath])
+            routes.set(path, input.variant === 'runtime' ? bundle.runtimeModulePath : bundle.prerenderModulePath);
+    const sources = await sourceFiles(input.cloneRoot), result = {
+        variant: input.variant, rewrites: [], unresolved: sources.unresolved, coverage: 'literal-project-relative-imports',
+    };
+    const changes = [];
+    let total = 0;
+    await init;
+    for (const file of sources.files) {
+        const bytes = await stableBytes(input.cloneRoot, file, MAX_SOURCE_FILE_BYTES);
+        if ((total += bytes.length) > MAX_SOURCE_BYTES)
+            throw audioError('audio_build_budget_exceeded', 422);
+        let text;
+        try {
+            text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        }
+        catch {
+            throw audioError('audio_program_source_invalid', 400);
+        }
+        let imports;
+        try {
+            [imports] = parse(text, file);
+        }
+        catch {
+            result.unresolved.push({ file, offset: 0, reason: 'module_lexer_parse_failed' });
+            continue;
+        }
+        const replacements = [];
+        for (const item of imports) {
+            if (item.d === -2)
+                continue;
+            if (item.n === undefined) {
+                if (item.d >= 0)
+                    result.unresolved.push({ file, offset: item.s, reason: text.slice(item.s, item.e).includes('audio/programs/') ? 'computed_program_import' : 'computed_import_unverified' });
+                continue;
+            }
+            const boundary = item.n.search(/[?#]/), plain = boundary < 0 ? item.n : item.n.slice(0, boundary);
+            const resolved = importedPath(file, plain), selected = resolved && routes.get(resolved);
+            if (!selected) {
+                if (plain.includes('audio/programs/'))
+                    result.unresolved.push({ file, offset: item.s, reason: 'program_import_path_unresolved' });
+                continue;
+            }
+            if (boundary >= 0) {
+                result.unresolved.push({ file, offset: item.s, reason: 'program_import_query_unsupported' });
+                continue;
+            }
+            let replacement = item.n.startsWith('/') ? `/${selected}` : posix.relative(posix.dirname(file), selected);
+            if (!item.n.startsWith('/') && !replacement.startsWith('.'))
+                replacement = './' + replacement;
+            if (selected === resolved && item.n === replacement)
+                continue;
+            const start = item.d === -1 ? item.s - 1 : item.s, end = item.d === -1 ? item.e + 1 : item.e;
+            if (!['"', "'"].includes(text[start]) || text[end - 1] !== text[start]) {
+                result.unresolved.push({ file, offset: item.s, reason: 'non_string_program_import' });
+                continue;
+            }
+            replacements.push({ start, end, value: JSON.stringify(replacement), from: item.n, to: replacement });
+        }
+        if (!replacements.length)
+            continue;
+        let rewritten = text;
+        for (const item of [...replacements].sort((a, b) => b.start - a.start))
+            rewritten = rewritten.slice(0, item.start) + item.value + rewritten.slice(item.end);
+        changes.push({ file, bytes: Buffer.from(rewritten), beforeHash: digest(bytes), rows: replacements.map(({ from, to }) => ({ from, to })) });
+    }
+    // Validate the full plan before touching any clone source, then compare each inode's actual bytes.
+    for (const change of changes)
+        if (digest(await stableBytes(input.cloneRoot, change.file, MAX_SOURCE_FILE_BYTES)) !== change.beforeHash)
+            throw audioError('audio_build_input_changed');
+    for (const change of changes) {
+        await writeSharedFile(input.cloneRoot, await audioProjectPath(input.cloneRoot, change.file), change.bytes);
+        for (const row of change.rows)
+            result.rewrites.push({ file: change.file, ...row, beforeHash: change.beforeHash, afterHash: digest(change.bytes) });
+    }
+    await verifyAudioProgramBuildInputs(input.sourceRoot, input.snapshot);
+    await verifyAudioProgramBuildInputs(input.cloneRoot, input.snapshot);
+    return result;
+}
+/** The callback must return the actual final channel artifact, including its real container format. */
+export async function measureAudioProgramVariants(input) {
+    const { capabilities } = input;
+    if (typeof capabilities.webAudio !== 'boolean' || typeof capabilities.runtimeSynthesis !== 'boolean'
+        || !Number.isSafeInteger(capabilities.maxBytes) || capabilities.maxBytes < 1 || capabilities.maxBytes > 64 * 1024 * 1024)
+        throw audioError('invalid_audio_channel_capability', 400);
+    if (!capabilities.webAudio)
+        throw audioError('audio_delivery_unavailable', 422);
+    const checkAbort = () => { if (input.signal?.aborted)
+        throw audioError('audio_build_cancelled', 409); };
+    checkAbort();
+    const snapshot = input.snapshot ?? await readAudioProgramBuildInputs(input.root);
+    await verifyAudioProgramBuildInputs(input.root, snapshot);
+    const modes = capabilities.runtimeSynthesis ? ['runtime', 'prerender'] : ['prerender'];
+    const candidates = [], candidateRoots = new Set();
+    for (const variant of modes) {
+        checkAbort();
+        await verifyAudioProgramBuildInputs(input.root, snapshot);
+        try {
+            const prepared = await input.prepare(variant);
+            await assertAudioProgramBuildClone(input.root, prepared.projectRoot);
+            await assertAudioProgramBuildClone(input.root, prepared.artifactRoot);
+            const roots = await Promise.all([realpath(prepared.projectRoot), realpath(prepared.artifactRoot)]);
+            if ([...candidateRoots].some(old => roots.some(root => root === old || root.startsWith(old + sep) || old.startsWith(root + sep))))
+                throw audioError('invalid_audio_build_clone', 400);
+            for (const root of roots)
+                candidateRoots.add(root);
+            const copied = await readAudioProgramBuildInputs(input.root, prepared.projectRoot);
+            if (copied.inputHash !== snapshot.inputHash)
+                throw audioError('audio_build_input_changed');
+            const rewrite = await rewriteAudioProgramVariantImports({ sourceRoot: input.root, cloneRoot: prepared.projectRoot, snapshot, variant });
+            if (variant === 'prerender' && rewrite.unresolved.length > 0)
+                throw Object.assign(audioError('audio_program_import_unverified', 422), { details: rewrite.unresolved });
+            checkAbort();
+            const outputPath = await input.build({ ...prepared, variant, rewrite, signal: input.signal });
+            checkAbort();
+            await verifyAudioProgramBuildInputs(prepared.projectRoot, snapshot);
+            const artifactRoot = await realpath(prepared.artifactRoot), absolute = await realpath(outputPath), rel = relative(artifactRoot, absolute);
+            if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || resolve(artifactRoot, rel) !== absolute)
+                throw audioError('invalid_audio_build_artifact', 400);
+            const stat = await lstat(outputPath);
+            if (!stat.isFile() || stat.isSymbolicLink())
+                throw audioError('invalid_audio_build_artifact', 400);
+            const bytes = await stableBytes(artifactRoot, rel.split(sep).join('/'), 64 * 1024 * 1024);
+            if (!bytes.length)
+                throw audioError('invalid_audio_build_artifact', 400);
+            const artifactAudit = auditAudioProgramArtifact(bytes, outputPath, variant);
+            candidates.push({ variant, status: 'completed', ...prepared, outputPath, outputSize: bytes.length, outputHash: digest(bytes), rewrite, artifactAudit });
+        }
+        catch (error) {
+            if (input.signal?.aborted)
+                throw audioError('audio_build_cancelled', 409);
+            candidates.push({ variant, status: 'failed', error: error.code ?? error.message,
+                ...(error.details === undefined ? {} : { details: error.details }) });
+        }
+        await verifyAudioProgramBuildInputs(input.root, snapshot);
+    }
+    const valid = candidates.filter((candidate) => candidate.status === 'completed' && candidate.outputSize <= capabilities.maxBytes);
+    valid.sort((a, b) => a.outputSize - b.outputSize || Number(a.variant === 'runtime') - Number(b.variant === 'runtime'));
+    if (!valid.length)
+        throw Object.assign(audioError('audio_delivery_unavailable', 422), { details: { channel: capabilities.channel, candidates } });
+    return { version: 1, inputHash: snapshot.inputHash, channel: capabilities.channel, capabilities,
+        candidates, selected: valid[0], measuredFinalArtifacts: true };
+}

package/dist/workspace-runtime/workspaces/audio-assets/references.js

@@ -0,0 +1,107 @@
+import { constants } from 'node:fs';
+import { lstat, open, opendir } from 'node:fs/promises';
+import { workspaceAudioBindingSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { audioProjectPath, audioError, digest } from './storage.js';
+import { readAudioArtifactPackage } from './artifact-package.js';
+export async function readAudioReferenceFile(root, path) {
+    const target = await audioProjectPath(root, path), file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+        .catch(error => { if (error.code === 'ENOENT')
+        return undefined; throw error; });
+    if (!file)
+        return undefined;
+    try {
+        const before = await file.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size < 1 || before.size > 16_384)
+            throw audioError('invalid_audio_binding', 400);
+        const bytes = await file.readFile(), after = await file.stat(), named = await lstat(await audioProjectPath(root, path));
+        if (bytes.length !== before.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || named.ino !== before.ino || named.dev !== before.dev)
+            throw audioError('audio_binding_conflict');
+        return bytes;
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function verifyAudioReference(root, sourcePath, history, bytes) {
+    const binding = workspaceAudioBindingSchema.parse(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)));
+    if (binding.sourcePath !== sourcePath || !history.some(version => version.revision === binding.revision && version.contentHash === binding.sourceContentHash))
+        throw audioError('invalid_audio_binding', 400);
+    const directory = `dist/audio/${digest(sourcePath)}/${binding.sourceContentHash}/${binding.representationSetHash}`;
+    if (binding.modulePath !== `${directory}/sound.mjs`)
+        throw audioError('invalid_audio_binding', 400);
+    const bundle = await readAudioArtifactPackage(root, `${directory}/sound.${sourcePath.endsWith('.pcscore.json') ? 'pcscore' : 'pcaudio'}.json`);
+    if (bundle.sourcePath !== sourcePath || bundle.sourceContentHash !== binding.sourceContentHash
+        || digest(bundle.files.get(`${directory}/audition.wav`)) !== binding.auditionContentHash)
+        throw audioError('invalid_audio_binding', 400);
+    return binding;
+}
+export async function readAudioReferences(root, sourcePath, current, history, loadPrevious) {
+    const directory = await audioProjectPath(root, 'source/audio-bindings');
+    const handle = await opendir(directory).catch(error => { if (error.code === 'ENOENT')
+        return undefined; throw error; });
+    const names = [];
+    let entries = 0, truncated = false;
+    if (handle)
+        for await (const entry of handle) {
+            if (++entries > 1024) {
+                truncated = true;
+                break;
+            }
+            if (entry.isFile() && /^[a-zA-Z][a-zA-Z0-9_.-]{0,63}\.json$/.test(entry.name))
+                names.push(entry.name);
+            if (names.length > 128) {
+                truncated = true;
+                break;
+            }
+        }
+    names.sort();
+    const deadline = Date.now() + 5_000;
+    const references = [];
+    const version = (binding) => ({ revision: binding.revision, sourceContentHash: binding.sourceContentHash,
+        modulePath: binding.modulePath, representationSetHash: binding.representationSetHash });
+    for (const name of names.slice(0, 128)) {
+        if (Date.now() > deadline) {
+            truncated = true;
+            break;
+        }
+        const bindingPath = `source/audio-bindings/${name}`, bytes = await readAudioReferenceFile(root, bindingPath);
+        if (!bytes)
+            continue;
+        let raw;
+        try {
+            raw = JSON.parse(bytes.toString('utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (raw?.sourcePath !== sourcePath || raw?.eventName !== name.slice(0, -5))
+            continue;
+        const entry = { eventName: raw.eventName, bindingPath, bindingContentHash: digest(bytes), state: 'invalid', history: [] };
+        try {
+            const binding = await verifyAudioReference(root, sourcePath, history, bytes);
+            entry.version = version(binding);
+            entry.state = binding.sourceContentHash === current.contentHash ? 'current' : 'different_version';
+            let previous = binding.previousBinding;
+            const seen = new Set([entry.bindingContentHash]);
+            while (previous && entry.history.length < 20 && !seen.has(previous)) {
+                if (Date.now() > deadline) {
+                    truncated = true;
+                    break;
+                }
+                seen.add(previous);
+                const old = await loadPrevious(previous);
+                if (!old || digest(old) !== previous)
+                    break;
+                const checked = await verifyAudioReference(root, sourcePath, history, old);
+                if (checked.eventName !== binding.eventName)
+                    break;
+                entry.history.push({ ...version(checked), bindingContentHash: previous });
+                previous = checked.previousBinding;
+            }
+        }
+        catch { /* An invalid record remains visible, without an unverified package or restore target. */ }
+        references.push(entry);
+    }
+    return { version: 1, target: { kind: 'workspace-file', path: sourcePath }, sourceRevision: current.revision, sourceContentHash: current.contentHash,
+        references, scanLimit: 128, truncated, dynamicReferences: 'unverified' };
+}

package/dist/workspace-runtime/workspaces/audio-assets/service.js

@@ -1,9 +1,14 @@
 import { readFile } from 'node:fs/promises';
-import { parseSoundDocument, serializeSoundDocument, soundSourceRenderHash, soundDurationSeconds, isSoundDocumentPath, audioRenderKey, canonicalAudioJson, assertAudioProtection, assertScoreProtection, } from '@playcraft/common/cloud-workspace/runtime';
+import { parseSoundDocument, serializeSoundDocument, soundSourceRenderHash, soundDurationSeconds, isSoundDocumentPath, audioRenderKey, canonicalAudioJson, assertAudioProtection, assertScoreProtection, audioReferenceActionSchema, audioReferenceActionReceiptSchema, workspaceAudioBindingSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { writeSharedFile } from '../shared-write.js';
 import { AudioStore, audioError, audioProjectPath, readAudioSource, digest } from './storage.js';
 import { publishAudioRepresentations } from './representations.js';
 import { audioArtifactResources } from './artifact-package.js';
+import { readAudioArtifactPackage } from './artifact-package.js';
+import { createAudioLibrarySnapshot } from './library-package.js';
+import { readImportedAudioLibrarySource } from './library-import.js';
+import { readAudioReferences, readAudioReferenceFile, verifyAudioReference } from './references.js';
+import { writeWorkspaceBinaryFile } from '../binary-write.js';
 import { readAudioBindingUsage } from './binding-usage.js';
 const safeId = (id) => typeof id === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(id);
 const targetId = (target) => target.kind === 'workspace-file' ? `file:${target.path}` : `candidate:${target.taskId}:${target.candidateId}`;
@@ -13,6 +18,7 @@ const publicState = async (record, projectRoot) => {
     const usage = record.target.kind === 'workspace-file' && record.usage
         ? await readAudioBindingUsage(projectRoot, record.target.path, current.contentHash, record.history, record.usage) : undefined;
     return { version: 1, target: record.target, ...current, history: record.history, ...(usage ? { usage } : {}),
+        ...(record.libraryOrigin ? { libraryOrigin: record.libraryOrigin } : {}),
         ...(record.representation ? { representation: record.representation } : {}),
         ...(record.adoptionReceipt ? { adoptionReceipt: record.adoptionReceipt } : {}) };
 };
@@ -68,6 +74,20 @@ export class WorkspaceAudioAssets {
                 this.checkFormatPath(target.path, version.document);
                 record = { ...record, target, current: version, representation: undefined, adoptionReceipt: undefined,
                     history: [...(record?.history ?? []), summary(version)] };
+                try {
+                    const imported = await readImportedAudioLibrarySource(this.projectRoot, target.path, version.contentHash);
+                    if (imported) {
+                        record.libraryOrigin = imported.origin;
+                        if (imported.current) {
+                            await this.store.bytes('auditions', imported.current.audition.contentHash, imported.current.wav);
+                            record.current = { ...version, renderState: 'ready', audition: imported.current.audition };
+                            record.representation = imported.current.representation;
+                        }
+                    }
+                }
+                catch (error) {
+                    record.current = { ...version, renderState: 'failed', renderError: error instanceof Error && /^audio_library_/.test(error.message) ? error.message : 'audio_library_dependency_invalid' };
+                }
                 await this.saveRecord(record);
             }
         }
@@ -78,6 +98,118 @@ export class WorkspaceAudioAssets {
         return record;
     }
     read(target) { return this.exclusive(async () => publicState(await this.observe(target), this.projectRoot)); }
+    references(target) {
+        return this.exclusive(async () => {
+            if (target.kind !== 'workspace-file')
+                throw audioError('invalid_audio_target', 400);
+            const record = await this.observe(target);
+            return readAudioReferences(this.projectRoot, target.path, record.current, record.history, hash => this.previousBinding(hash));
+        });
+    }
+    async previousBinding(hash) {
+        try {
+            return await readFile(this.store.blobPath('bindings', hash));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    }
+    referenceAction(raw) {
+        return this.exclusive(async () => {
+            const input = audioReferenceActionSchema.parse(raw), payloadHash = digest(canonicalAudioJson(input));
+            let intent = await this.store.read('reference-requests', input.requestId);
+            if (intent && intent.payloadHash !== payloadHash)
+                throw audioError('audio_request_conflict');
+            if (intent?.status === 'complete')
+                return audioReferenceActionReceiptSchema.parse(intent.result);
+            const record = await this.observe(input.target), bindingPath = `source/audio-bindings/${input.eventName}.json`;
+            const current = await readAudioReferenceFile(this.projectRoot, bindingPath), currentHash = current ? digest(current) : null;
+            const alreadyWritten = intent?.status === 'pending' && currentHash === digest(Buffer.from(intent.entry, 'base64'));
+            if (!alreadyWritten) {
+                this.expected(record, { action: 'bind', requestId: input.requestId, target: input.target,
+                    expectedRevision: input.expectedRevision, expectedContentHash: input.expectedContentHash });
+                if (currentHash !== input.expectedBindingContentHash)
+                    throw audioError('audio_binding_conflict');
+            }
+            if (!intent) {
+                let bytes;
+                if (input.action === 'replace') {
+                    if (record.current.renderState !== 'ready' || !record.current.audition || !record.representation
+                        || record.representation.sourceContentHash !== record.current.contentHash)
+                        throw audioError('audio_audition_unavailable', 409);
+                    const entry = workspaceAudioBindingSchema.parse({ version: 1, operationId: input.requestId, eventName: input.eventName,
+                        sourcePath: input.target.path, sourceContentHash: record.current.contentHash, revision: record.current.revision,
+                        auditionContentHash: record.current.audition.contentHash, modulePath: record.representation.modulePath,
+                        representationSetHash: record.representation.representationSetHash, integrationStatus: 'integration_required', previousBinding: currentHash });
+                    bytes = Buffer.from(`${canonicalAudioJson(entry)}\n`);
+                    await verifyAudioReference(this.projectRoot, input.target.path, record.history, bytes);
+                }
+                else {
+                    const snapshot = await readAudioReferences(this.projectRoot, input.target.path, record.current, record.history, hash => this.previousBinding(hash));
+                    const tracked = snapshot.references.find(reference => reference.eventName === input.eventName);
+                    if (!tracked?.history.some(version => version.bindingContentHash === input.previousBindingHash))
+                        throw audioError('invalid_audio_binding', 400);
+                    const previous = await this.previousBinding(input.previousBindingHash);
+                    if (!previous || digest(previous) !== input.previousBindingHash)
+                        throw audioError('invalid_audio_binding', 400);
+                    await verifyAudioReference(this.projectRoot, input.target.path, record.history, previous);
+                    bytes = Buffer.from(previous);
+                }
+                if (current)
+                    await this.store.bytes('bindings', currentHash, current);
+                intent = { payloadHash, status: 'pending', beforeHash: currentHash, entry: bytes.toString('base64') };
+                await this.store.write('reference-requests', input.requestId, intent);
+            }
+            const bytes = Buffer.from(intent.entry, 'base64'), binding = await verifyAudioReference(this.projectRoot, input.target.path, record.history, bytes);
+            if (binding.eventName !== input.eventName)
+                throw audioError('invalid_audio_binding', 400);
+            if (!alreadyWritten) {
+                try {
+                    await writeWorkspaceBinaryFile(this.projectRoot, { path: bindingPath, contentBase64: intent.entry, expectedContentHash: intent.beforeHash });
+                }
+                catch (error) {
+                    if (error.code === 'content_conflict')
+                        throw audioError('audio_binding_conflict');
+                    throw error;
+                }
+            }
+            record.usage = { status: 'integration_required', bindingPath, eventName: input.eventName, sourceContentHash: binding.sourceContentHash,
+                ...(binding.previousBinding ? { previousContentHash: binding.previousBinding } : {}) };
+            await this.saveRecord(record);
+            await this.options.onWrite?.(input.target.path, record.current, [bindingPath], input.requestId);
+            const result = audioReferenceActionReceiptSchema.parse({ version: 1, requestId: input.requestId, action: input.action, target: input.target,
+                eventName: input.eventName, bindingPath, bindingContentHash: digest(bytes), sourceContentHash: binding.sourceContentHash,
+                revision: binding.revision, modulePath: binding.modulePath, representationSetHash: binding.representationSetHash, integrationStatus: 'integration_required' });
+            await this.store.write('reference-requests', input.requestId, { ...intent, status: 'complete', result });
+            return result;
+        });
+    }
+    librarySnapshot(target, revision, contentHash) {
+        return this.exclusive(async () => {
+            const record = await this.observe(target), version = record.current;
+            if (version.revision !== revision || version.contentHash !== contentHash)
+                throw audioError('audio_revision_conflict');
+            if (version.renderState !== 'ready' || !version.audition)
+                throw audioError('audio_audition_unavailable', 404);
+            const sourcePath = target.kind === 'workspace-file' ? target.path
+                : `source/audio/${target.candidateId}.${version.document.format === 'playcraft.score' ? 'pcscore' : 'pcaudio'}.json`;
+            if (record.representation?.sourceContentHash === contentHash) {
+                const entry = `${record.representation.modulePath.slice(0, -'sound.mjs'.length)}sound.${version.document.format === 'playcraft.score' ? 'pcscore' : 'pcaudio'}.json`;
+                const packaged = await readAudioArtifactPackage(this.projectRoot, entry);
+                const files = [...packaged.files].map(([path, bytes]) => ({ path: path.slice(path.lastIndexOf('/') + 1),
+                    mimeType: path.endsWith('.wav') ? 'audio/wav' : path.endsWith('.mjs') ? 'text/javascript' : 'application/json',
+                    size: bytes.length, contentHash: digest(bytes), content: bytes.toString('base64') }));
+                return { version: 1, target, revision, sourcePath, files };
+            }
+            const wav = await readFile(this.store.blobPath('auditions', version.audition.contentHash));
+            if (digest(wav) !== version.audition.contentHash || wav.length !== version.audition.size)
+                throw audioError('audio_audition_unavailable', 404);
+            return createAudioLibrarySnapshot({ target, revision, sourcePath, document: version.document, sourceText: version.sourceText,
+                contentHash, sourceRenderHash: version.sourceRenderHash, audition: version.audition, wav });
+        });
+    }
     async content(target, revision, representation = 'audition') {
         const record = await this.observe(target), version = revision === undefined || revision === record.current.revision ? record.current :
             await this.store.read('versions', `${targetId(target)}:${revision}`);

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

@@ -357,7 +357,14 @@ export async function saveWorkspaceGit(root, input) {
     // user (or an agent) finishes the merge with an explicit commit; saves resume after it.
     if ((await mergeState(rootReal)).merging)
         return { pushed: false, withheld: [] };
+    const { readAudioBuildInputs, verifyAudioBuildInputs } = await import('./audio-assets/build-inputs.js');
+    const audio = await readAudioBuildInputs(rootReal);
     await git(rootReal, ['add', '-A'], 60000);
+    // dist is normally ignored. Save only verified immutable audio closures, never unrelated outputs.
+    const audioPaths = [...new Set([...audio.packages, ...(audio.programs?.packages ?? [])].flatMap(bundle => bundle.files.map(file => file.path)))];
+    for (let index = 0; index < audioPaths.length; index += 64)
+        await git(rootReal, ['--literal-pathspecs', 'add', '-f', '--', ...audioPaths.slice(index, index + 64)], 60000);
+    await verifyAudioBuildInputs(rootReal, audio);
     const staged = (await git(rootReal, ['diff', '--cached', '--name-only', '-z'], 60000)).split('\0').filter(Boolean);
     const withheld = staged.filter(isCredentialFile);
     await unstage(rootReal, withheld);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.67",
+  "version": "0.1.68",
   "private": false,
   "type": "module",
   "engines": {
@@ -44,6 +44,8 @@
     "verify:parameter-skill": "node scripts/generate-parameter-skill.mjs --check && node --test scripts/generate-parameter-skill.test.mjs",
     "verify:level-editor-skill": "node scripts/generate-level-editor-skill.mjs --check",
     "verify:asset-skills": "node scripts/generate-asset-skills.mjs --check && node --test scripts/generate-asset-skills.test.mjs",
+    "generate:audio-program-companion": "node scripts/generate-audio-program-companion.mjs",
+    "verify:audio-program-companion": "node scripts/generate-audio-program-companion.mjs --check",
     "verify:agent-stop": "node scripts/verify-agent-stop.mjs",
     "verify-sprite-overlay": "node scripts/verify-sprite-overlay.mjs",
     "link": "node scripts/bump-local.js && pnpm build && npm link",
@@ -54,8 +56,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.67",
-    "@playcraft/common": "0.1.67",
+    "@playcraft/build": "0.1.68",
+    "@playcraft/common": "0.1.68",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
@@ -64,6 +66,7 @@
     "dotenv": "^17.2.3",
     "drizzle-orm": "^0.45.1",
     "earcut": "3.2.4",
+    "es-module-lexer": "1.7.0",
     "execa": "^9.6.1",
     "express": "^5.2.1",
     "fluent-ffmpeg": "^2.1.3",

package/project-template/.claude/skills/playcraft-audio-generation/SKILL.md

@@ -3,7 +3,7 @@ name: playcraft-audio-generation
 description: Use when generating or replacing playable audio, reusing library audio, managing durable audio tasks, or locally compressing, trimming, looping, normalizing, and mixing sound.
 triggers: 生成音效,生成bgm,生成背景音乐,generate sfx,generate bgm,generate audio,音频,音效,背景音乐,sfx,bgm,loop音频,音频压缩,音频处理,audio,compress audio,fade,normalize,音频后处理,音频管线
 compatibility: agent,opencode
-version: 1.3.0
+version: 1.4.0
 surfaces:
   - sandbox-agent
 ---
@@ -16,7 +16,7 @@ AI (Artificial Intelligence, 人工智能) 音频包含 SFX (Sound Effects, 音
 
 ### 云工作区的可编辑短音效
 
-仅在当前锁定技能版本与工作区能力支持时使用本段流程。先运行 `playcraft audio source capabilities`，检查 `enabled`、`writable`、对应 `operations`；生成与渲染还须 `renderer.ready`。能力缺失或关闭时保留源及已有试听，报告不可用，不替换工程技能锁，不移除声音上下文后继续执行。`synth-sfx` 保持短音效流程；仅在 `audioScoreVersion:1` 与 `audioScoreContextVersion:1` 均声明时使用下述乐谱／多轨流程。外部采样和动态混合仍不支持。
+仅在当前锁定技能版本与工作区能力支持时使用本段流程。先运行 `playcraft audio source capabilities`，检查 `enabled`、`writable`、对应 `operations`；生成与渲染还须 `renderer.ready`。能力缺失或关闭时保留源及已有试听，报告不可用，不替换工程技能锁，不移除声音上下文后继续执行。`synth-sfx` 保持短音效流程；仅在 `audioScoreVersion:1` 与 `audioScoreContextVersion:1` 均声明时使用下述乐谱／多轨流程。动态混合使用独立高级程序入口，不写入既有音效或乐谱源。
 
 默认从描述、试听、采用开始，只展示适用的时长、音量、音高、明亮度简单控件；用户要求细节后再展开精确参数。工程源在 `source/audio/` 等 `dist/` 外目录，最终表示包位于 `dist/audio/`。未采用候选保持私有，不因续改而强制写入工程。
 
@@ -84,6 +84,24 @@ playcraft audio source adopt --task <taskId> --candidate <candidateId> \
 
 音乐完整包成员为 `sound.pcscore.json / audition.wav / runtime.mjs / sound.mjs / manifest.json`，只使用回执中的固定模块。`createSound().prepare()` 不默认展开整段音乐采样；`play()` 按乐谱和循环段调度，返回的 `stop()` 或播放器 `stop()/dispose()` 会结束循环并释放资源。场景退出、页面隐藏或切换试听时应调用停止，禁止遗留循环。单次播放可传 `play({loop:false})`；指定段落或轨道试听通过受支持的 `selection` 参数。试听渲染文件本身是完整单次表示，循环起止需随乐谱一起使用。
 
+### 高级：游戏状态与短采样混合
+
+用户明确要求按游戏状态改变声音，或组合短采样与合成音时，先检查 `playcraft audio program --help` 是否存在。旧工作区不支持该命令时保留现有源和技能锁并报告。不要为普通生成和简单调整主动创建音频程序。
+
+```bash
+# --asset 必须是采用回执中的完整不可变声音包成员；可选 --sample 是 dist/audio 中有摘要目录的短采样。
+playcraft audio program init --asset <sound.pcscore.json或sound.pcaudio.json固定路径> --output source/audio/states.pcaudioprogram.json
+playcraft audio program validate --path source/audio/states.pcaudioprogram.json
+playcraft audio program compile --path source/audio/states.pcaudioprogram.json
+playcraft audio program inspect --manifest <编译回执manifestPath>
+```
+
+程序是独立的 `playcraft.audio-program@1`，最多 8 项资产、16 个离散状态、每状态 4 层及 60 秒。状态明确指定增益、半音、低通与乐谱拍段；切换采用停止并重启语义，不承诺无缝交叉淡化。短采样只接受单声道 44100 Hz、PCM（Pulse Code Modulation，脉冲编码调制）16 位标准波形文件，每个最多 2 秒、最多 4 个；不接受外部地址或任意脚本。依赖必须带精确路径、内容摘要和大小。编译会校验完整声音包及平台引擎，渲染所有状态并拒绝超峰值；不静默截断或归一化。全部状态波形总量限 16 MiB，输入依赖限 2 MiB。
+
+从编译回执的 `runtimeModulePath` 导入 `createSound`，在明确交互中 `await player.play('idle')`；状态变化时 `await player.setState('action')`。切换场景或页面隐藏时停止，销毁时 `dispose()`。`prerenderModulePath` 使用同一接口，已把音高、滤波和混合烘焙到各状态波形，播放不重复处理；两种方案仍要求浏览器支持音频上下文。模块与共享引擎均不可变，修改程序后重新编译，保留旧模块用于回退。只修改 `dist/audio` 包内文件会触发校验失败。
+
+渠道选型必须按完整实际构建产物字节数比较，包括运行时、嵌入依赖和波形；源 JSON（JavaScript Object Notation，JavaScript 对象表示法）大小不能代表最终压缩收益。未知渠道能力采用保守回退，渠道不支持音频上下文时不能宣称预渲染模块可用。完整渠道包通过平台交付页生成与下载，不保存到工作区 `dist/`。
+
 ### 复用素材与持久化音频任务
 
 ```bash

package/project-template-v2/.claude/skills/playcraft-audio-generation/SKILL.md

@@ -3,7 +3,7 @@ name: playcraft-audio-generation
 description: Use when generating or replacing playable audio, reusing library audio, managing durable audio tasks, or locally compressing, trimming, looping, normalizing, and mixing sound.
 triggers: 生成音效,生成bgm,生成背景音乐,generate sfx,generate bgm,generate audio,音频,音效,背景音乐,sfx,bgm,loop音频,音频压缩,音频处理,audio,compress audio,fade,normalize,音频后处理,音频管线
 compatibility: agent,opencode
-version: 1.3.0
+version: 1.4.0
 surfaces:
   - sandbox-agent
 ---
@@ -16,7 +16,7 @@ AI (Artificial Intelligence, 人工智能) 音频包含 SFX (Sound Effects, 音
 
 ### 云工作区的可编辑短音效
 
-仅在当前锁定技能版本与工作区能力支持时使用本段流程。先运行 `playcraft audio source capabilities`，检查 `enabled`、`writable`、对应 `operations`；生成与渲染还须 `renderer.ready`。能力缺失或关闭时保留源及已有试听，报告不可用，不替换工程技能锁，不移除声音上下文后继续执行。`synth-sfx` 保持短音效流程；仅在 `audioScoreVersion:1` 与 `audioScoreContextVersion:1` 均声明时使用下述乐谱／多轨流程。外部采样和动态混合仍不支持。
+仅在当前锁定技能版本与工作区能力支持时使用本段流程。先运行 `playcraft audio source capabilities`，检查 `enabled`、`writable`、对应 `operations`；生成与渲染还须 `renderer.ready`。能力缺失或关闭时保留源及已有试听，报告不可用，不替换工程技能锁，不移除声音上下文后继续执行。`synth-sfx` 保持短音效流程；仅在 `audioScoreVersion:1` 与 `audioScoreContextVersion:1` 均声明时使用下述乐谱／多轨流程。动态混合使用独立高级程序入口，不写入既有音效或乐谱源。
 
 默认从描述、试听、采用开始，只展示适用的时长、音量、音高、明亮度简单控件；用户要求细节后再展开精确参数。工程源在 `source/audio/` 等 `dist/` 外目录，最终表示包位于 `dist/audio/`。未采用候选保持私有，不因续改而强制写入工程。
 
@@ -84,6 +84,24 @@ playcraft audio source adopt --task <taskId> --candidate <candidateId> \
 
 音乐完整包成员为 `sound.pcscore.json / audition.wav / runtime.mjs / sound.mjs / manifest.json`，只使用回执中的固定模块。`createSound().prepare()` 不默认展开整段音乐采样；`play()` 按乐谱和循环段调度，返回的 `stop()` 或播放器 `stop()/dispose()` 会结束循环并释放资源。场景退出、页面隐藏或切换试听时应调用停止，禁止遗留循环。单次播放可传 `play({loop:false})`；指定段落或轨道试听通过受支持的 `selection` 参数。试听渲染文件本身是完整单次表示，循环起止需随乐谱一起使用。
 
+### 高级：游戏状态与短采样混合
+
+用户明确要求按游戏状态改变声音，或组合短采样与合成音时，先检查 `playcraft audio program --help` 是否存在。旧工作区不支持该命令时保留现有源和技能锁并报告。不要为普通生成和简单调整主动创建音频程序。
+
+```bash
+# --asset 必须是采用回执中的完整不可变声音包成员；可选 --sample 是 dist/audio 中有摘要目录的短采样。
+playcraft audio program init --asset <sound.pcscore.json或sound.pcaudio.json固定路径> --output source/audio/states.pcaudioprogram.json
+playcraft audio program validate --path source/audio/states.pcaudioprogram.json
+playcraft audio program compile --path source/audio/states.pcaudioprogram.json
+playcraft audio program inspect --manifest <编译回执manifestPath>
+```
+
+程序是独立的 `playcraft.audio-program@1`，最多 8 项资产、16 个离散状态、每状态 4 层及 60 秒。状态明确指定增益、半音、低通与乐谱拍段；切换采用停止并重启语义，不承诺无缝交叉淡化。短采样只接受单声道 44100 Hz、PCM（Pulse Code Modulation，脉冲编码调制）16 位标准波形文件，每个最多 2 秒、最多 4 个；不接受外部地址或任意脚本。依赖必须带精确路径、内容摘要和大小。编译会校验完整声音包及平台引擎，渲染所有状态并拒绝超峰值；不静默截断或归一化。全部状态波形总量限 16 MiB，输入依赖限 2 MiB。
+
+从编译回执的 `runtimeModulePath` 导入 `createSound`，在明确交互中 `await player.play('idle')`；状态变化时 `await player.setState('action')`。切换场景或页面隐藏时停止，销毁时 `dispose()`。`prerenderModulePath` 使用同一接口，已把音高、滤波和混合烘焙到各状态波形，播放不重复处理；两种方案仍要求浏览器支持音频上下文。模块与共享引擎均不可变，修改程序后重新编译，保留旧模块用于回退。只修改 `dist/audio` 包内文件会触发校验失败。
+
+渠道选型必须按完整实际构建产物字节数比较，包括运行时、嵌入依赖和波形；源 JSON（JavaScript Object Notation，JavaScript 对象表示法）大小不能代表最终压缩收益。未知渠道能力采用保守回退，渠道不支持音频上下文时不能宣称预渲染模块可用。完整渠道包通过平台交付页生成与下载，不保存到工作区 `dist/`。
+
 ### 复用素材与持久化音频任务
 
 ```bash