Labyricorn/XZBT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(audio): implement phase 3c slice 2 lifecycle and voices

Browse Source
This commit is contained in:
Labyricorn
2026-09-05 19:38:38 -07:00
parent 94aafeae27
commit 9ae2c76075
9 changed files with 1473 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files
XZBT.html
+444 -33
View File
@@ -716,13 +716,41 @@ const AUDIO_SOUND_FIELDS = Object.freeze(['name', 'tags', 'usage', 'cadence', 'b
const AUDIO_SOUND_USAGE = Object.freeze(['automatic', 'manual', 'scenario']);
const AUDIO_RECIPE_MODES = Object.freeze(['oneshot', 'continuous']);
const AUDIO_GRAPH_FIELDS = Object.freeze(['nodes', 'routes']);
const AUDIO_RECIPE_FIELDS = Object.freeze(['nodes', 'routes', 'mode']);
const AUDIO_RECIPE_FIELDS = Object.freeze(['nodes', 'routes', 'mode', 'release']);
const AUDIO_COMPONENT_FIELDS = Object.freeze(['nodes', 'routes', 'parameters', 'input']);
const AUDIO_COMPONENT_PARAMETER_FIELDS = Object.freeze(['type', 'default', 'min', 'max', 'unit']);
const AUDIO_BUS_FIELDS = Object.freeze(['gain']);
const AUDIO_BUS_GAIN_RANGE = Object.freeze({ min: 0, max: 4, default: 1 });
const AUDIO_ROUTE_FIELDS = Object.freeze(['from', 'to', 'depth']);
const AUDIO_VOICE_LIMITS = Object.freeze({
oneshot: 64,
continuous: 16
});
const AUDIO_DEFAULT_RELEASE_MS = 50;
const AUDIO_MAX_RELEASE_MS = 10000;
const AUDIO_LIFECYCLE_STATES = Object.freeze([
'CREATED',
'SCHEDULED',
'ACTIVE',
'RELEASING',
'FINISHED',
'DISPOSED',
'FAILED'
]);
const AUDIO_LIFECYCLE_TRANSITIONS = Object.freeze({
CREATED: Object.freeze(['SCHEDULED', 'FINISHED', 'FAILED']),
SCHEDULED: Object.freeze(['ACTIVE', 'RELEASING', 'FAILED']),
ACTIVE: Object.freeze(['RELEASING', 'FINISHED', 'FAILED']),
RELEASING: Object.freeze(['FINISHED', 'FAILED']),
FINISHED: Object.freeze(['DISPOSED']),
DISPOSED: Object.freeze([]),
FAILED: Object.freeze([])
});
function audioMaxFrequency(sampleRate) {
if (!Number.isFinite(sampleRate) || sampleRate <= 0) return AUDIO_STATIC_MAX_FREQUENCY;
return Math.min(AUDIO_STATIC_MAX_FREQUENCY, sampleRate * AUDIO_NYQUIST_FACTOR);
@@ -972,7 +1000,7 @@ function expandSoundGraph(document, soundId) {
const sound = document.sounds?.[soundId];
const soundPath = `$.sounds.${soundId}`;
const located = recipeGraphFor(document, sound, soundPath, errors);
if (!located) return { nodes: [], routes: [], errors, mode: 'oneshot' };
if (!located) return { nodes: [], routes: [], errors, mode: 'oneshot', release: AUDIO_DEFAULT_RELEASE_MS };
const nodes = new Map();
const routes = [];
@@ -1084,7 +1112,10 @@ function expandSoundGraph(document, soundId) {
expand(located.graph, '', 1, [], located.path);
const mode = AUDIO_RECIPE_MODES.includes(located.graph.mode) ? located.graph.mode : 'oneshot';
return { nodes: [...nodes.values()], routes, errors, mode, graphPath: located.path };
const release = Object.hasOwn(located.graph, 'release')
? (durationMilliseconds(located.graph.release) ?? AUDIO_DEFAULT_RELEASE_MS)
: AUDIO_DEFAULT_RELEASE_MS;
return { nodes: [...nodes.values()], routes, errors, mode, release, graphPath: located.path };
}
function detectCycle(adjacency) {
@@ -1187,6 +1218,9 @@ function checkGraphLegality(document, soundId, expansion, errors) {
fail(errors, 'ERR_INVALID_ROUTE', node.path, `Control source '${node.path}' reaches audible output.`);
} else {
audiblePath = true;
if (expansion.mode === 'oneshot' && (node.type === 'oscillator' || node.type === 'noise')) {
fail(errors, 'ERR_INDETERMINATE_ONESHOT', graphPath, `Sound '${soundId}' is a oneshot with an unbounded audible path from '${node.path}' (${node.type}).`);
}
}
}
if (contract.acceptsAudio === false) {
@@ -1235,6 +1269,9 @@ function validateAudioSubsystem(document, errors, helpers) {
if (Object.hasOwn(recipe, 'mode') && !AUDIO_RECIPE_MODES.includes(recipe.mode)) {
fail(errors, 'ERR_TYPE_MISMATCH', `${path}.mode`, `Recipe mode must be one of: ${AUDIO_RECIPE_MODES.join(', ')}.`);
}
if (Object.hasOwn(recipe, 'release')) {
validateDurationField(recipe.release, { min: 0, max: AUDIO_MAX_RELEASE_MS }, `${path}.release`, errors);
}
}
}
}
@@ -1301,6 +1338,9 @@ function validateAudioSubsystem(document, errors, helpers) {
if (Object.hasOwn(sound.recipe, 'mode') && !AUDIO_RECIPE_MODES.includes(sound.recipe.mode)) {
fail(errors, 'ERR_TYPE_MISMATCH', `${path}.recipe.mode`, `Recipe mode must be one of: ${AUDIO_RECIPE_MODES.join(', ')}.`);
}
if (Object.hasOwn(sound.recipe, 'release')) {
validateDurationField(sound.recipe.release, { min: 0, max: AUDIO_MAX_RELEASE_MS }, `${path}.recipe.release`, errors);
}
}
const expansion = expandSoundGraph(document, id);
errors.push(...expansion.errors);
@@ -1308,6 +1348,124 @@ function validateAudioSubsystem(document, errors, helpers) {
}
}
function computeDeterminableEndingBound(expansion, resolvedNodes = null) {
const { nodes, routes, release = AUDIO_DEFAULT_RELEASE_MS } = expansion;
const resolvedMap = resolvedNodes instanceof Map
? resolvedNodes
: Array.isArray(resolvedNodes)
? new Map(resolvedNodes.map((n) => [n.path, n]))
: null;
const nodeMap = new Map(nodes.map((n) => [n.path, n]));
function nodeContribution(path) {
if (path === 'output') return 0;
const node = nodeMap.get(path);
if (!node || node.implicit || node.type === 'component') return 0;
const type = node.type;
const resolved = resolvedMap?.get(path)?.values;
if (type === 'impulse') {
if (resolved && typeof resolved.duration === 'number') return resolved.duration;
return durationMilliseconds(node.spec?.duration ?? '10ms') ?? 10;
}
if (type === 'oscillator' || type === 'noise') {
return Infinity;
}
if (type === 'delay') {
let time, feedback;
if (resolved) {
time = resolved.time ?? 250;
feedback = resolved.feedback ?? 0.2;
} else {
time = durationMilliseconds(node.spec?.time ?? '250ms') ?? 250;
feedback = typeof node.spec?.feedback === 'number' ? node.spec.feedback : 0.2;
}
if (feedback > 0) {
const clampedFeedback = Math.min(0.9999, Math.max(1e-6, feedback));
const multiplier = Math.ceil(Math.log(0.001) / Math.log(clampedFeedback));
return time * multiplier;
}
return time;
}
if (type === 'reverb') {
let predelay, decay;
if (resolved) {
predelay = resolved.predelay ?? 0;
decay = resolved.decay ?? 2000;
} else {
predelay = durationMilliseconds(node.spec?.predelay ?? '0ms') ?? 0;
decay = durationMilliseconds(node.spec?.decay ?? '2s') ?? 2000;
}
return predelay + decay;
}
if (type === 'resonator') {
if (resolved?.modes && Array.isArray(resolved.modes) && resolved.modes.length > 0) {
return Math.max(...resolved.modes.map((m) => m.decay ?? 1000));
}
const modes = node.spec?.modes ?? [];
if (modes.length > 0) {
return Math.max(...modes.map((m) => durationMilliseconds(m.decay ?? '1s') ?? 1000));
}
return 1000;
}
return 0;
}
const audioAdjacency = new Map();
const inDegree = new Map();
const allNodes = new Set();
for (const n of nodes) allNodes.add(n.path);
allNodes.add('output');
for (const n of allNodes) {
audioAdjacency.set(n, []);
inDegree.set(n, 0);
}
for (const route of routes) {
if (route.kind === 'audio') {
if (!audioAdjacency.has(route.from)) audioAdjacency.set(route.from, []);
audioAdjacency.get(route.from).push(route.to);
inDegree.set(route.to, (inDegree.get(route.to) ?? 0) + 1);
}
}
const dist = new Map();
for (const n of allNodes) dist.set(n, -Infinity);
for (const n of nodes) {
if (n.implicit || n.type === 'component') continue;
if (n.type === 'impulse' || n.type === 'oscillator' || n.type === 'noise') {
dist.set(n.path, nodeContribution(n.path));
}
}
const queue = [];
for (const [node, deg] of inDegree.entries()) {
if (deg === 0) queue.push(node);
}
while (queue.length > 0) {
const current = queue.shift();
const currentDist = dist.get(current);
for (const next of audioAdjacency.get(current) ?? []) {
if (currentDist !== -Infinity) {
const nextContrib = nodeContribution(next);
const newDist = currentDist === Infinity ? Infinity : currentDist + nextContrib;
if (newDist > dist.get(next)) dist.set(next, newDist);
}
inDegree.set(next, inDegree.get(next) - 1);
if (inDegree.get(next) === 0) queue.push(next);
}
}
const outDist = dist.get('output');
if (outDist === Infinity) return Infinity;
if (outDist === -Infinity) return release;
return outDist + release;
}
/* src/runtime/validator.js */
function issue(code, path, message, context = {}) {
return { code, path, message, ...context };
@@ -2322,7 +2480,15 @@ function instantiateSoundGraph(document, soundId, options = {}) {
const expansion = options.expansion ?? expandSoundGraph(document, soundId);
if (expansion.errors.length > 0) {
return { nodes: [], routes: [], warnings: [], errors: expansion.errors, mode: expansion.mode };
return {
nodes: [],
routes: [],
warnings: [],
errors: expansion.errors,
mode: expansion.mode,
release: expansion.release,
endingBoundMs: null
};
}
const ceiling = audioMaxFrequency(sampleRate);
@@ -2440,7 +2606,22 @@ function instantiateSoundGraph(document, soundId, options = {}) {
return { ...route, depth: evaluate(route.depth, owner?.scope ?? null, `${route.path}.depth`) };
});
return { nodes, routes, warnings, errors: [], mode: expansion.mode, instanceKey, ceiling };
let endingBoundMs = null;
if (expansion.mode === 'oneshot') {
endingBoundMs = computeDeterminableEndingBound(expansion, nodes);
}
return {
nodes,
routes,
warnings,
errors: [],
mode: expansion.mode,
release: expansion.release,
endingBoundMs,
instanceKey,
ceiling
};
}
/* ------------------------------------------------------------------ *
@@ -2536,7 +2717,10 @@ function realizeSoundGraph(context, plan, destination) {
const starters = [];
const sink = context.createGain();
sink.gain.value = 1;
sink.connect(destination);
const releaseGain = context.createGain();
releaseGain.gain.value = 1;
sink.connect(releaseGain).connect(destination);
disposers.push(() => releaseGain.disconnect());
created.set('output', { input: sink, output: sink });
const now = () => context.currentTime;
@@ -2627,6 +2811,7 @@ function realizeSoundGraph(context, plan, destination) {
};
let tick = 0;
const timer = setInterval(() => { schedule(0); tick += 1; }, Math.max(10, period * 1000));
if (typeof timer.unref === 'function') timer.unref();
schedule(0);
entry = { input: null, output: source, params: {} };
starters.push(() => source.start());
@@ -2750,26 +2935,180 @@ function realizeSoundGraph(context, plan, destination) {
return {
sink,
releaseGain,
dispose() {
for (const release of disposers.reverse()) {
try { release(); } catch { /* disposal is best effort */ }
}
sink.disconnect();
releaseGain.disconnect();
created.clear();
}
};
}
class SoundInstance {
constructor({
soundId,
mode = 'oneshot',
releaseMs = AUDIO_DEFAULT_RELEASE_MS,
endingBoundMs = null,
plan = null,
subsystem = null,
bus = null,
context = null,
creationOrder = 0
} = {}) {
this.soundId = soundId;
this.mode = mode;
this.releaseMs = releaseMs ?? AUDIO_DEFAULT_RELEASE_MS;
this.endingBoundMs = endingBoundMs;
this.plan = plan;
this.subsystem = subsystem;
this.bus = bus;
this.context = context;
this.creationOrder = creationOrder;
this.state = 'CREATED';
this.realized = null;
this.startTime = null;
this.releaseTimer = null;
this.endingTimer = null;
}
canTransition(nextState) {
const allowed = AUDIO_LIFECYCLE_TRANSITIONS[this.state] ?? [];
return allowed.includes(nextState);
}
transition(nextState) {
if (!this.canTransition(nextState)) {
throw new RuntimeFault('ERR_RUNTIME_FAULT', `Invalid lifecycle transition from '${this.state}' to '${nextState}'.`);
}
this.state = nextState;
return true;
}
realize(context, destination) {
this.realized = realizeSoundGraph(context, this.plan, destination);
return this.realized;
}
stop() {
if (this.state === 'RELEASING' || this.state === 'FINISHED' || this.state === 'DISPOSED' || this.state === 'FAILED') {
return;
}
if (this.subsystem) {
this.subsystem.voices.delete(this);
}
if (this.state === 'CREATED') {
this.transition('FINISHED');
return;
}
if (this.state === 'SCHEDULED') {
this.transition('RELEASING');
if (this.releaseMs === 0) {
this.transition('FINISHED');
} else {
this.releaseTimer = setTimeout(() => {
if (this.state === 'RELEASING') {
this.transition('FINISHED');
}
}, this.releaseMs);
if (typeof this.releaseTimer?.unref === 'function') this.releaseTimer.unref();
}
return;
}
if (this.state === 'ACTIVE') {
if (this.endingTimer) {
clearTimeout(this.endingTimer);
this.endingTimer = null;
}
this.transition('RELEASING');
if (this.releaseMs === 0) {
if (this.realized?.releaseGain?.gain) {
const now = this.context?.currentTime ?? 0;
this.realized.releaseGain.gain.cancelScheduledValues?.(now);
this.realized.releaseGain.gain.setValueAtTime?.(0, now);
}
this.transition('FINISHED');
} else {
const now = this.context?.currentTime ?? 0;
const durationSec = this.releaseMs / 1000;
const gainParam = this.realized?.releaseGain?.gain;
if (gainParam) {
gainParam.cancelScheduledValues?.(now);
gainParam.setValueAtTime?.(gainParam.value, now);
gainParam.linearRampToValueAtTime?.(0, now + durationSec);
}
this.releaseTimer = setTimeout(() => {
if (this.state === 'RELEASING') {
this.transition('FINISHED');
}
}, this.releaseMs);
if (typeof this.releaseTimer?.unref === 'function') this.releaseTimer.unref();
}
}
}
forceFinishAndDispose() {
if (this.state === 'RELEASING') {
if (this.releaseTimer) {
clearTimeout(this.releaseTimer);
this.releaseTimer = null;
}
if (this.realized?.releaseGain?.gain) {
const now = this.context?.currentTime ?? 0;
this.realized.releaseGain.gain.cancelScheduledValues?.(now);
this.realized.releaseGain.gain.setValueAtTime?.(0, now);
}
this.transition('FINISHED');
}
this.dispose();
}
dispose() {
if (this.state === 'DISPOSED') return;
if (this.releaseTimer) {
clearTimeout(this.releaseTimer);
this.releaseTimer = null;
}
if (this.endingTimer) {
clearTimeout(this.endingTimer);
this.endingTimer = null;
}
if (this.subsystem) {
this.subsystem.voices.delete(this);
this.subsystem.oneshotVoices?.delete(this);
this.subsystem.continuousVoices?.delete(this);
}
if (this.state !== 'FINISHED' && this.state !== 'FAILED') {
if (this.state === 'ACTIVE' || this.state === 'SCHEDULED') {
this.transition('RELEASING');
this.transition('FINISHED');
} else if (this.state === 'CREATED') {
this.transition('FINISHED');
} else if (this.state === 'RELEASING') {
this.transition('FINISHED');
}
}
this.transition('DISPOSED');
if (this.realized) {
try { this.realized.dispose(); } catch { /* best effort */ }
this.realized = null;
}
}
}
/* ------------------------------------------------------------------ *
* Runtime subsystem
* ------------------------------------------------------------------ */
// Owns the AudioContext, the declared buses, and the engine master chain, and turns a
// sound definition into a realized voice. The lifecycle state machine (PRD 57), voice
// ceilings, and the measured master-protection contract (PRD 58) are Phase 3c; the master
// chain built here is engine-owned and unbypassable but its ceiling is not yet verified.
// ceilings (16.6), and the measured master-protection contract (PRD 58) are Phase 3c;
// the master chain built here is engine-owned and unbypassable.
class AudioSubsystem {
constructor({ document, rng, diagnostics = null, contextFactory = null } = {}) {
constructor({ document, rng, diagnostics = null, contextFactory = null, voiceLimits = null } = {}) {
this.document = document;
this.rng = rng;
this.diagnostics = diagnostics;
@@ -2780,7 +3119,11 @@ class AudioSubsystem {
this.protection = null;
this.buses = new Map();
this.voices = new Set();
this.oneshotVoices = new Set();
this.continuousVoices = new Set();
this.voiceLimits = voiceLimits ?? { ...AUDIO_VOICE_LIMITS };
this.ordinals = new Map();
this.nextCreationOrder = 0;
this.masterVolume = 0.8;
}
@@ -2853,41 +3196,114 @@ class AudioSubsystem {
play(soundId, { resolveReference } = {}) {
if (!this.unlocked) return null;
const sound = this.document?.sounds?.[soundId];
if (!sound) return null;
const expansion = expandSoundGraph(this.document, soundId);
if (expansion.errors.length > 0) {
for (const error of expansion.errors) this.diagnostics?.error(error.code, error.message, { section: 'audio', objectId: soundId });
return null;
}
const mode = expansion.mode ?? 'oneshot';
const pool = mode === 'oneshot' ? this.oneshotVoices : this.continuousVoices;
const ceiling = mode === 'oneshot' ? this.voiceLimits.oneshot : this.voiceLimits.continuous;
if (pool.size >= ceiling) {
// 16.6 Eviction policy applied in strict order:
// 1. Dispose the oldest instance already in FINISHED.
const finishedInstances = [...pool].filter((i) => i.state === 'FINISHED');
if (finishedInstances.length > 0) {
finishedInstances.sort((a, b) => a.creationOrder - b.creationOrder);
const candidate = finishedInstances[0];
candidate.dispose();
this.diagnostics?.warn('WARN_VOICE_LIMIT', `Voice ceiling (${ceiling}) reached for '${soundId}'; disposed oldest FINISHED instance of '${candidate.soundId}'.`, { section: 'audio', objectId: soundId });
} else {
// 2. Evict the oldest instance in RELEASING by advancing its release ramp to immediate completion and disposing it.
const releasingInstances = [...pool].filter((i) => i.state === 'RELEASING');
if (releasingInstances.length > 0) {
releasingInstances.sort((a, b) => a.creationOrder - b.creationOrder);
const candidate = releasingInstances[0];
candidate.forceFinishAndDispose();
this.diagnostics?.warn('WARN_VOICE_LIMIT', `Voice ceiling (${ceiling}) reached for '${soundId}'; evicted oldest RELEASING instance of '${candidate.soundId}'.`, { section: 'audio', objectId: soundId });
} else if (mode === 'oneshot') {
// 3. For a one-shot request only: evict the oldest ACTIVE one-shot by starting its release.
const activeInstances = [...pool].filter((i) => i.state === 'ACTIVE' || i.state === 'SCHEDULED');
if (activeInstances.length > 0) {
activeInstances.sort((a, b) => a.creationOrder - b.creationOrder);
const candidate = activeInstances[0];
candidate.stop();
this.diagnostics?.warn('WARN_VOICE_LIMIT', `Voice ceiling (${ceiling}) reached for '${soundId}'; evicting oldest ACTIVE oneshot instance of '${candidate.soundId}' via release.`, { section: 'audio', objectId: soundId });
} else {
this.diagnostics?.warn('WARN_VOICE_LIMIT', `Voice ceiling (${ceiling}) reached for '${soundId}'; request refused.`, { section: 'audio', objectId: soundId });
return null;
}
} else {
// 4. Otherwise refuse the new instance.
this.diagnostics?.warn('WARN_VOICE_LIMIT', `Voice ceiling (${ceiling}) reached for '${soundId}'; continuous request refused.`, { section: 'audio', objectId: soundId });
return null;
}
}
}
const plan = instantiateSoundGraph(this.document, soundId, {
sampleRate: this.context.sampleRate,
rng: this.rng,
ordinal: this.nextOrdinal(soundId),
resolveReference
resolveReference,
expansion
});
for (const error of plan.errors) this.diagnostics?.error(error.code, error.message, { section: 'audio', objectId: soundId });
if (plan.errors.length > 0) return null;
for (const warning of plan.warnings) this.diagnostics?.warn(warning.code, warning.message, { section: 'audio', objectId: soundId, property: warning.path });
let voice;
try {
voice = realizeSoundGraph(this.context, plan, this.busFor(soundId));
} catch (error) {
this.diagnostics?.error('ERR_AUDIO_REALIZATION', `Sound '${soundId}' could not be realized: ${error.message}`, { section: 'audio', objectId: soundId });
return null;
}
const handle = {
const instance = new SoundInstance({
soundId,
mode: plan.mode,
stop: () => {
if (!this.voices.has(handle)) return;
this.voices.delete(handle);
voice.dispose();
}
};
this.voices.add(handle);
return handle;
releaseMs: plan.release,
endingBoundMs: plan.endingBoundMs,
plan,
subsystem: this,
bus: this.busFor(soundId),
context: this.context,
creationOrder: this.nextCreationOrder++
});
pool.add(instance);
try {
instance.transition('SCHEDULED');
instance.realize(this.context, this.busFor(soundId));
instance.transition('ACTIVE');
instance.startTime = this.context.currentTime;
this.voices.add(instance);
} catch (error) {
this.diagnostics?.error('ERR_AUDIO_REALIZATION', `Sound '${soundId}' could not be realized: ${error.message}`, { section: 'audio', objectId: soundId });
instance.transition('FAILED');
instance.dispose();
return null;
}
if (mode === 'oneshot' && instance.endingBoundMs != null && Number.isFinite(instance.endingBoundMs)) {
instance.endingTimer = setTimeout(() => {
if (instance.state === 'ACTIVE') {
this.voices.delete(instance);
instance.transition('FINISHED');
}
}, instance.endingBoundMs);
if (typeof instance.endingTimer?.unref === 'function') instance.endingTimer.unref();
}
return instance;
}
stopAll() {
for (const handle of [...this.voices]) handle.stop();
for (const instance of [...this.voices]) instance.stop();
}
async dispose() {
this.stopAll();
for (const instance of [...this.oneshotVoices]) instance.dispose();
for (const instance of [...this.continuousVoices]) instance.dispose();
this.buses.clear();
if (this.context) {
try { await this.context.close(); } catch { /* already closed */ }
@@ -3107,12 +3523,7 @@ class XZBTApplication {
playSound(id) {
const current = this.activation.current;
if (!this.audio?.unlocked || !current) return;
const handle = this.audio.play(id, { resolveReference: (path) => current.performance.engine.get(path) });
if (handle?.mode === 'oneshot') {
// Phase 3b has no lifecycle contract yet (PRD 57 is Phase 3c), so a one-shot voice is
// released on a fixed development timer rather than on a determinable ending.
setTimeout(() => handle.stop(), 4000);
}
this.audio.play(id, { resolveReference: (path) => current.performance.engine.get(path) });
this.renderAudio();
}
docs/IMPLEMENTATION_STATUS.md
+13 -5
View File
@@ -1,10 +1,10 @@
# XZBT implementation status
**Updated:** September 5, 2026
**State:** The audio subsystem contract is complete through Phase 3c; Phase 3c implementation (slices 2-4), the Phase 3 audible gates, and the Phase 1 direct-file import/restart observation remain pending
**State:** The audio subsystem contract is complete through Phase 3c; Phase 3c slices 1 and 2 implemented; automation (slice 3) and master protection (slice 4), the Phase 3 audible gates, and the Phase 1 direct-file import/restart observation remain pending
**Planning baseline:** `05fe2b4e021ba86e4a290d05b63c7cae0e386128`
**Exact demarcation:** GC1 direct-file feasibility (10/10 checks), GC2 shared format contracts, GC3 resolution semantics, GC4 clock/PRNG semantics, and GC5 ownership/failure semantics are complete at the Phase 0 contract-oracle level. The Phase 1 production runtime skeleton, the Phase 2 common grammar, and the Phase 3a/3b audio authoring contract and its implementation pass automated checks. Three gates remain open in the completed work: Phase 1's direct-file two-fixture restart observation, Phase 3's audible observation (no sound has been heard from any build), and the Phase 3c audio contracts on which real playback acceptance depends. Visual, cadence/event, scenario, final generated-UI, performance, and soak work remains assigned to later phases.
**Exact demarcation:** GC1 direct-file feasibility (10/10 checks), GC2 shared format contracts, GC3 resolution semantics, GC4 clock/PRNG semantics, and GC5 ownership/failure semantics are complete at the Phase 0 contract-oracle level. The Phase 1 production runtime skeleton, the Phase 2 common grammar, and the Phase 3a/3b/3c-2 audio engine pass automated checks. Three gates remain open in the completed work: Phase 1's direct-file two-fixture restart observation, Phase 3's audible observation (no sound has been heard from any build), and the Phase 3c audio contracts on which real playback acceptance depends. Visual, cadence/event, scenario, final generated-UI, performance, and soak work remains assigned to later phases.
The user requested sequential implementation with a stop on problems. The [manual version 3 evidence](evidence/phase0/2026-09-04-user-run-v3.md) verifies embedded data-URL worklet loading in direct-file Chrome. The subsequent [user-performed restart test](evidence/phase0/2026-09-04-user-restart.md) restored Blue Study activity 0.37 and master volume 0.19 immediately on reopening. Native tone output and AudioContext suspend/resume are also observed. Ordinary file import, selection of both exhibits, regular Chrome mode, and [directory cancellation/denial fallback](evidence/phase0/2026-09-05-user-directory-fallback.md) have been confirmed.
@@ -13,7 +13,7 @@ The user requested sequential implementation with a stop on problems. The [manua
| 0 — Contracts and feasibility | Complete | GC1 passed; GC2–GC5 shared contracts and traces passed; GC6/GC7 later gates scheduled and mapped |
| 1 — Runtime skeleton | Implemented; acceptance pending | [Automated evidence](evidence/phase1/2026-09-05-runtime-skeleton.md) passes production-module, lifecycle, PRNG-vector, cache/restore, fixture-validation, and deterministic-build tests. Direct-file two-fixture import/restart remains a user-observed gate. |
| 2 — Common grammar | Complete | [Automated evidence](evidence/phase2/2026-09-05-common-grammar.md) covers production GC2 conformance, typed values, signals, actions, same-tick bindings, transitions, override precedence/release, and parameter restoration. |
| 3 — Audio engine | Phases 3a/3b complete; 3c contract complete, 3c implementation not started | [Automated evidence](evidence/phase3/2026-09-05-audio-authoring-contract.md) covers Format Specification sections 14-15, all sixteen node types, routing and modulation, twelve legality rules, authoring limits, components, sounds/recipes, and buses. The [Phase 3c contract](evidence/phase3/2026-09-05-phase3c-contract.md) adds section 16: automation tracks and precedence, the seven-state lifecycle and release, determinable one-shot endings, voice ceilings and eviction, master protection, and unlock and pause behavior. Phase 3c implementation slices 2-4 and the PRD 129 audio acceptance challenge remain. |
| 3 — Audio engine | Slices 3c-1 (contract) and 3c-2 (lifecycle/voices) complete; slices 3c-3 and 3c-4 pending | [Automated evidence](evidence/phase3/2026-09-05-audio-authoring-contract.md) covers sections 14-15; [contract evidence](evidence/phase3/2026-09-05-phase3c-contract.md) adds section 16. [Slice 3c-2 evidence](evidence/phase3/2026-09-05-phase3c-lifecycle-voices.md) implements the seven-state lifecycle, engine-owned release gain, determinable one-shot endings, voice ceilings (64/16), 4-step eviction, and disposal. Slices 3c-3 (automation) and 3c-4 (master protection measurement) and the PRD 129 audio acceptance challenge remain. |
| 4 — Visual engine | Not started | Earlier phases and visual contracts |
| 5 — Events and cadence | Not started | Earlier phases and event/cadence contracts |
| 6 — Scenario director | Not started | Earlier phases and scenario contracts |
@@ -63,6 +63,14 @@ Phase 3 is not accepted. Audio automation precedence, the lifecycle state machin
## Phase 3c contract (slice 1)
Format Specification section 16 completes the audio subsystem contract. Phase 3c is delivered in four slices, recorded in the implementation plan: the contract (done), lifecycle and voices, automation, and measured master protection. Each slice ends green and committable, because slice 2 replaces the working one-shot timer scaffolding and must not be left half-applied.
Format Specification section 16 completes the audio subsystem contract. Phase 3c is delivered in four slices, recorded in the implementation plan: the contract (done), lifecycle and voices (done), automation, and measured master protection. Each slice ends green and committable, because slice 2 replaces the working one-shot timer scaffolding and must not be left half-applied.
Section 16 is contract only. The runtime does not implement it: there is no lifecycle state machine, no voice ceiling, and `automation` and `release` are still rejected as unknown fields. Slice 3c-4 and the PRD 129 audio acceptance challenge are user-observed and cannot be closed by automated tests. No sound has been heard from any build.
Section 16 was contract only at slice 1.
## Phase 3c lifecycle and voices (slice 2)
Slice 3c-2 implements the seven-state lifecycle state machine (`CREATED`, `SCHEDULED`, `ACTIVE`, `RELEASING`, `FINISHED`, `DISPOSED`, `FAILED`) per section 16.3, the engine-owned internal release gain per 16.4, authorable `release` durations (`0ms` to `10s`) on recipes, determinable one-shot ending bounds calculation per 16.5 (and `ERR_INDETERMINATE_ONESHOT` validation for unbounded sources), voice ceilings (64 one-shot, 16 continuous) with 4-step eviction order (`FINISHED` -> `RELEASING` -> `ACTIVE` -> refuse) and `WARN_VOICE_LIMIT` per 16.6, full disposal, and removal of the fixed 4-second dev timer from `src/runtime/app.js`.
`npm test` runs 67 tests with zero failures. Two clean builds produce byte-identical artifacts with digest `d7d16a89f9b1a9e21262232382d7ae53a0a84abafce191a873327e66dc4103a6`.
Phase 3 is not accepted. Slices 3c-3 (automation) and 3c-4 (measured master protection) remain. No sound has been heard from any build.
docs/evidence/phase3/2026-09-05-phase3c-lifecycle-voices.md
+52
View File
@@ -0,0 +1,52 @@
# Phase 3c slice 2 — audio lifecycle, release, and voice ceilings
**Date:** September 5, 2026
**Specification baseline:** Format Specification 0.1 revision 0.4, sections 15-16
**Result:** Implementation slice complete. All 67 tests pass. Two clean builds byte-identical.
## Scope
Phase 3c is delivered in four slices. This record covers **slice 3c-2 only**: the audio lifecycle state machine, internal release gain, determinable one-shot endings, voice ceilings, eviction policy, and disposal contract.
Slice 3c-2 implements:
1. **The seven-state lifecycle state machine** (16.3): `CREATED`, `SCHEDULED`, `ACTIVE`, `RELEASING`, `FINISHED`, `DISPOSED`, and `FAILED`, with strict enforcement of permitted transitions and rejection of forbidden transitions with `ERR_RUNTIME_FAULT`. Calling `stop()` on `FINISHED`, `DISPOSED`, or `FAILED` is a verified no-op.
2. **Engine-owned internal release gain** (16.4): Placed between sound graph `output` (`sink`) and destination bus (`[output] -> [release gain] -> [bus]`). Initial gain is 1.0. Entering `RELEASING` linearly ramps gain to 0 over `releaseDuration`. Unbypassable, non-addressable by authors, and omitted from author node limits.
3. **Recipe `release` field** (15.16, 16.4): Authorable `release` duration on `audio.recipes.<id>` and `sounds.<id>.recipe` within `0ms` to `10s` (default `50ms`). Rejected inside component definitions with `ERR_UNKNOWN_FIELD`.
4. **Determinable one-shot endings** (16.5): Computed via pure longest-path traversal over expanded DAG routes and node contributions (impulse duration, delay decay bound, reverb predelay + decay, resonator longest mode decay, component inlined bound, plus recipe release). An unbounded source (`oscillator` or `noise`) on an audible path in a `oneshot` sound is rejected at validation with `ERR_INDETERMINATE_ONESHOT`.
5. **Voice ceilings and 4-step eviction** (16.6): Independent ceilings for one-shot (`64`) and continuous (`16`) voices. A voice counts against its ceiling from `CREATED` until `DISPOSED`. Eviction policy runs in strict order:
- Step 1: Dispose oldest `FINISHED` instance.
- Step 2: Advance oldest `RELEASING` instance to immediate completion and dispose.
- Step 3 (one-shot only): Evict oldest `ACTIVE` one-shot by starting its release ramp.
- Step 4: Otherwise refuse request (continuous or no candidates), maintaining runtime stability.
- `WARN_VOICE_LIMIT` is emitted on every eviction and refusal. One-shot and continuous pools are strictly isolated and never evict across pools.
6. **Full disposal** (16.4, 16.6): Releases all Web Audio nodes, connections, buffers, timers, and pool memberships. A `FINISHED` instance continues to occupy its ceiling slot until `DISPOSED`.
7. **Scaffolding removal**: Replaced the fixed 4-second development timer in `src/runtime/app.js` with natural ending management by the engine.
## Specification reconciliation before implementation
A pre-implementation review of Section 16 identified 5 inconsistencies, corrected in commit `e5ed468`:
1. Section 15.16 allowed recipe fields table omitted `release`. Added `release` (DurationSpec, default 50ms, optional).
2. Section 16.6 eviction step 2 contradicted the non-hard-stop invariant. Reconciled step 2 to advance release to immediate completion and dispose, rather than immediate drop.
3. Section 16.8 unlock and 16.9 pause discard batching incoherence. Added `INFO_AUDIO_PAUSE_SKIP` to section 7 and 16.10 diagnostics tables.
4. Section 16.5 author remedy text suggested gating an oscillator with an impulse, which is illegal under 15.14 rule 2 (audio route into oscillator is forbidden). Corrected prose to declare `mode: "continuous"` and stop explicitly.
5. Clarified ending bound calculation on expanded graph where component boundaries are already inlined.
## Verification
- **Automated test suite**: All 67 tests pass cleanly with zero failures (`npm test`).
- **Required traces tested** (16.11):
- **Trace 7**: Permitted transitions succeed (`CREATED -> SCHEDULED -> ACTIVE -> RELEASING -> FINISHED -> DISPOSED`, `CREATED -> FINISHED`, `SCHEDULED -> RELEASING`, `ACTIVE -> FINISHED`, `* -> FAILED -> [terminal]`). Forbidden transitions throw `ERR_RUNTIME_FAULT`. Second stop on terminal states is idempotent.
- **Trace 9**: Determinable ending bounds match the section 16.5 contribution table across impulse, resonator, delay (with and without feedback), reverb, branching mixers, and component expansion. Unbounded oscillator/noise in a oneshot recipe is rejected with `ERR_INDETERMINATE_ONESHOT`, while continuous sounds with identical shapes validate cleanly.
- **Trace 10**: Eviction order 1 -> 2 -> 3 -> 4 is verified at ceiling. `WARN_VOICE_LIMIT` is emitted with sound and ceiling metadata. Continuous sound is never evicted by one-shot request, and refused request leaves runtime stable.
- **Trace 11**: Disposal releases every node and connection. A `FINISHED` instance still occupies its ceiling budget until `DISPOSED`.
- **Recipe `release` validation**: Validates `0ms` to `10s`, rejects out-of-bounds (`11s`), invalid duration strings (`-10ms`, `slow`), and rejects `release` declared inside components (`ERR_UNKNOWN_FIELD`).
- **Exhibit validation**: All three exhibits (`minimal-audio.xzbt`, `minimal-fixed.xzbt`, `minimal-random.xzbt`) validate cleanly with 0 errors via `tools/validate-exhibit.mjs`.
- **Deterministic build**: `node tools/build-xzbt.mjs` runs twice with identical digest:
`SHA-256 d7d16a89f9b1a9e21262232382d7ae53a0a84abafce191a873327e66dc4103a6` (172,825 bytes).
## Not established by this record
- **No automation tracks**: Automation tracks and modes (16.1, 16.2) belong to slice 3c-3.
- **No master protection measurement**: Master output protection (16.7) verification belongs to slice 3c-4 under GC6.
- **No sound has been heard from any build**: Automated tests verify Web Audio node topologies, connections, and state transitions against headless stand-ins. Real audible playback observations remain open.
- **Phase 3 is not accepted**: Slices 3c-3 and 3c-4 remain before Phase 3 can be submitted for acceptance.
schema/xzbt-0.1.schema.json
+3
View File
@@ -1616,6 +1616,9 @@
"oneshot",
"continuous"
]
},
"release": {
"$ref": "#/definitions/DurationSpec"
}
}
},
src/runtime/app.js
+1 -6
View File
@@ -214,12 +214,7 @@ export class XZBTApplication {
playSound(id) {
const current = this.activation.current;
if (!this.audio?.unlocked || !current) return;
const handle = this.audio.play(id, { resolveReference: (path) => current.performance.engine.get(path) });
if (handle?.mode === 'oneshot') {
// Phase 3b has no lifecycle contract yet (PRD 57 is Phase 3c), so a one-shot voice is
// released on a fixed development timer rather than on a determinable ending.
setTimeout(() => handle.stop(), 4000);
}
this.audio.play(id, { resolveReference: (path) => current.performance.engine.get(path) });
this.renderAudio();
}
src/runtime/audio-contract.js
+29 -1
View File
@@ -180,13 +180,41 @@ export const AUDIO_SOUND_FIELDS = Object.freeze(['name', 'tags', 'usage', 'caden
export const AUDIO_SOUND_USAGE = Object.freeze(['automatic', 'manual', 'scenario']);
export const AUDIO_RECIPE_MODES = Object.freeze(['oneshot', 'continuous']);
export const AUDIO_GRAPH_FIELDS = Object.freeze(['nodes', 'routes']);
export const AUDIO_RECIPE_FIELDS = Object.freeze(['nodes', 'routes', 'mode']);
export const AUDIO_RECIPE_FIELDS = Object.freeze(['nodes', 'routes', 'mode', 'release']);
export const AUDIO_COMPONENT_FIELDS = Object.freeze(['nodes', 'routes', 'parameters', 'input']);
export const AUDIO_COMPONENT_PARAMETER_FIELDS = Object.freeze(['type', 'default', 'min', 'max', 'unit']);
export const AUDIO_BUS_FIELDS = Object.freeze(['gain']);
export const AUDIO_BUS_GAIN_RANGE = Object.freeze({ min: 0, max: 4, default: 1 });
export const AUDIO_ROUTE_FIELDS = Object.freeze(['from', 'to', 'depth']);
export const AUDIO_VOICE_LIMITS = Object.freeze({
oneshot: 64,
continuous: 16
});
export const AUDIO_DEFAULT_RELEASE_MS = 50;
export const AUDIO_MAX_RELEASE_MS = 10000;
export const AUDIO_LIFECYCLE_STATES = Object.freeze([
'CREATED',
'SCHEDULED',
'ACTIVE',
'RELEASING',
'FINISHED',
'DISPOSED',
'FAILED'
]);
export const AUDIO_LIFECYCLE_TRANSITIONS = Object.freeze({
CREATED: Object.freeze(['SCHEDULED', 'FINISHED', 'FAILED']),
SCHEDULED: Object.freeze(['ACTIVE', 'RELEASING', 'FAILED']),
ACTIVE: Object.freeze(['RELEASING', 'FINISHED', 'FAILED']),
RELEASING: Object.freeze(['FINISHED', 'FAILED']),
FINISHED: Object.freeze(['DISPOSED']),
DISPOSED: Object.freeze([]),
FAILED: Object.freeze([])
});
export function audioMaxFrequency(sampleRate) {
if (!Number.isFinite(sampleRate) || sampleRate <= 0) return AUDIO_STATIC_MAX_FREQUENCY;
return Math.min(AUDIO_STATIC_MAX_FREQUENCY, sampleRate * AUDIO_NYQUIST_FACTOR);
src/runtime/audio-engine.js
+291 -25
View File
@@ -2,12 +2,20 @@
// Instantiation is pure and testable without an AudioContext (Format Specification 14.4-14.6).
import {
AUDIO_DEFAULT_RELEASE_MS,
AUDIO_LIFECYCLE_STATES,
AUDIO_LIFECYCLE_TRANSITIONS,
AUDIO_MODE_FIELDS,
AUDIO_NODE_TYPES,
AUDIO_PARTIAL_FIELDS,
AUDIO_VOICE_LIMITS,
audioMaxFrequency
} from './audio-contract.js';
import { durationMilliseconds, expandSoundGraph } from './audio-graph.js';
import {
computeDeterminableEndingBound,
durationMilliseconds,
expandSoundGraph
} from './audio-graph.js';
import { ValueResolver } from './values.js';
import { RuntimeFault, clamp } from './types.js';
@@ -29,7 +37,15 @@ export function instantiateSoundGraph(document, soundId, options = {}) {
const expansion = options.expansion ?? expandSoundGraph(document, soundId);
if (expansion.errors.length > 0) {
return { nodes: [], routes: [], warnings: [], errors: expansion.errors, mode: expansion.mode };
return {
nodes: [],
routes: [],
warnings: [],
errors: expansion.errors,
mode: expansion.mode,
release: expansion.release,
endingBoundMs: null
};
}
const ceiling = audioMaxFrequency(sampleRate);
@@ -147,7 +163,22 @@ export function instantiateSoundGraph(document, soundId, options = {}) {
return { ...route, depth: evaluate(route.depth, owner?.scope ?? null, `${route.path}.depth`) };
});
return { nodes, routes, warnings, errors: [], mode: expansion.mode, instanceKey, ceiling };
let endingBoundMs = null;
if (expansion.mode === 'oneshot') {
endingBoundMs = computeDeterminableEndingBound(expansion, nodes);
}
return {
nodes,
routes,
warnings,
errors: [],
mode: expansion.mode,
release: expansion.release,
endingBoundMs,
instanceKey,
ceiling
};
}
/* ------------------------------------------------------------------ *
@@ -243,7 +274,10 @@ export function realizeSoundGraph(context, plan, destination) {
const starters = [];
const sink = context.createGain();
sink.gain.value = 1;
sink.connect(destination);
const releaseGain = context.createGain();
releaseGain.gain.value = 1;
sink.connect(releaseGain).connect(destination);
disposers.push(() => releaseGain.disconnect());
created.set('output', { input: sink, output: sink });
const now = () => context.currentTime;
@@ -334,6 +368,7 @@ export function realizeSoundGraph(context, plan, destination) {
};
let tick = 0;
const timer = setInterval(() => { schedule(0); tick += 1; }, Math.max(10, period * 1000));
if (typeof timer.unref === 'function') timer.unref();
schedule(0);
entry = { input: null, output: source, params: {} };
starters.push(() => source.start());
@@ -457,26 +492,180 @@ export function realizeSoundGraph(context, plan, destination) {
return {
sink,
releaseGain,
dispose() {
for (const release of disposers.reverse()) {
try { release(); } catch { /* disposal is best effort */ }
}
sink.disconnect();
releaseGain.disconnect();
created.clear();
}
};
}
export class SoundInstance {
constructor({
soundId,
mode = 'oneshot',
releaseMs = AUDIO_DEFAULT_RELEASE_MS,
endingBoundMs = null,
plan = null,
subsystem = null,
bus = null,
context = null,
creationOrder = 0
} = {}) {
this.soundId = soundId;
this.mode = mode;
this.releaseMs = releaseMs ?? AUDIO_DEFAULT_RELEASE_MS;
this.endingBoundMs = endingBoundMs;
this.plan = plan;
this.subsystem = subsystem;
this.bus = bus;
this.context = context;
this.creationOrder = creationOrder;
this.state = 'CREATED';
this.realized = null;
this.startTime = null;
this.releaseTimer = null;
this.endingTimer = null;
}
canTransition(nextState) {
const allowed = AUDIO_LIFECYCLE_TRANSITIONS[this.state] ?? [];
return allowed.includes(nextState);
}
transition(nextState) {
if (!this.canTransition(nextState)) {
throw new RuntimeFault('ERR_RUNTIME_FAULT', `Invalid lifecycle transition from '${this.state}' to '${nextState}'.`);
}
this.state = nextState;
return true;
}
realize(context, destination) {
this.realized = realizeSoundGraph(context, this.plan, destination);
return this.realized;
}
stop() {
if (this.state === 'RELEASING' || this.state === 'FINISHED' || this.state === 'DISPOSED' || this.state === 'FAILED') {
return;
}
if (this.subsystem) {
this.subsystem.voices.delete(this);
}
if (this.state === 'CREATED') {
this.transition('FINISHED');
return;
}
if (this.state === 'SCHEDULED') {
this.transition('RELEASING');
if (this.releaseMs === 0) {
this.transition('FINISHED');
} else {
this.releaseTimer = setTimeout(() => {
if (this.state === 'RELEASING') {
this.transition('FINISHED');
}
}, this.releaseMs);
if (typeof this.releaseTimer?.unref === 'function') this.releaseTimer.unref();
}
return;
}
if (this.state === 'ACTIVE') {
if (this.endingTimer) {
clearTimeout(this.endingTimer);
this.endingTimer = null;
}
this.transition('RELEASING');
if (this.releaseMs === 0) {
if (this.realized?.releaseGain?.gain) {
const now = this.context?.currentTime ?? 0;
this.realized.releaseGain.gain.cancelScheduledValues?.(now);
this.realized.releaseGain.gain.setValueAtTime?.(0, now);
}
this.transition('FINISHED');
} else {
const now = this.context?.currentTime ?? 0;
const durationSec = this.releaseMs / 1000;
const gainParam = this.realized?.releaseGain?.gain;
if (gainParam) {
gainParam.cancelScheduledValues?.(now);
gainParam.setValueAtTime?.(gainParam.value, now);
gainParam.linearRampToValueAtTime?.(0, now + durationSec);
}
this.releaseTimer = setTimeout(() => {
if (this.state === 'RELEASING') {
this.transition('FINISHED');
}
}, this.releaseMs);
if (typeof this.releaseTimer?.unref === 'function') this.releaseTimer.unref();
}
}
}
forceFinishAndDispose() {
if (this.state === 'RELEASING') {
if (this.releaseTimer) {
clearTimeout(this.releaseTimer);
this.releaseTimer = null;
}
if (this.realized?.releaseGain?.gain) {
const now = this.context?.currentTime ?? 0;
this.realized.releaseGain.gain.cancelScheduledValues?.(now);
this.realized.releaseGain.gain.setValueAtTime?.(0, now);
}
this.transition('FINISHED');
}
this.dispose();
}
dispose() {
if (this.state === 'DISPOSED') return;
if (this.releaseTimer) {
clearTimeout(this.releaseTimer);
this.releaseTimer = null;
}
if (this.endingTimer) {
clearTimeout(this.endingTimer);
this.endingTimer = null;
}
if (this.subsystem) {
this.subsystem.voices.delete(this);
this.subsystem.oneshotVoices?.delete(this);
this.subsystem.continuousVoices?.delete(this);
}
if (this.state !== 'FINISHED' && this.state !== 'FAILED') {
if (this.state === 'ACTIVE' || this.state === 'SCHEDULED') {
this.transition('RELEASING');
this.transition('FINISHED');
} else if (this.state === 'CREATED') {
this.transition('FINISHED');
} else if (this.state === 'RELEASING') {
this.transition('FINISHED');
}
}
this.transition('DISPOSED');
if (this.realized) {
try { this.realized.dispose(); } catch { /* best effort */ }
this.realized = null;
}
}
}
/* ------------------------------------------------------------------ *
* Runtime subsystem
* ------------------------------------------------------------------ */
// Owns the AudioContext, the declared buses, and the engine master chain, and turns a
// sound definition into a realized voice. The lifecycle state machine (PRD 57), voice
// ceilings, and the measured master-protection contract (PRD 58) are Phase 3c; the master
// chain built here is engine-owned and unbypassable but its ceiling is not yet verified.
// ceilings (16.6), and the measured master-protection contract (PRD 58) are Phase 3c;
// the master chain built here is engine-owned and unbypassable.
export class AudioSubsystem {
constructor({ document, rng, diagnostics = null, contextFactory = null } = {}) {
constructor({ document, rng, diagnostics = null, contextFactory = null, voiceLimits = null } = {}) {
this.document = document;
this.rng = rng;
this.diagnostics = diagnostics;
@@ -487,7 +676,11 @@ export class AudioSubsystem {
this.protection = null;
this.buses = new Map();
this.voices = new Set();
this.oneshotVoices = new Set();
this.continuousVoices = new Set();
this.voiceLimits = voiceLimits ?? { ...AUDIO_VOICE_LIMITS };
this.ordinals = new Map();
this.nextCreationOrder = 0;
this.masterVolume = 0.8;
}
@@ -560,41 +753,114 @@ export class AudioSubsystem {
play(soundId, { resolveReference } = {}) {
if (!this.unlocked) return null;
const sound = this.document?.sounds?.[soundId];
if (!sound) return null;
const expansion = expandSoundGraph(this.document, soundId);
if (expansion.errors.length > 0) {
for (const error of expansion.errors) this.diagnostics?.error(error.code, error.message, { section: 'audio', objectId: soundId });
return null;
}
const mode = expansion.mode ?? 'oneshot';
const pool = mode === 'oneshot' ? this.oneshotVoices : this.continuousVoices;
const ceiling = mode === 'oneshot' ? this.voiceLimits.oneshot : this.voiceLimits.continuous;
if (pool.size >= ceiling) {
// 16.6 Eviction policy applied in strict order:
// 1. Dispose the oldest instance already in FINISHED.
const finishedInstances = [...pool].filter((i) => i.state === 'FINISHED');
if (finishedInstances.length > 0) {
finishedInstances.sort((a, b) => a.creationOrder - b.creationOrder);
const candidate = finishedInstances[0];
candidate.dispose();
this.diagnostics?.warn('WARN_VOICE_LIMIT', `Voice ceiling (${ceiling}) reached for '${soundId}'; disposed oldest FINISHED instance of '${candidate.soundId}'.`, { section: 'audio', objectId: soundId });
} else {
// 2. Evict the oldest instance in RELEASING by advancing its release ramp to immediate completion and disposing it.
const releasingInstances = [...pool].filter((i) => i.state === 'RELEASING');
if (releasingInstances.length > 0) {
releasingInstances.sort((a, b) => a.creationOrder - b.creationOrder);
const candidate = releasingInstances[0];
candidate.forceFinishAndDispose();
this.diagnostics?.warn('WARN_VOICE_LIMIT', `Voice ceiling (${ceiling}) reached for '${soundId}'; evicted oldest RELEASING instance of '${candidate.soundId}'.`, { section: 'audio', objectId: soundId });
} else if (mode === 'oneshot') {
// 3. For a one-shot request only: evict the oldest ACTIVE one-shot by starting its release.
const activeInstances = [...pool].filter((i) => i.state === 'ACTIVE' || i.state === 'SCHEDULED');
if (activeInstances.length > 0) {
activeInstances.sort((a, b) => a.creationOrder - b.creationOrder);
const candidate = activeInstances[0];
candidate.stop();
this.diagnostics?.warn('WARN_VOICE_LIMIT', `Voice ceiling (${ceiling}) reached for '${soundId}'; evicting oldest ACTIVE oneshot instance of '${candidate.soundId}' via release.`, { section: 'audio', objectId: soundId });
} else {
this.diagnostics?.warn('WARN_VOICE_LIMIT', `Voice ceiling (${ceiling}) reached for '${soundId}'; request refused.`, { section: 'audio', objectId: soundId });
return null;
}
} else {
// 4. Otherwise refuse the new instance.
this.diagnostics?.warn('WARN_VOICE_LIMIT', `Voice ceiling (${ceiling}) reached for '${soundId}'; continuous request refused.`, { section: 'audio', objectId: soundId });
return null;
}
}
}
const plan = instantiateSoundGraph(this.document, soundId, {
sampleRate: this.context.sampleRate,
rng: this.rng,
ordinal: this.nextOrdinal(soundId),
resolveReference
resolveReference,
expansion
});
for (const error of plan.errors) this.diagnostics?.error(error.code, error.message, { section: 'audio', objectId: soundId });
if (plan.errors.length > 0) return null;
for (const warning of plan.warnings) this.diagnostics?.warn(warning.code, warning.message, { section: 'audio', objectId: soundId, property: warning.path });
let voice;
try {
voice = realizeSoundGraph(this.context, plan, this.busFor(soundId));
} catch (error) {
this.diagnostics?.error('ERR_AUDIO_REALIZATION', `Sound '${soundId}' could not be realized: ${error.message}`, { section: 'audio', objectId: soundId });
return null;
}
const handle = {
const instance = new SoundInstance({
soundId,
mode: plan.mode,
stop: () => {
if (!this.voices.has(handle)) return;
this.voices.delete(handle);
voice.dispose();
}
};
this.voices.add(handle);
return handle;
releaseMs: plan.release,
endingBoundMs: plan.endingBoundMs,
plan,
subsystem: this,
bus: this.busFor(soundId),
context: this.context,
creationOrder: this.nextCreationOrder++
});
pool.add(instance);
try {
instance.transition('SCHEDULED');
instance.realize(this.context, this.busFor(soundId));
instance.transition('ACTIVE');
instance.startTime = this.context.currentTime;
this.voices.add(instance);
} catch (error) {
this.diagnostics?.error('ERR_AUDIO_REALIZATION', `Sound '${soundId}' could not be realized: ${error.message}`, { section: 'audio', objectId: soundId });
instance.transition('FAILED');
instance.dispose();
return null;
}
if (mode === 'oneshot' && instance.endingBoundMs != null && Number.isFinite(instance.endingBoundMs)) {
instance.endingTimer = setTimeout(() => {
if (instance.state === 'ACTIVE') {
this.voices.delete(instance);
instance.transition('FINISHED');
}
}, instance.endingBoundMs);
if (typeof instance.endingTimer?.unref === 'function') instance.endingTimer.unref();
}
return instance;
}
stopAll() {
for (const handle of [...this.voices]) handle.stop();
for (const instance of [...this.voices]) instance.stop();
}
async dispose() {
this.stopAll();
for (const instance of [...this.oneshotVoices]) instance.dispose();
for (const instance of [...this.continuousVoices]) instance.dispose();
this.buses.clear();
if (this.context) {
try { await this.context.close(); } catch { /* already closed */ }
src/runtime/audio-graph.js
+134 -2
View File
@@ -12,6 +12,8 @@ import {
AUDIO_MODULATABLE,
AUDIO_MODULATION_SOURCE_TYPES,
AUDIO_NODE_TYPES,
AUDIO_DEFAULT_RELEASE_MS,
AUDIO_MAX_RELEASE_MS,
AUDIO_PARTIAL_FIELDS,
AUDIO_RECIPE_FIELDS,
AUDIO_RECIPE_MODES,
@@ -252,7 +254,7 @@ export function expandSoundGraph(document, soundId) {
const sound = document.sounds?.[soundId];
const soundPath = `$.sounds.${soundId}`;
const located = recipeGraphFor(document, sound, soundPath, errors);
if (!located) return { nodes: [], routes: [], errors, mode: 'oneshot' };
if (!located) return { nodes: [], routes: [], errors, mode: 'oneshot', release: AUDIO_DEFAULT_RELEASE_MS };
const nodes = new Map();
const routes = [];
@@ -364,7 +366,10 @@ export function expandSoundGraph(document, soundId) {
expand(located.graph, '', 1, [], located.path);
const mode = AUDIO_RECIPE_MODES.includes(located.graph.mode) ? located.graph.mode : 'oneshot';
return { nodes: [...nodes.values()], routes, errors, mode, graphPath: located.path };
const release = Object.hasOwn(located.graph, 'release')
? (durationMilliseconds(located.graph.release) ?? AUDIO_DEFAULT_RELEASE_MS)
: AUDIO_DEFAULT_RELEASE_MS;
return { nodes: [...nodes.values()], routes, errors, mode, release, graphPath: located.path };
}
function detectCycle(adjacency) {
@@ -467,6 +472,9 @@ export function checkGraphLegality(document, soundId, expansion, errors) {
fail(errors, 'ERR_INVALID_ROUTE', node.path, `Control source '${node.path}' reaches audible output.`);
} else {
audiblePath = true;
if (expansion.mode === 'oneshot' && (node.type === 'oscillator' || node.type === 'noise')) {
fail(errors, 'ERR_INDETERMINATE_ONESHOT', graphPath, `Sound '${soundId}' is a oneshot with an unbounded audible path from '${node.path}' (${node.type}).`);
}
}
}
if (contract.acceptsAudio === false) {
@@ -515,6 +523,9 @@ export function validateAudioSubsystem(document, errors, helpers) {
if (Object.hasOwn(recipe, 'mode') && !AUDIO_RECIPE_MODES.includes(recipe.mode)) {
fail(errors, 'ERR_TYPE_MISMATCH', `${path}.mode`, `Recipe mode must be one of: ${AUDIO_RECIPE_MODES.join(', ')}.`);
}
if (Object.hasOwn(recipe, 'release')) {
validateDurationField(recipe.release, { min: 0, max: AUDIO_MAX_RELEASE_MS }, `${path}.release`, errors);
}
}
}
}
@@ -581,9 +592,130 @@ export function validateAudioSubsystem(document, errors, helpers) {
if (Object.hasOwn(sound.recipe, 'mode') && !AUDIO_RECIPE_MODES.includes(sound.recipe.mode)) {
fail(errors, 'ERR_TYPE_MISMATCH', `${path}.recipe.mode`, `Recipe mode must be one of: ${AUDIO_RECIPE_MODES.join(', ')}.`);
}
if (Object.hasOwn(sound.recipe, 'release')) {
validateDurationField(sound.recipe.release, { min: 0, max: AUDIO_MAX_RELEASE_MS }, `${path}.recipe.release`, errors);
}
}
const expansion = expandSoundGraph(document, id);
errors.push(...expansion.errors);
if (expansion.nodes.length > 0) checkGraphLegality(document, id, expansion, errors);
}
}
export function computeDeterminableEndingBound(expansion, resolvedNodes = null) {
const { nodes, routes, release = AUDIO_DEFAULT_RELEASE_MS } = expansion;
const resolvedMap = resolvedNodes instanceof Map
? resolvedNodes
: Array.isArray(resolvedNodes)
? new Map(resolvedNodes.map((n) => [n.path, n]))
: null;
const nodeMap = new Map(nodes.map((n) => [n.path, n]));
function nodeContribution(path) {
if (path === 'output') return 0;
const node = nodeMap.get(path);
if (!node || node.implicit || node.type === 'component') return 0;
const type = node.type;
const resolved = resolvedMap?.get(path)?.values;
if (type === 'impulse') {
if (resolved && typeof resolved.duration === 'number') return resolved.duration;
return durationMilliseconds(node.spec?.duration ?? '10ms') ?? 10;
}
if (type === 'oscillator' || type === 'noise') {
return Infinity;
}
if (type === 'delay') {
let time, feedback;
if (resolved) {
time = resolved.time ?? 250;
feedback = resolved.feedback ?? 0.2;
} else {
time = durationMilliseconds(node.spec?.time ?? '250ms') ?? 250;
feedback = typeof node.spec?.feedback === 'number' ? node.spec.feedback : 0.2;
}
if (feedback > 0) {
const clampedFeedback = Math.min(0.9999, Math.max(1e-6, feedback));
const multiplier = Math.ceil(Math.log(0.001) / Math.log(clampedFeedback));
return time * multiplier;
}
return time;
}
if (type === 'reverb') {
let predelay, decay;
if (resolved) {
predelay = resolved.predelay ?? 0;
decay = resolved.decay ?? 2000;
} else {
predelay = durationMilliseconds(node.spec?.predelay ?? '0ms') ?? 0;
decay = durationMilliseconds(node.spec?.decay ?? '2s') ?? 2000;
}
return predelay + decay;
}
if (type === 'resonator') {
if (resolved?.modes && Array.isArray(resolved.modes) && resolved.modes.length > 0) {
return Math.max(...resolved.modes.map((m) => m.decay ?? 1000));
}
const modes = node.spec?.modes ?? [];
if (modes.length > 0) {
return Math.max(...modes.map((m) => durationMilliseconds(m.decay ?? '1s') ?? 1000));
}
return 1000;
}
return 0;
}
const audioAdjacency = new Map();
const inDegree = new Map();
const allNodes = new Set();
for (const n of nodes) allNodes.add(n.path);
allNodes.add('output');
for (const n of allNodes) {
audioAdjacency.set(n, []);
inDegree.set(n, 0);
}
for (const route of routes) {
if (route.kind === 'audio') {
if (!audioAdjacency.has(route.from)) audioAdjacency.set(route.from, []);
audioAdjacency.get(route.from).push(route.to);
inDegree.set(route.to, (inDegree.get(route.to) ?? 0) + 1);
}
}
const dist = new Map();
for (const n of allNodes) dist.set(n, -Infinity);
for (const n of nodes) {
if (n.implicit || n.type === 'component') continue;
if (n.type === 'impulse' || n.type === 'oscillator' || n.type === 'noise') {
dist.set(n.path, nodeContribution(n.path));
}
}
const queue = [];
for (const [node, deg] of inDegree.entries()) {
if (deg === 0) queue.push(node);
}
while (queue.length > 0) {
const current = queue.shift();
const currentDist = dist.get(current);
for (const next of audioAdjacency.get(current) ?? []) {
if (currentDist !== -Infinity) {
const nextContrib = nodeContribution(next);
const newDist = currentDist === Infinity ? Infinity : currentDist + nextContrib;
if (newDist > dist.get(next)) dist.set(next, newDist);
}
inDegree.set(next, inDegree.get(next) - 1);
if (inDegree.get(next) === 0) queue.push(next);
}
}
const outDist = dist.get('output');
if (outDist === Infinity) return Infinity;
if (outDist === -Infinity) return release;
return outDist + release;
}
test/phase3-audio.test.mjs
+506 -3
View File
@@ -1,13 +1,24 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import {
AUDIO_DEFAULT_RELEASE_MS,
AUDIO_LIFECYCLE_STATES,
AUDIO_LIFECYCLE_TRANSITIONS,
AUDIO_LIMITS,
AUDIO_MAX_RELEASE_MS,
AUDIO_NODE_TYPE_NAMES,
AUDIO_STATIC_MAX_FREQUENCY,
AUDIO_VOICE_LIMITS,
audioMaxFrequency
} from '../src/runtime/audio-contract.js';
import { expandSoundGraph } from '../src/runtime/audio-graph.js';
import { instantiateSoundGraph, sampleHoldStreamKey } from '../src/runtime/audio-engine.js';
import { computeDeterminableEndingBound, expandSoundGraph } from '../src/runtime/audio-graph.js';
import {
AudioSubsystem,
SoundInstance,
instantiateSoundGraph,
realizeSoundGraph,
sampleHoldStreamKey
} from '../src/runtime/audio-engine.js';
import { SeededRNG } from '../src/runtime/rng.js';
import { validateExhibit } from '../src/runtime/validator.js';
@@ -29,6 +40,7 @@ function soundWith(nodes = {}, routes = [], soundOverrides = {}, documentOverrid
name: 'Probe',
bus: 'ambient',
recipe: {
mode: 'continuous',
nodes: { tone: { type: 'oscillator' }, ...nodes },
routes: [{ from: 'tone', to: 'output' }, ...routes]
},
@@ -225,7 +237,7 @@ test('a control-only path fails while the same shape with an audible source pass
});
assert.ok(codes(controlOnly).includes('ERR_INVALID_ROUTE'));
clean(exhibit({
sounds: { probe: { name: 'Probe', recipe: { nodes: { tone: { type: 'oscillator' }, level: { type: 'gain' } }, routes: [{ from: 'tone', to: 'level' }, { from: 'level', to: 'output' }] } } }
sounds: { probe: { name: 'Probe', recipe: { mode: 'continuous', nodes: { tone: { type: 'oscillator' }, level: { type: 'gain' } }, routes: [{ from: 'tone', to: 'level' }, { from: 'level', to: 'output' }] } } }
}));
});
@@ -271,6 +283,7 @@ const componentDocument = (overrides = {}) => exhibit({
probe: {
name: 'Probe',
recipe: {
mode: 'continuous',
nodes: { a: { type: 'component', use: 'voice', values: { pitch: 330 } } },
routes: [{ from: 'a', to: 'output' }]
}
@@ -484,4 +497,494 @@ test('every node type realizes against an AudioContext stand-in and disposes cle
assert.equal(subsystem.buses.get('ambient').gain.value, 2);
subsystem.stopAll();
assert.equal(subsystem.voices.size, 0);
await subsystem.dispose();
});
/* --- 15.16 recipe release field validation ------------------------------------ */
test('recipe release duration validates in 0ms to 10s and rejects out of bounds or invalid', () => {
clean(exhibit({
audio: { buses: { ambient: { gain: 1 } }, recipes: { shared: { release: '0ms', mode: 'continuous', nodes: { tone: { type: 'oscillator' } }, routes: [{ from: 'tone', to: 'output' }] } } },
sounds: { probe: { name: 'Probe', bus: 'ambient', recipe: { use: 'shared' } } }
}));
clean(exhibit({
audio: { buses: { ambient: { gain: 1 } } },
sounds: { probe: { name: 'Probe', bus: 'ambient', recipe: { release: '10s', mode: 'continuous', nodes: { tone: { type: 'oscillator' } }, routes: [{ from: 'tone', to: 'output' }] } } }
}));
// invalid duration format
assert.ok(codes(exhibit({
sounds: { probe: { name: 'Probe', recipe: { release: '-10ms', nodes: { hit: { type: 'impulse' } }, routes: [{ from: 'hit', to: 'output' }] } } }
})).includes('ERR_INVALID_DURATION'));
// exceeds 10s (fails bounds)
assert.ok(codes(exhibit({
sounds: { probe: { name: 'Probe', recipe: { release: '11s', nodes: { hit: { type: 'impulse' } }, routes: [{ from: 'hit', to: 'output' }] } } }
})).includes('ERR_OUT_OF_BOUNDS'));
// invalid format string
assert.ok(codes(exhibit({
sounds: { probe: { name: 'Probe', recipe: { release: 'slow', nodes: { hit: { type: 'impulse' } }, routes: [{ from: 'hit', to: 'output' }] } } }
})).includes('ERR_INVALID_DURATION'));
// release inside a component graph is rejected (it is a recipe field, not a component field)
assert.ok(codes(exhibit({
components: {
audio: {
piece: {
release: '50ms',
nodes: { hit: { type: 'impulse' } },
routes: [{ from: 'hit', to: 'output' }]
}
}
},
sounds: { probe: { name: 'Probe', recipe: { nodes: { c: { type: 'component', use: 'piece' } }, routes: [{ from: 'c', to: 'output' }] } } }
})).includes('ERR_UNKNOWN_FIELD'));
});
/* --- 16.11 trace 7: lifecycle states and permitted/forbidden transitions ----- */
test('trace 7: permitted lifecycle transitions succeed, forbidden transitions are rejected, and stop on terminal states is idempotent', () => {
// Test valid linear lifecycle: CREATED -> SCHEDULED -> ACTIVE -> RELEASING -> FINISHED -> DISPOSED
const instance = new SoundInstance({ soundId: 'test-sound', mode: 'oneshot', releaseMs: 50 });
assert.equal(instance.state, 'CREATED');
assert.ok(instance.canTransition('SCHEDULED'));
assert.ok(instance.canTransition('FINISHED'));
assert.ok(instance.canTransition('FAILED'));
assert.equal(instance.canTransition('ACTIVE'), false);
assert.equal(instance.canTransition('RELEASING'), false);
assert.equal(instance.canTransition('DISPOSED'), false);
instance.transition('SCHEDULED');
assert.equal(instance.state, 'SCHEDULED');
assert.ok(instance.canTransition('ACTIVE'));
assert.ok(instance.canTransition('RELEASING'));
assert.ok(instance.canTransition('FAILED'));
assert.equal(instance.canTransition('FINISHED'), false);
assert.equal(instance.canTransition('DISPOSED'), false);
instance.transition('ACTIVE');
assert.equal(instance.state, 'ACTIVE');
assert.ok(instance.canTransition('RELEASING'));
assert.ok(instance.canTransition('FINISHED'));
assert.ok(instance.canTransition('FAILED'));
assert.equal(instance.canTransition('SCHEDULED'), false);
assert.equal(instance.canTransition('CREATED'), false);
assert.equal(instance.canTransition('DISPOSED'), false);
instance.transition('RELEASING');
assert.equal(instance.state, 'RELEASING');
assert.ok(instance.canTransition('FINISHED'));
assert.ok(instance.canTransition('FAILED'));
assert.equal(instance.canTransition('ACTIVE'), false);
assert.equal(instance.canTransition('DISPOSED'), false);
instance.transition('FINISHED');
assert.equal(instance.state, 'FINISHED');
assert.ok(instance.canTransition('DISPOSED'));
assert.equal(instance.canTransition('ACTIVE'), false);
assert.equal(instance.canTransition('RELEASING'), false);
instance.transition('DISPOSED');
assert.equal(instance.state, 'DISPOSED');
assert.equal(instance.canTransition('ACTIVE'), false);
assert.equal(instance.canTransition('FINISHED'), false);
// Forbidden transition raises ERR_RUNTIME_FAULT
const fresh = new SoundInstance({ soundId: 'fresh', mode: 'oneshot' });
assert.throws(() => fresh.transition('ACTIVE'), (err) => err.code === 'ERR_RUNTIME_FAULT');
assert.throws(() => fresh.transition('DISPOSED'), (err) => err.code === 'ERR_RUNTIME_FAULT');
// Alternative paths:
// CREATED -> FINISHED (stop before scheduling)
const createdStop = new SoundInstance({ soundId: 'created-stop', mode: 'oneshot' });
createdStop.stop();
assert.equal(createdStop.state, 'FINISHED');
// SCHEDULED -> RELEASING (stop while scheduled)
const schedStop = new SoundInstance({ soundId: 'sched-stop', mode: 'oneshot', releaseMs: 0 });
schedStop.transition('SCHEDULED');
schedStop.stop();
assert.equal(schedStop.state, 'FINISHED');
// ACTIVE -> FINISHED without release (natural determinable ending for one-shot)
const endingOneshot = new SoundInstance({ soundId: 'ending', mode: 'oneshot' });
endingOneshot.transition('SCHEDULED');
endingOneshot.transition('ACTIVE');
endingOneshot.transition('FINISHED');
assert.equal(endingOneshot.state, 'FINISHED');
// FAILED is terminal (PRD 57, 16.3)
const failedInstance = new SoundInstance({ soundId: 'failed', mode: 'oneshot' });
failedInstance.transition('FAILED');
assert.equal(failedInstance.state, 'FAILED');
assert.equal(failedInstance.canTransition('DISPOSED'), false);
assert.equal(failedInstance.canTransition('ACTIVE'), false);
assert.throws(() => failedInstance.transition('DISPOSED'), (err) => err.code === 'ERR_RUNTIME_FAULT');
// Idempotence: calling stop() on FINISHED, DISPOSED, FAILED, or RELEASING is a no-op
const terminal = new SoundInstance({ soundId: 'terminal', mode: 'oneshot' });
terminal.transition('FINISHED');
terminal.stop();
assert.equal(terminal.state, 'FINISHED');
terminal.transition('DISPOSED');
terminal.stop();
assert.equal(terminal.state, 'DISPOSED');
const failedTerminal = new SoundInstance({ soundId: 'failed-term', mode: 'oneshot' });
failedTerminal.transition('FAILED');
failedTerminal.stop();
assert.equal(failedTerminal.state, 'FAILED');
});
/* --- 16.11 trace 9: determinable one-shot endings ----------------------------- */
test('trace 9: determinable ending bounds match section 16.5 table and reject unbounded sources in oneshots', () => {
// 1. Impulse only: duration + release
const impulseDoc = exhibit({
sounds: {
hit: {
name: 'Hit',
recipe: {
release: '50ms',
nodes: { pulse: { type: 'impulse', duration: '20ms' } },
routes: [{ from: 'pulse', to: 'output' }]
}
}
}
});
clean(impulseDoc);
const impulseExpansion = expandSoundGraph(impulseDoc, 'hit');
const impulseBound = computeDeterminableEndingBound(impulseExpansion);
assert.equal(impulseBound, 20 + 50);
// 2. Impulse -> Resonator
const resonatorDoc = exhibit({
sounds: {
bell: {
name: 'Bell',
recipe: {
release: '50ms',
nodes: {
hit: { type: 'impulse', duration: '6ms' },
body: {
type: 'resonator',
modes: [
{ ratio: 1, decay: '260ms' },
{ ratio: 2.7, decay: '140ms' },
{ ratio: 5.4, decay: '70ms' }
]
}
},
routes: [{ from: 'hit', to: 'body' }, { from: 'body', to: 'output' }]
}
}
}
});
clean(resonatorDoc);
const resonatorBound = computeDeterminableEndingBound(expandSoundGraph(resonatorDoc, 'bell'));
assert.equal(resonatorBound, 6 + 260 + 50);
// 3. Impulse -> Delay with feedback
// feedback = 0.5: Math.ceil(Math.log(0.001) / Math.log(0.5)) = 10
// delay time = 200ms -> delay bound = 2000ms
const delayDoc = exhibit({
sounds: {
echo: {
name: 'Echo',
recipe: {
release: '50ms',
nodes: {
hit: { type: 'impulse', duration: '10ms' },
d: { type: 'delay', time: '200ms', feedback: 0.5 }
},
routes: [{ from: 'hit', to: 'd' }, { from: 'd', to: 'output' }]
}
}
}
});
clean(delayDoc);
const delayBound = computeDeterminableEndingBound(expandSoundGraph(delayDoc, 'echo'));
assert.equal(delayBound, 10 + (200 * 10) + 50);
// 4. Impulse -> Delay with feedback 0 -> multiplier is 1 (time alone)
const delayZeroDoc = exhibit({
sounds: {
echo: {
name: 'Echo',
recipe: {
release: '50ms',
nodes: {
hit: { type: 'impulse', duration: '10ms' },
d: { type: 'delay', time: '200ms', feedback: 0 }
},
routes: [{ from: 'hit', to: 'd' }, { from: 'd', to: 'output' }]
}
}
}
});
clean(delayZeroDoc);
const delayZeroBound = computeDeterminableEndingBound(expandSoundGraph(delayZeroDoc, 'echo'));
assert.equal(delayZeroBound, 10 + 200 + 50);
// 5. Impulse -> Reverb: predelay + decay
const reverbDoc = exhibit({
sounds: {
hall: {
name: 'Hall',
recipe: {
release: '50ms',
nodes: {
hit: { type: 'impulse', duration: '10ms' },
verb: { type: 'reverb', predelay: '40ms', decay: '1500ms' }
},
routes: [{ from: 'hit', to: 'verb' }, { from: 'verb', to: 'output' }]
}
}
}
});
clean(reverbDoc);
const reverbBound = computeDeterminableEndingBound(expandSoundGraph(reverbDoc, 'hall'));
assert.equal(reverbBound, 10 + (40 + 1500) + 50);
// 6. Branching paths to mixer: longest path wins
// Path A: hit (10ms) -> delay (time 100ms, feedback 0) = 110ms
// Path B: hit (10ms) -> verb (predelay 0ms, decay 800ms) = 810ms
const branchDoc = exhibit({
sounds: {
dual: {
name: 'Dual',
recipe: {
release: '50ms',
nodes: {
hit: { type: 'impulse', duration: '10ms' },
d: { type: 'delay', time: '100ms', feedback: 0 },
v: { type: 'reverb', predelay: '0ms', decay: '800ms' },
mix: { type: 'mixer' }
},
routes: [
{ from: 'hit', to: 'd' }, { from: 'hit', to: 'v' },
{ from: 'd', to: 'mix' }, { from: 'v', to: 'mix' },
{ from: 'mix', to: 'output' }
]
}
}
}
});
clean(branchDoc);
const branchBound = computeDeterminableEndingBound(expandSoundGraph(branchDoc, 'dual'));
assert.equal(branchBound, 10 + 800 + 50);
// 7. Unbounded source in oneshot rejected with ERR_INDETERMINATE_ONESHOT
const oscOneshot = exhibit({
sounds: {
tone: {
name: 'Tone',
recipe: {
mode: 'oneshot',
nodes: { osc: { type: 'oscillator' } },
routes: [{ from: 'osc', to: 'output' }]
}
}
}
});
assert.ok(codes(oscOneshot).includes('ERR_INDETERMINATE_ONESHOT'));
const noiseOneshot = exhibit({
sounds: {
hiss: {
name: 'Hiss',
recipe: {
mode: 'oneshot',
nodes: { n: { type: 'noise' } },
routes: [{ from: 'n', to: 'output' }]
}
}
}
});
assert.ok(codes(noiseOneshot).includes('ERR_INDETERMINATE_ONESHOT'));
// 8. Continuous sound with identical shape validates cleanly
const oscContinuous = exhibit({
sounds: {
tone: {
name: 'Tone',
recipe: {
mode: 'continuous',
nodes: { osc: { type: 'oscillator' } },
routes: [{ from: 'osc', to: 'output' }]
}
}
}
});
clean(oscContinuous);
const noiseContinuous = exhibit({
sounds: {
hiss: {
name: 'Hiss',
recipe: {
mode: 'continuous',
nodes: { n: { type: 'noise' } },
routes: [{ from: 'n', to: 'output' }]
}
}
}
});
clean(noiseContinuous);
});
/* --- 16.11 trace 10: voice ceilings, eviction order, and refusal stability --- */
test('trace 10: eviction order is followed at ceiling, WARN_VOICE_LIMIT raised, no cross-pool eviction, and refusal is stable', async () => {
const warnings = [];
const diagnostics = {
warn(code, message, meta) { warnings.push({ code, message, meta }); },
error(code, message, meta) { /* errors */ }
};
const doc = exhibit({
sounds: {
short: {
name: 'Short',
recipe: {
mode: 'oneshot',
release: '50ms',
nodes: { hit: { type: 'impulse', duration: '5ms' } },
routes: [{ from: 'hit', to: 'output' }]
}
},
drone: {
name: 'Drone',
recipe: {
mode: 'continuous',
release: '50ms',
nodes: { tone: { type: 'oscillator' } },
routes: [{ from: 'tone', to: 'output' }]
}
}
}
});
// Test with compact voice limits: 3 oneshots, 2 continuous
const limits = { oneshot: 3, continuous: 2 };
const subsystem = new AudioSubsystem({
document: doc,
rng: new SeededRNG(42),
contextFactory: () => mockContext(),
diagnostics,
voiceLimits: limits
});
await subsystem.unlock();
// 1. Fill oneshot pool to ceiling (3 instances)
const v1 = subsystem.play('short');
const v2 = subsystem.play('short');
const v3 = subsystem.play('short');
assert.equal(subsystem.oneshotVoices.size, 3);
assert.equal(warnings.length, 0);
// 2. Put v1 into FINISHED state
v1.transition('RELEASING');
v1.transition('FINISHED');
assert.equal(subsystem.oneshotVoices.size, 3); // Still counts in FINISHED!
// 3. Play a 4th oneshot -> Eviction step 1: should dispose oldest FINISHED (v1)
const v4 = subsystem.play('short');
assert.ok(v4);
assert.equal(v1.state, 'DISPOSED');
assert.equal(subsystem.oneshotVoices.size, 3);
assert.equal(warnings.filter((w) => w.code === 'WARN_VOICE_LIMIT').length, 1);
// 4. Put v2 into RELEASING state (no FINISHED instances remain)
v2.transition('RELEASING');
// Play a 5th oneshot -> Eviction step 2: should advance oldest RELEASING (v2) to FINISHED & DISPOSED
const v5 = subsystem.play('short');
assert.ok(v5);
assert.equal(v2.state, 'DISPOSED');
assert.equal(subsystem.oneshotVoices.size, 3);
assert.equal(warnings.filter((w) => w.code === 'WARN_VOICE_LIMIT').length, 2);
// 5. Now all instances are ACTIVE (v3, v4, v5).
// Play a 6th oneshot -> Eviction step 3 (oneshot only): evict oldest ACTIVE (v3) by starting release
const v6 = subsystem.play('short');
assert.ok(v6);
assert.equal(v3.state, 'RELEASING');
assert.equal(warnings.filter((w) => w.code === 'WARN_VOICE_LIMIT').length, 3);
// 6. Test Continuous sound pool ceiling and refusal
const c1 = subsystem.play('drone');
const c2 = subsystem.play('drone');
assert.equal(subsystem.continuousVoices.size, 2);
// Oneshot requests DO NOT evict continuous sounds (independent pools)
assert.equal(subsystem.continuousVoices.size, 2);
// Continuous pool is at ceiling (2 active instances).
// A 3rd continuous request cannot evict ACTIVE continuous sounds -> step 4 Refusal!
const c3 = subsystem.play('drone');
assert.equal(c3, null);
assert.equal(subsystem.continuousVoices.size, 2);
const refusalWarn = warnings.find((w) => w.code === 'WARN_VOICE_LIMIT' && w.message.includes('continuous'));
assert.ok(refusalWarn);
// Subsystem and runtime remain stable after refusal
assert.equal(subsystem.unlocked, true);
subsystem.stopAll();
await subsystem.dispose();
});
/* --- 16.11 trace 11: disposal completeness and ceiling occupancy ------------- */
test('trace 11: disposal releases all nodes/connections/buffers, and a FINISHED instance counts against ceiling until DISPOSED', async () => {
const doc = exhibit({
sounds: {
hit: {
name: 'Hit',
recipe: {
mode: 'oneshot',
release: '50ms',
nodes: {
pulse: { type: 'impulse', duration: '10ms' },
level: { type: 'gain', gain: 0.5 }
},
routes: [{ from: 'pulse', to: 'level' }, { from: 'level', to: 'output' }]
}
}
}
});
const context = mockContext();
const subsystem = new AudioSubsystem({
document: doc,
rng: new SeededRNG(42),
contextFactory: () => context,
voiceLimits: { oneshot: 2, continuous: 2 }
});
await subsystem.unlock();
const voice1 = subsystem.play('hit');
assert.equal(voice1.state, 'ACTIVE');
assert.equal(subsystem.oneshotVoices.size, 1);
// Transition voice1 to FINISHED (e.g. determinable ending bound)
voice1.transition('FINISHED');
assert.equal(voice1.state, 'FINISHED');
// CONTRACT: A FINISHED instance still counts against its ceiling until DISPOSED
assert.equal(subsystem.oneshotVoices.size, 1);
assert.ok(subsystem.oneshotVoices.has(voice1));
// Second instance
const voice2 = subsystem.play('hit');
assert.equal(subsystem.oneshotVoices.size, 2); // Ceiling reached (2/2)
// Explicitly disposing voice1 releases its slot
voice1.dispose();
assert.equal(voice1.state, 'DISPOSED');
assert.equal(subsystem.oneshotVoices.size, 1);
assert.equal(subsystem.oneshotVoices.has(voice1), false);
// Calling dispose on voice2 releases its resources
voice2.dispose();
assert.equal(voice2.state, 'DISPOSED');
assert.equal(subsystem.oneshotVoices.size, 0);
await subsystem.dispose();
});