@playcraft/cli 0.1.67 → 0.1.68

package/dist/commands/audio-program.js

@@ -0,0 +1,82 @@
+import { constants } from 'node:fs';
+import { dirname, posix, resolve } from 'node:path';
+import { parseAudioDynamicProgram, serializeAudioDynamicProgram, validateAudioDynamicProgram } from '@playcraft/common/cloud-workspace/runtime';
+import { readAudioArtifactPackage } from '../workspace-runtime/workspaces/audio-assets/artifact-package.js';
+import { audioProjectPath, digest } from '../workspace-runtime/workspaces/audio-assets/storage.js';
+import { compileAudioProgram, readAudioProgramFile, readAudioProgramPackage } from '../workspace-runtime/workspaces/audio-assets/program-package.js';
+import { ensureSharedDirectory, openSharedFile } from '../workspace-runtime/workspaces/shared-write.js';
+const messages = {
+    en: { topic: 'Advanced game state audio programs', init: 'Create a bounded program from a saved sound bundle',
+        compile: 'Validate all dependencies and render state variants with the sandboxed browser', inspect: 'Inspect a verified immutable program bundle',
+        validate: 'Validate program syntax without rendering', root: 'Project root', asset: 'Saved immutable sound source in dist/audio',
+        sample: 'Optional short mono PCM (Pulse Code Modulation, 脉冲编码调制) 16-bit WAV (Waveform Audio File Format, 波形音频文件格式) sample', output: 'New .pcaudioprogram.json source path', path: 'Program source path', manifest: 'Compiled program manifest path', failed: 'Audio program failed', defaultName: 'Game sound' },
+    zh: { topic: '高级游戏状态音频程序', init: '从已保存的完整声音包创建有界状态程序', compile: '校验依赖并用保留沙箱的浏览器渲染状态',
+        inspect: '检查已验证的不可变音频程序包', validate: '校验程序格式，不执行渲染', root: '工程根目录', asset: 'dist/audio 中已保存的不可变声音源',
+        sample: '可选短单声道十六位脉冲编码调制采样文件', output: '新 .pcaudioprogram.json 源路径', path: '音频程序源路径', manifest: '已编译的音频程序清单路径', failed: '音频程序操作失败', defaultName: '游戏声音' },
+};
+const t = (key) => messages[(process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en').startsWith('zh') ? 'zh' : 'en'][key];
+const result = (action) => async (options) => {
+    try {
+        console.log(JSON.stringify(await action(options), null, 2));
+    }
+    catch (error) {
+        console.error(`${t('failed')}: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+};
+const reference = async (root, path, max) => {
+    const data = await readAudioProgramFile(root, path, max);
+    return { path, contentHash: digest(data), size: data.length };
+};
+/** Advanced entry is opt-in; the default sound editor retains its simpler controls. */
+export function registerAudioProgramCommands(audio) {
+    const program = audio.command('program').description(t('topic'));
+    const scoped = (command) => command.option('--root <directory>', t('root'), '.');
+    scoped(program.command('init').description(t('init'))).requiredOption('--asset <path>', t('asset')).option('--sample <path>', t('sample'))
+        .requiredOption('--output <path>', t('output')).action(result(async (options) => {
+        const root = resolve(options.root), path = options.output;
+        if (!path.endsWith('.pcaudioprogram.json') || path.startsWith('dist/'))
+            throw new Error('invalid_audio_path');
+        await readAudioArtifactPackage(root, options.asset);
+        const assets = [{ id: 'sound', kind: 'synth', source: await reference(root, options.asset, 65536),
+                manifest: await reference(root, `${posix.dirname(options.asset)}/manifest.json`, 65536) }];
+        if (options.sample)
+            assets.push({ id: 'sample', kind: 'sample', file: await reference(root, options.sample, 176444) });
+        const base = { assetId: 'sound', gain: .5, pitchSemitones: 0, lowpassHz: null, loop: true, rangeBeats: null };
+        const document = validateAudioDynamicProgram({ format: 'playcraft.audio-program', formatVersion: 1, name: t('defaultName'),
+            transition: 'restart', masterGain: .6, initialState: 'idle', assets,
+            states: [{ id: 'idle', durationSeconds: 4, layers: [base] }, { id: 'action', durationSeconds: 4, layers: [{ ...base, lowpassHz: 3000 },
+                        ...(options.sample ? [{ assetId: 'sample', gain: .2, pitchSemitones: 0, lowpassHz: null, loop: false, rangeBeats: null }] : [])] }] });
+        const destination = await audioProjectPath(root, path, true);
+        await ensureSharedDirectory(root, dirname(destination));
+        const handle = await openSharedFile(root, destination, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW);
+        try {
+            await handle.writeFile(serializeAudioDynamicProgram(document));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        return { path, contentHash: digest(serializeAudioDynamicProgram(document)), stateIds: document.states.map(state => state.id) };
+    }));
+    scoped(program.command('validate').description(t('validate'))).requiredOption('--path <path>', t('path')).action(result(async (options) => {
+        const document = parseAudioDynamicProgram(await readAudioProgramFile(resolve(options.root), options.path, 65536));
+        return { valid: true, stateIds: document.states.map(state => state.id), assetIds: document.assets.map(asset => asset.id) };
+    }));
+    scoped(program.command('compile').description(t('compile'))).requiredOption('--path <path>', t('path')).action(result(async (options) => {
+        const abort = new AbortController(), cancel = () => abort.abort();
+        process.once('SIGINT', cancel);
+        try {
+            const value = await compileAudioProgram(resolve(options.root), options.path, abort.signal);
+            return { manifestPath: value.manifestPath, semanticHash: value.semanticHash, runtimeModulePath: value.runtimeModulePath,
+                prerenderModulePath: value.prerenderModulePath, states: value.manifest.states };
+        }
+        finally {
+            process.off('SIGINT', cancel);
+        }
+    }));
+    scoped(program.command('inspect').description(t('inspect'))).requiredOption('--manifest <path>', t('manifest')).action(result(async (options) => {
+        const value = await readAudioProgramPackage(resolve(options.root), options.manifest);
+        return { manifest: value.manifest, runtimeModulePath: value.runtimeModulePath, prerenderModulePath: value.prerenderModulePath };
+    }));
+}

package/dist/commands/audio.js

@@ -1,5 +1,6 @@
 import { getAudioInfo, compressAudio, trimAudio, convertAudio, fadeAudio, concatAudio, normalizeAudio, loopAudio, mixAudio, } from '../utils/audio-processor.js';
 import { registerAudioSourceCommands } from './audio-source.js';
+import { registerAudioProgramCommands } from './audio-program.js';
 import { audioSourceMessage } from '../audio-source/messages.js';
 /**
  * Parse and validate `audio mix --volumes` / `--offsets` against `--inputs`.
@@ -49,6 +50,7 @@ export function registerAudioCommands(program) {
         .command('audio')
         .description(audioSourceMessage('audioTopic'));
     registerAudioSourceCommands(audio);
+    registerAudioProgramCommands(audio);
     // ── audio-info ──────────────────────────────────────────────────────────
     audio
         .command('info')

package/dist/workspace-runtime/server/audio-assets.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { workspaceAudioTargetSchema, workspaceRelativePathSchema, workspaceAudioProtectionSchema, isSoundDocumentPath } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceAudioTargetSchema, workspaceRelativePathSchema, workspaceAudioProtectionSchema, isSoundDocumentPath, audioReferenceActionSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { WorkspaceAudioAssets } from '../workspaces/audio-assets/service.js';
 import { audioRendererScript, workspaceAudioRenderer } from '../workspaces/audio-assets/renderer.js';
 import { audioError } from '../workspaces/audio-assets/storage.js';
@@ -116,7 +116,8 @@ async function rendererProbe(state, root, scope, kind = 'synth-sfx') {
 }
 /** Audio protocol negotiation is independent of legacy binary audio export. */
 export async function handleAudioAssetRequest(state, request, response, url) {
-    if (!['/runtime/audio/capabilities', '/runtime/audio/assets', '/runtime/audio/content', '/runtime/audio/actions'].includes(url.pathname))
+    if (!['/runtime/audio/capabilities', '/runtime/audio/assets', '/runtime/audio/content', '/runtime/audio/actions',
+        '/runtime/audio/library-snapshot', '/runtime/audio/references'].includes(url.pathname))
         return false;
     try {
         if (request.headers['x-playcraft-audio-protocol'] !== '1')
@@ -127,7 +128,7 @@ export async function handleAudioAssetRequest(state, request, response, url) {
             const renderer = enabled ? await rendererProbe(state, root, `${workspaceId ?? 'single'}:${directoryName}`) : { ready: false, reason: 'feature_disabled' };
             const scoreRenderer = enabled && request.headers['x-playcraft-audio-score-protocol'] === '1'
                 ? await rendererProbe(state, root, `${workspaceId ?? 'single'}:${directoryName}`, 'score') : { ready: false, reason: enabled ? 'audio_score_protocol_required' : 'feature_disabled' };
-            send(response, 200, { version: 1, audioAssetVersion: 1, audioScoreVersion: 1, audioScoreContextVersion: 1,
+            send(response, 200, { version: 1, audioAssetVersion: 1, audioScoreVersion: 1, audioScoreContextVersion: 1, audioLibraryVersion: 1, audioReferencesVersion: 1,
                 enabled, writable: enabled, documentVersions: [1], contentKinds: request.headers['x-playcraft-audio-score-protocol'] === '1' ? ['synth-sfx', 'score'] : ['synth-sfx'],
                 renderer: { ...renderer, engineId: 'playcraft-webaudio-sfx', engineVersion: '1.0.0' },
                 scoreRenderer: { ...scoreRenderer, engineId: 'playcraft-webaudio-score', engineVersion: '1.0.0' },
@@ -144,6 +145,51 @@ export async function handleAudioAssetRequest(state, request, response, url) {
             send(response, 200, result);
             return true;
         }
+        if (request.method === 'GET' && url.pathname === '/runtime/audio/library-snapshot') {
+            if (!enabled)
+                throw audioError('audio_feature_disabled', 403);
+            const target = targetFrom(url), revision = Number(url.searchParams.get('revision')), hash = url.searchParams.get('contentHash');
+            if (!Number.isSafeInteger(revision) || revision < 1 || !hash || !/^[a-f0-9]{64}$/.test(hash))
+                throw audioError('invalid_audio_request', 400);
+            const current = await assets.read(target);
+            requireScore(current.document.format === 'playcraft.score');
+            send(response, 200, await assets.librarySnapshot(target, revision, hash));
+            return true;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/audio/references') {
+            const target = targetFrom(url);
+            if (target.kind !== 'workspace-file')
+                throw audioError('invalid_audio_target', 400);
+            const current = await assets.read(target);
+            requireScore(current.document.format === 'playcraft.score');
+            send(response, 200, await assets.references(target));
+            return true;
+        }
+        if (request.method === 'POST' && url.pathname === '/runtime/audio/references') {
+            if (!enabled)
+                throw audioError('audio_feature_disabled', 403);
+            if (state.journal.destroyed())
+                throw audioError('runtime_destroyed');
+            const input = audioReferenceActionSchema.safeParse(await body(request));
+            if (!input.success)
+                throw audioError('invalid_audio_request', 400);
+            requireScore(input.data.target.path.endsWith('.pcscore.json'));
+            const sessionId = url.searchParams.get('sessionId');
+            if (sessionId) {
+                const session = state.journal.getSession(sessionId);
+                if (!session || session.workspaceId !== workspaceId || (session.directoryName ?? 'basic') !== directoryName)
+                    throw audioError('audio_scope_mismatch', 403);
+                if (session.permissionMode === 'read-only')
+                    throw audioError('plan_mode_write_forbidden', 403);
+            }
+            const result = await withDirectoryWrite(state, { workspaceId, directoryName, wait: false, sessionId: sessionId ?? undefined }, async () => {
+                if (await batchDirectoryHeld(state, workspaceId, directoryName))
+                    throw audioError('batch_workspace_readonly', 403);
+                return state.journal.exclusive(`file:${revisionScope(state, workspaceId, directoryName) ?? 'single'}:source/audio-bindings/${input.data.eventName}.json`, () => assets.referenceAction(input.data));
+            });
+            send(response, 200, result);
+            return true;
+        }
         if (request.method === 'GET' && url.pathname === '/runtime/audio/content') {
             const revision = url.searchParams.has('revision') ? Number(url.searchParams.get('revision')) : undefined;
             if (revision !== undefined && (!Number.isSafeInteger(revision) || revision < 1))

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

@@ -6,6 +6,8 @@ import { BINARY_WORKSPACE_FILE_MAX_BYTES, WORKSPACE_LIBRARY_ATTACHMENT_MAX_BYTES
 import { observeWorkspaceBinaryFile, writeWorkspaceBinaryFile } from './binary-write.js';
 import { shareWorkspaceAssetDirectory } from './asset-publication-access.js';
 import { ensureSharedDirectory } from './shared-write.js';
+import { isEditableAudioLibraryAsset, prepareAudioLibraryImport } from './audio-assets/library-import.js';
+import { readAudioArtifactPackage } from './audio-assets/artifact-package.js';
 const RESERVED = new Set(['.git', 'node_modules', '.playcraft-temp', '.tmp']);
 const digest = (value) => createHash('sha256').update(value).digest('hex');
 const missing = (error) => error?.code === 'ENOENT';
@@ -158,6 +160,9 @@ async function readTransaction(root, transaction) {
             || !/^[a-f0-9]{64}$/.test(value.incomingHash))
             throw new AssetLibraryImportError('invalid_library_import');
         validPath(value.target);
+        if (value.audioPackagePaths && (value.audioPackagePaths.length !== 5 || new Set(value.audioPackagePaths).size !== 5
+            || value.audioPackagePaths.some(path => !/^dist\/audio\/[a-f0-9]{64}\/[a-f0-9]{64}\/[a-f0-9]{64}\/(?:sound\.(?:pcaudio|pcscore)\.json|audition\.wav|runtime\.mjs|sound\.mjs|manifest\.json)$/.test(path))))
+            throw new AssetLibraryImportError('invalid_library_import');
         if ((value.operationId !== undefined || value.assetId !== undefined || value.paths !== undefined)
             && (typeof value.operationId !== 'string' || !value.operationId || value.operationId.length > 128
                 || typeof value.assetId !== 'string' || !value.assetId || value.assetId.length > 128
@@ -203,8 +208,17 @@ export async function recoverInterruptedLibraryImports(root) {
                 throw new AssetLibraryImportError('invalid_library_import_path');
             if (current?.isDirectory() && !current.isSymbolicLink() && !incoming
                 && await directorySnapshot(target) === manifest.incomingHash) {
+                if (manifest.audioPackagePaths) {
+                    const primary = manifest.audioPackagePaths.find(path => /\/sound\.(?:pcaudio|pcscore)\.json$/.test(path));
+                    if (!primary)
+                        throw new AssetLibraryImportError('invalid_library_import');
+                    const packaged = await readAudioArtifactPackage(rootReal, primary);
+                    if (!packaged.sourcePath.startsWith(`${manifest.target}/`) || packaged.files.size !== 5
+                        || [...packaged.files.keys()].some(path => !manifest.audioPackagePaths.includes(path)))
+                        throw new AssetLibraryImportError('invalid_library_import');
+                }
                 if (manifest.operationId && manifest.assetId && manifest.paths)
-                    result.published.push({ operationId: manifest.operationId, assetId: manifest.assetId, paths: manifest.paths });
+                    result.published.push({ operationId: manifest.operationId, assetId: manifest.assetId, paths: [...manifest.paths, ...(manifest.audioPackagePaths ?? [])] });
                 await removeTransaction(rootReal, transaction);
                 result.recovered.push(manifest.target);
                 continue;
@@ -236,7 +250,7 @@ export async function recoverInterruptedLibraryImports(root) {
     }
     return result;
 }
-async function publishBundle(root, target, asset, replace, assertCurrent, operationId) {
+async function publishBundle(root, target, asset, replace, assertCurrent, operationId, audioPackagePaths) {
     const parent = dirname(target) === '.' ? '' : dirname(target);
     await createPublicDirectory(root, parent);
     const previous = await statTarget(root, target);
@@ -256,6 +270,7 @@ async function publishBundle(root, target, asset, replace, assertCurrent, operat
             await writeWorkspaceBinaryFile(staged, { path: file.path, contentBase64: file.content, expectedContentHash: null });
         }
         const manifest = { version: 1, target, phase: 'prepared', originalHash: originalHash ?? null,
+            ...(audioPackagePaths ? { audioPackagePaths } : {}),
             incomingHash: await directorySnapshot(staged), ...(operationId ? { operationId, assetId: asset.assetId,
                 paths: asset.files.map(file => `${target}/${file.path}`) } : {}) };
         await saveTransaction(root, transaction, manifest);
@@ -364,9 +379,13 @@ export async function importWorkspaceLibraryAssets(root, selection, snapshot, as
                 }
             }
             if (asset.kind === 'bundle') {
-                const paths = asset.files.map(file => validPath(`${target}/${file.path}`));
-                publishedTransaction = await publishBundle(rootReal, target, asset, payload.collision === 'replace', assertCurrent, options.operationId);
+                const audio = isEditableAudioLibraryAsset(asset) ? await prepareAudioLibraryImport(rootReal, target, asset, assertCurrent) : undefined;
+                const incoming = audio?.asset ?? asset;
+                const paths = incoming.files.map(file => validPath(`${target}/${file.path}`));
+                publishedTransaction = await publishBundle(rootReal, target, incoming, payload.collision === 'replace', assertCurrent, options.operationId, audio?.packagePaths);
                 result.paths.push(...paths);
+                if (audio)
+                    result.paths.push(...audio.packagePaths);
             }
             else {
                 const observed = existing ? await observeWorkspaceBinaryFile(rootReal, target) : undefined;
@@ -378,9 +397,10 @@ export async function importWorkspaceLibraryAssets(root, selection, snapshot, as
         }
         catch (error) {
             const code = error instanceof AssetLibraryImportError ? error.message
-                : error?.code === 'content_conflict' ? 'content_conflict'
-                    : ['EACCES', 'EPERM'].includes(String(error?.code)) ? 'workspace_permission_denied'
-                        : 'asset_library_import_failed';
+                : error instanceof Error && ['invalid_audio_library_package', 'audio_library_engine_unavailable', 'audio_library_source_unverified', 'audio_representation_conflict'].includes(error.message) ? error.message
+                    : error?.code === 'content_conflict' ? 'content_conflict'
+                        : ['EACCES', 'EPERM'].includes(String(error?.code)) ? 'workspace_permission_denied'
+                            : 'asset_library_import_failed';
             result.failures.push({ assetId, error: code });
         }
         processed.add(assetId);

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

@@ -4,6 +4,7 @@ import { canonicalAudioJson } from '@playcraft/common/cloud-workspace/runtime';
 import { readAudioArtifactPackage } from './artifact-package.js';
 import { audioError, audioProjectPath, digest, readAudioSource } from './storage.js';
 import { ensureSharedDirectory, writeSharedFile } from '../shared-write.js';
+import { readAudioProgramBuildInputs } from './program-build-inputs.js';
 const hashPart = /^[a-f0-9]{64}$/;
 const MAX_PACKAGES = 256;
 const MAX_PACKAGE_BYTES = 64 * 1024 * 1024;
@@ -65,12 +66,15 @@ export async function readAudioBuildInputs(root, destination) {
         }
         packages.push({ primaryPath, sourcePath: bundle.sourcePath, sourceContentHash: sourceText === undefined ? null : digest(sourceText), files });
     }
-    return { version: 1, inputHash: digest(canonicalAudioJson(packages)), packages };
+    const programs = await readAudioProgramBuildInputs(root, destination);
+    // Existing projects retain their original snapshot identity when no state programs are present.
+    return { version: 1, inputHash: digest(canonicalAudioJson(programs.packages.length ? { packages, programs } : packages)), packages,
+        ...(programs.packages.length ? { programs } : {}) };
 }
 export async function verifyAudioBuildInputs(root, snapshot) {
     if ((await readAudioBuildInputs(root)).inputHash !== snapshot.inputHash)
         throw audioError('audio_build_input_changed');
 }
 export function markAudioBuildInputs(bytes, snapshot) {
-    return snapshot.packages.length ? Buffer.concat([Buffer.from(`<!--playcraft-audio-inputs:v1:${snapshot.inputHash}-->\n`), bytes]) : bytes;
+    return snapshot.packages.length || snapshot.programs?.packages.length ? Buffer.concat([Buffer.from(`<!--playcraft-audio-inputs:v1:${snapshot.inputHash}-->\n`), bytes]) : bytes;
 }

package/dist/workspace-runtime/workspaces/audio-assets/library-import.js

@@ -0,0 +1,149 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, open, readdir, readFile, rename, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { canonicalAudioJson, audioRepresentationSetHash, inspectAudioLibrarySnapshot, audioLibraryOriginSchema, audioLibraryPayloadHash } from '@playcraft/common/cloud-workspace/runtime';
+import { audioRendererScript } from './renderer.js';
+import { readAudioArtifactPackage } from './artifact-package.js';
+import { audioProjectPath, audioError, digest } from './storage.js';
+import { ensureSharedDirectory, writeSharedFile } from '../shared-write.js';
+export const isEditableAudioLibraryAsset = (asset) => {
+    if (asset.files.some(file => /(?:^|\/)sound\.(?:pcaudio|pcscore)\.json$/.test(file.path)))
+        return true;
+    try {
+        const file = asset.files.find(file => file.path === 'manifest.json');
+        const value = file && JSON.parse(Buffer.from(file.content, 'base64').toString('utf8'));
+        return Boolean(value && (value.sourcePath !== undefined || value.representationSetHash !== undefined));
+    }
+    catch {
+        return false;
+    }
+};
+function inspectAsset(asset, requirePlatformProof = true) {
+    if (requirePlatformProof && !asset.audioSource)
+        throw audioError('audio_library_source_unverified', 409);
+    try {
+        const manifestFile = asset.files.find(file => file.path === 'manifest.json');
+        if (!manifestFile)
+            throw new Error();
+        const manifest = JSON.parse(Buffer.from(manifestFile.content, 'base64').toString('utf8'));
+        const checked = inspectAudioLibrarySnapshot({ version: 1, target: asset.audioSource?.source.target ?? { kind: 'workspace-file', path: manifest.sourcePath },
+            revision: asset.audioSource?.source.revision ?? 1, sourcePath: manifest.sourcePath,
+            files: asset.files.map(file => ({ path: file.path, mimeType: file.mimeType, content: file.content,
+                contentHash: file.sha256, size: Buffer.from(file.content, 'base64').length })) });
+        if (asset.audioSource && audioLibraryPayloadHash(checked.source) !== audioLibraryPayloadHash(asset.audioSource.source))
+            throw new Error();
+        return checked;
+    }
+    catch {
+        throw audioError('invalid_audio_library_package', 400);
+    }
+}
+async function trustedEngine(checked) {
+    const engine = await audioRendererScript(checked.document.format === 'playcraft.score' ? 'score' : 'synth-sfx');
+    const suffix = checked.document.format === 'playcraft.score' ? '\nexport { renderSoundDocument, createStandaloneSoundPlayer };\n'
+        : '\nexport { renderAudioDocument, createStandaloneAudioPlayer };\n';
+    if (checked.source.rendererBuildHash !== engine.rendererBuildHash || Buffer.from(checked.files.get('runtime.mjs')).toString('utf8') !== engine.script + suffix)
+        throw audioError('audio_library_engine_unavailable', 409);
+}
+/** Verify against platform engine bytes before publishing any executable member. */
+export async function prepareAudioLibraryImport(root, target, asset, assertCurrent) {
+    const checked = inspectAsset(asset);
+    await trustedEngine(checked);
+    await assertCurrent();
+    const sourcePath = `${target}/${checked.source.entryPath}`;
+    await audioProjectPath(root, sourcePath);
+    const { representationSetHash: _previous, ...oldPayload } = checked.manifest;
+    const payload = { ...oldPayload, sourcePath }, representationSetHash = audioRepresentationSetHash(payload);
+    const manifest = Buffer.from(`${canonicalAudioJson({ ...payload, representationSetHash })}\n`);
+    const directory = `dist/audio/${digest(sourcePath)}/${checked.source.sourceContentHash}/${representationSetHash}`;
+    const members = new Map([...checked.files].map(([path, bytes]) => [path, Buffer.from(bytes)]));
+    members.set('manifest.json', manifest);
+    const destination = dirname(await audioProjectPath(root, `${directory}/manifest.json`));
+    await ensureSharedDirectory(root, dirname(destination));
+    const staging = `${destination}.${randomUUID()}.tmp`;
+    await ensureSharedDirectory(root, staging);
+    try {
+        for (const [path, bytes] of members)
+            await writeSharedFile(root, join(staging, path), bytes);
+        await assertCurrent();
+        const existing = await lstat(destination).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (existing) {
+            if (!existing.isDirectory() || existing.isSymbolicLink() || (await readdir(destination)).sort().join(',') !== [...members.keys()].sort().join(','))
+                throw audioError('audio_representation_conflict');
+            for (const [path, bytes] of members)
+                if (digest(await readFile(await audioProjectPath(root, `${directory}/${path}`))) !== digest(bytes))
+                    throw audioError('audio_representation_conflict');
+        }
+        else {
+            await rename(staging, destination);
+            const parent = await open(dirname(destination), 'r');
+            try {
+                await parent.sync();
+            }
+            finally {
+                await parent.close();
+            }
+        }
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+    const origin = { assetId: asset.assetId, contentHash: asset.contentHash, libraryPath: asset.libraryPath,
+        sourcePath: checked.source.sourcePath, sourceContentHash: checked.source.sourceContentHash, representationSetHash: checked.source.representationSetHash };
+    const metadata = Buffer.from(`${canonicalAudioJson({ version: 1, sourcePath, sourceContentHash: checked.source.sourceContentHash,
+        primaryPath: `${directory}/${checked.source.entryPath}`, representationSetHash, origin })}\n`);
+    const files = [{ path: checked.source.entryPath, bytes: members.get(checked.source.entryPath), mimeType: 'application/json' },
+        { path: 'audio-library.json', bytes: metadata, mimeType: 'application/json' }].map(({ bytes, ...file }) => ({ ...file, content: bytes.toString('base64'), sha256: digest(bytes) }));
+    const portable = { ...asset, files,
+        contentHash: digest(JSON.stringify(files.map(file => [file.path, file.sha256]).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0))) };
+    return { asset: portable, packagePaths: [...members.keys()].map(path => `${directory}/${path}`) };
+}
+/** Recover verified import ancestry; reuse its audition only while the current source still matches. */
+export async function readImportedAudioLibrarySource(root, sourcePath, contentHash) {
+    const directory = dirname(sourcePath), sidecar = await audioProjectPath(root, `${directory === '.' ? '' : directory + '/'}audio-library.json`);
+    const stat = await lstat(sidecar).catch(error => { if (error.code === 'ENOENT')
+        return undefined; throw error; });
+    if (!stat)
+        return undefined;
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 65_536)
+        throw audioError('audio_library_dependency_invalid', 409);
+    const metadata = JSON.parse(await readFile(sidecar, 'utf8'));
+    if (metadata.sourcePath !== sourcePath)
+        return undefined;
+    if (metadata.version !== 1 || typeof metadata.primaryPath !== 'string')
+        throw audioError('audio_library_dependency_invalid', 409);
+    try {
+        const packaged = await readAudioArtifactPackage(root, metadata.primaryPath);
+        const files = [...packaged.files].map(([path, bytes]) => ({ path: path.slice(path.lastIndexOf('/') + 1), content: bytes.toString('base64'), sha256: digest(bytes),
+            mimeType: path.endsWith('.mjs') ? 'text/javascript' : path.endsWith('.wav') ? 'audio/wav' : 'application/json' }));
+        const asset = { assetId: 'verified-local', name: 'sound', libraryPath: '', visibility: 'team', kind: 'bundle', contentHash: ''.padStart(64, '0'), files };
+        const checked = inspectAsset(asset, false);
+        await trustedEngine(checked);
+        if (checked.source.sourcePath !== sourcePath || checked.source.sourceContentHash !== metadata.sourceContentHash || checked.source.representationSetHash !== metadata.representationSetHash)
+            throw new Error();
+        const origin = audioLibraryOriginSchema.parse(metadata.origin), { representationSetHash: _relocated, ...payload } = checked.manifest;
+        if (origin.sourceContentHash !== checked.source.sourceContentHash
+            || audioRepresentationSetHash({ ...payload, sourcePath: origin.sourcePath }) !== origin.representationSetHash)
+            throw new Error();
+        const wav = Buffer.from(checked.files.get('audition.wav')), frames = (wav.length - 44) / 2;
+        let peak = 0, sum = 0;
+        for (let frame = 0; frame < frames; frame++) {
+            const value = wav.readInt16LE(44 + frame * 2) / 32768;
+            peak = Math.max(peak, Math.abs(value));
+            sum += value * value;
+        }
+        if (peak > .9801)
+            throw new Error();
+        const current = { wav, audition: { mimeType: 'audio/wav', size: wav.length, contentHash: digest(wav), pcmContentHash: checked.manifest.pcmContentHash,
+                rendererBuildHash: checked.source.rendererBuildHash, chromiumVersion: checked.manifest.chromiumVersion, renderKey: checked.manifest.renderKey,
+                metrics: { peak, rms: Math.sqrt(sum / frames), frames, sampleRate: 44100, channels: 1, silent: peak === 0 } },
+            representation: { sourceContentHash: checked.source.sourceContentHash, rendererBuildHash: checked.source.rendererBuildHash, representationSetHash: checked.source.representationSetHash,
+                modulePath: `${dirname(metadata.primaryPath)}/sound.mjs`, manifestPath: `${dirname(metadata.primaryPath)}/manifest.json`,
+                files: [...packaged.files].map(([path, bytes]) => ({ path, size: bytes.length, contentHash: digest(bytes) })) } };
+        return { origin, current: checked.source.sourceContentHash === contentHash ? current : undefined };
+    }
+    catch (error) {
+        throw audioError(error?.message === 'audio_library_engine_unavailable' ? 'audio_library_engine_unavailable' : 'audio_library_dependency_invalid', 409);
+    }
+}

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

@@ -0,0 +1,26 @@
+import { canonicalAudioJson, audioRepresentationSetHash, audioLibraryModule, inspectAudioLibrarySnapshot } from '@playcraft/common/cloud-workspace/runtime';
+import { audioRendererScript } from './renderer.js';
+import { audioError, digest } from './storage.js';
+/** Package a verified audition and its fixed engine; saving to the library does not adopt the candidate. */
+export async function createAudioLibrarySnapshot(input) {
+    const score = input.document.format === 'playcraft.score', engine = await audioRendererScript(score ? 'score' : 'synth-sfx');
+    if (engine.rendererBuildHash !== input.audition.rendererBuildHash)
+        throw audioError('engine_build_mismatch', 503);
+    const runtime = engine.script + (score ? '\nexport { renderSoundDocument, createStandaloneSoundPlayer };\n'
+        : '\nexport { renderAudioDocument, createStandaloneAudioPlayer };\n');
+    const members = [
+        { path: score ? 'sound.pcscore.json' : 'sound.pcaudio.json', mimeType: 'application/json', role: 'editable', bytes: Buffer.from(input.sourceText) },
+        { path: 'audition.wav', mimeType: 'audio/wav', role: 'audition', bytes: Buffer.from(input.wav) },
+        { path: 'runtime.mjs', mimeType: 'text/javascript', role: 'runtime', bytes: Buffer.from(runtime) },
+        { path: 'sound.mjs', mimeType: 'text/javascript', role: 'delivery', bytes: Buffer.from(audioLibraryModule(input.document, input.contentHash, engine.rendererBuildHash)) },
+    ];
+    const files = members.map(({ bytes, ...file }) => ({ ...file, size: bytes.length, contentHash: digest(bytes) }));
+    const payload = { version: 1, sourcePath: input.sourcePath, sourceContentHash: input.contentHash, sourceRenderHash: input.sourceRenderHash,
+        engine: input.document.engine, rendererBuildHash: engine.rendererBuildHash, chromiumVersion: input.audition.chromiumVersion,
+        renderKey: input.audition.renderKey, pcmContentHash: input.audition.pcmContentHash, files };
+    const manifest = Buffer.from(`${canonicalAudioJson({ ...payload, representationSetHash: audioRepresentationSetHash(payload) })}\n`);
+    const snapshot = { version: 1, target: input.target, revision: input.revision, sourcePath: input.sourcePath,
+        files: [...members.map(({ bytes, role: _role, ...file }) => ({ ...file, size: bytes.length, contentHash: digest(bytes), content: bytes.toString('base64') })),
+            { path: 'manifest.json', mimeType: 'application/json', size: manifest.length, contentHash: digest(manifest), content: manifest.toString('base64') }] };
+    return inspectAudioLibrarySnapshot(snapshot).snapshot;
+}

package/dist/workspace-runtime/workspaces/audio-assets/program-artifact-audit.js

@@ -0,0 +1,90 @@
+import { inflateRawSync } from 'node:zlib';
+import { extname } from 'node:path';
+import { audioError } from './storage.js';
+const MAX_BYTES = 64 * 1024 * 1024, MAX_ENTRIES = 4096;
+const MARKERS = { runtime: 'playcraft.audio-program.runtime.v1', prerender: 'playcraft.audio-program.prerender.v1' };
+const invalid = () => audioError('audio_program_artifact_unverified', 422);
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (const byte of bytes) {
+        crc ^= byte;
+        for (let i = 0; i < 8; i++)
+            crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/** Inspect archive members, never compressed binary substrings or evaluated project code. */
+function zipTextEntries(bytes) {
+    let end = -1;
+    for (let i = bytes.length - 22, minimum = Math.max(0, bytes.length - 65557); i >= minimum; i--)
+        if (bytes.readUInt32LE(i) === 0x06054b50 && i + 22 + bytes.readUInt16LE(i + 20) === bytes.length) {
+            end = i;
+            break;
+        }
+    if (end < 0 || bytes.readUInt16LE(end + 4) !== 0 || bytes.readUInt16LE(end + 6) !== 0)
+        throw invalid();
+    const count = bytes.readUInt16LE(end + 10), length = bytes.readUInt32LE(end + 12), offset = bytes.readUInt32LE(end + 16);
+    if (count > MAX_ENTRIES || count !== bytes.readUInt16LE(end + 8) || offset + length !== end)
+        throw invalid();
+    const entries = [];
+    let cursor = offset, inflated = 0;
+    for (let i = 0; i < count; i++) {
+        if (cursor + 46 > end || bytes.readUInt32LE(cursor) !== 0x02014b50)
+            throw invalid();
+        const flags = bytes.readUInt16LE(cursor + 8), method = bytes.readUInt16LE(cursor + 10), checksum = bytes.readUInt32LE(cursor + 16);
+        const packed = bytes.readUInt32LE(cursor + 20), size = bytes.readUInt32LE(cursor + 24), nameLength = bytes.readUInt16LE(cursor + 28);
+        const next = cursor + 46 + nameLength + bytes.readUInt16LE(cursor + 30) + bytes.readUInt16LE(cursor + 32), local = bytes.readUInt32LE(cursor + 42);
+        if (next > end || flags & 1 || ![0, 8].includes(method) || size > MAX_BYTES || local + 30 > offset || bytes.readUInt16LE(cursor + 34))
+            throw invalid();
+        const nameBytes = bytes.subarray(cursor + 46, cursor + 46 + nameLength), name = new TextDecoder('utf-8', { fatal: true }).decode(nameBytes);
+        if (!name || name.includes('\\') || name.startsWith('/') || name.split('/').includes('..') || name.includes('\0'))
+            throw invalid();
+        if (bytes.readUInt32LE(local) !== 0x04034b50 || bytes.readUInt16LE(local + 8) !== method || bytes.readUInt16LE(local + 6) !== flags)
+            throw invalid();
+        const localNameLength = bytes.readUInt16LE(local + 26), start = local + 30 + localNameLength + bytes.readUInt16LE(local + 28);
+        if (!bytes.subarray(local + 30, local + 30 + localNameLength).equals(nameBytes) || start + packed > offset)
+            throw invalid();
+        if (/\.(?:[cm]?js|html?)$/i.test(name)) {
+            if ((inflated += size) > MAX_BYTES)
+                throw invalid();
+            const data = bytes.subarray(start, start + packed), value = method === 0 ? data : inflateRawSync(data, { maxOutputLength: Math.max(1, size) });
+            if (value.length !== size || crc32(value) !== checksum)
+                throw invalid();
+            entries.push({ name, bytes: value });
+        }
+        cursor = next;
+    }
+    if (cursor !== end || !entries.length)
+        throw invalid();
+    return entries;
+}
+export function auditAudioProgramArtifact(bytes, outputPath, variant) {
+    if (!bytes.length || bytes.length > MAX_BYTES || !['runtime', 'prerender'].includes(variant))
+        throw invalid();
+    const extension = extname(outputPath).toLowerCase(), format = extension === '.zip' ? 'zip' : extension === '.html' || extension === '.htm' ? 'html' : undefined;
+    if (!format)
+        throw invalid();
+    const entries = format === 'zip' ? zipTextEntries(bytes) : [{ name: outputPath, bytes }];
+    const result = { format, inspectedFiles: entries.length, inspectedBytes: 0, expectedMarkerCount: 0, forbiddenMarkerCount: 0, coverage: 'html-javascript-and-explicit-base64-data' };
+    const seen = new Set();
+    const inspect = (data, depth) => {
+        if ((result.inspectedBytes += data.length) > MAX_BYTES)
+            throw invalid();
+        const text = new TextDecoder('utf-8', { fatal: true }).decode(data);
+        result.expectedMarkerCount += text.split(MARKERS[variant]).length - 1;
+        result.forbiddenMarkerCount += text.split(MARKERS[variant === 'runtime' ? 'prerender' : 'runtime']).length - 1;
+        for (const match of text.matchAll(/data:(?:text\/(?:javascript|html)|application\/(?:javascript|json));base64,([A-Za-z0-9+/]+={0,2})/g)) {
+            if (depth >= 3 || match[1].length > MAX_BYTES * 4 / 3)
+                throw invalid();
+            if (seen.has(match[1]))
+                continue;
+            seen.add(match[1]);
+            inspect(Buffer.from(match[1], 'base64'), depth + 1);
+        }
+    };
+    for (const entry of entries)
+        inspect(entry.bytes, 0);
+    if (result.forbiddenMarkerCount || !result.expectedMarkerCount)
+        throw Object.assign(invalid(), { details: { variant, ...result } });
+    return result;
+}