@playcraft/cli 0.1.66 → 0.1.68

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

@@ -0,0 +1,459 @@
+import { readFile } from 'node:fs/promises';
+import { parseSoundDocument, serializeSoundDocument, soundSourceRenderHash, soundDurationSeconds, isSoundDocumentPath, audioRenderKey, canonicalAudioJson, assertAudioProtection, assertScoreProtection, audioReferenceActionSchema, audioReferenceActionReceiptSchema, workspaceAudioBindingSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { writeSharedFile } from '../shared-write.js';
+import { AudioStore, audioError, audioProjectPath, readAudioSource, digest } from './storage.js';
+import { publishAudioRepresentations } from './representations.js';
+import { audioArtifactResources } from './artifact-package.js';
+import { readAudioArtifactPackage } from './artifact-package.js';
+import { createAudioLibrarySnapshot } from './library-package.js';
+import { readImportedAudioLibrarySource } from './library-import.js';
+import { readAudioReferences, readAudioReferenceFile, verifyAudioReference } from './references.js';
+import { writeWorkspaceBinaryFile } from '../binary-write.js';
+import { readAudioBindingUsage } from './binding-usage.js';
+const safeId = (id) => typeof id === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(id);
+const targetId = (target) => target.kind === 'workspace-file' ? `file:${target.path}` : `candidate:${target.taskId}:${target.candidateId}`;
+const summary = (version) => ({ revision: version.revision, contentHash: version.contentHash, createdAt: version.createdAt });
+const publicState = async (record, projectRoot) => {
+    const { sourceText: _text, ...current } = record.current;
+    const usage = record.target.kind === 'workspace-file' && record.usage
+        ? await readAudioBindingUsage(projectRoot, record.target.path, current.contentHash, record.history, record.usage) : undefined;
+    return { version: 1, target: record.target, ...current, history: record.history, ...(usage ? { usage } : {}),
+        ...(record.libraryOrigin ? { libraryOrigin: record.libraryOrigin } : {}),
+        ...(record.representation ? { representation: record.representation } : {}),
+        ...(record.adoptionReceipt ? { adoptionReceipt: record.adoptionReceipt } : {}) };
+};
+/** The transport supplies the workspace write lease; this store preserves source-specific outcomes. */
+export class WorkspaceAudioAssets {
+    projectRoot;
+    scope;
+    options;
+    store;
+    serial = Promise.resolve();
+    constructor(projectRoot, stateRoot, scope, options) {
+        this.projectRoot = projectRoot;
+        this.scope = scope;
+        this.options = options;
+        this.store = new AudioStore(stateRoot, scope);
+    }
+    exclusive(action) {
+        const next = this.serial.catch(() => undefined).then(action);
+        this.serial = next;
+        return next;
+    }
+    validateTarget(target) {
+        if (!target || !['workspace-file', 'generation-candidate'].includes(target.kind))
+            throw audioError('invalid_audio_target', 400);
+        if (target.kind === 'generation-candidate') {
+            if (!safeId(target.taskId) || !safeId(target.candidateId))
+                throw audioError('invalid_audio_target', 400);
+        }
+        else if (!isSoundDocumentPath(target.path ?? ''))
+            throw audioError('unsupported_audio_format', 400);
+        return target;
+    }
+    version(document, revision, sourceText) {
+        const text = sourceText ?? serializeSoundDocument(document);
+        const parsed = parseSoundDocument(text);
+        return { document: parsed, sourceText: text, revision, contentHash: digest(text), sourceRenderHash: soundSourceRenderHash(parsed),
+            createdAt: new Date().toISOString(), renderState: 'pending' };
+    }
+    async saveRecord(record) {
+        const id = targetId(record.target);
+        await this.store.write('versions', `${id}:${record.current.revision}`, record.current);
+        await this.store.write('records', id, record);
+    }
+    async observe(target) {
+        this.validateTarget(target);
+        let record = await this.store.read('records', targetId(target));
+        if (target.kind === 'workspace-file') {
+            const raw = await readAudioSource(this.projectRoot, target.path);
+            if (raw === undefined)
+                throw audioError('audio_source_not_found', 404);
+            if (!record || record.current.contentHash !== digest(raw)) {
+                const version = this.version(undefined, (record?.current.revision ?? 0) + 1, raw);
+                this.checkFormatPath(target.path, version.document);
+                record = { ...record, target, current: version, representation: undefined, adoptionReceipt: undefined,
+                    history: [...(record?.history ?? []), summary(version)] };
+                try {
+                    const imported = await readImportedAudioLibrarySource(this.projectRoot, target.path, version.contentHash);
+                    if (imported) {
+                        record.libraryOrigin = imported.origin;
+                        if (imported.current) {
+                            await this.store.bytes('auditions', imported.current.audition.contentHash, imported.current.wav);
+                            record.current = { ...version, renderState: 'ready', audition: imported.current.audition };
+                            record.representation = imported.current.representation;
+                        }
+                    }
+                }
+                catch (error) {
+                    record.current = { ...version, renderState: 'failed', renderError: error instanceof Error && /^audio_library_/.test(error.message) ? error.message : 'audio_library_dependency_invalid' };
+                }
+                await this.saveRecord(record);
+            }
+        }
+        if (!record)
+            throw audioError('audio_candidate_not_found', 404);
+        if (canonicalAudioJson(record.target) !== canonicalAudioJson(target))
+            throw audioError('invalid_audio_target', 400);
+        return record;
+    }
+    read(target) { return this.exclusive(async () => publicState(await this.observe(target), this.projectRoot)); }
+    references(target) {
+        return this.exclusive(async () => {
+            if (target.kind !== 'workspace-file')
+                throw audioError('invalid_audio_target', 400);
+            const record = await this.observe(target);
+            return readAudioReferences(this.projectRoot, target.path, record.current, record.history, hash => this.previousBinding(hash));
+        });
+    }
+    async previousBinding(hash) {
+        try {
+            return await readFile(this.store.blobPath('bindings', hash));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    }
+    referenceAction(raw) {
+        return this.exclusive(async () => {
+            const input = audioReferenceActionSchema.parse(raw), payloadHash = digest(canonicalAudioJson(input));
+            let intent = await this.store.read('reference-requests', input.requestId);
+            if (intent && intent.payloadHash !== payloadHash)
+                throw audioError('audio_request_conflict');
+            if (intent?.status === 'complete')
+                return audioReferenceActionReceiptSchema.parse(intent.result);
+            const record = await this.observe(input.target), bindingPath = `source/audio-bindings/${input.eventName}.json`;
+            const current = await readAudioReferenceFile(this.projectRoot, bindingPath), currentHash = current ? digest(current) : null;
+            const alreadyWritten = intent?.status === 'pending' && currentHash === digest(Buffer.from(intent.entry, 'base64'));
+            if (!alreadyWritten) {
+                this.expected(record, { action: 'bind', requestId: input.requestId, target: input.target,
+                    expectedRevision: input.expectedRevision, expectedContentHash: input.expectedContentHash });
+                if (currentHash !== input.expectedBindingContentHash)
+                    throw audioError('audio_binding_conflict');
+            }
+            if (!intent) {
+                let bytes;
+                if (input.action === 'replace') {
+                    if (record.current.renderState !== 'ready' || !record.current.audition || !record.representation
+                        || record.representation.sourceContentHash !== record.current.contentHash)
+                        throw audioError('audio_audition_unavailable', 409);
+                    const entry = workspaceAudioBindingSchema.parse({ version: 1, operationId: input.requestId, eventName: input.eventName,
+                        sourcePath: input.target.path, sourceContentHash: record.current.contentHash, revision: record.current.revision,
+                        auditionContentHash: record.current.audition.contentHash, modulePath: record.representation.modulePath,
+                        representationSetHash: record.representation.representationSetHash, integrationStatus: 'integration_required', previousBinding: currentHash });
+                    bytes = Buffer.from(`${canonicalAudioJson(entry)}\n`);
+                    await verifyAudioReference(this.projectRoot, input.target.path, record.history, bytes);
+                }
+                else {
+                    const snapshot = await readAudioReferences(this.projectRoot, input.target.path, record.current, record.history, hash => this.previousBinding(hash));
+                    const tracked = snapshot.references.find(reference => reference.eventName === input.eventName);
+                    if (!tracked?.history.some(version => version.bindingContentHash === input.previousBindingHash))
+                        throw audioError('invalid_audio_binding', 400);
+                    const previous = await this.previousBinding(input.previousBindingHash);
+                    if (!previous || digest(previous) !== input.previousBindingHash)
+                        throw audioError('invalid_audio_binding', 400);
+                    await verifyAudioReference(this.projectRoot, input.target.path, record.history, previous);
+                    bytes = Buffer.from(previous);
+                }
+                if (current)
+                    await this.store.bytes('bindings', currentHash, current);
+                intent = { payloadHash, status: 'pending', beforeHash: currentHash, entry: bytes.toString('base64') };
+                await this.store.write('reference-requests', input.requestId, intent);
+            }
+            const bytes = Buffer.from(intent.entry, 'base64'), binding = await verifyAudioReference(this.projectRoot, input.target.path, record.history, bytes);
+            if (binding.eventName !== input.eventName)
+                throw audioError('invalid_audio_binding', 400);
+            if (!alreadyWritten) {
+                try {
+                    await writeWorkspaceBinaryFile(this.projectRoot, { path: bindingPath, contentBase64: intent.entry, expectedContentHash: intent.beforeHash });
+                }
+                catch (error) {
+                    if (error.code === 'content_conflict')
+                        throw audioError('audio_binding_conflict');
+                    throw error;
+                }
+            }
+            record.usage = { status: 'integration_required', bindingPath, eventName: input.eventName, sourceContentHash: binding.sourceContentHash,
+                ...(binding.previousBinding ? { previousContentHash: binding.previousBinding } : {}) };
+            await this.saveRecord(record);
+            await this.options.onWrite?.(input.target.path, record.current, [bindingPath], input.requestId);
+            const result = audioReferenceActionReceiptSchema.parse({ version: 1, requestId: input.requestId, action: input.action, target: input.target,
+                eventName: input.eventName, bindingPath, bindingContentHash: digest(bytes), sourceContentHash: binding.sourceContentHash,
+                revision: binding.revision, modulePath: binding.modulePath, representationSetHash: binding.representationSetHash, integrationStatus: 'integration_required' });
+            await this.store.write('reference-requests', input.requestId, { ...intent, status: 'complete', result });
+            return result;
+        });
+    }
+    librarySnapshot(target, revision, contentHash) {
+        return this.exclusive(async () => {
+            const record = await this.observe(target), version = record.current;
+            if (version.revision !== revision || version.contentHash !== contentHash)
+                throw audioError('audio_revision_conflict');
+            if (version.renderState !== 'ready' || !version.audition)
+                throw audioError('audio_audition_unavailable', 404);
+            const sourcePath = target.kind === 'workspace-file' ? target.path
+                : `source/audio/${target.candidateId}.${version.document.format === 'playcraft.score' ? 'pcscore' : 'pcaudio'}.json`;
+            if (record.representation?.sourceContentHash === contentHash) {
+                const entry = `${record.representation.modulePath.slice(0, -'sound.mjs'.length)}sound.${version.document.format === 'playcraft.score' ? 'pcscore' : 'pcaudio'}.json`;
+                const packaged = await readAudioArtifactPackage(this.projectRoot, entry);
+                const files = [...packaged.files].map(([path, bytes]) => ({ path: path.slice(path.lastIndexOf('/') + 1),
+                    mimeType: path.endsWith('.wav') ? 'audio/wav' : path.endsWith('.mjs') ? 'text/javascript' : 'application/json',
+                    size: bytes.length, contentHash: digest(bytes), content: bytes.toString('base64') }));
+                return { version: 1, target, revision, sourcePath, files };
+            }
+            const wav = await readFile(this.store.blobPath('auditions', version.audition.contentHash));
+            if (digest(wav) !== version.audition.contentHash || wav.length !== version.audition.size)
+                throw audioError('audio_audition_unavailable', 404);
+            return createAudioLibrarySnapshot({ target, revision, sourcePath, document: version.document, sourceText: version.sourceText,
+                contentHash, sourceRenderHash: version.sourceRenderHash, audition: version.audition, wav });
+        });
+    }
+    async content(target, revision, representation = 'audition') {
+        const record = await this.observe(target), version = revision === undefined || revision === record.current.revision ? record.current :
+            await this.store.read('versions', `${targetId(target)}:${revision}`);
+        if (!version)
+            throw audioError('audio_version_not_found', 404);
+        if (representation === 'source')
+            return { bytes: Buffer.from(version.sourceText), mimeType: 'application/json', contentHash: version.contentHash };
+        if (!version?.audition || version.renderState !== 'ready')
+            throw audioError('audio_audition_unavailable', 404);
+        const bytes = await readFile(this.store.blobPath('auditions', version.audition.contentHash));
+        if (digest(bytes) !== version.audition.contentHash || bytes.length !== version.audition.size)
+            throw audioError('audio_audition_unavailable', 404);
+        return { bytes, mimeType: version.audition.mimeType, contentHash: version.audition.contentHash };
+    }
+    expected(record, action) {
+        if (record.current.revision !== action.expectedRevision || record.current.contentHash !== action.expectedContentHash)
+            throw audioError('audio_revision_conflict');
+    }
+    checkFormatPath(path, document) {
+        if (!path.endsWith(document.format === 'playcraft.score' ? '.pcscore.json' : '.pcaudio.json'))
+            throw audioError('unsupported_audio_format', 400);
+    }
+    checkProtection(previous, next, action) {
+        if (previous.format !== next.format)
+            throw audioError('unsupported_content_kind', 400);
+        if (previous.format === 'playcraft.score' && next.format === 'playcraft.score') {
+            const protection = action.protection;
+            if (protection && ('lockedVoiceIds' in protection || 'preserveTargets' in protection))
+                throw audioError('invalid_audio_target', 400);
+            assertScoreProtection(previous, next, protection);
+        }
+        else if (previous.format === 'playcraft.audio' && next.format === 'playcraft.audio') {
+            const protection = action.protection;
+            if (protection && ('lockedTrackIds' in protection || 'preserveMelody' in protection || 'selection' in protection))
+                throw audioError('invalid_audio_target', 400);
+            assertAudioProtection(previous, next, protection);
+        }
+    }
+    async action(input, signal) {
+        if (!safeId(input.requestId))
+            throw audioError('invalid_audio_request', 400);
+        return this.exclusive(async () => {
+            const payloadHash = digest(canonicalAudioJson(input)), known = await this.store.read('requests', input.requestId);
+            if (known && known.payloadHash !== payloadHash)
+                throw audioError('idempotency_conflict');
+            if (known?.status === 'complete' && known.result)
+                return known.result;
+            if (known?.transaction)
+                return this.recover(input.requestId, known);
+            if (known?.candidateRecord) {
+                const current = await this.store.read('records', targetId(known.candidateRecord.target));
+                if (current && current.current.revision > known.candidateRecord.current.revision)
+                    throw audioError('audio_revision_conflict');
+                await this.saveRecord(known.candidateRecord);
+                const result = await publicState(known.candidateRecord, this.projectRoot);
+                await this.store.write('requests', input.requestId, { payloadHash, status: 'complete', result });
+                return result;
+            }
+            if (signal?.aborted)
+                throw audioError('audio_render_cancelled');
+            await this.store.write('requests', input.requestId, { payloadHash, status: 'pending' });
+            let record;
+            if (input.action === 'create-candidate') {
+                if (!safeId(input.taskId) || !safeId(input.candidateId))
+                    throw audioError('invalid_audio_target', 400);
+                const target = { kind: 'generation-candidate', taskId: input.taskId, candidateId: input.candidateId };
+                const existing = await this.store.read('records', targetId(target));
+                const version = this.version(input.document, 1);
+                if (existing && (!known || existing.current.revision !== 1 || existing.current.contentHash !== version.contentHash))
+                    throw audioError('audio_candidate_exists');
+                record = existing ?? { target, current: version, history: [summary(version)] };
+                if (!existing)
+                    await this.saveRecord(record);
+            }
+            else {
+                const target = this.validateTarget(input.target);
+                if (target.kind === 'workspace-file' && target.path.startsWith('dist/'))
+                    throw audioError('immutable_audio_representation', 400);
+                await this.recoverPendingFor(target);
+                record = await this.observe(target);
+                this.expected(record, input);
+                if (input.action === 'render') {
+                    record = await this.render(record, signal);
+                    if (record.target.kind === 'workspace-file' && record.current.renderState === 'ready' && record.current.audition) {
+                        const wav = await readFile(this.store.blobPath('auditions', record.current.audition.contentHash));
+                        record.representation = await publishAudioRepresentations(this.projectRoot, record.target.path, { ...record.current, audition: record.current.audition }, wav);
+                        await this.saveRecord(record);
+                        await this.options.onWrite?.(record.target.path, record.current, record.representation.files.map(file => file.path), input.requestId);
+                    }
+                }
+                else if (input.action === 'adopt')
+                    return this.adopt(record, input, payloadHash);
+                else if (input.action === 'save' || input.action === 'rollback') {
+                    const old = input.action === 'rollback' ? await this.store.read('versions', `${targetId(record.target)}:${input.versionRevision}`) : undefined;
+                    if (input.action === 'rollback' && !old)
+                        throw audioError('audio_version_not_found', 404);
+                    const version = this.version(old?.document ?? input.document, record.current.revision + 1, old?.sourceText);
+                    this.checkProtection(record.current.document, version.document, input);
+                    const next = { ...record, current: version, representation: undefined, adoptionReceipt: undefined, history: [...record.history, summary(version)] };
+                    if (record.target.kind === 'workspace-file') {
+                        const path = record.target.path;
+                        const pending = { payloadHash, status: 'pending', transaction: { record: next, path, beforeHash: record.current.contentHash,
+                                sourceText: version.sourceText, paths: [path] } };
+                        await this.store.write('requests', input.requestId, pending);
+                        await this.store.write('pending', path, { requestId: input.requestId });
+                        return this.recover(input.requestId, pending);
+                    }
+                    record = next;
+                    await this.store.write('requests', input.requestId, { payloadHash, status: 'pending', candidateRecord: record });
+                    await this.saveRecord(record);
+                }
+                else if (input.action === 'bind') {
+                    record = await this.bind(record, input);
+                }
+                else
+                    throw audioError('invalid_audio_action', 400);
+            }
+            const result = await publicState(record, this.projectRoot);
+            await this.store.write('requests', input.requestId, { payloadHash, status: 'complete', result });
+            return result;
+        });
+    }
+    async render(record, signal) {
+        if (record.current.renderState === 'ready' && record.current.audition) {
+            const existing = await readFile(this.store.blobPath('auditions', record.current.audition.contentHash));
+            if (digest(existing) !== record.current.audition.contentHash)
+                throw audioError('audio_audition_unavailable', 404);
+            return record;
+        }
+        record.current = { ...record.current, renderState: 'running', renderError: undefined, audition: undefined };
+        await this.saveRecord(record);
+        try {
+            const rendered = await this.options.render(record.current.document, signal);
+            const expectedFrames = Math.ceil(soundDurationSeconds(record.current.document) * 44100);
+            if (rendered.metrics.frames !== expectedFrames || rendered.metrics.channels !== 1 || rendered.metrics.sampleRate !== 44100 || !Number.isFinite(rendered.metrics.peak))
+                throw audioError('audio_render_failed', 422);
+            if (rendered.metrics.peak > .98)
+                throw audioError('render_peak_exceeded', 422);
+            const contentHash = digest(rendered.wav);
+            await this.store.bytes('auditions', contentHash, rendered.wav);
+            const renderKey = audioRenderKey({ sourceRenderHash: record.current.sourceRenderHash, rendererBuildHash: rendered.rendererBuildHash,
+                chromiumVersion: rendered.chromiumVersion, sampleRate: 44100, channels: 1, frames: expectedFrames, format: 'pcm-f32' });
+            record.current = { ...record.current, renderState: 'ready', audition: { mimeType: 'audio/wav', size: rendered.wav.length,
+                    contentHash, pcmContentHash: rendered.pcmContentHash, rendererBuildHash: rendered.rendererBuildHash,
+                    chromiumVersion: rendered.chromiumVersion, renderKey, metrics: rendered.metrics } };
+        }
+        catch (error) {
+            const code = error instanceof Error && /^[a-z][a-z0-9_]{0,127}$/.test(error.message) ? error.message : 'audio_render_failed';
+            record.current = { ...record.current, renderState: signal?.aborted || code === 'audio_render_cancelled' ? 'cancelled' : 'failed', renderError: code };
+        }
+        await this.saveRecord(record);
+        return record;
+    }
+    async recoverPendingFor(target) {
+        if (target.kind !== 'workspace-file')
+            return;
+        const pending = await this.store.read('pending', target.path);
+        if (!pending)
+            return;
+        const request = await this.store.read('requests', pending.requestId);
+        if (request?.status === 'pending' && request.transaction)
+            await this.recover(pending.requestId, request);
+    }
+    async recover(requestId, receipt) {
+        const tx = receipt.transaction;
+        const source = await readAudioSource(this.projectRoot, tx.path), hash = source === undefined ? null : digest(source);
+        if (hash !== tx.beforeHash && hash !== tx.record.current.contentHash)
+            throw audioError('audio_revision_conflict');
+        if (hash !== tx.record.current.contentHash) {
+            const target = await audioProjectPath(this.projectRoot, tx.path, true);
+            await writeSharedFile(this.projectRoot, target, tx.sourceText);
+            await this.options.onPhase?.('source-published');
+        }
+        await this.saveRecord(tx.record);
+        const result = await publicState(tx.record, this.projectRoot);
+        await this.store.write('requests', requestId, { ...receipt, status: 'complete', result });
+        await this.options.onWrite?.(tx.path, tx.record.current, tx.paths, requestId);
+        return result;
+    }
+    async adopt(record, input, payloadHash) {
+        if (record.target.kind !== 'generation-candidate' || record.current.renderState !== 'ready' || !record.current.audition)
+            throw audioError('audio_audition_unavailable');
+        const path = input.path ?? `source/audio/${record.target.candidateId}.${record.current.document.format === 'playcraft.score' ? 'pcscore' : 'pcaudio'}.json`;
+        this.checkFormatPath(path, record.current.document);
+        if (path.startsWith('dist/'))
+            throw audioError('immutable_audio_representation', 400);
+        await audioProjectPath(this.projectRoot, path);
+        await this.recoverPendingFor({ kind: 'workspace-file', path });
+        const previousRaw = await readAudioSource(this.projectRoot, path);
+        const previous = previousRaw === undefined ? undefined : await this.observe({ kind: 'workspace-file', path });
+        if ((input.expectedDestinationContentHash ?? null) !== (previous?.current.contentHash ?? null) ||
+            (input.expectedDestinationRevision ?? 0) !== (previous?.current.revision ?? 0))
+            throw audioError('audio_revision_conflict');
+        const audition = record.current.audition, bytes = await readFile(this.store.blobPath('auditions', audition.contentHash));
+        const representation = await publishAudioRepresentations(this.projectRoot, path, { ...record.current, audition }, bytes);
+        const version = { ...record.current, revision: (previous?.current.revision ?? 0) + 1, createdAt: new Date().toISOString() };
+        const paths = [...representation.files.map(file => file.path), path];
+        const adopted = { target: { kind: 'workspace-file', path }, current: version,
+            representation, usage: previous?.usage, history: [...(previous?.history ?? []), summary(version)], adoptionReceipt: { operationId: input.requestId, path,
+                taskId: record.target.taskId, candidateId: record.target.candidateId, candidateRevision: record.current.revision,
+                sourceContentHash: record.current.contentHash, representationSetHash: representation.representationSetHash, files: representation.files } };
+        const receipt = { payloadHash, status: 'pending', transaction: { record: adopted, path,
+                beforeHash: previous?.current.contentHash ?? null, sourceText: record.current.sourceText, paths } };
+        await this.store.write('requests', input.requestId, receipt);
+        await this.store.write('pending', path, { requestId: input.requestId });
+        await this.options.onPhase?.('representations-published');
+        return this.recover(input.requestId, receipt);
+    }
+    async bind(record, input) {
+        if (record.target.kind !== 'workspace-file' || record.current.renderState !== 'ready' || !record.current.audition ||
+            !record.representation || record.representation.sourceContentHash !== record.current.contentHash)
+            throw audioError('audio_audition_unavailable');
+        if (!input.eventName || !/^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(input.eventName))
+            throw audioError('invalid_audio_binding', 400);
+        const primary = record.representation.files.find(file => /\/sound\.(?:pcaudio|pcscore)\.json$/.test(file.path));
+        if (!primary)
+            throw audioError('invalid_audio_package', 400);
+        await audioArtifactResources(this.projectRoot, primary.path);
+        const bindingPath = `source/audio-bindings/${input.eventName}.json`;
+        const previous = await audioProjectPath(this.projectRoot, bindingPath, true);
+        const previousBytes = await readFile(previous).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        let previousEntry;
+        try {
+            previousEntry = previousBytes ? JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(previousBytes)) : undefined;
+        }
+        catch { /* Preserve the original bytes below. */ }
+        if (previousEntry?.operationId === input.requestId && previousEntry.sourcePath === record.target.path && previousEntry.sourceContentHash === record.current.contentHash) {
+            record.usage = { status: 'integration_required', bindingPath, eventName: input.eventName, sourceContentHash: record.current.contentHash,
+                ...(previousEntry.previousBinding ? { previousContentHash: previousEntry.previousBinding } : {}) };
+            await this.saveRecord(record);
+            return record;
+        }
+        const entry = { version: 1, operationId: input.requestId, eventName: input.eventName, sourcePath: record.target.path,
+            sourceContentHash: record.current.contentHash, revision: record.current.revision, auditionContentHash: record.current.audition.contentHash,
+            modulePath: record.representation.modulePath, representationSetHash: record.representation.representationSetHash,
+            integrationStatus: 'integration_required', previousBinding: previousBytes ? digest(previousBytes) : null };
+        if (previousBytes)
+            await this.store.bytes('bindings', digest(previousBytes), previousBytes);
+        await writeSharedFile(this.projectRoot, previous, `${canonicalAudioJson(entry)}\n`);
+        record.usage = { status: 'integration_required', bindingPath, eventName: input.eventName,
+            sourceContentHash: record.current.contentHash, ...(previousBytes ? { previousContentHash: digest(previousBytes) } : {}) };
+        await this.saveRecord(record);
+        await this.options.onWrite?.(record.target.path, record.current, [bindingPath], input.requestId);
+        return record;
+    }
+}

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

@@ -0,0 +1,125 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readFile, realpath, rename, rm } from 'node:fs/promises';
+import { dirname, join, resolve, relative, sep } from 'node:path';
+import { workspaceRelativePathSchema, isSoundDocumentPath } from '@playcraft/common/cloud-workspace/runtime';
+export const digest = (value) => createHash('sha256').update(value).digest('hex');
+export const audioError = (code, status = 409) => Object.assign(new Error(code), { code, status });
+/** Private audio state is indexed by hashes, never by caller-controlled path components. */
+export class AudioStore {
+    root;
+    constructor(stateRoot, scope) { this.root = join(stateRoot, 'audio-assets', digest(scope)); }
+    path(bucket, identity) { return join(this.root, bucket, `${digest(identity)}.json`); }
+    async read(bucket, identity) {
+        const file = this.path(bucket, identity);
+        try {
+            const stat = await lstat(file);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16 * 1024 * 1024)
+                throw audioError('audio_state_unavailable');
+            return JSON.parse(await readFile(file, 'utf8'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    }
+    async write(bucket, identity, value) {
+        const target = this.path(bucket, identity);
+        // private: controller state is outside the shared project tree.
+        await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+        await atomicPrivate(target, JSON.stringify(value));
+    }
+    async bytes(bucket, identity, bytes) {
+        const target = join(this.root, bucket, digest(identity));
+        // private: candidate blobs remain controller-managed until adoption.
+        await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+        const existing = await readFile(target).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (existing) {
+            if (digest(existing) !== digest(bytes))
+                throw audioError('audio_blob_conflict');
+            return target;
+        }
+        await atomicPrivate(target, bytes);
+        return target;
+    }
+    blobPath(bucket, identity) { return join(this.root, bucket, digest(identity)); }
+}
+async function atomicPrivate(target, value) {
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    try {
+        // private: atomic state replacement is readable only by the controller.
+        const file = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        try {
+            await file.writeFile(value);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, target);
+        const parent = await open(dirname(target), 'r');
+        try {
+            await parent.sync();
+        }
+        finally {
+            await parent.close();
+        }
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Reject symlinks even when their destination happens to remain inside the project. */
+export async function audioProjectPath(root, path, createParents = false) {
+    const parsed = workspaceRelativePathSchema.safeParse(path);
+    if (!parsed.success || parsed.data.split('/').some(part => ['.git', '.playcraft', 'node_modules'].includes(part)))
+        throw audioError('invalid_audio_path', 400);
+    const base = await realpath(root);
+    let target = base;
+    const parts = parsed.data.split('/');
+    for (let index = 0; index < parts.length; index++) {
+        target = join(target, parts[index]);
+        let stat = await lstat(target).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (!stat && createParents && index < parts.length - 1) {
+            // shared: project source and package parents are used by both identities.
+            await mkdir(target, { mode: 0o2770 });
+            stat = await lstat(target);
+        }
+        if (stat?.isSymbolicLink() || stat && index < parts.length - 1 && !stat.isDirectory())
+            throw audioError('invalid_audio_path', 400);
+    }
+    const rel = relative(base, resolve(target));
+    if (!rel || rel.startsWith(`..${sep}`) || rel === '..')
+        throw audioError('invalid_audio_path', 400);
+    return target;
+}
+export async function readAudioSource(root, path) {
+    if (!isSoundDocumentPath(path))
+        throw audioError('unsupported_audio_format', 400);
+    const target = await audioProjectPath(root, path);
+    const stat = await lstat(target).catch(error => { if (error.code === 'ENOENT')
+        return undefined; throw error; });
+    if (!stat)
+        return undefined;
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > 65_536)
+        throw audioError('invalid_audio_document', 400);
+    const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const bytes = await file.readFile();
+        const after = await file.stat();
+        if (bytes.length > 65_536 || stat.ino !== after.ino || stat.size !== after.size || stat.mtimeMs !== after.mtimeMs)
+            throw audioError('audio_revision_conflict');
+        try {
+            return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        }
+        catch {
+            throw audioError('invalid_audio_document', 400);
+        }
+    }
+    finally {
+        await file.close();
+    }
+}

package/dist/workspace-runtime/workspaces/build-isolation.js

@@ -3,6 +3,7 @@ import { copyFile, cp, lstat, mkdir, readdir, readlink, symlink } from 'node:fs/
 import { dirname, join, relative, sep } from 'node:path';
 import { listWorkspaceBuildInputs } from './git.js';
 import { ensureSharedDirectory } from './shared-write.js';
+import { readAudioBuildInputs } from './audio-assets/build-inputs.js';
 /** Staging under the workspace from earlier runtimes' sandbox delivery builds; never a build input. */
 const STAGING_DIRECTORY = '.playcraft-delivery';
 /** Never copied into the build copy: history, outputs and caches that the build neither reads nor owns. */
@@ -72,4 +73,5 @@ export async function isolateWorkspaceForBuild(root, destination) {
         }
     });
     await Promise.all(workers);
+    return readAudioBuildInputs(root, destination);
 }