@playcraft/cli 0.1.66 → 0.1.68

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) };
+}

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' };
+}