Skip to main content

skenion_runtime/
dsp.rs

1use std::collections::{BTreeMap, HashMap};
2use std::f32::consts::TAU;
3
4use serde::{Deserialize, Serialize};
5use serde_json::{Map, Value, json};
6use thiserror::Error;
7
8use crate::{
9    AudioClockBridgeMethod, AudioClockBridgePlan, AudioClockDomain, AudioClockDomainAuthority,
10    AudioEndpoint, AudioEndpointDirection, AudioGraphPartition, DataFlow, Edge, ExecutionModel,
11    ExecutionPlan, GraphDocument, GraphNode, NodeRegistry, PlanError, Port, PortDirection,
12    ProjectRequestCurrent, RuntimeDiagnostic, build_execution_plan,
13    build_execution_plan_request_current, expand_project_graph_current, plan_audio_clock_bridge,
14    schema_version_diagnostic, validate_project,
15};
16
17const AUDIO_SIGNAL_KIND: &str = "signal.audio";
18const AUDIO_INPUT_KIND: &str = "audio.input";
19const AUDIO_OUTPUT_KIND: &str = "audio.output";
20const AUDIO_CLOCK_BRIDGE_KIND: &str = "audio.clock-bridge";
21const AUDIO_RESAMPLE_KIND: &str = "audio.resample";
22const DEFAULT_BLOCK_SIZE: u32 = 64;
23const DEFAULT_SAMPLE_RATE: u32 = 48_000;
24const DEFAULT_SAMPLE_FORMAT: &str = "f32";
25
26#[derive(Debug, Clone, Copy, PartialEq, Eq)]
27pub struct AudioDspPlanOptions {
28    pub block_size: u32,
29    pub sample_rate: u32,
30}
31
32impl Default for AudioDspPlanOptions {
33    fn default() -> Self {
34        Self {
35            block_size: DEFAULT_BLOCK_SIZE,
36            sample_rate: DEFAULT_SAMPLE_RATE,
37        }
38    }
39}
40
41#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
42#[serde(rename_all = "camelCase")]
43pub struct AudioDspPlan {
44    pub graph_id: String,
45    pub graph_revision: String,
46    pub block_size: u32,
47    pub sample_rate: u32,
48    pub endpoints: Vec<AudioEndpoint>,
49    pub clock_domains: Vec<AudioClockDomain>,
50    pub partitions: Vec<AudioGraphPartition>,
51    pub bridge_plans: Vec<AudioClockBridgePlan>,
52    pub nodes: Vec<AudioDspPlanNode>,
53    pub edges: Vec<AudioDspPlanEdge>,
54    pub buffers: Vec<AudioDspBuffer>,
55}
56
57#[derive(Debug, Clone, PartialEq, Eq)]
58pub struct AudioEndpointPlanNode {
59    pub node_id: String,
60    pub kind: String,
61    pub clock_domain_id: String,
62}
63
64#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
65#[serde(rename_all = "camelCase")]
66pub struct AudioDspPlanNode {
67    pub node_id: String,
68    pub kind: String,
69    pub kind_version: String,
70    pub order: usize,
71    pub params: Map<String, Value>,
72    pub signal_inputs: Vec<AudioDspSignalInput>,
73    pub control_inputs: Vec<AudioDspControlInput>,
74    pub signal_outputs: Vec<AudioDspSignalOutput>,
75}
76
77#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
78#[serde(rename_all = "camelCase")]
79pub struct AudioDspSignalInput {
80    pub port_id: String,
81    pub source_node_id: String,
82    pub source_port_id: String,
83    pub buffer_id: String,
84}
85
86#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
87#[serde(rename_all = "camelCase")]
88pub struct AudioDspControlInput {
89    pub port_id: String,
90    pub data_kind: String,
91    #[serde(skip_serializing_if = "Option::is_none")]
92    pub source_node_id: Option<String>,
93    #[serde(skip_serializing_if = "Option::is_none")]
94    pub source_port_id: Option<String>,
95}
96
97#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
98#[serde(rename_all = "camelCase")]
99pub struct AudioDspSignalOutput {
100    pub port_id: String,
101    pub buffer_id: String,
102}
103
104#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
105#[serde(rename_all = "camelCase")]
106pub struct AudioDspPlanEdge {
107    pub from_node: String,
108    pub from_port: String,
109    pub to_node: String,
110    pub to_port: String,
111    pub buffer_id: String,
112}
113
114#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
115#[serde(rename_all = "camelCase")]
116pub struct AudioDspBuffer {
117    pub id: String,
118    pub producer_node_id: String,
119    pub producer_port_id: String,
120    pub sample_format: String,
121    pub channels: u32,
122}
123
124#[derive(Debug, Clone, Copy, PartialEq, Eq)]
125pub struct AudioOfflineDspOptions {
126    pub blocks: u32,
127    pub plan: AudioDspPlanOptions,
128}
129
130impl Default for AudioOfflineDspOptions {
131    fn default() -> Self {
132        Self {
133            blocks: 1,
134            plan: AudioDspPlanOptions::default(),
135        }
136    }
137}
138
139#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
140#[serde(rename_all = "camelCase")]
141pub struct AudioOfflineDspReport {
142    pub graph_id: String,
143    pub graph_revision: String,
144    pub block_size: u32,
145    pub sample_rate: u32,
146    pub blocks: Vec<AudioDspBlockReport>,
147    pub snapshots: Vec<AudioDspSnapshot>,
148}
149
150#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
151#[serde(rename_all = "camelCase")]
152pub struct AudioDspBlockReport {
153    pub index: u32,
154    pub buffers: Vec<AudioDspRenderedBuffer>,
155}
156
157#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
158#[serde(rename_all = "camelCase")]
159pub struct AudioDspRenderedBuffer {
160    pub buffer_id: String,
161    pub producer_node_id: String,
162    pub producer_port_id: String,
163    pub samples: Vec<f32>,
164}
165
166#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
167#[serde(rename_all = "camelCase")]
168pub struct AudioDspSnapshot {
169    pub block_index: u32,
170    pub node_id: String,
171    pub port_id: String,
172    pub value: f32,
173}
174
175#[derive(Debug, Clone, Copy, PartialEq, Eq)]
176pub struct AudioRealtimeDspOptions {
177    pub plan: AudioDspPlanOptions,
178    pub channels: usize,
179}
180
181impl Default for AudioRealtimeDspOptions {
182    fn default() -> Self {
183        Self {
184            plan: AudioDspPlanOptions::default(),
185            channels: 2,
186        }
187    }
188}
189
190#[derive(Debug, Error)]
191pub enum AudioDspPlanError {
192    #[error("audio dsp project validation failed")]
193    InvalidProject {
194        diagnostics: Box<[RuntimeDiagnostic]>,
195    },
196    #[error("{message}")]
197    Plan {
198        message: String,
199        diagnostics: Box<[RuntimeDiagnostic]>,
200    },
201    #[error("audio dsp block size must be greater than zero")]
202    InvalidBlockSize { diagnostic: Box<RuntimeDiagnostic> },
203    #[error("audio dsp sample rate must be greater than zero")]
204    InvalidSampleRate { diagnostic: Box<RuntimeDiagnostic> },
205    #[error("audio signal port {node_id}.{port_id} is not an audio_block node")]
206    SignalPortOutsideAudioBlock {
207        node_id: String,
208        port_id: String,
209        diagnostic: Box<RuntimeDiagnostic>,
210    },
211    #[error(
212        "audio signal route from {source_node_id} domain {source_clock_domain_id} to {target_node_id} domain {target_clock_domain_id} requires audio.clock-bridge or audio.resample"
213    )]
214    ClockDomainCrossingRequiresBridge {
215        source_node_id: String,
216        target_node_id: String,
217        source_clock_domain_id: String,
218        target_clock_domain_id: String,
219        diagnostic: Box<RuntimeDiagnostic>,
220    },
221}
222
223impl AudioDspPlanError {
224    pub fn diagnostics(&self) -> Vec<RuntimeDiagnostic> {
225        match self {
226            Self::InvalidProject { diagnostics } | Self::Plan { diagnostics, .. } => {
227                diagnostics.to_vec()
228            }
229            Self::InvalidBlockSize { diagnostic }
230            | Self::InvalidSampleRate { diagnostic }
231            | Self::SignalPortOutsideAudioBlock { diagnostic, .. }
232            | Self::ClockDomainCrossingRequiresBridge { diagnostic, .. } => {
233                vec![(**diagnostic).clone()]
234            }
235        }
236    }
237
238    fn from_diagnostics(diagnostics: Vec<RuntimeDiagnostic>) -> Self {
239        Self::InvalidProject {
240            diagnostics: diagnostics.into_boxed_slice(),
241        }
242    }
243
244    #[allow(dead_code)]
245    fn from_project_validation_report(report: crate::ProjectValidationReport) -> Self {
246        Self::InvalidProject {
247            diagnostics: report
248                .errors()
249                .iter()
250                .map(|error| {
251                    RuntimeDiagnostic::structured_error(
252                        "audio-dsp.invalid-project",
253                        error.message.clone(),
254                        json!({ "surface": "internal-project-validation" }),
255                    )
256                })
257                .collect::<Vec<_>>()
258                .into_boxed_slice(),
259        }
260    }
261
262    #[allow(dead_code)]
263    fn from_plan_error(error: PlanError) -> Self {
264        match error {
265            PlanError::InvalidProject(report) => Self::from_project_validation_report(report),
266            error => {
267                let message = error.to_string();
268                Self::Plan {
269                    diagnostics: vec![RuntimeDiagnostic::structured_error(
270                        "audio-dsp.plan",
271                        message.clone(),
272                        json!({ "surface": "internal-plan" }),
273                    )]
274                    .into_boxed_slice(),
275                    message,
276                }
277            }
278        }
279    }
280}
281
282#[derive(Debug, Error)]
283pub enum AudioOfflineDspError {
284    #[error("{0}")]
285    Plan(#[from] AudioDspPlanError),
286    #[error("audio offline dsp block count must be greater than zero")]
287    InvalidBlockCount { diagnostic: Box<RuntimeDiagnostic> },
288    #[error("offline audio dsp node {node_id} uses unsupported kind {kind}")]
289    UnsupportedNodeKind {
290        node_id: String,
291        kind: String,
292        diagnostic: Box<RuntimeDiagnostic>,
293    },
294}
295
296impl AudioOfflineDspError {
297    pub fn diagnostics(&self) -> Vec<RuntimeDiagnostic> {
298        match self {
299            Self::Plan(error) => error.diagnostics(),
300            Self::InvalidBlockCount { diagnostic }
301            | Self::UnsupportedNodeKind { diagnostic, .. } => vec![(**diagnostic).clone()],
302        }
303    }
304}
305
306#[derive(Debug, Error)]
307pub enum AudioRealtimeDspError {
308    #[error("{0}")]
309    Plan(#[from] AudioDspPlanError),
310    #[error("audio realtime dsp output channel count must be greater than zero")]
311    InvalidChannelCount { diagnostic: Box<RuntimeDiagnostic> },
312    #[error("audio realtime dsp graph must contain exactly one audio.output node, found {count}")]
313    OutputCount {
314        count: usize,
315        diagnostic: Box<RuntimeDiagnostic>,
316    },
317    #[error("audio realtime dsp node {node_id} uses unsupported kind {kind}")]
318    UnsupportedNodeKind {
319        node_id: String,
320        kind: String,
321        diagnostic: Box<RuntimeDiagnostic>,
322    },
323}
324
325impl AudioRealtimeDspError {
326    pub fn diagnostics(&self) -> Vec<RuntimeDiagnostic> {
327        match self {
328            Self::Plan(error) => error.diagnostics(),
329            Self::InvalidChannelCount { diagnostic }
330            | Self::OutputCount { diagnostic, .. }
331            | Self::UnsupportedNodeKind { diagnostic, .. } => vec![(**diagnostic).clone()],
332        }
333    }
334}
335
336#[derive(Debug, Clone, Copy, PartialEq)]
337enum AudioRealtimeNodeKind {
338    Sig { value: f32 },
339    Osc { frequency: f32 },
340    Mul,
341    Output,
342}
343
344#[derive(Debug, Clone, Copy, PartialEq)]
345struct AudioRealtimeNode {
346    kind: AudioRealtimeNodeKind,
347    output_buffer: Option<usize>,
348    left_buffer: Option<usize>,
349    right_buffer: Option<usize>,
350    phase: f32,
351}
352
353#[derive(Debug, Clone)]
354pub struct AudioRealtimeDspExecutor {
355    plan: AudioDspPlan,
356    channels: usize,
357    block_len: usize,
358    output_node_index: usize,
359    nodes: Vec<AudioRealtimeNode>,
360    buffers: Vec<Vec<f32>>,
361    scratch: Vec<f32>,
362}
363
364impl AudioRealtimeDspExecutor {
365    pub fn new(
366        request: &ProjectRequestCurrent,
367        options: AudioRealtimeDspOptions,
368    ) -> Result<Self, AudioRealtimeDspError> {
369        if options.channels == 0 {
370            return Err(AudioRealtimeDspError::InvalidChannelCount {
371                diagnostic: invalid_realtime_channel_count_diagnostic(),
372            });
373        }
374        let (plan, graph) = build_audio_dsp_plan_with_graph_current(request, options.plan)?;
375        Self::from_plan_and_graph(&graph, plan, options.channels)
376    }
377
378    #[allow(dead_code)]
379    pub(crate) fn new_from_graph(
380        graph: &GraphDocument,
381        registry: &NodeRegistry,
382        options: AudioRealtimeDspOptions,
383    ) -> Result<Self, AudioRealtimeDspError> {
384        if options.channels == 0 {
385            return Err(AudioRealtimeDspError::InvalidChannelCount {
386                diagnostic: invalid_realtime_channel_count_diagnostic(),
387            });
388        }
389        let plan = build_audio_dsp_plan(graph, registry, options.plan)?;
390        Self::from_plan_and_graph(graph, plan, options.channels)
391    }
392
393    fn from_plan_and_graph(
394        graph: &GraphDocument,
395        plan: AudioDspPlan,
396        channels: usize,
397    ) -> Result<Self, AudioRealtimeDspError> {
398        let output_nodes = plan
399            .nodes
400            .iter()
401            .filter(|node| node.kind == AUDIO_OUTPUT_KIND)
402            .collect::<Vec<_>>();
403        if output_nodes.len() != 1 {
404            return Err(AudioRealtimeDspError::OutputCount {
405                count: output_nodes.len(),
406                diagnostic: Box::new(RuntimeDiagnostic::structured_error(
407                    "audio-dsp.realtime-output-count",
408                    format!(
409                        "audio realtime dsp graph must contain exactly one audio.output node, found {}",
410                        output_nodes.len()
411                    ),
412                    json!({ "count": output_nodes.len() }),
413                )),
414            });
415        }
416        if let Some(node) = plan
417            .nodes
418            .iter()
419            .find(|node| !matches_realtime_kind(node.kind.as_str()))
420        {
421            return Err(AudioRealtimeDspError::UnsupportedNodeKind {
422                node_id: node.node_id.clone(),
423                kind: node.kind.clone(),
424                diagnostic: Box::new(RuntimeDiagnostic::structured_error(
425                    "audio-dsp.realtime-unsupported-node-kind",
426                    format!(
427                        "audio realtime dsp node {} uses unsupported kind {}",
428                        node.node_id, node.kind
429                    ),
430                    json!({
431                        "nodeId": node.node_id.as_str(),
432                        "kind": node.kind.as_str(),
433                    }),
434                )),
435            });
436        }
437
438        let node_params_by_id = graph
439            .nodes
440            .iter()
441            .map(|node| (node.id.clone(), node.params.clone()))
442            .collect::<BTreeMap<_, _>>();
443        let buffer_index_by_id = plan
444            .buffers
445            .iter()
446            .enumerate()
447            .map(|(index, buffer)| (buffer.id.clone(), index))
448            .collect::<BTreeMap<_, _>>();
449        let block_len = plan.block_size as usize;
450        let buffers = plan
451            .buffers
452            .iter()
453            .map(|_| vec![0.0; block_len])
454            .collect::<Vec<_>>();
455        let nodes = plan
456            .nodes
457            .iter()
458            .map(|node| realtime_node(node, &buffer_index_by_id, &node_params_by_id))
459            .collect::<Vec<_>>();
460        let output_node_index = plan
461            .nodes
462            .iter()
463            .position(|node| node.kind == AUDIO_OUTPUT_KIND)
464            .expect("realtime output count was already validated");
465
466        Ok(Self {
467            plan,
468            channels,
469            block_len,
470            output_node_index,
471            nodes,
472            buffers,
473            scratch: vec![0.0; block_len],
474        })
475    }
476
477    pub fn plan(&self) -> &AudioDspPlan {
478        &self.plan
479    }
480
481    pub fn channels(&self) -> usize {
482        self.channels
483    }
484
485    pub fn process_interleaved_output(&mut self, output: &mut [f32]) {
486        output.fill(0.0);
487        if output.is_empty() {
488            return;
489        }
490        let total_frames = output.len() / self.channels;
491        let mut frame_offset = 0;
492        while frame_offset < total_frames {
493            self.process_block();
494            let frames_to_copy = self.block_len.min(total_frames - frame_offset);
495            self.copy_output_frames(output, frame_offset, frames_to_copy);
496            frame_offset += frames_to_copy;
497        }
498    }
499
500    fn process_block(&mut self) {
501        for node_index in 0..self.nodes.len() {
502            match self.nodes[node_index].kind {
503                AudioRealtimeNodeKind::Sig { value } => self.render_sig(node_index, value),
504                AudioRealtimeNodeKind::Osc { frequency } => {
505                    self.render_osc(node_index, frequency);
506                }
507                AudioRealtimeNodeKind::Mul => self.render_mul(node_index),
508                AudioRealtimeNodeKind::Output => {}
509            }
510        }
511    }
512
513    fn render_sig(&mut self, node_index: usize, value: f32) {
514        if let Some(buffer) = self.signal_output_buffer_mut(node_index) {
515            buffer.fill(value);
516        }
517    }
518
519    fn render_osc(&mut self, node_index: usize, frequency: f32) {
520        let increment = frequency / self.plan.sample_rate as f32;
521        let mut phase_value = self.nodes[node_index].phase;
522        let samples = self.scratch.as_mut_slice();
523        for sample in samples.iter_mut().take(self.block_len) {
524            *sample = (phase_value * TAU).sin();
525            phase_value = (phase_value + increment).rem_euclid(1.0);
526        }
527        self.nodes[node_index].phase = phase_value;
528        self.copy_scratch_to_output(node_index);
529    }
530
531    fn render_mul(&mut self, node_index: usize) {
532        let left = self.nodes[node_index].left_buffer;
533        let right = self.nodes[node_index].right_buffer;
534        for index in 0..self.block_len {
535            let sample = self.sample(left, index) * self.sample(right, index);
536            self.scratch[index] = sample;
537        }
538        self.copy_scratch_to_output(node_index);
539    }
540
541    fn copy_scratch_to_output(&mut self, node_index: usize) {
542        if let Some(output_index) = self.nodes[node_index].output_buffer {
543            self.buffers[output_index].copy_from_slice(&self.scratch);
544        }
545    }
546
547    fn copy_output_frames(
548        &mut self,
549        output: &mut [f32],
550        frame_offset: usize,
551        frames_to_copy: usize,
552    ) {
553        let output_node = self.nodes[self.output_node_index];
554        let left = output_node.left_buffer;
555        let right = output_node.right_buffer;
556        for local_frame in 0..frames_to_copy {
557            let output_frame = frame_offset + local_frame;
558            let output_base = output_frame * self.channels;
559            output[output_base] = self.sample(left, local_frame);
560            if self.channels > 1 {
561                output[output_base + 1] = self.sample(right, local_frame);
562            }
563        }
564    }
565
566    fn signal_output_buffer_mut(&mut self, node_index: usize) -> Option<&mut Vec<f32>> {
567        self.nodes[node_index]
568            .output_buffer
569            .map(|output_buffer| &mut self.buffers[output_buffer])
570    }
571
572    fn sample(&self, buffer_id: Option<usize>, index: usize) -> f32 {
573        buffer_id
574            .and_then(|id| self.buffers.get(id))
575            .and_then(|buffer| buffer.get(index))
576            .copied()
577            .unwrap_or(0.0)
578    }
579}
580
581pub fn build_audio_dsp_plan_current(
582    request: &ProjectRequestCurrent,
583    options: AudioDspPlanOptions,
584) -> Result<AudioDspPlan, AudioDspPlanError> {
585    build_audio_dsp_plan_with_graph_current(request, options).map(|(plan, _)| plan)
586}
587
588fn build_audio_dsp_plan_with_graph_current(
589    request: &ProjectRequestCurrent,
590    options: AudioDspPlanOptions,
591) -> Result<(AudioDspPlan, GraphDocument), AudioDspPlanError> {
592    validate_audio_dsp_plan_options(options)?;
593    validate_audio_dsp_request_schema_versions_current(request)?;
594    let (execution_plan, _diagnostics) = build_execution_plan_request_current(request)
595        .map_err(AudioDspPlanError::from_diagnostics)?;
596    let expanded_graph = expand_project_graph_current(&request.graph, &request.patch_library)
597        .map_err(AudioDspPlanError::from_diagnostics)?;
598    let graph = lower_graph_for_execution(&expanded_graph);
599    let plan = build_audio_dsp_plan_from_execution_plan(&graph, &execution_plan, options)?;
600    Ok((plan, graph))
601}
602
603fn validate_audio_dsp_request_schema_versions_current(
604    request: &ProjectRequestCurrent,
605) -> Result<(), AudioDspPlanError> {
606    let mut diagnostics = Vec::new();
607    if let Some(document) = &request.document {
608        if let Some(diagnostic) =
609            schema_version_diagnostic("project", Some(document.schema_version.as_str()))
610        {
611            diagnostics.push(diagnostic);
612        }
613    }
614    if let Some(diagnostic) =
615        schema_version_diagnostic("graph", Some(request.graph.schema_version.as_str()))
616    {
617        diagnostics.push(diagnostic);
618    }
619
620    if diagnostics.is_empty() {
621        Ok(())
622    } else {
623        Err(AudioDspPlanError::InvalidProject {
624            diagnostics: diagnostics.into_boxed_slice(),
625        })
626    }
627}
628
629#[allow(dead_code)]
630pub(crate) fn build_audio_dsp_plan(
631    graph: &GraphDocument,
632    registry: &NodeRegistry,
633    options: AudioDspPlanOptions,
634) -> Result<AudioDspPlan, AudioDspPlanError> {
635    validate_audio_dsp_plan_options(options)?;
636
637    validate_project(graph, registry).map_err(AudioDspPlanError::from_project_validation_report)?;
638    let execution_plan =
639        build_execution_plan(graph, registry).map_err(AudioDspPlanError::from_plan_error)?;
640    build_audio_dsp_plan_from_execution_plan(graph, &execution_plan, options)
641}
642
643fn build_audio_dsp_plan_from_execution_plan(
644    graph: &GraphDocument,
645    execution_plan: &ExecutionPlan,
646    options: AudioDspPlanOptions,
647) -> Result<AudioDspPlan, AudioDspPlanError> {
648    let nodes_by_id = graph
649        .nodes
650        .iter()
651        .map(|node| (node.id.as_str(), node))
652        .collect::<HashMap<_, _>>();
653    let audio_node_ids = execution_plan
654        .nodes
655        .iter()
656        .filter(|node| node.execution_model == ExecutionModel::AudioBlock)
657        .map(|node| node.node_id.as_str())
658        .collect::<Vec<_>>();
659    let audio_node_set = audio_node_ids
660        .iter()
661        .copied()
662        .collect::<std::collections::HashSet<_>>();
663
664    reject_signal_ports_outside_audio_block(graph, &audio_node_set)?;
665    let endpoint_nodes = audio_endpoint_plan_nodes(graph);
666    let endpoints = audio_endpoints(graph, &endpoint_nodes);
667    let clock_domains = audio_clock_domains(&endpoint_nodes, options.sample_rate);
668    let partitions = audio_graph_partitions(graph, &endpoint_nodes, &audio_node_set);
669    let bridge_plans = audio_clock_bridge_plans(graph, &endpoint_nodes)?;
670
671    let mut buffers = Vec::new();
672    let mut buffer_by_output = BTreeMap::new();
673    for node_id in &audio_node_ids {
674        let node = nodes_by_id
675            .get(node_id)
676            .expect("execution plan should only contain graph nodes");
677        for port in node
678            .ports
679            .iter()
680            .filter(|port| is_audio_signal_output(port))
681        {
682            let buffer_id = format!("audio_buffer_{}", buffers.len());
683            buffer_by_output.insert((node.id.as_str(), port.id.as_str()), buffer_id.clone());
684            buffers.push(AudioDspBuffer {
685                id: buffer_id,
686                producer_node_id: node.id.clone(),
687                producer_port_id: port.id.clone(),
688                sample_format: DEFAULT_SAMPLE_FORMAT.to_owned(),
689                channels: 1,
690            });
691        }
692    }
693
694    let mut signal_edges = Vec::new();
695    for edge in graph
696        .edges
697        .iter()
698        .filter(|edge| is_audio_signal_edge(edge, graph))
699    {
700        let buffer_id = buffer_by_output
701            .get(&(edge.from.node.as_str(), edge.from.port.as_str()))
702            .cloned()
703            .expect("validated audio signal edge should have a producer output buffer");
704        signal_edges.push(AudioDspPlanEdge {
705            from_node: edge.from.node.clone(),
706            from_port: edge.from.port.clone(),
707            to_node: edge.to.node.clone(),
708            to_port: edge.to.port.clone(),
709            buffer_id,
710        });
711    }
712
713    let nodes = audio_node_ids
714        .iter()
715        .enumerate()
716        .map(|(order, node_id)| {
717            let node = nodes_by_id
718                .get(node_id)
719                .expect("execution plan should only contain graph nodes");
720            audio_plan_node(node, order, &signal_edges, &buffer_by_output, graph)
721        })
722        .collect();
723
724    Ok(AudioDspPlan {
725        graph_id: graph.id.clone(),
726        graph_revision: graph.revision.clone(),
727        block_size: options.block_size,
728        sample_rate: options.sample_rate,
729        endpoints,
730        clock_domains,
731        partitions,
732        bridge_plans,
733        nodes,
734        edges: signal_edges,
735        buffers,
736    })
737}
738
739fn lower_graph_for_execution(graph: &crate::GraphDocumentCurrent) -> GraphDocument {
740    GraphDocument {
741        schema: "skenion.graph".to_owned(),
742        schema_version: "0.1.0".to_owned(),
743        id: graph.id.clone(),
744        revision: graph.revision.clone(),
745        nodes: graph
746            .nodes
747            .iter()
748            .map(|node| crate::session::lower_graph_node_for_execution(node, &node.id))
749            .collect(),
750        edges: graph
751            .edges
752            .iter()
753            .map(crate::session::lower_edge_for_execution)
754            .collect(),
755    }
756}
757
758fn validate_audio_dsp_plan_options(options: AudioDspPlanOptions) -> Result<(), AudioDspPlanError> {
759    if options.block_size == 0 {
760        return Err(AudioDspPlanError::InvalidBlockSize {
761            diagnostic: Box::new(RuntimeDiagnostic::structured_error(
762                "audio-dsp.invalid-block-size",
763                "audio dsp block size must be greater than zero",
764                json!({ "blockSize": options.block_size }),
765            )),
766        });
767    }
768    if options.sample_rate == 0 {
769        return Err(AudioDspPlanError::InvalidSampleRate {
770            diagnostic: Box::new(RuntimeDiagnostic::structured_error(
771                "audio-dsp.invalid-sample-rate",
772                "audio dsp sample rate must be greater than zero",
773                json!({ "sampleRate": options.sample_rate }),
774            )),
775        });
776    }
777    Ok(())
778}
779
780fn validate_audio_offline_dsp_options(
781    options: AudioOfflineDspOptions,
782) -> Result<(), AudioOfflineDspError> {
783    if options.blocks == 0 {
784        return Err(AudioOfflineDspError::InvalidBlockCount {
785            diagnostic: Box::new(RuntimeDiagnostic::structured_error(
786                "audio-dsp.invalid-offline-block-count",
787                "audio offline dsp block count must be greater than zero",
788                json!({ "blocks": options.blocks }),
789            )),
790        });
791    }
792    Ok(())
793}
794
795fn invalid_realtime_channel_count_diagnostic() -> Box<RuntimeDiagnostic> {
796    Box::new(RuntimeDiagnostic::structured_error(
797        "audio-dsp.invalid-realtime-channel-count",
798        "audio realtime dsp output channel count must be greater than zero",
799        json!({ "channels": 0 }),
800    ))
801}
802
803pub fn run_offline_audio_dsp_current(
804    request: &ProjectRequestCurrent,
805    options: AudioOfflineDspOptions,
806) -> Result<AudioOfflineDspReport, AudioOfflineDspError> {
807    validate_audio_offline_dsp_options(options)?;
808    let (plan, graph) = build_audio_dsp_plan_with_graph_current(request, options.plan)?;
809    run_offline_audio_dsp_with_plan(&graph, plan, options)
810}
811
812#[allow(dead_code)]
813pub(crate) fn run_offline_audio_dsp(
814    graph: &GraphDocument,
815    registry: &NodeRegistry,
816    options: AudioOfflineDspOptions,
817) -> Result<AudioOfflineDspReport, AudioOfflineDspError> {
818    validate_audio_offline_dsp_options(options)?;
819
820    let plan = build_audio_dsp_plan(graph, registry, options.plan)?;
821    run_offline_audio_dsp_with_plan(graph, plan, options)
822}
823
824fn run_offline_audio_dsp_with_plan(
825    graph: &GraphDocument,
826    plan: AudioDspPlan,
827    options: AudioOfflineDspOptions,
828) -> Result<AudioOfflineDspReport, AudioOfflineDspError> {
829    let block_len = plan.block_size as usize;
830    let nodes_by_id = graph
831        .nodes
832        .iter()
833        .map(|node| (node.id.as_str(), node))
834        .collect::<HashMap<_, _>>();
835    let mut oscillator_phase_by_node = BTreeMap::<String, f32>::new();
836    let mut block_reports = Vec::new();
837    let mut snapshots = Vec::new();
838
839    for block_index in 0..options.blocks {
840        let mut buffers = plan
841            .buffers
842            .iter()
843            .map(|buffer| (buffer.id.clone(), vec![0.0; block_len]))
844            .collect::<BTreeMap<_, _>>();
845
846        for node in &plan.nodes {
847            match node.kind.as_str() {
848                "audio.sig" => render_sig(node, &mut buffers, block_len),
849                "audio.osc" => render_osc(
850                    node,
851                    &nodes_by_id,
852                    &mut oscillator_phase_by_node,
853                    &mut buffers,
854                    block_len,
855                    plan.sample_rate,
856                ),
857                "audio.operator.mul" => render_mul(node, &mut buffers, block_len),
858                "audio.snapshot" => {
859                    snapshots.push(snapshot_signal(node, &buffers, block_index));
860                }
861                _ => {
862                    return Err(AudioOfflineDspError::UnsupportedNodeKind {
863                        node_id: node.node_id.clone(),
864                        kind: node.kind.clone(),
865                        diagnostic: Box::new(RuntimeDiagnostic::structured_error(
866                            "audio-dsp.offline-unsupported-node-kind",
867                            format!(
868                                "offline audio dsp node {} uses unsupported kind {}",
869                                node.node_id, node.kind
870                            ),
871                            json!({
872                                "nodeId": node.node_id.as_str(),
873                                "kind": node.kind.as_str(),
874                            }),
875                        )),
876                    });
877                }
878            }
879        }
880
881        let rendered_buffers = plan
882            .buffers
883            .iter()
884            .map(|buffer| AudioDspRenderedBuffer {
885                buffer_id: buffer.id.clone(),
886                producer_node_id: buffer.producer_node_id.clone(),
887                producer_port_id: buffer.producer_port_id.clone(),
888                samples: buffers
889                    .get(&buffer.id)
890                    .expect("allocated dsp buffer should exist for every plan buffer")
891                    .clone(),
892            })
893            .collect();
894        block_reports.push(AudioDspBlockReport {
895            index: block_index,
896            buffers: rendered_buffers,
897        });
898    }
899
900    Ok(AudioOfflineDspReport {
901        graph_id: plan.graph_id,
902        graph_revision: plan.graph_revision,
903        block_size: plan.block_size,
904        sample_rate: plan.sample_rate,
905        blocks: block_reports,
906        snapshots,
907    })
908}
909
910fn render_sig(node: &AudioDspPlanNode, buffers: &mut BTreeMap<String, Vec<f32>>, block_len: usize) {
911    let value = param_f32(&node.params, "value", 0.0);
912    write_signal_output(node, buffers, vec![value; block_len]);
913}
914
915fn render_osc(
916    node: &AudioDspPlanNode,
917    nodes_by_id: &HashMap<&str, &GraphNode>,
918    phase_by_node: &mut BTreeMap<String, f32>,
919    buffers: &mut BTreeMap<String, Vec<f32>>,
920    block_len: usize,
921    sample_rate: u32,
922) {
923    let frequency = control_input_f32(node, "frequency", nodes_by_id)
924        .unwrap_or_else(|| param_f32(&node.params, "frequency", 440.0));
925    let phase = phase_by_node.entry(node.node_id.clone()).or_insert(0.0);
926    let increment = frequency / sample_rate as f32;
927    let mut samples = Vec::with_capacity(block_len);
928    for _ in 0..block_len {
929        samples.push((*phase * TAU).sin());
930        *phase = (*phase + increment).rem_euclid(1.0);
931    }
932    write_signal_output(node, buffers, samples);
933}
934
935fn render_mul(node: &AudioDspPlanNode, buffers: &mut BTreeMap<String, Vec<f32>>, block_len: usize) {
936    let left = signal_input_block(node, "left", buffers, block_len);
937    let right = signal_input_block(node, "right", buffers, block_len);
938    let samples = left
939        .iter()
940        .zip(right.iter())
941        .map(|(left, right)| left * right)
942        .collect();
943    write_signal_output(node, buffers, samples);
944}
945
946fn snapshot_signal(
947    node: &AudioDspPlanNode,
948    buffers: &BTreeMap<String, Vec<f32>>,
949    block_index: u32,
950) -> AudioDspSnapshot {
951    let value = signal_input_block(node, "signal", buffers, 1)
952        .first()
953        .copied()
954        .unwrap_or(0.0);
955    AudioDspSnapshot {
956        block_index,
957        node_id: node.node_id.clone(),
958        port_id: "value".to_owned(),
959        value,
960    }
961}
962
963fn write_signal_output(
964    node: &AudioDspPlanNode,
965    buffers: &mut BTreeMap<String, Vec<f32>>,
966    samples: Vec<f32>,
967) {
968    let output = node
969        .signal_outputs
970        .first()
971        .expect("offline dsp signal node should expose a signal output");
972    let buffer = buffers
973        .get_mut(&output.buffer_id)
974        .expect("offline dsp signal output should have an allocated buffer");
975    *buffer = samples;
976}
977
978fn signal_input_block(
979    node: &AudioDspPlanNode,
980    port_id: &str,
981    buffers: &BTreeMap<String, Vec<f32>>,
982    block_len: usize,
983) -> Vec<f32> {
984    node.signal_inputs
985        .iter()
986        .find(|input| input.port_id == port_id)
987        .and_then(|input| buffers.get(&input.buffer_id))
988        .cloned()
989        .unwrap_or_else(|| vec![0.0; block_len])
990}
991
992fn control_input_f32(
993    node: &AudioDspPlanNode,
994    port_id: &str,
995    nodes_by_id: &HashMap<&str, &GraphNode>,
996) -> Option<f32> {
997    node.control_inputs
998        .iter()
999        .find(|input| input.port_id == port_id)
1000        .and_then(|input| input.source_node_id.as_deref())
1001        .and_then(|node_id| nodes_by_id.get(node_id))
1002        .map(|node| param_f32(&node.params, "value", 0.0))
1003}
1004
1005fn control_input_f32_from_params(
1006    node: &AudioDspPlanNode,
1007    port_id: &str,
1008    node_params_by_id: &BTreeMap<String, Map<String, Value>>,
1009) -> Option<f32> {
1010    for input in &node.control_inputs {
1011        if input.port_id != port_id {
1012            continue;
1013        }
1014        let node_id = input.source_node_id.as_deref()?;
1015        let params = node_params_by_id.get(node_id)?;
1016        return Some(param_f32(params, "value", 0.0));
1017    }
1018    None
1019}
1020
1021fn param_f32(params: &Map<String, Value>, key: &str, default: f32) -> f32 {
1022    params
1023        .get(key)
1024        .and_then(Value::as_f64)
1025        .map(|value| value as f32)
1026        .unwrap_or(default)
1027}
1028
1029fn matches_realtime_kind(kind: &str) -> bool {
1030    matches!(
1031        kind,
1032        "audio.sig" | "audio.osc" | "audio.operator.mul" | AUDIO_OUTPUT_KIND
1033    )
1034}
1035
1036fn audio_endpoint_plan_nodes(graph: &GraphDocument) -> Vec<AudioEndpointPlanNode> {
1037    graph
1038        .nodes
1039        .iter()
1040        .filter(|node| node.kind == AUDIO_INPUT_KIND || node.kind == AUDIO_OUTPUT_KIND)
1041        .map(|node| AudioEndpointPlanNode {
1042            node_id: node.id.clone(),
1043            kind: node.kind.clone(),
1044            clock_domain_id: audio_clock_domain_id(node),
1045        })
1046        .collect()
1047}
1048
1049fn audio_clock_domain_id(node: &GraphNode) -> String {
1050    node.params
1051        .get("clockDomain")
1052        .and_then(serde_json::Value::as_str)
1053        .filter(|value| !value.is_empty())
1054        .map(ToOwned::to_owned)
1055        .unwrap_or_else(|| format!("endpoint:{}", node.id))
1056}
1057
1058fn audio_endpoints(
1059    graph: &GraphDocument,
1060    endpoint_nodes: &[AudioEndpointPlanNode],
1061) -> Vec<AudioEndpoint> {
1062    endpoint_nodes
1063        .iter()
1064        .filter_map(|endpoint| {
1065            let node = graph
1066                .nodes
1067                .iter()
1068                .find(|node| node.id == endpoint.node_id)?;
1069            let direction = if node.kind == AUDIO_INPUT_KIND {
1070                AudioEndpointDirection::Input
1071            } else {
1072                AudioEndpointDirection::Output
1073            };
1074            let channel_ports = node
1075                .ports
1076                .iter()
1077                .filter(|port| is_audio_signal_port(port))
1078                .map(|port| port.id.clone())
1079                .collect();
1080            Some(AudioEndpoint {
1081                id: node.id.clone(),
1082                node_id: node.id.clone(),
1083                direction,
1084                channel_ports,
1085                requested_config: None,
1086                resolved_config: None,
1087                clock_domain_id: Some(endpoint.clock_domain_id.clone()),
1088            })
1089        })
1090        .collect()
1091}
1092
1093fn audio_clock_domains(
1094    endpoint_nodes: &[AudioEndpointPlanNode],
1095    sample_rate: u32,
1096) -> Vec<AudioClockDomain> {
1097    let mut domains = BTreeMap::<String, Vec<String>>::new();
1098    for endpoint in endpoint_nodes {
1099        domains
1100            .entry(endpoint.clock_domain_id.clone())
1101            .or_default()
1102            .push(endpoint.node_id.clone());
1103    }
1104    domains
1105        .into_iter()
1106        .map(|(id, endpoint_ids)| AudioClockDomain {
1107            id: id.clone(),
1108            authority: if id.starts_with("endpoint:") {
1109                AudioClockDomainAuthority::Unavailable
1110            } else {
1111                AudioClockDomainAuthority::UserConfigured
1112            },
1113            source: "runtime.audio-domain-planner.v0".to_owned(),
1114            sample_rate: Some(sample_rate),
1115            drift_compensated: None,
1116            shared_with: Some(endpoint_ids),
1117        })
1118        .collect()
1119}
1120
1121fn audio_graph_partitions(
1122    graph: &GraphDocument,
1123    endpoint_nodes: &[AudioEndpointPlanNode],
1124    audio_node_set: &std::collections::HashSet<&str>,
1125) -> Vec<AudioGraphPartition> {
1126    let mut nodes_by_domain = BTreeMap::<String, Vec<String>>::new();
1127    for endpoint in endpoint_nodes {
1128        nodes_by_domain
1129            .entry(endpoint.clock_domain_id.clone())
1130            .or_default()
1131            .push(endpoint.node_id.clone());
1132    }
1133    if endpoint_nodes.is_empty() {
1134        return Vec::new();
1135    }
1136    let default_domain = endpoint_nodes
1137        .iter()
1138        .find(|endpoint| endpoint.kind == AUDIO_OUTPUT_KIND)
1139        .or_else(|| endpoint_nodes.first())
1140        .map(|endpoint| endpoint.clock_domain_id.clone())
1141        .expect("endpoint_nodes is not empty");
1142    for node in &graph.nodes {
1143        if !audio_node_set.contains(node.id.as_str()) || is_audio_endpoint_kind(&node.kind) {
1144            continue;
1145        }
1146        nodes_by_domain
1147            .entry(default_domain.clone())
1148            .or_default()
1149            .push(node.id.clone());
1150    }
1151    nodes_by_domain
1152        .into_iter()
1153        .map(|(clock_domain_id, node_ids)| {
1154            let endpoint_ids = endpoint_nodes
1155                .iter()
1156                .filter(|endpoint| endpoint.clock_domain_id == clock_domain_id)
1157                .map(|endpoint| endpoint.node_id.clone())
1158                .collect::<Vec<_>>();
1159            AudioGraphPartition {
1160                id: format!("partition:{clock_domain_id}"),
1161                clock_domain_id,
1162                endpoint_ids,
1163                node_ids,
1164            }
1165        })
1166        .collect()
1167}
1168
1169fn audio_clock_bridge_plans(
1170    graph: &GraphDocument,
1171    endpoint_nodes: &[AudioEndpointPlanNode],
1172) -> Result<Vec<AudioClockBridgePlan>, AudioDspPlanError> {
1173    let nodes_by_id = graph
1174        .nodes
1175        .iter()
1176        .map(|node| (node.id.as_str(), node))
1177        .collect::<HashMap<_, _>>();
1178    let mut plans = Vec::new();
1179
1180    for source in endpoint_nodes
1181        .iter()
1182        .filter(|endpoint| endpoint.kind == AUDIO_INPUT_KIND)
1183    {
1184        for output in endpoint_nodes
1185            .iter()
1186            .filter(|endpoint| endpoint.kind == AUDIO_OUTPUT_KIND)
1187        {
1188            let Some(route) =
1189                find_audio_route_to_output(graph, &nodes_by_id, &source.node_id, &output.node_id)
1190            else {
1191                continue;
1192            };
1193            let bridge_node_id = route.explicit_bridge_node_id.as_deref();
1194            let source_domain = endpoint_domain(source);
1195            let target_domain = endpoint_domain(output);
1196            let mut plan = plan_audio_clock_bridge(&source_domain, &target_domain, bridge_node_id);
1197            if matches!(
1198                route.explicit_bridge_kind.as_deref(),
1199                Some(AUDIO_RESAMPLE_KIND)
1200            ) {
1201                plan.method = AudioClockBridgeMethod::Resample;
1202            }
1203            if plan.method == AudioClockBridgeMethod::Invalid {
1204                return Err(AudioDspPlanError::ClockDomainCrossingRequiresBridge {
1205                    source_node_id: source.node_id.clone(),
1206                    target_node_id: output.node_id.clone(),
1207                    source_clock_domain_id: source.clock_domain_id.clone(),
1208                    target_clock_domain_id: output.clock_domain_id.clone(),
1209                    diagnostic: Box::new(RuntimeDiagnostic::structured_error(
1210                        "audio-dsp.clock-domain-crossing-requires-bridge",
1211                        format!(
1212                            "audio signal route from {} domain {} to {} domain {} requires audio.clock-bridge or audio.resample",
1213                            source.node_id,
1214                            source.clock_domain_id,
1215                            output.node_id,
1216                            output.clock_domain_id
1217                        ),
1218                        json!({
1219                            "sourceNodeId": source.node_id.as_str(),
1220                            "targetNodeId": output.node_id.as_str(),
1221                            "sourceClockDomainId": source.clock_domain_id.as_str(),
1222                            "targetClockDomainId": output.clock_domain_id.as_str(),
1223                        }),
1224                    )),
1225                });
1226            }
1227            plans.push(plan);
1228        }
1229    }
1230
1231    Ok(plans)
1232}
1233
1234fn endpoint_domain(endpoint: &AudioEndpointPlanNode) -> AudioClockDomain {
1235    AudioClockDomain {
1236        id: endpoint.clock_domain_id.clone(),
1237        authority: if endpoint.clock_domain_id.starts_with("endpoint:") {
1238            AudioClockDomainAuthority::Unavailable
1239        } else {
1240            AudioClockDomainAuthority::UserConfigured
1241        },
1242        source: endpoint.node_id.clone(),
1243        sample_rate: None,
1244        drift_compensated: None,
1245        shared_with: None,
1246    }
1247}
1248
1249#[derive(Debug, Clone, PartialEq, Eq)]
1250struct AudioSignalRoute {
1251    explicit_bridge_node_id: Option<String>,
1252    explicit_bridge_kind: Option<String>,
1253}
1254
1255fn find_audio_route_to_output(
1256    graph: &GraphDocument,
1257    nodes_by_id: &HashMap<&str, &GraphNode>,
1258    source_node_id: &str,
1259    output_node_id: &str,
1260) -> Option<AudioSignalRoute> {
1261    let mut stack = vec![(source_node_id.to_owned(), None::<(String, String)>)];
1262    let mut visited = std::collections::HashSet::<String>::new();
1263    while let Some((node_id, bridge)) = stack.pop() {
1264        if !visited.insert(node_id.clone()) {
1265            continue;
1266        }
1267        if node_id == output_node_id {
1268            return Some(AudioSignalRoute {
1269                explicit_bridge_node_id: bridge.as_ref().map(|(id, _)| id.clone()),
1270                explicit_bridge_kind: bridge.map(|(_, kind)| kind),
1271            });
1272        }
1273        for edge in graph.edges.iter().filter(|edge| edge.from.node == node_id) {
1274            if !is_audio_signal_edge(edge, graph) {
1275                continue;
1276            }
1277            let next_bridge = nodes_by_id
1278                .get(edge.to.node.as_str())
1279                .filter(|node| is_audio_clock_boundary_kind(&node.kind))
1280                .map(|node| (node.id.clone(), node.kind.clone()))
1281                .or_else(|| bridge.clone());
1282            stack.push((edge.to.node.clone(), next_bridge));
1283        }
1284    }
1285    None
1286}
1287
1288fn is_audio_endpoint_kind(kind: &str) -> bool {
1289    kind == AUDIO_INPUT_KIND || kind == AUDIO_OUTPUT_KIND
1290}
1291
1292fn is_audio_clock_boundary_kind(kind: &str) -> bool {
1293    kind == AUDIO_CLOCK_BRIDGE_KIND || kind == AUDIO_RESAMPLE_KIND
1294}
1295
1296fn realtime_node(
1297    node: &AudioDspPlanNode,
1298    buffer_index_by_id: &BTreeMap<String, usize>,
1299    node_params_by_id: &BTreeMap<String, Map<String, Value>>,
1300) -> AudioRealtimeNode {
1301    AudioRealtimeNode {
1302        kind: realtime_node_kind(node, node_params_by_id),
1303        output_buffer: signal_output_buffer_index(node, buffer_index_by_id),
1304        left_buffer: signal_input_buffer_index(node, "left", buffer_index_by_id),
1305        right_buffer: signal_input_buffer_index(node, "right", buffer_index_by_id),
1306        phase: 0.0,
1307    }
1308}
1309
1310fn realtime_node_kind(
1311    node: &AudioDspPlanNode,
1312    node_params_by_id: &BTreeMap<String, Map<String, Value>>,
1313) -> AudioRealtimeNodeKind {
1314    match node.kind.as_str() {
1315        "audio.sig" => AudioRealtimeNodeKind::Sig {
1316            value: param_f32(&node.params, "value", 0.0),
1317        },
1318        "audio.osc" => AudioRealtimeNodeKind::Osc {
1319            frequency: control_input_f32_from_params(node, "frequency", node_params_by_id)
1320                .unwrap_or_else(|| param_f32(&node.params, "frequency", 440.0)),
1321        },
1322        "audio.operator.mul" => AudioRealtimeNodeKind::Mul,
1323        _ => AudioRealtimeNodeKind::Output,
1324    }
1325}
1326
1327fn signal_input_buffer_index(
1328    node: &AudioDspPlanNode,
1329    port_id: &str,
1330    buffer_index_by_id: &BTreeMap<String, usize>,
1331) -> Option<usize> {
1332    node.signal_inputs
1333        .iter()
1334        .find(|input| input.port_id == port_id)
1335        .and_then(|input| buffer_index_by_id.get(&input.buffer_id))
1336        .copied()
1337}
1338
1339fn signal_output_buffer_index(
1340    node: &AudioDspPlanNode,
1341    buffer_index_by_id: &BTreeMap<String, usize>,
1342) -> Option<usize> {
1343    node.signal_outputs
1344        .first()
1345        .and_then(|output| buffer_index_by_id.get(&output.buffer_id))
1346        .copied()
1347}
1348
1349fn reject_signal_ports_outside_audio_block(
1350    graph: &GraphDocument,
1351    audio_node_set: &std::collections::HashSet<&str>,
1352) -> Result<(), AudioDspPlanError> {
1353    for node in &graph.nodes {
1354        if audio_node_set.contains(node.id.as_str()) {
1355            continue;
1356        }
1357        if let Some(port) = node.ports.iter().find(|port| is_audio_signal_port(port)) {
1358            return Err(AudioDspPlanError::SignalPortOutsideAudioBlock {
1359                node_id: node.id.clone(),
1360                port_id: port.id.clone(),
1361                diagnostic: Box::new(RuntimeDiagnostic::structured_error(
1362                    "audio-dsp.signal-port-outside-audio-block",
1363                    format!(
1364                        "audio signal port {}.{} is not an audio_block node",
1365                        node.id, port.id
1366                    ),
1367                    json!({
1368                        "nodeId": node.id.as_str(),
1369                        "portId": port.id.as_str(),
1370                    }),
1371                )),
1372            });
1373        }
1374    }
1375    Ok(())
1376}
1377
1378fn audio_plan_node(
1379    node: &GraphNode,
1380    order: usize,
1381    signal_edges: &[AudioDspPlanEdge],
1382    buffer_by_output: &BTreeMap<(&str, &str), String>,
1383    graph: &GraphDocument,
1384) -> AudioDspPlanNode {
1385    let signal_inputs = signal_edges
1386        .iter()
1387        .filter(|edge| edge.to_node == node.id)
1388        .map(|edge| AudioDspSignalInput {
1389            port_id: edge.to_port.clone(),
1390            source_node_id: edge.from_node.clone(),
1391            source_port_id: edge.from_port.clone(),
1392            buffer_id: edge.buffer_id.clone(),
1393        })
1394        .collect();
1395    let signal_outputs = node
1396        .ports
1397        .iter()
1398        .filter(|port| is_audio_signal_output(port))
1399        .map(|port| AudioDspSignalOutput {
1400            port_id: port.id.clone(),
1401            buffer_id: buffer_by_output
1402                .get(&(node.id.as_str(), port.id.as_str()))
1403                .expect("audio output should have an allocated buffer")
1404                .clone(),
1405        })
1406        .collect();
1407    let control_inputs = node
1408        .ports
1409        .iter()
1410        .filter(|port| port.direction == PortDirection::Input && !is_audio_signal_port(port))
1411        .map(|port| {
1412            let source = graph
1413                .edges
1414                .iter()
1415                .find(|edge| edge.to.node == node.id && edge.to.port == port.id);
1416            AudioDspControlInput {
1417                port_id: port.id.clone(),
1418                data_kind: port.data_type.data_kind.clone(),
1419                source_node_id: source.map(|edge| edge.from.node.clone()),
1420                source_port_id: source.map(|edge| edge.from.port.clone()),
1421            }
1422        })
1423        .collect();
1424
1425    AudioDspPlanNode {
1426        node_id: node.id.clone(),
1427        kind: node.kind.clone(),
1428        kind_version: node.kind_version.clone(),
1429        order,
1430        params: node.params.clone(),
1431        signal_inputs,
1432        control_inputs,
1433        signal_outputs,
1434    }
1435}
1436
1437fn is_audio_signal_edge(edge: &Edge, graph: &GraphDocument) -> bool {
1438    let Some(from) = find_port(graph, &edge.from.node, &edge.from.port) else {
1439        return false;
1440    };
1441    let Some(to) = find_port(graph, &edge.to.node, &edge.to.port) else {
1442        return false;
1443    };
1444    is_audio_signal_output(from) && is_audio_signal_input(to)
1445}
1446
1447fn find_port<'a>(graph: &'a GraphDocument, node_id: &str, port_id: &str) -> Option<&'a Port> {
1448    graph
1449        .nodes
1450        .iter()
1451        .find(|node| node.id == node_id)
1452        .and_then(|node| node.ports.iter().find(|port| port.id == port_id))
1453}
1454
1455fn is_audio_signal_port(port: &Port) -> bool {
1456    port.data_type.flow == DataFlow::Signal && port.data_type.data_kind == AUDIO_SIGNAL_KIND
1457}
1458
1459fn is_audio_signal_input(port: &Port) -> bool {
1460    port.direction == PortDirection::Input && is_audio_signal_port(port)
1461}
1462
1463fn is_audio_signal_output(port: &Port) -> bool {
1464    port.direction == PortDirection::Output && is_audio_signal_port(port)
1465}
1466
1467#[cfg(test)]
1468mod tests {
1469    use serde_json::json;
1470
1471    use super::*;
1472    use crate::NodeDefinition;
1473
1474    fn registry() -> NodeRegistry {
1475        let mut registry = NodeRegistry::new();
1476        for definition in [
1477            audio_source_definition("audio.osc", "frequency"),
1478            audio_sig_definition(),
1479            audio_binary_definition("audio.operator.mul"),
1480            audio_unary_definition("audio.operator.sqrt", "in"),
1481            audio_snapshot_definition(),
1482            audio_input_definition(),
1483            audio_output_definition(),
1484            audio_clock_boundary_definition("audio.clock-bridge"),
1485            audio_clock_boundary_definition("audio.resample"),
1486            float_definition(),
1487            bad_signal_definition(),
1488        ] {
1489            registry.insert(definition).unwrap();
1490        }
1491        registry
1492    }
1493
1494    fn graph(value: serde_json::Value) -> GraphDocument {
1495        serde_json::from_value(value).unwrap()
1496    }
1497
1498    #[test]
1499    fn builds_stable_audio_block_plan_with_buffers_and_control_inputs() {
1500        let graph = graph(json!({
1501          "schema": "skenion.graph",
1502          "schemaVersion": "0.1.0",
1503          "id": "audio-dsp",
1504          "revision": "7",
1505          "nodes": [
1506            float_node("freq", 220.0),
1507            audio_osc_node("osc"),
1508            audio_binary_node("mul", "audio.operator.mul"),
1509            audio_snapshot_node("snap")
1510          ],
1511          "edges": [
1512            { "from": { "node": "freq", "port": "value" }, "to": { "node": "osc", "port": "frequency" } },
1513            { "from": { "node": "osc", "port": "out" }, "to": { "node": "mul", "port": "left" } },
1514            { "from": { "node": "mul", "port": "out" }, "to": { "node": "snap", "port": "signal" } }
1515          ]
1516        }));
1517
1518        let plan = build_audio_dsp_plan(
1519            &graph,
1520            &registry(),
1521            AudioDspPlanOptions {
1522                block_size: 128,
1523                sample_rate: 44_100,
1524            },
1525        )
1526        .unwrap();
1527
1528        assert_eq!(plan.graph_id, "audio-dsp");
1529        assert_eq!(plan.graph_revision, "7");
1530        assert_eq!(plan.block_size, 128);
1531        assert_eq!(plan.sample_rate, 44_100);
1532        assert_eq!(
1533            plan.nodes
1534                .iter()
1535                .map(|node| (node.order, node.node_id.as_str()))
1536                .collect::<Vec<_>>(),
1537            vec![(0, "osc"), (1, "mul"), (2, "snap")]
1538        );
1539        assert_eq!(
1540            plan.buffers
1541                .iter()
1542                .map(|buffer| {
1543                    (
1544                        buffer.id.as_str(),
1545                        buffer.producer_node_id.as_str(),
1546                        buffer.producer_port_id.as_str(),
1547                    )
1548                })
1549                .collect::<Vec<_>>(),
1550            vec![
1551                ("audio_buffer_0", "osc", "out"),
1552                ("audio_buffer_1", "mul", "out")
1553            ]
1554        );
1555        assert_eq!(
1556            plan.edges
1557                .iter()
1558                .map(|edge| {
1559                    (
1560                        edge.from_node.as_str(),
1561                        edge.from_port.as_str(),
1562                        edge.to_node.as_str(),
1563                        edge.to_port.as_str(),
1564                        edge.buffer_id.as_str(),
1565                    )
1566                })
1567                .collect::<Vec<_>>(),
1568            vec![
1569                ("osc", "out", "mul", "left", "audio_buffer_0"),
1570                ("mul", "out", "snap", "signal", "audio_buffer_1")
1571            ]
1572        );
1573        assert_eq!(
1574            plan.nodes[0].control_inputs,
1575            vec![AudioDspControlInput {
1576                port_id: "frequency".to_owned(),
1577                data_kind: "number.float".to_owned(),
1578                source_node_id: Some("freq".to_owned()),
1579                source_port_id: Some("value".to_owned()),
1580            }]
1581        );
1582        assert_eq!(
1583            plan.nodes[1].signal_inputs,
1584            vec![AudioDspSignalInput {
1585                port_id: "left".to_owned(),
1586                source_node_id: "osc".to_owned(),
1587                source_port_id: "out".to_owned(),
1588                buffer_id: "audio_buffer_0".to_owned(),
1589            }]
1590        );
1591        assert_eq!(plan.nodes[2].signal_outputs, Vec::new());
1592        assert_eq!(plan.nodes[2].control_inputs[0].port_id, "trigger");
1593    }
1594
1595    #[test]
1596    fn builds_empty_plan_when_graph_has_no_audio_nodes() {
1597        let graph = graph(json!({
1598          "schema": "skenion.graph",
1599          "schemaVersion": "0.1.0",
1600          "id": "control-only",
1601          "revision": "1",
1602          "nodes": [float_node("value", 1.0)],
1603          "edges": []
1604        }));
1605
1606        let plan =
1607            build_audio_dsp_plan(&graph, &registry(), AudioDspPlanOptions::default()).unwrap();
1608
1609        assert_eq!(plan.nodes, Vec::new());
1610        assert_eq!(plan.edges, Vec::new());
1611        assert_eq!(plan.buffers, Vec::new());
1612        assert_eq!(plan.block_size, DEFAULT_BLOCK_SIZE);
1613        assert_eq!(plan.sample_rate, DEFAULT_SAMPLE_RATE);
1614    }
1615
1616    #[test]
1617    fn plans_same_clock_domain_audio_input_to_output_as_direct_route() {
1618        let graph = graph(json!({
1619          "schema": "skenion.graph",
1620          "schemaVersion": "0.1.0",
1621          "id": "same-domain-audio-route",
1622          "revision": "1",
1623          "nodes": [
1624            audio_input_node_with_domain("input", "device:aggregate-a"),
1625            audio_output_node_with_domain("output", "device:aggregate-a")
1626          ],
1627          "edges": [
1628            { "from": { "node": "input", "port": "out" }, "to": { "node": "output", "port": "left" } }
1629          ]
1630        }));
1631
1632        let plan =
1633            build_audio_dsp_plan(&graph, &registry(), AudioDspPlanOptions::default()).unwrap();
1634
1635        assert_eq!(
1636            plan.endpoints
1637                .iter()
1638                .map(|endpoint| {
1639                    (
1640                        endpoint.node_id.as_str(),
1641                        endpoint.direction.clone(),
1642                        endpoint.clock_domain_id.as_deref(),
1643                    )
1644                })
1645                .collect::<Vec<_>>(),
1646            vec![
1647                (
1648                    "input",
1649                    AudioEndpointDirection::Input,
1650                    Some("device:aggregate-a")
1651                ),
1652                (
1653                    "output",
1654                    AudioEndpointDirection::Output,
1655                    Some("device:aggregate-a")
1656                )
1657            ]
1658        );
1659        assert_eq!(plan.clock_domains.len(), 1);
1660        assert_eq!(plan.clock_domains[0].id, "device:aggregate-a");
1661        assert_eq!(
1662            plan.clock_domains[0].authority,
1663            AudioClockDomainAuthority::UserConfigured
1664        );
1665        assert_eq!(
1666            plan.partitions
1667                .iter()
1668                .map(|partition| {
1669                    (
1670                        partition.clock_domain_id.as_str(),
1671                        partition.endpoint_ids.as_slice(),
1672                    )
1673                })
1674                .collect::<Vec<_>>(),
1675            vec![(
1676                "device:aggregate-a",
1677                ["input".to_owned(), "output".to_owned()].as_slice()
1678            )]
1679        );
1680        assert_eq!(plan.bridge_plans.len(), 1);
1681        assert_eq!(plan.bridge_plans[0].method, AudioClockBridgeMethod::Direct);
1682        assert!(!plan.bridge_plans[0].required);
1683    }
1684
1685    #[test]
1686    fn rejects_independent_audio_input_to_output_without_explicit_bridge() {
1687        let graph = graph(json!({
1688          "schema": "skenion.graph",
1689          "schemaVersion": "0.1.0",
1690          "id": "missing-clock-bridge",
1691          "revision": "1",
1692          "nodes": [
1693            audio_input_node_with_domain("input", "device:input-clock"),
1694            audio_output_node_with_domain("output", "device:output-clock")
1695          ],
1696          "edges": [
1697            { "from": { "node": "input", "port": "out" }, "to": { "node": "output", "port": "left" } }
1698          ]
1699        }));
1700
1701        let error =
1702            build_audio_dsp_plan(&graph, &registry(), AudioDspPlanOptions::default()).unwrap_err();
1703
1704        assert!(matches!(
1705            error,
1706            AudioDspPlanError::ClockDomainCrossingRequiresBridge {
1707                source_node_id,
1708                target_node_id,
1709                source_clock_domain_id,
1710                target_clock_domain_id,
1711                ..
1712            } if source_node_id == "input"
1713                && target_node_id == "output"
1714                && source_clock_domain_id == "device:input-clock"
1715                && target_clock_domain_id == "device:output-clock"
1716        ));
1717    }
1718
1719    #[test]
1720    fn unconnected_audio_endpoint_route_has_no_bridge_plan() {
1721        let graph = graph(json!({
1722          "schema": "skenion.graph",
1723          "schemaVersion": "0.1.0",
1724          "id": "unconnected-endpoints",
1725          "revision": "1",
1726          "nodes": [
1727            audio_input_node("input"),
1728            audio_output_node("output")
1729          ],
1730          "edges": []
1731        }));
1732
1733        let plan =
1734            build_audio_dsp_plan(&graph, &registry(), AudioDspPlanOptions::default()).unwrap();
1735
1736        assert_eq!(plan.endpoints.len(), 2);
1737        assert_eq!(plan.bridge_plans, Vec::new());
1738    }
1739
1740    #[test]
1741    fn partitions_audio_nodes_under_input_domain_when_no_output_exists() {
1742        let graph = graph(json!({
1743          "schema": "skenion.graph",
1744          "schemaVersion": "0.1.0",
1745          "id": "input-only-partition",
1746          "revision": "1",
1747          "nodes": [
1748            audio_input_node("input"),
1749            audio_sig_node("sig", 0.25)
1750          ],
1751          "edges": []
1752        }));
1753
1754        let plan =
1755            build_audio_dsp_plan(&graph, &registry(), AudioDspPlanOptions::default()).unwrap();
1756
1757        assert_eq!(plan.bridge_plans, Vec::new());
1758        assert_eq!(
1759            plan.partitions
1760                .iter()
1761                .map(|partition| {
1762                    (
1763                        partition.clock_domain_id.as_str(),
1764                        partition.endpoint_ids.clone(),
1765                        partition.node_ids.clone(),
1766                    )
1767                })
1768                .collect::<Vec<_>>(),
1769            vec![(
1770                "endpoint:input",
1771                vec!["input".to_owned()],
1772                vec!["input".to_owned(), "sig".to_owned()]
1773            )]
1774        );
1775    }
1776
1777    #[test]
1778    fn plans_explicit_clock_bridge_for_independent_audio_domains() {
1779        let graph = graph(json!({
1780          "schema": "skenion.graph",
1781          "schemaVersion": "0.1.0",
1782          "id": "clock-bridge-route",
1783          "revision": "1",
1784          "nodes": [
1785            audio_input_node_with_domain("input", "device:input-clock"),
1786            audio_clock_boundary_node("bridge", "audio.clock-bridge"),
1787            audio_output_node_with_domain("output", "device:output-clock")
1788          ],
1789          "edges": [
1790            { "from": { "node": "input", "port": "out" }, "to": { "node": "bridge", "port": "in" } },
1791            { "from": { "node": "bridge", "port": "out" }, "to": { "node": "output", "port": "left" } }
1792          ]
1793        }));
1794
1795        let plan =
1796            build_audio_dsp_plan(&graph, &registry(), AudioDspPlanOptions::default()).unwrap();
1797
1798        assert_eq!(plan.bridge_plans.len(), 1);
1799        assert!(plan.bridge_plans[0].required);
1800        assert_eq!(
1801            plan.bridge_plans[0].source_clock_domain_id,
1802            "device:input-clock"
1803        );
1804        assert_eq!(
1805            plan.bridge_plans[0].target_clock_domain_id,
1806            "device:output-clock"
1807        );
1808        assert_eq!(
1809            plan.bridge_plans[0].method,
1810            AudioClockBridgeMethod::ClockBridge
1811        );
1812        assert_eq!(
1813            plan.bridge_plans[0].bridge_node_id.as_deref(),
1814            Some("bridge")
1815        );
1816    }
1817
1818    #[test]
1819    fn plans_default_endpoint_domains_as_unavailable_with_explicit_bridge() {
1820        let graph = graph(json!({
1821          "schema": "skenion.graph",
1822          "schemaVersion": "0.1.0",
1823          "id": "default-endpoint-domains",
1824          "revision": "1",
1825          "nodes": [
1826            audio_input_node("input"),
1827            audio_clock_boundary_node("bridge", "audio.clock-bridge"),
1828            audio_output_node("output")
1829          ],
1830          "edges": [
1831            { "from": { "node": "input", "port": "out" }, "to": { "node": "bridge", "port": "in" } },
1832            { "from": { "node": "bridge", "port": "out" }, "to": { "node": "output", "port": "left" } }
1833          ]
1834        }));
1835
1836        let plan =
1837            build_audio_dsp_plan(&graph, &registry(), AudioDspPlanOptions::default()).unwrap();
1838
1839        assert_eq!(
1840            plan.clock_domains
1841                .iter()
1842                .map(|domain| (domain.id.as_str(), domain.authority.clone()))
1843                .collect::<Vec<_>>(),
1844            vec![
1845                ("endpoint:input", AudioClockDomainAuthority::Unavailable),
1846                ("endpoint:output", AudioClockDomainAuthority::Unavailable)
1847            ]
1848        );
1849        assert_eq!(
1850            plan.bridge_plans[0].source_clock_domain_id,
1851            "endpoint:input"
1852        );
1853        assert_eq!(
1854            plan.bridge_plans[0].target_clock_domain_id,
1855            "endpoint:output"
1856        );
1857    }
1858
1859    #[test]
1860    fn plans_explicit_resample_for_independent_audio_domains() {
1861        let graph = graph(json!({
1862          "schema": "skenion.graph",
1863          "schemaVersion": "0.1.0",
1864          "id": "resample-route",
1865          "revision": "1",
1866          "nodes": [
1867            audio_input_node_with_domain("input", "device:input-clock"),
1868            audio_clock_boundary_node("resample", "audio.resample"),
1869            audio_output_node_with_domain("output", "device:output-clock")
1870          ],
1871          "edges": [
1872            { "from": { "node": "input", "port": "out" }, "to": { "node": "resample", "port": "in" } },
1873            { "from": { "node": "resample", "port": "out" }, "to": { "node": "output", "port": "left" } }
1874          ]
1875        }));
1876
1877        let plan =
1878            build_audio_dsp_plan(&graph, &registry(), AudioDspPlanOptions::default()).unwrap();
1879
1880        assert_eq!(plan.bridge_plans.len(), 1);
1881        assert_eq!(
1882            plan.bridge_plans[0].method,
1883            AudioClockBridgeMethod::Resample
1884        );
1885        assert_eq!(
1886            plan.bridge_plans[0].bridge_node_id.as_deref(),
1887            Some("resample")
1888        );
1889    }
1890
1891    #[test]
1892    fn audio_route_helper_skips_cycles_and_non_signal_edges() {
1893        let graph = graph(json!({
1894          "schema": "skenion.graph",
1895          "schemaVersion": "0.1.0",
1896          "id": "route-helper",
1897          "revision": "1",
1898          "nodes": [
1899            audio_input_node("input"),
1900            audio_clock_boundary_node("bridge_a", "audio.clock-bridge"),
1901            audio_clock_boundary_node("bridge_b", "audio.clock-bridge"),
1902            audio_output_node("output"),
1903            float_node("not_signal", 1.0)
1904          ],
1905          "edges": [
1906            { "from": { "node": "input", "port": "out" }, "to": { "node": "not_signal", "port": "value" } },
1907            { "from": { "node": "input", "port": "out" }, "to": { "node": "bridge_a", "port": "in" } },
1908            { "from": { "node": "bridge_a", "port": "out" }, "to": { "node": "bridge_b", "port": "in" } },
1909            { "from": { "node": "bridge_b", "port": "out" }, "to": { "node": "output", "port": "left" } },
1910            { "from": { "node": "bridge_b", "port": "out" }, "to": { "node": "bridge_a", "port": "in" } }
1911          ]
1912        }));
1913        let nodes_by_id = graph
1914            .nodes
1915            .iter()
1916            .map(|node| (node.id.as_str(), node))
1917            .collect::<HashMap<_, _>>();
1918
1919        let route = find_audio_route_to_output(&graph, &nodes_by_id, "input", "output").unwrap();
1920        let missing = find_audio_route_to_output(&graph, &nodes_by_id, "output", "input");
1921
1922        assert_eq!(route.explicit_bridge_node_id.as_deref(), Some("bridge_b"));
1923        assert_eq!(
1924            route.explicit_bridge_kind.as_deref(),
1925            Some("audio.clock-bridge")
1926        );
1927        assert_eq!(missing, None);
1928    }
1929
1930    #[test]
1931    fn rejects_invalid_options_and_projects() {
1932        let graph = graph(json!({
1933          "schema": "skenion.graph",
1934          "schemaVersion": "0.1.0",
1935          "id": "invalid-options",
1936          "revision": "1",
1937          "nodes": [float_node("value", 1.0)],
1938          "edges": []
1939        }));
1940        let registry = registry();
1941
1942        let block_error = build_audio_dsp_plan(
1943            &graph,
1944            &registry,
1945            AudioDspPlanOptions {
1946                block_size: 0,
1947                sample_rate: 48_000,
1948            },
1949        )
1950        .unwrap_err();
1951        let rate_error = build_audio_dsp_plan(
1952            &graph,
1953            &registry,
1954            AudioDspPlanOptions {
1955                block_size: 64,
1956                sample_rate: 0,
1957            },
1958        )
1959        .unwrap_err();
1960        let project_error =
1961            build_audio_dsp_plan(&graph, &NodeRegistry::new(), AudioDspPlanOptions::default())
1962                .unwrap_err();
1963
1964        assert!(matches!(
1965            block_error,
1966            AudioDspPlanError::InvalidBlockSize { .. }
1967        ));
1968        assert!(matches!(
1969            rate_error,
1970            AudioDspPlanError::InvalidSampleRate { .. }
1971        ));
1972        assert!(matches!(
1973            project_error,
1974            AudioDspPlanError::InvalidProject { .. }
1975        ));
1976    }
1977
1978    #[test]
1979    fn rejects_signal_ports_outside_audio_block_nodes() {
1980        let graph = graph(json!({
1981          "schema": "skenion.graph",
1982          "schemaVersion": "0.1.0",
1983          "id": "bad-signal",
1984          "revision": "1",
1985          "nodes": [bad_signal_node("bad")],
1986          "edges": []
1987        }));
1988
1989        let error =
1990            build_audio_dsp_plan(&graph, &registry(), AudioDspPlanOptions::default()).unwrap_err();
1991
1992        assert!(matches!(
1993            error,
1994            AudioDspPlanError::SignalPortOutsideAudioBlock { .. }
1995        ));
1996        assert!(error.to_string().contains("bad.out"));
1997    }
1998
1999    #[test]
2000    fn signal_edge_helper_ignores_missing_endpoint_ports() {
2001        let graph = graph(json!({
2002          "schema": "skenion.graph",
2003          "schemaVersion": "0.1.0",
2004          "id": "missing-edge-ports",
2005          "revision": "1",
2006          "nodes": [audio_osc_node("osc"), audio_binary_node("mul", "audio.operator.mul")],
2007          "edges": []
2008        }));
2009        let missing_from = serde_json::from_value::<Edge>(json!({
2010          "from": { "node": "osc", "port": "missing" },
2011          "to": { "node": "mul", "port": "left" }
2012        }))
2013        .unwrap();
2014        let missing_to = serde_json::from_value::<Edge>(json!({
2015          "from": { "node": "osc", "port": "out" },
2016          "to": { "node": "mul", "port": "missing" }
2017        }))
2018        .unwrap();
2019
2020        assert!(!is_audio_signal_edge(&missing_from, &graph));
2021        assert!(!is_audio_signal_edge(&missing_to, &graph));
2022    }
2023
2024    #[test]
2025    fn runs_offline_sig_mul_snapshot_blocks() {
2026        let graph = graph(json!({
2027          "schema": "skenion.graph",
2028          "schemaVersion": "0.1.0",
2029          "id": "offline-mul",
2030          "revision": "3",
2031          "nodes": [
2032            audio_sig_node("left", 2.0),
2033            audio_sig_node("right", 0.5),
2034            audio_binary_node("mul", "audio.operator.mul"),
2035            audio_snapshot_node("snap")
2036          ],
2037          "edges": [
2038            { "from": { "node": "left", "port": "out" }, "to": { "node": "mul", "port": "left" } },
2039            { "from": { "node": "right", "port": "out" }, "to": { "node": "mul", "port": "right" } },
2040            { "from": { "node": "mul", "port": "out" }, "to": { "node": "snap", "port": "signal" } }
2041          ]
2042        }));
2043
2044        let report = run_offline_audio_dsp(
2045            &graph,
2046            &registry(),
2047            AudioOfflineDspOptions {
2048                blocks: 2,
2049                plan: AudioDspPlanOptions {
2050                    block_size: 4,
2051                    sample_rate: 48_000,
2052                },
2053            },
2054        )
2055        .unwrap();
2056
2057        assert_eq!(report.graph_id, "offline-mul");
2058        assert_eq!(report.graph_revision, "3");
2059        assert_eq!(report.block_size, 4);
2060        assert_eq!(report.sample_rate, 48_000);
2061        assert_eq!(report.blocks.len(), 2);
2062        assert_eq!(
2063            rendered_samples(&report, 0, "mul", "out"),
2064            vec![1.0, 1.0, 1.0, 1.0]
2065        );
2066        assert_eq!(
2067            report
2068                .snapshots
2069                .iter()
2070                .map(|snapshot| (
2071                    snapshot.block_index,
2072                    snapshot.node_id.as_str(),
2073                    snapshot.value
2074                ))
2075                .collect::<Vec<_>>(),
2076            vec![(0, "snap", 1.0), (1, "snap", 1.0)]
2077        );
2078    }
2079
2080    #[test]
2081    fn runs_offline_oscillator_with_control_frequency_and_phase_continuity() {
2082        let graph = graph(json!({
2083          "schema": "skenion.graph",
2084          "schemaVersion": "0.1.0",
2085          "id": "offline-osc",
2086          "revision": "5",
2087          "nodes": [
2088            float_node("freq", 1.0),
2089            audio_osc_node("osc")
2090          ],
2091          "edges": [
2092            { "from": { "node": "freq", "port": "value" }, "to": { "node": "osc", "port": "frequency" } }
2093          ]
2094        }));
2095
2096        let report = run_offline_audio_dsp(
2097            &graph,
2098            &registry(),
2099            AudioOfflineDspOptions {
2100                blocks: 2,
2101                plan: AudioDspPlanOptions {
2102                    block_size: 4,
2103                    sample_rate: 4,
2104                },
2105            },
2106        )
2107        .unwrap();
2108
2109        assert_samples_close(
2110            &rendered_samples(&report, 0, "osc", "out"),
2111            &[0.0, 1.0, 0.0, -1.0],
2112        );
2113        assert_samples_close(
2114            &rendered_samples(&report, 1, "osc", "out"),
2115            &[0.0, 1.0, 0.0, -1.0],
2116        );
2117    }
2118
2119    #[test]
2120    fn offline_execution_uses_param_frequency_and_zero_for_missing_signal_input() {
2121        let graph = graph(json!({
2122          "schema": "skenion.graph",
2123          "schemaVersion": "0.1.0",
2124          "id": "offline-fallbacks",
2125          "revision": "2",
2126          "nodes": [
2127            audio_osc_node("osc"),
2128            audio_sig_node("left", 3.0),
2129            audio_binary_node("mul", "audio.operator.mul")
2130          ],
2131          "edges": [
2132            { "from": { "node": "left", "port": "out" }, "to": { "node": "mul", "port": "left" } }
2133          ]
2134        }));
2135
2136        let report = run_offline_audio_dsp(
2137            &graph,
2138            &registry(),
2139            AudioOfflineDspOptions {
2140                blocks: 1,
2141                plan: AudioDspPlanOptions {
2142                    block_size: 4,
2143                    sample_rate: 1_760,
2144                },
2145            },
2146        )
2147        .unwrap();
2148
2149        assert_samples_close(
2150            &rendered_samples(&report, 0, "osc", "out"),
2151            &[0.0, 1.0, 0.0, -1.0],
2152        );
2153        assert_eq!(
2154            rendered_samples(&report, 0, "mul", "out"),
2155            vec![0.0, 0.0, 0.0, 0.0]
2156        );
2157    }
2158
2159    #[test]
2160    fn rejects_invalid_offline_options_and_unsupported_nodes() {
2161        let graph = graph(json!({
2162          "schema": "skenion.graph",
2163          "schemaVersion": "0.1.0",
2164          "id": "offline-errors",
2165          "revision": "1",
2166          "nodes": [
2167            audio_sig_node("input", -4.0),
2168            audio_unary_node("sqrt", "audio.operator.sqrt")
2169          ],
2170          "edges": [
2171            { "from": { "node": "input", "port": "out" }, "to": { "node": "sqrt", "port": "in" } }
2172          ]
2173        }));
2174
2175        let block_error = run_offline_audio_dsp(
2176            &graph,
2177            &registry(),
2178            AudioOfflineDspOptions {
2179                blocks: 0,
2180                plan: AudioDspPlanOptions::default(),
2181            },
2182        )
2183        .unwrap_err();
2184        let unsupported_error =
2185            run_offline_audio_dsp(&graph, &registry(), AudioOfflineDspOptions::default())
2186                .unwrap_err();
2187
2188        assert!(matches!(
2189            block_error,
2190            AudioOfflineDspError::InvalidBlockCount { .. }
2191        ));
2192        assert!(matches!(
2193            unsupported_error,
2194            AudioOfflineDspError::UnsupportedNodeKind { .. }
2195        ));
2196        assert!(
2197            unsupported_error
2198                .to_string()
2199                .contains("audio.operator.sqrt")
2200        );
2201    }
2202
2203    #[test]
2204    fn realtime_executor_writes_stereo_output_from_audio_output_sink() {
2205        let graph = graph(json!({
2206          "schema": "skenion.graph",
2207          "schemaVersion": "0.1.0",
2208          "id": "realtime-output",
2209          "revision": "1",
2210          "nodes": [
2211            audio_sig_node("left", 0.25),
2212            audio_sig_node("right", -0.5),
2213            audio_output_node("out")
2214          ],
2215          "edges": [
2216            { "from": { "node": "left", "port": "out" }, "to": { "node": "out", "port": "left" } },
2217            { "from": { "node": "right", "port": "out" }, "to": { "node": "out", "port": "right" } }
2218          ]
2219        }));
2220        let mut executor = AudioRealtimeDspExecutor::new_from_graph(
2221            &graph,
2222            &registry(),
2223            AudioRealtimeDspOptions {
2224                plan: AudioDspPlanOptions {
2225                    block_size: 4,
2226                    sample_rate: 48_000,
2227                },
2228                channels: 2,
2229            },
2230        )
2231        .unwrap();
2232        let mut output = vec![99.0; 8];
2233
2234        executor.process_interleaved_output(&mut output);
2235
2236        assert_eq!(executor.channels(), 2);
2237        assert_eq!(executor.plan().block_size, 4);
2238        assert_eq!(output, vec![0.25, -0.5, 0.25, -0.5, 0.25, -0.5, 0.25, -0.5]);
2239
2240        let mut empty = Vec::new();
2241        executor.process_interleaved_output(&mut empty);
2242        assert!(empty.is_empty());
2243    }
2244
2245    #[test]
2246    fn realtime_executor_runs_mul_before_audio_output_sink() {
2247        let graph = graph(json!({
2248          "schema": "skenion.graph",
2249          "schemaVersion": "0.1.0",
2250          "id": "realtime-mul",
2251          "revision": "1",
2252          "nodes": [
2253            audio_sig_node("left", 2.0),
2254            audio_sig_node("right", 0.5),
2255            audio_binary_node("mul", "audio.operator.mul"),
2256            audio_output_node("out")
2257          ],
2258          "edges": [
2259            { "from": { "node": "left", "port": "out" }, "to": { "node": "mul", "port": "left" } },
2260            { "from": { "node": "right", "port": "out" }, "to": { "node": "mul", "port": "right" } },
2261            { "from": { "node": "mul", "port": "out" }, "to": { "node": "out", "port": "left" } },
2262            { "from": { "node": "mul", "port": "out" }, "to": { "node": "out", "port": "right" } }
2263          ]
2264        }));
2265        let mut executor = AudioRealtimeDspExecutor::new_from_graph(
2266            &graph,
2267            &registry(),
2268            AudioRealtimeDspOptions {
2269                plan: AudioDspPlanOptions {
2270                    block_size: 4,
2271                    sample_rate: 48_000,
2272                },
2273                channels: 2,
2274            },
2275        )
2276        .unwrap();
2277        let mut output = vec![0.0; 8];
2278
2279        executor.process_interleaved_output(&mut output);
2280
2281        assert_eq!(output, vec![1.0; 8]);
2282    }
2283
2284    #[test]
2285    fn realtime_executor_keeps_oscillator_phase_across_partial_callbacks() {
2286        let graph = graph(json!({
2287          "schema": "skenion.graph",
2288          "schemaVersion": "0.1.0",
2289          "id": "realtime-osc",
2290          "revision": "1",
2291          "nodes": [
2292            audio_osc_node("osc"),
2293            audio_output_node("out")
2294          ],
2295          "edges": [
2296            { "from": { "node": "osc", "port": "out" }, "to": { "node": "out", "port": "left" } }
2297          ]
2298        }));
2299        let mut executor = AudioRealtimeDspExecutor::new_from_graph(
2300            &graph,
2301            &registry(),
2302            AudioRealtimeDspOptions {
2303                plan: AudioDspPlanOptions {
2304                    block_size: 4,
2305                    sample_rate: 1_760,
2306                },
2307                channels: 2,
2308            },
2309        )
2310        .unwrap();
2311        let mut output = vec![0.0; 12];
2312
2313        executor.process_interleaved_output(&mut output);
2314        let left = output
2315            .chunks_exact(2)
2316            .map(|frame| frame[0])
2317            .collect::<Vec<_>>();
2318        let right = output
2319            .chunks_exact(2)
2320            .map(|frame| frame[1])
2321            .collect::<Vec<_>>();
2322
2323        assert_samples_close(&left, &[0.0, 1.0, 0.0, -1.0, 0.0, 1.0]);
2324        assert_eq!(right, vec![0.0; 6]);
2325    }
2326
2327    #[test]
2328    fn realtime_executor_reports_output_and_kind_errors_without_processing() {
2329        let graph_without_output = graph(json!({
2330          "schema": "skenion.graph",
2331          "schemaVersion": "0.1.0",
2332          "id": "no-output",
2333          "revision": "1",
2334          "nodes": [audio_sig_node("sig", 1.0)],
2335          "edges": []
2336        }));
2337        let duplicate_outputs = graph(json!({
2338          "schema": "skenion.graph",
2339          "schemaVersion": "0.1.0",
2340          "id": "duplicate-output",
2341          "revision": "1",
2342          "nodes": [audio_output_node("a"), audio_output_node("b")],
2343          "edges": []
2344        }));
2345        let unsupported = graph(json!({
2346          "schema": "skenion.graph",
2347          "schemaVersion": "0.1.0",
2348          "id": "unsupported-realtime",
2349          "revision": "1",
2350          "nodes": [
2351            audio_unary_node("sqrt", "audio.operator.sqrt"),
2352            audio_output_node("out")
2353          ],
2354          "edges": [
2355            { "from": { "node": "sqrt", "port": "out" }, "to": { "node": "out", "port": "left" } }
2356          ]
2357        }));
2358        let invalid_channels = AudioRealtimeDspExecutor::new_from_graph(
2359            &graph_without_output,
2360            &registry(),
2361            AudioRealtimeDspOptions {
2362                plan: AudioDspPlanOptions::default(),
2363                channels: 0,
2364            },
2365        )
2366        .unwrap_err();
2367        let missing_output = AudioRealtimeDspExecutor::new_from_graph(
2368            &graph_without_output,
2369            &registry(),
2370            AudioRealtimeDspOptions::default(),
2371        )
2372        .unwrap_err();
2373        let duplicate_output = AudioRealtimeDspExecutor::new_from_graph(
2374            &duplicate_outputs,
2375            &registry(),
2376            AudioRealtimeDspOptions::default(),
2377        )
2378        .unwrap_err();
2379        let unsupported_kind = AudioRealtimeDspExecutor::new_from_graph(
2380            &unsupported,
2381            &registry(),
2382            AudioRealtimeDspOptions::default(),
2383        )
2384        .unwrap_err();
2385
2386        assert!(matches!(
2387            invalid_channels,
2388            AudioRealtimeDspError::InvalidChannelCount { .. }
2389        ));
2390        assert!(matches!(
2391            missing_output,
2392            AudioRealtimeDspError::OutputCount { count: 0, .. }
2393        ));
2394        assert!(matches!(
2395            duplicate_output,
2396            AudioRealtimeDspError::OutputCount { count: 2, .. }
2397        ));
2398        assert!(matches!(
2399            unsupported_kind,
2400            AudioRealtimeDspError::UnsupportedNodeKind { .. }
2401        ));
2402    }
2403
2404    #[test]
2405    fn realtime_control_input_helper_handles_absent_sources() {
2406        let node = AudioDspPlanNode {
2407            node_id: "osc".to_owned(),
2408            kind: "audio.osc".to_owned(),
2409            kind_version: "0.1.0".to_owned(),
2410            order: 0,
2411            params: Map::new(),
2412            signal_inputs: Vec::new(),
2413            control_inputs: vec![
2414                AudioDspControlInput {
2415                    port_id: "other".to_owned(),
2416                    data_kind: "number.float".to_owned(),
2417                    source_node_id: None,
2418                    source_port_id: None,
2419                },
2420                AudioDspControlInput {
2421                    port_id: "frequency".to_owned(),
2422                    data_kind: "number.float".to_owned(),
2423                    source_node_id: None,
2424                    source_port_id: None,
2425                },
2426            ],
2427            signal_outputs: Vec::new(),
2428        };
2429        let mut node_params = BTreeMap::new();
2430
2431        assert_eq!(
2432            control_input_f32_from_params(&node, "frequency", &node_params),
2433            None
2434        );
2435        assert_eq!(
2436            control_input_f32_from_params(&node, "missing", &node_params),
2437            None
2438        );
2439
2440        let mut node_with_missing_source = node.clone();
2441        node_with_missing_source.control_inputs[1].source_node_id = Some("missing".to_owned());
2442        assert_eq!(
2443            control_input_f32_from_params(&node_with_missing_source, "frequency", &node_params),
2444            None
2445        );
2446
2447        node_params.insert(
2448            "missing".to_owned(),
2449            Map::from_iter([("value".to_owned(), json!(12.5))]),
2450        );
2451        assert_eq!(
2452            control_input_f32_from_params(&node_with_missing_source, "frequency", &node_params),
2453            Some(12.5)
2454        );
2455    }
2456
2457    #[test]
2458    fn public_current_audio_dsp_entrypoints_validate_and_lower_internally() {
2459        let request = project_request_current(
2460            json!({
2461              "schema": "skenion.graph",
2462              "schemaVersion": "0.1.0",
2463              "id": "public-current-audio",
2464              "revision": "1",
2465              "nodes": [
2466                audio_sig_node_current("left", 0.25),
2467                audio_sig_node_current("right", -0.5),
2468                audio_output_node_current("out")
2469              ],
2470              "edges": [
2471                {
2472                  "id": "edge_left_out",
2473                  "source": { "nodeId": "left", "portId": "out" },
2474                  "target": { "nodeId": "out", "portId": "left" },
2475                  "resolvedType": "signal.audio"
2476                },
2477                {
2478                  "id": "edge_right_out",
2479                  "source": { "nodeId": "right", "portId": "out" },
2480                  "target": { "nodeId": "out", "portId": "right" },
2481                  "resolvedType": "signal.audio"
2482                }
2483              ]
2484            }),
2485            vec![
2486                audio_sig_definition_current(),
2487                audio_output_definition_current(),
2488            ],
2489        );
2490
2491        let plan = build_audio_dsp_plan_current(
2492            &request,
2493            AudioDspPlanOptions {
2494                block_size: 4,
2495                sample_rate: 48_000,
2496            },
2497        )
2498        .unwrap();
2499        assert_eq!(plan.graph_id, "public-current-audio");
2500        assert_eq!(
2501            plan.nodes
2502                .iter()
2503                .map(|node| node.node_id.as_str())
2504                .collect::<Vec<_>>(),
2505            vec!["left", "right", "out"]
2506        );
2507
2508        let mut executor = AudioRealtimeDspExecutor::new(
2509            &request,
2510            AudioRealtimeDspOptions {
2511                plan: AudioDspPlanOptions {
2512                    block_size: 4,
2513                    sample_rate: 48_000,
2514                },
2515                channels: 2,
2516            },
2517        )
2518        .unwrap();
2519        let mut output = vec![0.0; 8];
2520        executor.process_interleaved_output(&mut output);
2521        assert_eq!(output, vec![0.25, -0.5, 0.25, -0.5, 0.25, -0.5, 0.25, -0.5]);
2522
2523        let offline_request = project_request_current(
2524            json!({
2525              "schema": "skenion.graph",
2526              "schemaVersion": "0.1.0",
2527              "id": "public-current-offline-audio",
2528              "revision": "1",
2529              "nodes": [
2530                audio_sig_node_current("sig", 0.75),
2531                audio_snapshot_node_current("snap")
2532              ],
2533              "edges": [
2534                {
2535                  "id": "edge_sig_snap",
2536                  "source": { "nodeId": "sig", "portId": "out" },
2537                  "target": { "nodeId": "snap", "portId": "signal" },
2538                  "resolvedType": "signal.audio"
2539                }
2540              ]
2541            }),
2542            vec![
2543                audio_sig_definition_current(),
2544                audio_snapshot_definition_current(),
2545            ],
2546        );
2547        let report = run_offline_audio_dsp_current(
2548            &offline_request,
2549            AudioOfflineDspOptions {
2550                blocks: 1,
2551                plan: AudioDspPlanOptions {
2552                    block_size: 4,
2553                    sample_rate: 48_000,
2554                },
2555            },
2556        )
2557        .unwrap();
2558        assert_eq!(report.snapshots[0].value, 0.75);
2559
2560        let mut unsupported_request = request.clone();
2561        unsupported_request.graph.schema_version = "9.9.9".to_owned();
2562        let error =
2563            build_audio_dsp_plan_current(&unsupported_request, AudioDspPlanOptions::default())
2564                .unwrap_err();
2565        assert!(error.diagnostics().iter().any(|diagnostic| {
2566            diagnostic.code.as_deref() == Some("project.unsupported-schema-version")
2567        }));
2568    }
2569
2570    fn audio_source_definition(id: &str, input_port: &str) -> NodeDefinition {
2571        node_definition(json!({
2572          "schema": "skenion.node.definition",
2573          "schemaVersion": "0.1.0",
2574          "id": id,
2575          "version": "0.1.0",
2576          "displayName": id,
2577          "category": "Audio",
2578          "ports": [
2579            { "id": input_port, "direction": "input", "type": { "flow": "value", "dataKind": "number.float" }, "activation": "latched" },
2580            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
2581          ],
2582          "execution": { "model": "audio_block" },
2583          "state": { "persistent": false },
2584          "permissions": [],
2585          "capabilities": []
2586        }))
2587    }
2588
2589    fn audio_sig_definition() -> NodeDefinition {
2590        node_definition(json!({
2591          "schema": "skenion.node.definition",
2592          "schemaVersion": "0.1.0",
2593          "id": "audio.sig",
2594          "version": "0.1.0",
2595          "displayName": "sig~",
2596          "category": "Audio",
2597          "ports": [
2598            { "id": "value", "direction": "input", "type": { "flow": "value", "dataKind": "number.float" }, "activation": "latched" },
2599            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
2600          ],
2601          "execution": { "model": "audio_block" },
2602          "state": { "persistent": false },
2603          "permissions": [],
2604          "capabilities": []
2605        }))
2606    }
2607
2608    fn audio_binary_definition(id: &str) -> NodeDefinition {
2609        node_definition(json!({
2610          "schema": "skenion.node.definition",
2611          "schemaVersion": "0.1.0",
2612          "id": id,
2613          "version": "0.1.0",
2614          "displayName": id,
2615          "category": "Audio",
2616          "ports": [
2617            { "id": "left", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" },
2618            { "id": "right", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" },
2619            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
2620          ],
2621          "execution": { "model": "audio_block" },
2622          "state": { "persistent": false },
2623          "permissions": [],
2624          "capabilities": []
2625        }))
2626    }
2627
2628    fn audio_unary_definition(id: &str, input_port: &str) -> NodeDefinition {
2629        node_definition(json!({
2630          "schema": "skenion.node.definition",
2631          "schemaVersion": "0.1.0",
2632          "id": id,
2633          "version": "0.1.0",
2634          "displayName": id,
2635          "category": "Audio",
2636          "ports": [
2637            { "id": input_port, "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" },
2638            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
2639          ],
2640          "execution": { "model": "audio_block" },
2641          "state": { "persistent": false },
2642          "permissions": [],
2643          "capabilities": []
2644        }))
2645    }
2646
2647    fn audio_snapshot_definition() -> NodeDefinition {
2648        node_definition(json!({
2649          "schema": "skenion.node.definition",
2650          "schemaVersion": "0.1.0",
2651          "id": "audio.snapshot",
2652          "version": "0.1.0",
2653          "displayName": "snapshot~",
2654          "category": "Audio",
2655          "ports": [
2656            { "id": "signal", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" },
2657            { "id": "trigger", "direction": "input", "type": { "flow": "event", "dataKind": "message.any" }, "activation": "trigger" },
2658            { "id": "value", "direction": "output", "type": { "flow": "value", "dataKind": "number.float" } }
2659          ],
2660          "execution": { "model": "audio_block" },
2661          "state": { "persistent": false },
2662          "permissions": [],
2663          "capabilities": []
2664        }))
2665    }
2666
2667    fn audio_input_definition() -> NodeDefinition {
2668        node_definition(json!({
2669          "schema": "skenion.node.definition",
2670          "schemaVersion": "0.1.0",
2671          "id": "audio.input",
2672          "version": "0.1.0",
2673          "displayName": "adc~",
2674          "category": "Audio",
2675          "ports": [
2676            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
2677          ],
2678          "execution": { "model": "audio_block" },
2679          "state": { "persistent": false },
2680          "permissions": [],
2681          "capabilities": []
2682        }))
2683    }
2684
2685    fn audio_output_definition() -> NodeDefinition {
2686        node_definition(json!({
2687          "schema": "skenion.node.definition",
2688          "schemaVersion": "0.1.0",
2689          "id": "audio.output",
2690          "version": "0.1.0",
2691          "displayName": "dac~",
2692          "category": "Audio",
2693          "ports": [
2694            { "id": "left", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" },
2695            { "id": "right", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" }
2696          ],
2697          "execution": { "model": "audio_block" },
2698          "state": { "persistent": false },
2699          "permissions": [],
2700          "capabilities": []
2701        }))
2702    }
2703
2704    fn audio_clock_boundary_definition(id: &str) -> NodeDefinition {
2705        node_definition(json!({
2706          "schema": "skenion.node.definition",
2707          "schemaVersion": "0.1.0",
2708          "id": id,
2709          "version": "0.1.0",
2710          "displayName": id,
2711          "category": "Audio",
2712          "ports": [
2713            { "id": "in", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" },
2714            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
2715          ],
2716          "execution": { "model": "audio_block" },
2717          "state": { "persistent": false },
2718          "permissions": [],
2719          "capabilities": []
2720        }))
2721    }
2722
2723    fn float_definition() -> NodeDefinition {
2724        node_definition(json!({
2725          "schema": "skenion.node.definition",
2726          "schemaVersion": "0.1.0",
2727          "id": "core.float",
2728          "version": "0.1.0",
2729          "displayName": "Float",
2730          "category": "Core",
2731          "ports": [
2732            { "id": "value", "direction": "output", "type": { "flow": "value", "dataKind": "number.float" } }
2733          ],
2734          "execution": { "model": "value" },
2735          "state": { "persistent": false },
2736          "permissions": [],
2737          "capabilities": []
2738        }))
2739    }
2740
2741    fn bad_signal_definition() -> NodeDefinition {
2742        node_definition(json!({
2743          "schema": "skenion.node.definition",
2744          "schemaVersion": "0.1.0",
2745          "id": "test.bad-signal",
2746          "version": "0.1.0",
2747          "displayName": "Bad Signal",
2748          "category": "Test",
2749          "ports": [
2750            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
2751          ],
2752          "execution": { "model": "value" },
2753          "state": { "persistent": false },
2754          "permissions": [],
2755          "capabilities": []
2756        }))
2757    }
2758
2759    fn node_definition(value: serde_json::Value) -> NodeDefinition {
2760        serde_json::from_value(value).unwrap()
2761    }
2762
2763    fn project_request_current(
2764        graph: serde_json::Value,
2765        nodes: Vec<serde_json::Value>,
2766    ) -> ProjectRequestCurrent {
2767        ProjectRequestCurrent {
2768            document: None,
2769            graph: serde_json::from_value(graph).unwrap(),
2770            nodes: nodes
2771                .into_iter()
2772                .map(|node| serde_json::from_value::<crate::NodeDefinitionCurrent>(node).unwrap())
2773                .collect(),
2774            patch_library: Vec::new(),
2775            view_state: None,
2776        }
2777    }
2778
2779    fn audio_sig_definition_current() -> serde_json::Value {
2780        json!({
2781          "schema": "skenion.node.definition",
2782          "schemaVersion": "0.1.0",
2783          "id": "audio.sig",
2784          "version": "0.1.0",
2785          "displayName": "sig~",
2786          "category": "Audio",
2787          "ports": [
2788            { "id": "value", "direction": "input", "type": "value.number" },
2789            { "id": "out", "direction": "output", "type": "signal.audio", "rate": "audio" }
2790          ],
2791          "execution": { "model": "audio_block" },
2792          "state": { "persistent": false },
2793          "permissions": [],
2794          "capabilities": []
2795        })
2796    }
2797
2798    fn audio_snapshot_definition_current() -> serde_json::Value {
2799        json!({
2800          "schema": "skenion.node.definition",
2801          "schemaVersion": "0.1.0",
2802          "id": "audio.snapshot",
2803          "version": "0.1.0",
2804          "displayName": "snapshot~",
2805          "category": "Audio",
2806          "ports": [
2807            { "id": "signal", "direction": "input", "type": "signal.audio", "rate": "audio" },
2808            { "id": "trigger", "direction": "input", "type": "message.any", "rate": "event", "triggerMode": "trigger" },
2809            { "id": "value", "direction": "output", "type": "value.number" }
2810          ],
2811          "execution": { "model": "audio_block" },
2812          "state": { "persistent": false },
2813          "permissions": [],
2814          "capabilities": []
2815        })
2816    }
2817
2818    fn audio_output_definition_current() -> serde_json::Value {
2819        json!({
2820          "schema": "skenion.node.definition",
2821          "schemaVersion": "0.1.0",
2822          "id": "audio.output",
2823          "version": "0.1.0",
2824          "displayName": "dac~",
2825          "category": "Audio",
2826          "ports": [
2827            { "id": "left", "direction": "input", "type": "signal.audio", "rate": "audio" },
2828            { "id": "right", "direction": "input", "type": "signal.audio", "rate": "audio" }
2829          ],
2830          "execution": { "model": "audio_block" },
2831          "state": { "persistent": false },
2832          "permissions": [],
2833          "capabilities": []
2834        })
2835    }
2836
2837    fn audio_sig_node_current(id: &str, value: f64) -> serde_json::Value {
2838        json!({
2839          "id": id,
2840          "kind": "audio.sig",
2841          "kindVersion": "0.1.0",
2842          "params": { "value": value },
2843          "ports": [
2844            { "id": "value", "direction": "input", "type": "value.number" },
2845            { "id": "out", "direction": "output", "type": "signal.audio", "rate": "audio" }
2846          ]
2847        })
2848    }
2849
2850    fn audio_snapshot_node_current(id: &str) -> serde_json::Value {
2851        json!({
2852          "id": id,
2853          "kind": "audio.snapshot",
2854          "kindVersion": "0.1.0",
2855          "params": {},
2856          "ports": [
2857            { "id": "signal", "direction": "input", "type": "signal.audio", "rate": "audio" },
2858            { "id": "trigger", "direction": "input", "type": "message.any", "rate": "event", "triggerMode": "trigger" },
2859            { "id": "value", "direction": "output", "type": "value.number" }
2860          ]
2861        })
2862    }
2863
2864    fn audio_output_node_current(id: &str) -> serde_json::Value {
2865        json!({
2866          "id": id,
2867          "kind": "audio.output",
2868          "kindVersion": "0.1.0",
2869          "params": {},
2870          "ports": [
2871            { "id": "left", "direction": "input", "type": "signal.audio", "rate": "audio" },
2872            { "id": "right", "direction": "input", "type": "signal.audio", "rate": "audio" }
2873          ]
2874        })
2875    }
2876
2877    fn float_node(id: &str, value: f64) -> serde_json::Value {
2878        json!({
2879          "id": id,
2880          "kind": "core.float",
2881          "kindVersion": "0.1.0",
2882          "params": { "value": value },
2883          "ports": [
2884            { "id": "value", "direction": "output", "type": { "flow": "value", "dataKind": "number.float" } }
2885          ]
2886        })
2887    }
2888
2889    fn audio_osc_node(id: &str) -> serde_json::Value {
2890        json!({
2891          "id": id,
2892          "kind": "audio.osc",
2893          "kindVersion": "0.1.0",
2894          "params": { "frequency": 440.0 },
2895          "ports": [
2896            { "id": "frequency", "direction": "input", "type": { "flow": "value", "dataKind": "number.float" }, "activation": "latched" },
2897            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
2898          ]
2899        })
2900    }
2901
2902    fn audio_sig_node(id: &str, value: f64) -> serde_json::Value {
2903        json!({
2904          "id": id,
2905          "kind": "audio.sig",
2906          "kindVersion": "0.1.0",
2907          "params": { "value": value },
2908          "ports": [
2909            { "id": "value", "direction": "input", "type": { "flow": "value", "dataKind": "number.float" }, "activation": "latched" },
2910            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
2911          ]
2912        })
2913    }
2914
2915    fn audio_binary_node(id: &str, kind: &str) -> serde_json::Value {
2916        json!({
2917          "id": id,
2918          "kind": kind,
2919          "kindVersion": "0.1.0",
2920          "params": {},
2921          "ports": [
2922            { "id": "left", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" },
2923            { "id": "right", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" },
2924            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
2925          ]
2926        })
2927    }
2928
2929    fn audio_unary_node(id: &str, kind: &str) -> serde_json::Value {
2930        json!({
2931          "id": id,
2932          "kind": kind,
2933          "kindVersion": "0.1.0",
2934          "params": {},
2935          "ports": [
2936            { "id": "in", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" },
2937            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
2938          ]
2939        })
2940    }
2941
2942    fn audio_snapshot_node(id: &str) -> serde_json::Value {
2943        json!({
2944          "id": id,
2945          "kind": "audio.snapshot",
2946          "kindVersion": "0.1.0",
2947          "params": {},
2948          "ports": [
2949            { "id": "signal", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" },
2950            { "id": "trigger", "direction": "input", "type": { "flow": "event", "dataKind": "message.any" }, "activation": "trigger" },
2951            { "id": "value", "direction": "output", "type": { "flow": "value", "dataKind": "number.float" } }
2952          ]
2953        })
2954    }
2955
2956    fn audio_output_node(id: &str) -> serde_json::Value {
2957        json!({
2958          "id": id,
2959          "kind": "audio.output",
2960          "kindVersion": "0.1.0",
2961          "params": {},
2962          "ports": [
2963            { "id": "left", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" },
2964            { "id": "right", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" }
2965          ]
2966        })
2967    }
2968
2969    fn audio_input_node(id: &str) -> serde_json::Value {
2970        json!({
2971          "id": id,
2972          "kind": "audio.input",
2973          "kindVersion": "0.1.0",
2974          "params": {},
2975          "ports": [
2976            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
2977          ]
2978        })
2979    }
2980
2981    fn audio_input_node_with_domain(id: &str, clock_domain: &str) -> serde_json::Value {
2982        json!({
2983          "id": id,
2984          "kind": "audio.input",
2985          "kindVersion": "0.1.0",
2986          "params": { "clockDomain": clock_domain },
2987          "ports": [
2988            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
2989          ]
2990        })
2991    }
2992
2993    fn audio_output_node_with_domain(id: &str, clock_domain: &str) -> serde_json::Value {
2994        json!({
2995          "id": id,
2996          "kind": "audio.output",
2997          "kindVersion": "0.1.0",
2998          "params": { "clockDomain": clock_domain },
2999          "ports": [
3000            { "id": "left", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" },
3001            { "id": "right", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" }
3002          ]
3003        })
3004    }
3005
3006    fn audio_clock_boundary_node(id: &str, kind: &str) -> serde_json::Value {
3007        json!({
3008          "id": id,
3009          "kind": kind,
3010          "kindVersion": "0.1.0",
3011          "params": {},
3012          "ports": [
3013            { "id": "in", "direction": "input", "type": { "flow": "signal", "dataKind": "signal.audio" }, "activation": "latched" },
3014            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
3015          ]
3016        })
3017    }
3018
3019    fn bad_signal_node(id: &str) -> serde_json::Value {
3020        json!({
3021          "id": id,
3022          "kind": "test.bad-signal",
3023          "kindVersion": "0.1.0",
3024          "params": {},
3025          "ports": [
3026            { "id": "out", "direction": "output", "type": { "flow": "signal", "dataKind": "signal.audio" } }
3027          ]
3028        })
3029    }
3030
3031    fn rendered_samples(
3032        report: &AudioOfflineDspReport,
3033        block_index: usize,
3034        node_id: &str,
3035        port_id: &str,
3036    ) -> Vec<f32> {
3037        report.blocks[block_index]
3038            .buffers
3039            .iter()
3040            .find(|buffer| buffer.producer_node_id == node_id && buffer.producer_port_id == port_id)
3041            .unwrap()
3042            .samples
3043            .clone()
3044    }
3045
3046    fn assert_samples_close(actual: &[f32], expected: &[f32]) {
3047        assert_eq!(actual.len(), expected.len());
3048        for (actual, expected) in actual.iter().zip(expected.iter()) {
3049            assert!(
3050                (actual - expected).abs() < 0.000_001,
3051                "expected {expected}, got {actual}"
3052            );
3053        }
3054    }
3055}