@playcraft/cli 0.1.67 → 0.1.69

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

@@ -0,0 +1,194 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { chmod, mkdtemp, open, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { chromium } from 'playwright-core';
+import { AUDIO_DYNAMIC_LIMITS, parseAudioDynamicProgram, serializeAudioDynamicProgram, validateAudioDynamicProgram, } from '@playcraft/common/cloud-workspace/runtime';
+import { audioProgramRendererScript } from './program-engine.js';
+import { AUDIO_RENDER_CHUNK_BYTES, encodeAudioRenderChunk, writeAudioRenderOutput } from './render-worker.js';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+function inputSnapshot(program, files, stateId) {
+    const checked = parseAudioDynamicProgram(serializeAudioDynamicProgram(validateAudioDynamicProgram(program)));
+    const state = checked.states.find(item => item.id === stateId);
+    if (!state)
+        throw new Error('invalid_audio_state');
+    if (!files || ![Object.prototype, null].includes(Object.getPrototypeOf(files)))
+        throw new Error('audio_dependency_mismatch');
+    const dependencies = checked.assets.flatMap(asset => asset.kind === 'synth' ? [asset.source, asset.manifest] : [asset.file]);
+    if (dependencies.reduce((sum, ref) => sum + ref.size, 0) > AUDIO_DYNAMIC_LIMITS.inputBytes)
+        throw new Error('audio_program_budget_exceeded');
+    const encoded = Object.create(null);
+    let total = 0;
+    for (const [path, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(files))) {
+        if (!('value' in descriptor) || !(descriptor.value instanceof Uint8Array))
+            throw new Error('audio_dependency_mismatch');
+        total += descriptor.value.byteLength;
+        if (total > AUDIO_DYNAMIC_LIMITS.inputBytes)
+            throw new Error('audio_program_budget_exceeded');
+        const bytes = Buffer.from(descriptor.value), references = dependencies.filter(ref => ref.path === path);
+        if (!references.length || references.some(ref => bytes.length !== ref.size || digest(bytes) !== ref.contentHash))
+            throw new Error('audio_dependency_mismatch');
+        encoded[path] = bytes.toString('base64');
+    }
+    if (dependencies.some(ref => !Object.hasOwn(encoded, ref.path)))
+        throw new Error('audio_dependency_missing');
+    return { program: checked, files: encoded, stateId, frames: Math.ceil(state.durationSeconds * 44100) };
+}
+function checkedMetrics(value, frames) {
+    if (!value || value.frames !== frames || value.channels !== 1 || value.sampleRate !== 44100
+        || !Number.isFinite(value.peak) || value.peak < 0 || !Number.isFinite(value.rms) || value.rms < 0
+        || value.rms > value.peak + 1e-12 || typeof value.silent !== 'boolean' || value.silent !== (value.peak === 0))
+        throw new Error('invalid_audio_output');
+    if (value.peak > .98)
+        throw new Error('render_peak_exceeded');
+    return value;
+}
+async function verifyPcm(path, frames, expectedHash, assertActive) {
+    const hash = createHash('sha256');
+    let bytes = 0, peak = 0, energy = 0;
+    for await (const chunk of createReadStream(path, { highWaterMark: AUDIO_RENDER_CHUNK_BYTES })) {
+        assertActive();
+        bytes += chunk.length;
+        if (bytes > frames * 4 || chunk.length % 4)
+            throw new Error('invalid_audio_output');
+        hash.update(chunk);
+        for (let offset = 0; offset < chunk.length; offset += 4) {
+            const sample = chunk.readFloatLE(offset);
+            if (!Number.isFinite(sample))
+                throw new Error('invalid_audio_output');
+            peak = Math.max(peak, Math.abs(sample));
+            energy += sample * sample;
+        }
+    }
+    if (bytes !== frames * 4 || hash.digest('hex') !== expectedHash)
+        throw new Error('invalid_audio_output');
+    return checkedMetrics({ frames, channels: 1, sampleRate: 44100, peak, rms: Math.sqrt(energy / frames), silent: peak === 0 }, frames);
+}
+async function readWave(path, frames, assertActive) {
+    const file = await open(path, 'r');
+    try {
+        const size = 44 + frames * 2;
+        if ((await file.stat()).size !== size)
+            throw new Error('invalid_audio_output');
+        const bytes = Buffer.alloc(size);
+        for (let offset = 0; offset < size;) {
+            assertActive();
+            const { bytesRead } = await file.read(bytes, offset, Math.min(AUDIO_RENDER_CHUNK_BYTES, size - offset), offset);
+            if (!bytesRead)
+                throw new Error('invalid_audio_output');
+            offset += bytesRead;
+        }
+        if (bytes.toString('ascii', 0, 4) !== 'RIFF' || bytes.toString('ascii', 8, 12) !== 'WAVE'
+            || bytes.toString('ascii', 12, 16) !== 'fmt ' || bytes.toString('ascii', 36, 40) !== 'data'
+            || bytes.readUInt32LE(4) !== size - 8 || bytes.readUInt32LE(16) !== 16 || bytes.readUInt16LE(20) !== 1
+            || bytes.readUInt16LE(22) !== 1 || bytes.readUInt32LE(24) !== 44100 || bytes.readUInt32LE(28) !== 88200
+            || bytes.readUInt16LE(32) !== 2 || bytes.readUInt16LE(34) !== 16 || bytes.readUInt32LE(40) !== frames * 2)
+            throw new Error('invalid_audio_output');
+        return bytes;
+    }
+    finally {
+        await file.close();
+    }
+}
+/** The compile caller owns this process; only fixed platform code is executed by its owned browser. */
+export async function renderAudioProgramInBrowser(program, files, stateId, signal) {
+    const uid = process.getuid?.();
+    if (typeof uid !== 'number' || uid <= 0)
+        throw new Error('audio_renderer_identity_unavailable');
+    let cancelled = signal?.aborted === true, timedOut = false, browser, closing, scratch;
+    const assertActive = () => { if (timedOut)
+        throw new Error('audio_render_timeout'); if (cancelled || signal?.aborted)
+        throw new Error('audio_render_cancelled'); };
+    const closeOwnedBrowser = () => browser ? closing ??= browser.close() : Promise.resolve();
+    const cancel = () => { cancelled = true; void closeOwnedBrowser().catch(() => undefined); };
+    assertActive();
+    const snapshot = inputSnapshot(program, files, stateId);
+    signal?.addEventListener('abort', cancel, { once: true });
+    process.once('SIGTERM', cancel);
+    const deadline = setTimeout(() => { timedOut = true; cancel(); }, 60_000);
+    deadline.unref?.();
+    try {
+        assertActive();
+        const engine = await audioProgramRendererScript();
+        if (Buffer.byteLength(engine.script) > 512 * 1024 || !/^[a-f0-9]{64}$/.test(engine.rendererBuildHash)
+            || digest(engine.script) !== engine.rendererBuildHash)
+            throw new Error('engine_build_mismatch');
+        assertActive();
+        scratch = await mkdtemp(join(tmpdir(), 'playcraft-audio-program-'));
+        await chmod(scratch, 0o700);
+        const output = join(scratch, 'render');
+        browser = await chromium.launch({ executablePath: process.env.PLAYCRAFT_CHROMIUM_PATH || '/usr/bin/chromium',
+            headless: true, chromiumSandbox: true, timeout: 8000, handleSIGTERM: false, handleSIGINT: false, handleSIGHUP: false,
+            args: ['--mute-audio', '--disable-background-networking'] });
+        assertActive();
+        const chromiumVersion = browser.version();
+        const context = await browser.newContext({ serviceWorkers: 'block', acceptDownloads: false });
+        await context.route('**/*', route => route.abort('blockedbyclient'));
+        const page = await context.newPage();
+        await page.addScriptTag({ content: engine.script });
+        assertActive();
+        const rendered = await page.evaluateHandle(async ({ program, files, stateId, frames }) => {
+            const engine = globalThis.playcraftAudioProgram;
+            const decoded = Object.create(null);
+            let size = 0;
+            for (const [path, value] of Object.entries(files)) {
+                const text = atob(value);
+                size += text.length;
+                if (size > 2 * 1024 * 1024)
+                    throw new Error('audio_program_budget_exceeded');
+                const bytes = new Uint8Array(text.length);
+                for (let index = 0; index < text.length; index++)
+                    bytes[index] = text.charCodeAt(index);
+                decoded[path] = bytes;
+            }
+            const buffer = await engine.renderAudioDynamicProgram(program, decoded, stateId);
+            if (buffer.length !== frames || buffer.length > 2_646_000 || buffer.numberOfChannels !== 1 || buffer.sampleRate !== 44100)
+                throw new Error('invalid_audio_output');
+            const metrics = engine.soundPcmMetrics(buffer);
+            if (metrics.peak > .98)
+                throw new Error('render_peak_exceeded');
+            return { buffer, wav: engine.soundBufferToWav(buffer), metrics };
+        }, snapshot);
+        let summary;
+        try {
+            summary = await rendered.evaluate(value => ({ frames: value.buffer.length, wavBytes: value.wav.byteLength, metrics: value.metrics }));
+            checkedMetrics(summary.metrics, snapshot.frames);
+            assertActive();
+            await writeAudioRenderOutput(output, summary, chromiumVersion, request => {
+                assertActive();
+                return rendered.evaluate(encodeAudioRenderChunk, request);
+            }, snapshot.frames);
+        }
+        finally {
+            await rendered.dispose();
+        }
+        await closeOwnedBrowser();
+        assertActive();
+        const meta = JSON.parse(await readFile(`${output}.json`, 'utf8'));
+        if (!/^[a-f0-9]{64}$/.test(meta.pcmContentHash))
+            throw new Error('invalid_audio_output');
+        const metrics = await verifyPcm(`${output}.pcm`, snapshot.frames, meta.pcmContentHash, assertActive);
+        if (metrics.peak !== summary.metrics.peak || Math.abs(metrics.rms - summary.metrics.rms) > 1e-12)
+            throw new Error('invalid_audio_output');
+        const wav = await readWave(`${output}.wav`, snapshot.frames, assertActive);
+        assertActive();
+        return { wav, pcmContentHash: meta.pcmContentHash, chromiumVersion, metrics, rendererBuildHash: engine.rendererBuildHash };
+    }
+    catch (error) {
+        assertActive();
+        throw error;
+    }
+    finally {
+        try {
+            await closeOwnedBrowser();
+        }
+        finally {
+            signal?.removeEventListener('abort', cancel);
+            process.removeListener('SIGTERM', cancel);
+            clearTimeout(deadline);
+            if (scratch)
+                await rm(scratch, { recursive: true, force: true });
+        }
+    }
+}

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

@@ -0,0 +1,122 @@
+import { constants } from 'node:fs';
+import { lstat, open, opendir, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, sep } from 'node:path';
+import { canonicalAudioJson } from '@playcraft/common/cloud-workspace/runtime';
+import { readAudioProgramPackage } from './program-package.js';
+import { audioError, audioProjectPath, digest } from './storage.js';
+import { ensureSharedDirectory, writeSharedFile } from '../shared-write.js';
+export const AUDIO_PROGRAM_BUILD_PROTOCOL = 1;
+const HASH = /^[a-f0-9]{64}$/;
+const MAX_PACKAGES = 256, MAX_ENTRIES = 8192, MAX_BYTES = 64 * 1024 * 1024;
+/** A caller must provide an already-created build clone, never a source alias or ancestor. */
+export async function assertAudioProgramBuildClone(sourceRoot, cloneRoot) {
+    const [source, clone, stat] = await Promise.all([realpath(sourceRoot), realpath(cloneRoot), lstat(cloneRoot)]);
+    const rel = relative(source, clone), ancestor = relative(clone, source);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || !rel || !ancestor || !ancestor.startsWith(`..${sep}`) && ancestor !== '..' && !isAbsolute(ancestor)
+        || !rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel) && !rel.startsWith(`.playcraft-delivery${sep}`))
+        throw audioError('invalid_audio_build_clone', 400);
+}
+async function manifests(root) {
+    const found = [];
+    let entries = 0;
+    const visit = async (path, depth) => {
+        const absolute = await audioProjectPath(root, path);
+        const stat = await lstat(absolute).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (!stat)
+            return;
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw audioError('invalid_audio_path', 400);
+        const directory = await opendir(absolute, { bufferSize: 32 });
+        for await (const entry of directory) {
+            if (++entries > MAX_ENTRIES)
+                throw audioError('audio_build_budget_exceeded', 422);
+            if (depth === 3) {
+                if (entry.name === 'manifest.json') {
+                    if (!entry.isFile() || entry.isSymbolicLink())
+                        throw audioError('audio_program_package_invalid', 422);
+                    if (found.length >= MAX_PACKAGES)
+                        throw audioError('audio_build_budget_exceeded', 422);
+                    found.push(`${path}/manifest.json`);
+                }
+            }
+            else if (HASH.test(entry.name)) {
+                if (!entry.isDirectory() || entry.isSymbolicLink())
+                    throw audioError('audio_program_package_invalid', 422);
+                await visit(`${path}/${entry.name}`, depth + 1);
+            }
+        }
+    };
+    await visit('dist/audio/programs', 0);
+    return found.sort();
+}
+async function currentSource(root, path) {
+    const absolute = await audioProjectPath(root, path);
+    const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+        .catch(error => { if (error.code === 'ENOENT')
+        return undefined; throw error; });
+    if (!handle)
+        return undefined;
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size > 65536)
+            throw audioError('invalid_audio_program', 400);
+        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();
+    }
+}
+/** The authoritative reader verifies the complete program package before any ignored output joins a clone. */
+export async function readAudioProgramBuildInputs(root, destination) {
+    if (destination)
+        await assertAudioProgramBuildClone(root, destination);
+    const packages = [], copied = new Map();
+    let total = 0;
+    const capture = async (path, bytes) => {
+        const contentHash = digest(bytes), old = copied.get(path);
+        if (old && (old.contentHash !== contentHash || old.size !== bytes.length))
+            throw audioError('audio_build_input_changed');
+        if (!old) {
+            if ((total += bytes.length) > MAX_BYTES)
+                throw audioError('audio_build_budget_exceeded', 422);
+            copied.set(path, { contentHash, size: bytes.length });
+            if (destination) {
+                const target = await audioProjectPath(destination, path, true);
+                await ensureSharedDirectory(destination, dirname(target));
+                await writeSharedFile(destination, target, bytes);
+            }
+        }
+        return { path, contentHash, size: bytes.length };
+    };
+    for (const manifestPath of await manifests(root)) {
+        let bundle;
+        try {
+            bundle = await readAudioProgramPackage(root, manifestPath);
+        }
+        catch (error) {
+            throw Object.assign(audioError('audio_program_package_invalid', 422), { details: { manifestPath,
+                    reason: typeof error?.code === 'string' ? error.code : 'validation_failed' } });
+        }
+        const source = await currentSource(root, bundle.sourcePath), files = [];
+        for (const [path, bytes] of [...bundle.files].sort(([a], [b]) => a.localeCompare(b)))
+            files.push(await capture(path, bytes));
+        if (source !== undefined)
+            await capture(bundle.sourcePath, source);
+        packages.push({ manifestPath, sourcePath: bundle.sourcePath, sourceContentHash: bundle.sourceContentHash,
+            currentSourceContentHash: source === undefined ? null : digest(source), semanticHash: bundle.semanticHash,
+            runtimeModulePath: bundle.runtimeModulePath, prerenderModulePath: bundle.prerenderModulePath, files });
+    }
+    return { version: 1, inputHash: digest(canonicalAudioJson(packages)), packages };
+}
+export async function verifyAudioProgramBuildInputs(root, snapshot) {
+    if (snapshot.version !== 1 || digest(canonicalAudioJson(snapshot.packages)) !== snapshot.inputHash
+        || (await readAudioProgramBuildInputs(root)).inputHash !== snapshot.inputHash)
+        throw audioError('audio_build_input_changed');
+}
+export function markAudioProgramBuildInputs(bytes, snapshot) {
+    return snapshot.packages.length ? Buffer.concat([Buffer.from(`<!--playcraft-audio-program-inputs:v1:${snapshot.inputHash}-->\n`), bytes]) : bytes;
+}

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

