@playcraft/cli 0.1.66 → 0.1.68

package/dist/workspace-runtime/workspaces/artifact-files.js

@@ -2,22 +2,27 @@ import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { lstat, mkdir, open, readFile, realpath, link, unlink } from 'node:fs/promises';
 import { extname, join, posix, resolve, sep } from 'node:path';
-import { WORKSPACE_ARTIFACT_MAX_BYTES, isWorkspaceArtifactOutputPath, workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { WORKSPACE_ARTIFACT_MAX_BYTES, isWorkspaceArtifactOutputPath, workspaceRelativePathSchema, isSoundDocumentPath } from '@playcraft/common/cloud-workspace/runtime';
 import { openSharedFile } from './shared-write.js';
+import { audioArtifactResources } from './audio-assets/artifact-package.js';
 const formats = {
     '.png': ['image', 'image/png'], '.jpg': ['image', 'image/jpeg'], '.jpeg': ['image', 'image/jpeg'],
     '.webp': ['image', 'image/webp'], '.gif': ['image', 'image/gif'], '.avif': ['image', 'image/avif'], '.svg': ['image', 'image/svg+xml'],
     '.hdr': ['image', 'image/vnd.radiance'], '.exr': ['image', 'image/x-exr'],
     '.ktx': ['image', 'image/ktx'], '.ktx2': ['image', 'image/ktx2'], '.dds': ['image', 'image/vnd-ms.dds'],
     '.mp4': ['video', 'video/mp4'], '.webm': ['video', 'video/webm'], '.mov': ['video', 'video/quicktime'],
-    '.mp3': ['audio', 'audio/mpeg'], '.wav': ['audio', 'audio/wav'], '.ogg': ['audio', 'audio/ogg'], '.m4a': ['audio', 'audio/mp4'], '.flac': ['audio', 'audio/flac'],
+    '.mp3': ['audio', 'audio/mpeg'], '.wav': ['audio', 'audio/wav'], '.ogg': ['audio', 'audio/ogg'], '.opus': ['audio', 'audio/ogg'], '.m4a': ['audio', 'audio/mp4'], '.flac': ['audio', 'audio/flac'],
     '.glb': ['model', 'model/gltf-binary'], '.gltf': ['model', 'model/gltf+json'], '.obj': ['model', 'text/plain'], '.fbx': ['model', 'application/octet-stream'], '.stl': ['model', 'model/stl'], '.usdz': ['model', 'model/vnd.usdz+zip'],
     '.md': ['document', 'text/markdown'], '.txt': ['document', 'text/plain'], '.pdf': ['document', 'application/pdf'],
     '.html': ['document', 'text/html'], '.csv': ['document', 'text/csv'], '.docx': ['document', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
     '.pptx': ['document', 'application/vnd.openxmlformats-officedocument.presentationml.presentation'], '.xlsx': ['document', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
     '.zip': ['file', 'application/zip'],
 };
-export function artifactFormat(path) { return formats[extname(path).toLowerCase()]; }
+export function artifactFormat(path) {
+    if (isSoundDocumentPath(path))
+        return ['audio', 'application/json'];
+    return formats[extname(path).toLowerCase()];
+}
 export function artifactMime(path) { return artifactFormat(path)?.[1] ?? 'application/octet-stream'; }
 /** Reject every redirected path segment, including links that happen to remain in the workspace. */
 export async function artifactPath(root, path) {
@@ -152,6 +157,8 @@ async function binaryModelDocument(root, path) {
 }
 /** Only explicit model references become members; neighboring names never imply a relationship. */
 export async function artifactResources(root, path) {
+    if (isSoundDocumentPath(path))
+        return audioArtifactResources(root, path);
     const resources = new Set();
     const add = (from, uri) => { const result = resourcePath(from, uri); if (result)
         resources.add(result); };

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

@@ -1,18 +1,23 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { lstat, mkdir, open, readdir, rename, unlink } from 'node:fs/promises';
-import { basename, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import sharp from 'sharp';
-import { WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, isWorkspaceArtifactOutputPath, isWorkspaceArtifactOutputVersion, workspaceArtifactContentQuerySchema, workspaceArtifactListSchema, workspaceModelBuildSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, isWorkspaceArtifactOutputPath, isWorkspaceArtifactOutputVersion, workspaceArtifactContentQuerySchema, workspaceArtifactListSchema, isSoundDocumentPath, workspaceModelBuildSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { artifactBundleDigest, artifactDirectory, artifactFormat, artifactPath, artifactResources, snapshotArtifactBundle, snapshotArtifactFile } from './artifact-files.js';
 import { ARTIFACT_RECEIPTS_DIRECTORY, readArtifactReceipt } from './artifact-receipts.js';
 import { ensureSharedDirectory } from './shared-write.js';
 import { validateWorkspacePlayable } from '../previews/finalize.js';
 import { PREVIEW_HTML_MAX_BYTES, WORKSPACE_PLAYABLE_OUTPUT_PATH } from '@playcraft/common/cloud-workspace/runtime';
 import { applyWorkspaceModelBuildStates, sameWorkspaceModelBuild } from './model-build-inputs.js';
+import { audioArtifactDetails, validateAudioArtifactVersion } from './audio-assets/artifact-package.js';
+import { readAudioSource } from './audio-assets/storage.js';
 const serial = new Map();
 function digest(text) { return createHash('sha256').update(text).digest('hex'); }
-function artifactId(workspaceId, path) { return `artifact_${digest(`${workspaceId}\0${path}`).slice(0, 40)}`; }
+function artifactId(workspaceId, path) {
+    const audioKey = /^dist\/audio\/([a-f0-9]{64})\/[a-f0-9]{64}\/[a-f0-9]{64}\/sound\.(?:pcaudio|pcscore)\.json$/.exec(path)?.[1];
+    return `artifact_${digest(`${workspaceId}\0${audioKey ? `audio-source:${audioKey}` : path}`).slice(0, 40)}`;
+}
 function outputArtifacts(artifacts) {
     return artifacts.flatMap(artifact => {
         const versions = artifact.versions.filter(isWorkspaceArtifactOutputVersion);
@@ -152,10 +157,34 @@ export class WorkspaceArtifactStore {
             catch { /* An incomplete receipt stays pending; the next scan retries its original bytes. */ }
         }
         const candidates = await discoverPaths(root);
-        // Models are inspected before images so their explicitly referenced textures stay under the model.
-        candidates.sort((a, b) => Number(artifactFormat(b)?.[0] === 'model') - Number(artifactFormat(a)?.[0] === 'model') || a.localeCompare(b));
+        // Compound sounds and models claim their explicitly listed resources before standalone media.
+        const priority = (path) => isSoundDocumentPath(path) ? 2 : Number(artifactFormat(path)?.[0] === 'model');
+        candidates.sort((a, b) => priority(b) - priority(a) || a.localeCompare(b));
         const visible = outputArtifacts(catalog.artifacts);
         const members = new Set(visible.flatMap(artifact => artifact.versions.flatMap(version => version.files.filter(file => file.role !== 'primary').map(file => file.path))));
+        const audioMembers = new Set();
+        const currentAudio = new Set();
+        for (const path of candidates.filter(isSoundDocumentPath)) {
+            try {
+                const details = await audioArtifactDetails(root, path);
+                for (const member of details.resources) {
+                    members.add(member);
+                    audioMembers.add(member);
+                }
+                const source = await readAudioSource(root, details.sourcePath).catch(() => undefined);
+                if (source !== undefined && digest(source) === details.sourceContentHash)
+                    currentAudio.add(path);
+            }
+            catch {
+                // An incomplete sound package stays visible as ordinary files, never as a standalone audio fallback.
+                for (const candidate of candidates.filter(value => dirname(value) === dirname(path))) {
+                    members.add(candidate);
+                    if (candidate !== path)
+                        audioMembers.add(candidate);
+                }
+            }
+        }
+        candidates.sort((a, b) => priority(b) - priority(a) || Number(currentAudio.has(a)) - Number(currentAudio.has(b)) || a.localeCompare(b));
         for (const path of candidates) {
             if (members.has(path))
                 continue;
@@ -165,7 +194,9 @@ export class WorkspaceArtifactStore {
                 continue;
             try {
                 const current = visible.find(artifact => artifact.id === artifactId(this.scopeId, path));
-                const version = current?.versions.find(entry => entry.id === current.currentVersionId);
+                const version = isSoundDocumentPath(path)
+                    ? current?.versions.find(entry => entry.path === path && entry.id === catalog.observations[path]?.versionId) ?? current?.versions.find(entry => entry.path === path)
+                    : current?.versions.find(entry => entry.id === current.currentVersionId);
                 const knownWrite = sourcePaths.includes(path) && Boolean(source.operationId) && version?.source.operationId !== source.operationId;
                 const observation = catalog.observations[path];
                 if (!knownWrite && version && (path !== WORKSPACE_PLAYABLE_OUTPUT_PATH || current?.kind === 'playable')
@@ -229,6 +260,8 @@ export class WorkspaceArtifactStore {
         }
         catalog.artifacts = catalog.artifacts.filter(artifact => {
             const current = artifact.versions.find(version => version.id === artifact.currentVersionId);
+            if (audioMembers.has(current.path))
+                return false;
             return !isWorkspaceArtifactOutputVersion(current) || current.source.kind !== 'discovered' || !members.has(current.path);
         });
         catalog.artifacts.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id));
@@ -238,6 +271,10 @@ export class WorkspaceArtifactStore {
         return { list, changed: original !== JSON.stringify(list.artifacts) };
     }
     async versionKind(objects, version) {
+        if (isSoundDocumentPath(version.path)) {
+            await validateAudioArtifactVersion(objects, version.path, version.files);
+            return 'audio';
+        }
         if (version.path !== WORKSPACE_PLAYABLE_OUTPUT_PATH)
             return artifactFormat(version.path)[0];
         if (version.files.length !== 1)
@@ -260,11 +297,15 @@ export class WorkspaceArtifactStore {
     }
     async add(catalog, version, kind, objects) {
         const id = artifactId(this.scopeId, version.path);
+        const audioName = kind === 'audio' && isSoundDocumentPath(version.path)
+            ? (await validateAudioArtifactVersion(objects, version.path, version.files)).name : undefined;
         let artifact = catalog.artifacts.find(item => item.id === id);
         if (!artifact) {
             artifact = { id, kind, name: basename(version.path), currentVersionId: version.id, updatedAt: version.createdAt, versions: [] };
             catalog.artifacts.push(artifact);
         }
+        if (audioName)
+            artifact.name = audioName;
         if (kind === 'playable' && artifact.kind !== 'playable') {
             const valid = await Promise.all(artifact.versions.map(async (item) => {
                 try {

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/artifact-package.js

@@ -0,0 +1,104 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { posix } from 'node:path';
+import { parseSoundDocument, soundSourceRenderHash, audioRepresentationSetHash, canonicalAudioJson, isSoundDocumentPath, workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { audioProjectPath, audioError, digest } from './storage.js';
+const hash = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+async function bytes(root, path, maximum) {
+    const file = await open(await audioProjectPath(root, path), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const before = await file.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size > maximum)
+            throw audioError('invalid_audio_package', 400);
+        const result = await file.readFile(), after = await file.stat();
+        if (result.length !== before.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+            throw audioError('invalid_audio_package', 400);
+        return result;
+    }
+    finally {
+        await file.close();
+    }
+}
+/** A source alone is editable; only a fully verified manifest can identify a delivered sound bundle. */
+export async function audioArtifactResources(root, primaryPath) {
+    return (await audioArtifactDetails(root, primaryPath)).resources;
+}
+export async function audioArtifactDetails(root, primaryPath) {
+    return inspectPackage(primaryPath, (path, maximum) => bytes(root, path, maximum));
+}
+/** Build snapshots retain the exact verified bytes, avoiding a second unverified file read. */
+export async function readAudioArtifactPackage(root, primaryPath) {
+    const files = new Map();
+    const details = await inspectPackage(primaryPath, async (path, maximum) => {
+        const data = await bytes(root, path, maximum);
+        files.set(path, data);
+        return data;
+    });
+    return { ...details, files };
+}
+export async function validateAudioArtifactVersion(objects, primaryPath, files) {
+    if (files.length !== 5 || new Set(files.map(file => file.path)).size !== files.length ||
+        files.filter(file => file.role === 'primary').length !== 1 || !files.some(file => file.path === primaryPath && file.role === 'primary'))
+        throw audioError('invalid_audio_package', 400);
+    return inspectPackage(primaryPath, async (path, maximum) => {
+        const record = files.find(file => file.path === path);
+        if (!record || !hash(record.sha256))
+            throw audioError('invalid_audio_package', 400);
+        const result = await bytes(objects, record.sha256, maximum);
+        if (result.length !== record.size || digest(result) !== record.sha256)
+            throw audioError('invalid_audio_package', 400);
+        return result;
+    });
+}
+async function inspectPackage(primaryPath, read) {
+    const sourceBytes = await read(primaryPath, 65536), document = parseSoundDocument(sourceBytes);
+    const sourceName = document.format === 'playcraft.score' ? 'sound.pcscore.json' : 'sound.pcaudio.json';
+    const directory = posix.dirname(primaryPath), manifestPath = `${directory}/manifest.json`;
+    const manifestBytes = await read(manifestPath, 65536);
+    let manifest;
+    try {
+        manifest = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(manifestBytes));
+    }
+    catch {
+        throw audioError('invalid_audio_package', 400);
+    }
+    const allowed = ['version', 'sourcePath', 'sourceContentHash', 'sourceRenderHash', 'engine', 'rendererBuildHash', 'chromiumVersion',
+        'renderKey', 'pcmContentHash', 'files', 'representationSetHash'];
+    if (!manifest || Array.isArray(manifest) || Object.keys(manifest).length !== allowed.length || Object.keys(manifest).some(key => !allowed.includes(key)) ||
+        manifest.version !== 1 || !hash(manifest.sourceContentHash) || manifest.sourceContentHash !== digest(sourceBytes) ||
+        manifest.sourceRenderHash !== soundSourceRenderHash(document) || canonicalAudioJson(manifest.engine) !== canonicalAudioJson(document.engine) ||
+        !hash(manifest.rendererBuildHash) || !hash(manifest.renderKey) || !hash(manifest.pcmContentHash) ||
+        typeof manifest.chromiumVersion !== 'string' || !manifest.chromiumVersion || manifest.chromiumVersion.length > 128 ||
+        typeof manifest.sourcePath !== 'string' || !isSoundDocumentPath(manifest.sourcePath) ||
+        !manifest.sourcePath.endsWith(document.format === 'playcraft.score' ? '.pcscore.json' : '.pcaudio.json') ||
+        !workspaceRelativePathSchema.safeParse(manifest.sourcePath).success || manifest.sourcePath.split('/').some(part => ['.git', '.playcraft', 'node_modules'].includes(part)) ||
+        !hash(manifest.representationSetHash) || !Array.isArray(manifest.files) || manifest.files.length !== 4)
+        throw audioError('invalid_audio_package', 400);
+    if (digest(manifestBytes) !== digest(`${canonicalAudioJson(manifest)}\n`))
+        throw audioError('invalid_audio_package', 400);
+    const { representationSetHash, ...payload } = manifest;
+    if (audioRepresentationSetHash(payload) !== representationSetHash ||
+        directory !== `dist/audio/${digest(manifest.sourcePath)}/${manifest.sourceContentHash}/${representationSetHash}`)
+        throw audioError('invalid_audio_package', 400);
+    const expected = new Map([[sourceName, ['application/json', 'editable']], ['audition.wav', ['audio/wav', 'audition']],
+        ['runtime.mjs', ['text/javascript', 'runtime']], ['sound.mjs', ['text/javascript', 'delivery']]]);
+    const resources = new Set([manifestPath]);
+    for (const file of manifest.files) {
+        if (!file || Array.isArray(file) || Object.keys(file).sort().join(',') !== 'contentHash,mimeType,path,role,size' ||
+            typeof file.path !== 'string' || !expected.has(file.path) || !hash(file.contentHash) || !Number.isSafeInteger(file.size) ||
+            file.size < 1 || file.size > (document.format === 'playcraft.score' ? 6 * 1024 * 1024 : 2 * 1024 * 1024))
+            throw audioError('invalid_audio_package', 400);
+        const [mimeType, role] = expected.get(file.path);
+        expected.delete(file.path);
+        if (file.mimeType !== mimeType || file.role !== role)
+            throw audioError('invalid_audio_package', 400);
+        const path = `${directory}/${file.path}`, member = await read(path, file.size);
+        if (member.length !== file.size || digest(member) !== file.contentHash)
+            throw audioError('invalid_audio_package', 400);
+        if (path !== primaryPath)
+            resources.add(path);
+    }
+    if (expected.size || !primaryPath.endsWith('/' + sourceName))
+        throw audioError('invalid_audio_package', 400);
+    return { resources: [...resources].sort(), name: document.name, sourcePath: manifest.sourcePath, sourceContentHash: manifest.sourceContentHash };
+}

package/dist/workspace-runtime/workspaces/audio-assets/binding-usage.js

@@ -0,0 +1,71 @@
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { workspaceAudioBindingSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { readAudioArtifactPackage } from './artifact-package.js';
+import { audioProjectPath, digest } from './storage.js';
+const maximumBindingBytes = 16_384;
+/** Observe the tracked public binding without rewriting the source, binding, or private history. */
+export async function readAudioBindingUsage(root, sourcePath, sourceContentHash, history, tracked) {
+    if (!/^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(tracked.eventName))
+        return undefined;
+    const bindingPath = `source/audio-bindings/${tracked.eventName}.json`;
+    const location = { status: 'integration_required', bindingPath, eventName: tracked.eventName };
+    const invalid = { ...location, bindingState: 'invalid' };
+    if (tracked.bindingPath !== bindingPath)
+        return invalid;
+    try {
+        const path = await audioProjectPath(root, tracked.bindingPath);
+        const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        let bytes;
+        try {
+            const before = await file.stat();
+            if (!before.isFile() || before.nlink !== 1 || before.size < 1 || before.size > maximumBindingBytes)
+                return invalid;
+            // Recheck the path after opening, before reading any bytes through the retained descriptor.
+            const named = await lstat(await audioProjectPath(root, tracked.bindingPath));
+            if (named.dev !== before.dev || named.ino !== before.ino)
+                return invalid;
+            const buffer = Buffer.alloc(before.size + 1);
+            const { bytesRead } = await file.read(buffer, 0, buffer.length, 0), after = await file.stat();
+            if (bytesRead !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs)
+                return invalid;
+            bytes = buffer.subarray(0, bytesRead);
+        }
+        finally {
+            await file.close();
+        }
+        const parsed = workspaceAudioBindingSchema.safeParse(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)));
+        if (!parsed.success || parsed.data.eventName !== tracked.eventName)
+            return invalid;
+        const binding = parsed.data;
+        if (binding.sourcePath !== sourcePath)
+            return { ...location, bindingState: 'different_source' };
+        if (!history.some(version => version.revision === binding.revision && version.contentHash === binding.sourceContentHash))
+            return invalid;
+        const directory = `dist/audio/${digest(sourcePath)}/${binding.sourceContentHash}/${binding.representationSetHash}`;
+        if (binding.modulePath !== `${directory}/sound.mjs`)
+            return invalid;
+        const bundle = await readAudioArtifactPackage(root, `${directory}/sound.${sourcePath.endsWith('.pcscore.json') ? 'pcscore' : 'pcaudio'}.json`);
+        const audition = bundle.files.get(`${directory}/audition.wav`);
+        if (bundle.sourcePath !== sourcePath || bundle.sourceContentHash !== binding.sourceContentHash
+            || !audition || digest(audition) !== binding.auditionContentHash)
+            return invalid;
+        return { ...location, bindingState: binding.sourceContentHash === sourceContentHash ? 'current' : 'different_version',
+            sourceContentHash: binding.sourceContentHash, revision: binding.revision, modulePath: binding.modulePath,
+            representationSetHash: binding.representationSetHash,
+            ...(binding.previousBinding ? { previousContentHash: binding.previousBinding } : {}) };
+    }
+    catch (error) {
+        // Only an absent binding is missing; broken package members are invalid bindings.
+        if (error.code === 'ENOENT') {
+            try {
+                await lstat(await audioProjectPath(root, tracked.bindingPath));
+            }
+            catch (missing) {
+                if (missing.code === 'ENOENT')
+                    return { ...location, bindingState: 'missing' };
+            }
+        }
+        return invalid;
+    }
+}

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

@@ -0,0 +1,80 @@
+import { lstat, readdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+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;
+async function packagePaths(root) {
+    const paths = [];
+    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?.isDirectory() || stat.isSymbolicLink())
+            return;
+        if (depth === 3) {
+            if (paths.length >= MAX_PACKAGES)
+                throw audioError('audio_build_budget_exceeded', 422);
+            const names = await readdir(absolute);
+            for (const name of ['sound.pcaudio.json', 'sound.pcscore.json'])
+                if (names.includes(name)) {
+                    if (paths.length >= MAX_PACKAGES)
+                        throw audioError('audio_build_budget_exceeded', 422);
+                    paths.push(`${path}/${name}`);
+                }
+            return;
+        }
+        for (const entry of (await readdir(absolute, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name)))
+            if (entry.isDirectory() && !entry.isSymbolicLink() && hashPart.test(entry.name))
+                await visit(`${path}/${entry.name}`, depth + 1);
+    };
+    await visit('dist/audio', 0);
+    return paths;
+}
+/** Only validated immutable sound packages join source inputs; unrelated dist outputs stay excluded. */
+export async function readAudioBuildInputs(root, destination) {
+    const packages = [];
+    let totalBytes = 0;
+    for (const primaryPath of await packagePaths(root)) {
+        let bundle;
+        try {
+            bundle = await readAudioArtifactPackage(root, primaryPath);
+        }
+        catch {
+            continue;
+        }
+        const sourceText = await readAudioSource(root, bundle.sourcePath);
+        const files = [...bundle.files].map(([path, bytes]) => ({ path, contentHash: digest(bytes) })).sort((a, b) => a.path.localeCompare(b.path));
+        totalBytes += [...bundle.files.values()].reduce((total, bytes) => total + bytes.length, 0) + (sourceText === undefined ? 0 : Buffer.byteLength(sourceText));
+        if (totalBytes > MAX_PACKAGE_BYTES)
+            throw audioError('audio_build_budget_exceeded', 422);
+        if (destination) {
+            for (const [path, bytes] of bundle.files) {
+                const target = await audioProjectPath(destination, path, true);
+                await ensureSharedDirectory(destination, dirname(target));
+                await writeSharedFile(destination, target, bytes);
+            }
+            if (sourceText !== undefined) {
+                const target = await audioProjectPath(destination, bundle.sourcePath, true);
+                await ensureSharedDirectory(destination, dirname(target));
+                await writeSharedFile(destination, target, sourceText);
+            }
+        }
+        packages.push({ primaryPath, sourcePath: bundle.sourcePath, sourceContentHash: sourceText === undefined ? null : digest(sourceText), files });
+    }
+    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 || snapshot.programs?.packages.length ? Buffer.concat([Buffer.from(`<!--playcraft-audio-inputs:v1:${snapshot.inputHash}-->\n`), bytes]) : bytes;
+}