@@ -0,0 +1,39 @@
+import { createRequire } from 'node:module';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { assertUniqueJsonKeys, audioSha256, AudioRenderError } from '@playcraft/common/cloud-workspace/runtime';
+import { audioRendererScript } from './renderer.js';
+import { audioError, digest } from './storage.js';
+const strip = (text) => text.replace(/^export\s+(?=(?:async\s+)?function\b|const\b|class\b|let\b)/gm, '')
+    .replace(/^\/\/# sourceMappingURL=.*$/gm, '');
+async function body(name, permitted) {
+    const entry = createRequire(import.meta.url).resolve('@playcraft/common/cloud-workspace/runtime');
+    const source = await readFile(join(dirname(entry), name), 'utf8');
+    const pattern = /^import\s+[\s\S]*?\s+from\s+['"]([^'"]+)['"];?\s*$/gm;
+    if ([...source.matchAll(pattern)].some(match => !permitted.includes(match[1])))
+        throw audioError('engine_unavailable', 503);
+    const result = source.replace(pattern, '');
+    if (/^import\s|\bfrom\s+['"]/m.test(result))
+        throw audioError('engine_unavailable', 503);
+    return strip(result);
+}
+/** Only bundled platform code is executable; project dependencies remain validated bytes. */
+export async function audioProgramRendererScript() {
+    const score = await audioRendererScript('score');
+    const document = await body('audio-dynamic-document.js', ['./audio-document.js', './audio-synthesizer.js']);
+    const hybrid = await body('audio-hybrid-player.js', ['./audio-document.js', './audio-synthesizer.js', './score-synthesizer.js', './audio-dynamic-document.js']);
+    const script = `${score.script}\n${audioSha256.toString()}\n${assertUniqueJsonKeys.toString()}\n${document}\n${hybrid}\n` +
+        'globalThis.playcraftAudioProgram={renderAudioDynamicProgram,soundBufferToWav,soundPcmMetrics};';
+    return { script, rendererBuildHash: digest(script) };
+}
+export async function audioProgramGameRuntime() {
+    const { script, rendererBuildHash } = await audioProgramRendererScript();
+    const code = script.replace(/^globalThis\.playcraftAudio(?:Program)?\s*=.*;?$/gm, '') +
+        '\nexport {createAudioHybridPlayer,createStandaloneAudioPlayer,createStandaloneSoundPlayer};\n';
+    return { code, contentHash: digest(code), rendererBuildHash };
+}
+export async function audioProgramPrerenderRuntime() {
+    const player = await body('audio-prerender-player.js', ['./audio-document.js', './audio-synthesizer.js']);
+    const code = `${AudioRenderError.toString()}\n${audioSha256.toString()}\n${player}\nexport {createAudioPrerenderProgramPlayer};\n`;
+    return { code, contentHash: digest(code) };
+}

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

@@ -0,0 +1,289 @@
+import { constants } from 'node:fs';
+import { link, open, rename, rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { dirname, posix } from 'node:path';
+import { AUDIO_DYNAMIC_ENGINE, AUDIO_DYNAMIC_LIMITS, parseAudioDynamicProgram, audioDynamicProgramSemanticHash, canonicalAudioJson, isAudioDynamicProgramPath, readAudioHybridSample, } from '@playcraft/common/cloud-workspace/runtime';
+import { audioProjectPath, audioError, digest } from './storage.js';
+import { readAudioArtifactPackage } from './artifact-package.js';
+import { audioRendererScript } from './renderer.js';
+import { audioProgramGameRuntime, audioProgramPrerenderRuntime } from './program-engine.js';
+import { renderAudioProgramInBrowser } from './program-browser.js';
+import { ensureSharedDirectory, openSharedFile } from '../shared-write.js';
+const MAX_PACKAGE = 64 * 1024 * 1024, MAX_WAV = 16 * 1024 * 1024;
+const json = (value) => Buffer.from(canonicalAudioJson(value) + '\n');
+const validHash = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const fail = () => audioError('invalid_audio_program_package', 400);
+const role = (path, local) => local ? path.endsWith('.json') ? 'source' : 'module'
+    : path.endsWith('.wav') ? 'audio' : path.endsWith('runtime.mjs') ? 'runtime' : path.endsWith('manifest.json') ? 'manifest' : path.endsWith('.json') ? 'source' : 'module';
+function verifyWave(data, frames) {
+    if (data.length !== 44 + frames * 2 || data.toString('ascii', 0, 4) !== 'RIFF' || data.toString('ascii', 8, 12) !== 'WAVE'
+        || data.toString('ascii', 12, 16) !== 'fmt ' || data.toString('ascii', 36, 40) !== 'data' || data.readUInt32LE(4) !== data.length - 8
+        || data.readUInt32LE(16) !== 16 || data.readUInt16LE(20) !== 1 || data.readUInt16LE(22) !== 1 || data.readUInt32LE(24) !== 44100
+        || data.readUInt32LE(28) !== 88200 || data.readUInt16LE(32) !== 2 || data.readUInt16LE(34) !== 16 || data.readUInt32LE(40) !== frames * 2)
+        throw fail();
+    for (let offset = 44; offset < data.length; offset += 2)
+        if (Math.abs(data.readInt16LE(offset) / 32768) > .98005)
+            throw fail();
+}
+export async function readAudioProgramFile(root, path, maximum = MAX_PACKAGE) {
+    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 < 1 || before.size > maximum)
+            throw fail();
+        const data = await handle.readFile(), after = await handle.stat();
+        if (data.length !== before.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+            throw fail();
+        return data;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Project JavaScript is never imported. Synth dependencies must match the bundled platform engine. */
+async function inputs(root, program) {
+    const files = Object.create(null), closure = new Map();
+    for (const asset of program.assets) {
+        if (asset.kind === 'synth') {
+            const artifact = await readAudioArtifactPackage(root, asset.source.path);
+            const directory = posix.dirname(asset.source.path), source = artifact.files.get(asset.source.path);
+            const engine = await audioRendererScript(asset.source.path.endsWith('.pcscore.json') ? 'score' : 'synth-sfx');
+            const suffix = asset.source.path.endsWith('.pcscore.json')
+                ? '\nexport { renderSoundDocument, createStandaloneSoundPlayer };\n'
+                : '\nexport { renderAudioDocument, createStandaloneAudioPlayer };\n';
+            if (!artifact.files.get(`${directory}/runtime.mjs`)?.equals(Buffer.from(engine.script + suffix)))
+                throw audioError('engine_build_mismatch', 409);
+            for (const [path, bytes] of artifact.files)
+                closure.set(path, bytes);
+            files[asset.source.path] = source;
+            files[asset.manifest.path] = artifact.files.get(asset.manifest.path);
+        }
+        else {
+            const data = await readAudioProgramFile(root, asset.file.path, AUDIO_DYNAMIC_LIMITS.sampleBytes);
+            readAudioHybridSample(data);
+            files[asset.file.path] = data;
+            closure.set(asset.file.path, data);
+        }
+    }
+    const refs = program.assets.flatMap(asset => asset.kind === 'synth' ? [asset.source, asset.manifest] : [asset.file]);
+    if (refs.some(ref => !files[ref.path] || files[ref.path].length !== ref.size || digest(files[ref.path]) !== ref.contentHash))
+        throw audioError('audio_dependency_mismatch', 409);
+    if (Object.values(files).reduce((sum, bytes) => sum + bytes.length, 0) > AUDIO_DYNAMIC_LIMITS.inputBytes)
+        throw audioError('audio_program_budget_exceeded', 400);
+    return { files, closure };
+}
+function descriptor(program, states) {
+    return { semanticHash: audioDynamicProgramSemanticHash(program), transition: program.transition,
+        initialState: program.initialState, states: states.map(({ id, durationSeconds, path, contentHash, size }) => ({ id, durationSeconds, path, contentHash, size })) };
+}
+function moduleText(directory, runtimePath, factory, configuration, files) {
+    let importPath = posix.relative(directory, runtimePath);
+    if (!importPath.startsWith('.'))
+        importPath = './' + importPath;
+    const encoded = Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b)).map(([path, data]) => [path, Buffer.from(data).toString('base64')]));
+    return Buffer.from(`import {${factory}} from ${JSON.stringify(importPath)};\nconst configuration=${JSON.stringify(configuration)};\nconst encoded=${JSON.stringify(encoded)};\n` +
+        'function dependencies(){return Object.fromEntries(Object.entries(encoded).map(([path,text])=>[path,Uint8Array.from(atob(text),character=>character.charCodeAt(0))]));}\n' +
+        `export const semanticHash=${JSON.stringify(configuration.semanticHash ?? audioDynamicProgramSemanticHash(configuration))};\n` +
+        'export function createSound(context){if(!context){const key=Symbol.for("playcraft.audio.context.v1");context=globalThis[key];if(!context||context.state==="closed"){const Constructor=globalThis.AudioContext||globalThis.webkitAudioContext;if(!Constructor)throw new Error("audio_context_unavailable");context=globalThis[key]=new Constructor();}}' +
+        `return Object.assign(${factory}(context,configuration,dependencies()),{representation:${JSON.stringify(factory === 'createAudioHybridPlayer'
+            ? 'playcraft.audio-program.runtime.v1' : 'playcraft.audio-program.prerender.v1')}});}\n`);
+}
+async function representations(program, files, states, directory) {
+    const runtime = await audioProgramGameRuntime(), prerender = await audioProgramPrerenderRuntime();
+    const runtimePath = `dist/audio/shared/${runtime.contentHash}/runtime.mjs`;
+    const prerenderPath = `dist/audio/shared/${prerender.contentHash}/runtime.mjs`;
+    return { runtime, prerender, runtimePath, prerenderPath,
+        module: moduleText(directory, runtimePath, 'createAudioHybridPlayer', program, files),
+        prerenderModule: (waves) => moduleText(directory, prerenderPath, 'createAudioPrerenderProgramPlayer', descriptor(program, states), waves) };
+}
+function member(path, data, role, local) {
+    return { path, contentHash: digest(data), size: data.length, role, local };
+}
+function paths(directory, manifest, runtimePath, prerenderPath) {
+    const toFull = (file) => ({ path: file.local ? `${directory}/${file.path}` : file.path,
+        contentHash: file.contentHash, size: file.size, role: file.role });
+    const runtime = manifest.files.filter(file => file.local && file.path === 'program.mjs' || !file.local && file.path === runtimePath).map(toFull);
+    const prerender = manifest.files.filter(file => file.local && file.path === 'prerender.mjs' || !file.local && file.path === prerenderPath).map(toFull);
+    return { runtimeModulePath: `${directory}/program.mjs`, prerenderModulePath: `${directory}/prerender.mjs`, runtimeMembers: runtime, prerenderMembers: prerender };
+}
+/** Compile a separate advanced state program without changing any existing sound revision. */
+export async function compileAudioProgram(root, sourcePath, signal) {
+    if (!isAudioDynamicProgramPath(sourcePath) || sourcePath.startsWith('dist/'))
+        throw audioError('invalid_audio_path', 400);
+    const sourceBytes = await readAudioProgramFile(root, sourcePath, 65536), program = parseAudioDynamicProgram(sourceBytes);
+    if (program.states.reduce((sum, state) => sum + Math.ceil(state.durationSeconds * 44100) * 2 + 44, 0) > MAX_WAV)
+        throw audioError('audio_program_budget_exceeded', 400);
+    const { files: inputFiles, closure } = await inputs(root, program), states = [], waves = {};
+    const game = await audioProgramGameRuntime();
+    for (const state of program.states) {
+        const result = await renderAudioProgramInBrowser(program, inputFiles, state.id, signal);
+        if (result.rendererBuildHash !== game.rendererBuildHash)
+            throw audioError('engine_build_mismatch', 409);
+        const contentHash = digest(result.wav), path = `dist/audio/shared/${contentHash}/state.wav`;
+        waves[path] = result.wav;
+        states.push({ id: state.id, durationSeconds: state.durationSeconds, path, contentHash,
+            size: result.wav.length, pcmContentHash: result.pcmContentHash, chromiumVersion: result.chromiumVersion, frames: result.metrics.frames });
+    }
+    const sourceContentHash = digest(sourceBytes), parent = `dist/audio/programs/${digest(sourcePath)}/${sourceContentHash}`;
+    const placeholder = `${parent}/${'0'.repeat(64)}`;
+    const variants = await representations(program, inputFiles, states, placeholder);
+    const local = new Map([['program.pcaudioprogram.json', sourceBytes], ['program.mjs', variants.module], ['prerender.mjs', variants.prerenderModule(waves)]]);
+    const external = new Map(closure);
+    external.set(variants.runtimePath, Buffer.from(variants.runtime.code));
+    external.set(variants.prerenderPath, Buffer.from(variants.prerender.code));
+    for (const [path, bytes] of Object.entries(waves))
+        external.set(path, Buffer.from(bytes));
+    if ([...external.values(), ...local.values()].reduce((sum, data) => sum + data.length, 0) > MAX_PACKAGE)
+        throw audioError('audio_program_budget_exceeded', 400);
+    const members = [...local].map(([path, data]) => member(path, data, role(path, true), true))
+        .concat([...external].map(([path, data]) => member(path, data, role(path, false), false)))
+        .sort((a, b) => a.path.localeCompare(b.path));
+    const payload = { format: 'playcraft.audio-program-package', version: 1, sourcePath, sourceContentHash,
+        semanticHash: audioDynamicProgramSemanticHash(program), engine: AUDIO_DYNAMIC_ENGINE, rendererBuildHash: game.rendererBuildHash, states, files: members };
+    const manifest = { ...payload, representationSetHash: digest(json(payload)) };
+    const directory = `${parent}/${manifest.representationSetHash}`;
+    if (!sourceBytes.equals(await readAudioProgramFile(root, sourcePath, 65536)))
+        throw audioError('audio_revision_conflict', 409);
+    // Shared content is immutable. Exclusive writes never replace another package's bytes.
+    for (const [path, bytes] of external)
+        await immutable(root, path, bytes);
+    const target = await audioProjectPath(root, directory, true);
+    const stagingPath = `${parent}/stage-${randomUUID()}`, staging = await audioProjectPath(root, stagingPath);
+    await ensureSharedDirectory(root, staging);
+    try {
+        for (const [path, bytes] of [...local, ['manifest.json', json(manifest)]])
+            await immutable(root, `${stagingPath}/${path}`, bytes);
+        try {
+            await rename(staging, target);
+        }
+        catch (error) {
+            if (!['EEXIST', 'ENOTEMPTY'].includes(error.code ?? ''))
+                throw error;
+            await readAudioProgramPackage(root, `${directory}/manifest.json`);
+        }
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+    return readAudioProgramPackage(root, `${directory}/manifest.json`);
+}
+async function immutable(root, path, data) {
+    const target = await audioProjectPath(root, path, true);
+    await ensureSharedDirectory(root, dirname(target));
+    const existing = await readAudioProgramFile(root, path).catch(error => { if (error.code === 'ENOENT')
+        return undefined; throw error; });
+    if (existing) {
+        if (!existing.equals(data))
+            throw audioError('audio_package_conflict', 409);
+        return;
+    }
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    let collided = false;
+    try {
+        const handle = await openSharedFile(root, temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW);
+        try {
+            await handle.writeFile(data);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        // An exclusive hard-link publishes complete bytes without replacing a concurrent writer.
+        try {
+            await link(temporary, target);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            collided = true;
+        }
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    if (collided && !(await readAudioProgramFile(root, path)).equals(data))
+        throw audioError('audio_package_conflict', 409);
+    const parent = await open(dirname(target), 'r');
+    try {
+        await parent.sync();
+    }
+    finally {
+        await parent.close();
+    }
+}
+/** Verify every byte and regenerate both fixed module templates before a build can use them. */
+export async function readAudioProgramPackage(root, manifestPath) {
+    if (!/^dist\/audio\/programs\/[a-f0-9]{64}\/[a-f0-9]{64}\/[a-f0-9]{64}\/manifest\.json$/.test(manifestPath))
+        throw fail();
+    const manifestBytes = await readAudioProgramFile(root, manifestPath, 65536);
+    let manifest;
+    try {
+        manifest = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(manifestBytes));
+    }
+    catch {
+        throw fail();
+    }
+    if (!manifest || Array.isArray(manifest) || Object.keys(manifest).sort().join(',') !== 'engine,files,format,rendererBuildHash,representationSetHash,semanticHash,sourceContentHash,sourcePath,states,version'
+        || manifest.format !== 'playcraft.audio-program-package' || manifest.version !== 1 || !validHash(manifest.sourceContentHash)
+        || !validHash(manifest.semanticHash) || !validHash(manifest.rendererBuildHash) || !validHash(manifest.representationSetHash)
+        || typeof manifest.sourcePath !== 'string' || !isAudioDynamicProgramPath(manifest.sourcePath) || manifest.sourcePath.startsWith('dist/')
+        || canonicalAudioJson(manifest.engine) !== canonicalAudioJson(AUDIO_DYNAMIC_ENGINE) || !Array.isArray(manifest.files) || manifest.files.length > 80
+        || !Array.isArray(manifest.states) || manifest.states.length < 1 || manifest.states.length > 16 || !manifestBytes.equals(json(manifest)))
+        throw fail();
+    const { representationSetHash, ...payload } = manifest, directory = posix.dirname(manifestPath);
+    if (digest(json(payload)) !== representationSetHash || directory !== `dist/audio/programs/${digest(manifest.sourcePath)}/${manifest.sourceContentHash}/${representationSetHash}`)
+        throw fail();
+    const files = new Map(), localNames = new Set(['program.pcaudioprogram.json', 'program.mjs', 'prerender.mjs']);
+    let total = 0;
+    for (const file of manifest.files) {
+        if (!file || Object.keys(file).sort().join(',') !== 'contentHash,local,path,role,size' || !validHash(file.contentHash)
+            || typeof file.path !== 'string' || typeof file.local !== 'boolean' || !Number.isSafeInteger(file.size) || file.size < 1
+            || file.size > MAX_PACKAGE || file.role !== role(file.path, file.local)
+            || (total += file.size) > MAX_PACKAGE || file.local && !localNames.delete(file.path)
+            || !file.local && !file.path.startsWith('dist/audio/'))
+            throw fail();
+        const path = file.local ? `${directory}/${file.path}` : file.path;
+        if (files.has(path))
+            throw fail();
+        const data = await readAudioProgramFile(root, path, file.size);
+        if (data.length !== file.size || digest(data) !== file.contentHash)
+            throw fail();
+        files.set(path, data);
+    }
+    if (localNames.size)
+        throw fail();
+    const source = files.get(`${directory}/program.pcaudioprogram.json`), program = parseAudioDynamicProgram(source);
+    if (digest(source) !== manifest.sourceContentHash || audioDynamicProgramSemanticHash(program) !== manifest.semanticHash
+        || manifest.states.length !== program.states.length || manifest.states.reduce((sum, state) => sum + state.size, 0) > MAX_WAV)
+        throw fail();
+    const dependencies = await inputs(root, program), waves = {};
+    for (let i = 0; i < program.states.length; i++) {
+        const state = manifest.states[i], expected = program.states[i];
+        if (!state || Object.keys(state).sort().join(',') !== 'chromiumVersion,contentHash,durationSeconds,frames,id,path,pcmContentHash,size'
+            || state.id !== expected.id || state.durationSeconds !== expected.durationSeconds || state.frames !== Math.ceil(expected.durationSeconds * 44100)
+            || !validHash(state.contentHash) || !validHash(state.pcmContentHash) || state.path !== `dist/audio/shared/${state.contentHash}/state.wav`
+            || state.size !== 44 + state.frames * 2 || typeof state.chromiumVersion !== 'string' || !state.chromiumVersion || state.chromiumVersion.length > 128)
+            throw fail();
+        const wave = files.get(state.path);
+        if (!wave || wave.length !== state.size || digest(wave) !== state.contentHash)
+            throw fail();
+        verifyWave(wave, state.frames);
+        waves[state.path] = wave;
+    }
+    const variants = await representations(program, dependencies.files, manifest.states, directory);
+    if (variants.runtime.rendererBuildHash !== manifest.rendererBuildHash || !files.get(variants.runtimePath)?.equals(Buffer.from(variants.runtime.code))
+        || !files.get(variants.prerenderPath)?.equals(Buffer.from(variants.prerender.code)) || !files.get(`${directory}/program.mjs`)?.equals(variants.module)
+        || !files.get(`${directory}/prerender.mjs`)?.equals(variants.prerenderModule(waves)))
+        throw audioError('engine_build_mismatch', 409);
+    const expected = new Map(dependencies.closure);
+    expected.set(variants.runtimePath, Buffer.from(variants.runtime.code));
+    expected.set(variants.prerenderPath, Buffer.from(variants.prerender.code));
+    for (const [path, data] of Object.entries(waves))
+        expected.set(path, Buffer.from(data));
+    const external = manifest.files.filter(file => !file.local);
+    if (external.length !== expected.size || external.some(file => !expected.get(file.path)?.equals(files.get(file.path))))
+        throw fail();
+    files.set(manifestPath, manifestBytes);
+    return { manifest, manifestPath, sourcePath: manifest.sourcePath, sourceContentHash: manifest.sourceContentHash,
+        semanticHash: manifest.semanticHash, rendererBuildHash: manifest.rendererBuildHash, program, files, ...paths(directory, manifest, variants.runtimePath, variants.prerenderPath) };
+}