From 254d63dd54e97aa391802443f41646b8dd8eb3d6 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 4 Jul 2026 22:38:43 +0100 Subject: [PATCH 01/44] Rework Odin transport ownership and service names --- crates/sleipnir-daemon/Cargo.toml | 22 + crates/sleipnir-daemon/src/main.rs | 3394 ++++++++++++++++++++++++++++ 2 files changed, 3416 insertions(+) create mode 100644 crates/sleipnir-daemon/Cargo.toml create mode 100644 crates/sleipnir-daemon/src/main.rs diff --git a/crates/sleipnir-daemon/Cargo.toml b/crates/sleipnir-daemon/Cargo.toml new file mode 100644 index 0000000..89294ea --- /dev/null +++ b/crates/sleipnir-daemon/Cargo.toml @@ -0,0 +1,22 @@ +[package] +name = "sleipnir-daemon" +version = "0.1.0" +edition.workspace = true +license.workspace = true +publish.workspace = true + +[[bin]] +name = "sleipnir" +path = "src/main.rs" + +[dependencies] +anyhow = "1" +cultmesh-rs = { path = "../../vendor/cultmesh-rs" } +cultnet-rs = { path = "../../vendor/cultnet-rs" } +cultcache-rs = { path = "../../vendor/cultcache-rs" } +odin-core = { path = "../odin-core" } +rmp-serde = "1.3" +serde_json = "1" + +[target.'cfg(windows)'.dependencies] +vigem-client = "0.1.4" diff --git a/crates/sleipnir-daemon/src/main.rs b/crates/sleipnir-daemon/src/main.rs new file mode 100644 index 0000000..1593737 --- /dev/null +++ b/crates/sleipnir-daemon/src/main.rs @@ -0,0 +1,3394 @@ +use anyhow::{Context, Result, anyhow}; +use cultmesh_rs::{ + CultMesh, CultMeshNodeOptions, CultMeshRudpDocumentPublishOptions, CultMeshRudpSnapshotOptions, +}; +use cultnet_rs::{ + CultNetMessage, CultNetRawDocumentRecord, CultNetRawPayloadEncoding, CultNetRudpSocketMode, + CultNetRudpSocketTransportConnection, CultNetRudpSocketTransportOptions, CultNetWireContract, + encode_cultnet_message_to_vec, +}; +use odin_core::{ + EVE_PROVIDER_ADVERTISEMENT_SCHEMA, EveProviderAdvertisementRecord, EveSurfaceStateRecord, + SleipnirInputMappingRecord, IdunnDaemonHealthRecord, MUNINN_HID_CONTROLLER_STATE_SCHEMA, + MuninnHidControllerStateRecord, OdinDocuments, OdinEndpointQuery, discover_provider_endpoints, +}; +use std::collections::HashMap; +use std::env; +use std::fs; +use std::net::{SocketAddr, ToSocketAddrs, UdpSocket}; +use std::path::PathBuf; +use std::thread; +use std::time::{Duration, Instant}; + +const SLEIPNIR_HID_RUDP_CONNECTION_ID: u32 = 0x6d75_0005; +const SLEIPNIR_COMMAND_ROUTE: &str = "cultmesh://odin/command/sleipnir/input_mapping"; +const SLEIPNIR_INPUT_MAPPING_SCHEMA: &str = "sleipnir.input_mapping.v1"; +const IDUNN_HEALTH_RUDP_CONNECTION_ID: u32 = 0x1d0d_0001; +const CULTNET_RUDP_PROTOCOL_ID: &str = "cultnet.transport.rudp.v0"; +const INPUT_STALE_NEUTRAL_AFTER: Duration = Duration::from_millis(1_500); +const INPUT_STREAM_RECONNECT_AFTER: Duration = Duration::from_secs(3); +const DEFAULT_STICK_DEADZONE: f32 = 0.12; +const HID_RUDP_MAX_FRAGMENT_BYTES: u32 = 1_200; + +#[derive(Clone, Debug, PartialEq, Eq)] +struct Options { + store_path: PathBuf, + discovery_store_path: Option, + mapping_path: Option, + device_filter: Option, + host_id: String, + interval_ms: u64, + odin_cultmesh_uri: Option, + rudp_bind: Option, + command_route: String, + idunn_rudp_health: Option, + once: bool, + dry_run: bool, + trace: bool, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +struct IdunnRudpHealthOptions { + endpoint: SocketAddr, + daemon_id: String, + health_contract: String, +} + +struct ActiveRudpStream { + transport: CultNetRudpSocketTransportConnection, + target: Option, + last_connect_attempt_at: Option, + connected_logged: bool, + last_frame_at: Option, + last_stale_log_at: Option, + last_subscription: Option, + last_subscription_at: Option, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +struct HidControllerRudpSubscription { + device_filter: Option, + stream_id: Option, +} + +#[derive(Clone, Debug)] +struct SleipnirRuntimeState { + provider_id: String, + selected_muninn_endpoint: Option, + selected_device_filter: Option, + presentation: String, + virtual_backend: String, + stream_state: String, + last_device_id: Option, + last_device_kind: Option, + last_sequence: Option, + last_frame_age_ms: Option, + ignored_stream_frames: u64, + available_devices: Vec, + axis_map: HashMap, + button_map: HashMap, + pending_learn: Option, + updated_at: String, +} + +#[derive(Clone, Debug, PartialEq)] +struct SleipnirDesiredMapping { + enabled: bool, + device_filter: Option, + stream_id: Option, + presentation: String, + axis_map: HashMap, + button_map: HashMap, + pending_learn: Option, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +struct LearnRequest { + target: String, + binding_kind: String, + requested_at: Option, +} + +#[derive(Clone, Debug, PartialEq)] +struct AxisBinding { + source: usize, + invert: bool, + scale: f32, + deadzone: f32, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +struct AvailableHidDevice { + device_id: String, + device_kind: String, + source_path: String, + stream_id: String, + host_id: String, + endpoint: String, +} + +#[derive(Clone, Debug, PartialEq)] +struct VirtualPadState { + buttons: Vec, + left_x: i16, + left_y: i16, + left_trigger: u8, + right_trigger: u8, +} + +impl Default for VirtualPadState { + fn default() -> Self { + Self { + buttons: Vec::new(), + left_x: 0, + left_y: 0, + left_trigger: 0, + right_trigger: 0, + } + } +} + +trait VirtualPadBackend { + fn update(&mut self, state: &VirtualPadState) -> Result<()>; +} + +struct LoggingBackend; + +impl VirtualPadBackend for LoggingBackend { + fn update(&mut self, state: &VirtualPadState) -> Result<()> { + println!( + "Sleipnir dry-run virtual pad lx={} ly={} lt={} rt={} buttons=[{}]", + state.left_x, + state.left_y, + state.left_trigger, + state.right_trigger, + state.buttons.join(",") + ); + Ok(()) + } +} + +#[cfg(windows)] +struct VigemXboxBackend { + target: vigem_client::Xbox360Wired, +} + +#[cfg(windows)] +impl VigemXboxBackend { + fn connect() -> Result { + let client = vigem_client::Client::connect().context("connecting to ViGEmBus")?; + let mut target = + vigem_client::Xbox360Wired::new(client, vigem_client::TargetId::XBOX360_WIRED); + target + .plugin() + .context("plugging in virtual Xbox 360 controller")?; + target + .wait_ready() + .context("waiting for virtual Xbox 360 controller readiness")?; + Ok(Self { target }) + } +} + +#[cfg(windows)] +impl VirtualPadBackend for VigemXboxBackend { + fn update(&mut self, state: &VirtualPadState) -> Result<()> { + let mut raw_buttons = 0u16; + for button in &state.buttons { + raw_buttons |= xbutton_mask(button); + } + let gamepad = vigem_client::XGamepad { + buttons: vigem_client::XButtons::from(raw_buttons), + left_trigger: state.left_trigger, + right_trigger: state.right_trigger, + thumb_lx: state.left_x, + thumb_ly: state.left_y, + thumb_rx: 0, + thumb_ry: 0, + ..Default::default() + }; + self.target + .update(&gamepad) + .context("updating virtual Xbox 360 controller") + } +} + +#[cfg(windows)] +fn xbutton_mask(button: &str) -> u16 { + match button { + "up" => vigem_client::XButtons::UP, + "down" => vigem_client::XButtons::DOWN, + "left" => vigem_client::XButtons::LEFT, + "right" => vigem_client::XButtons::RIGHT, + "start" => vigem_client::XButtons::START, + "select" | "back" => vigem_client::XButtons::BACK, + "l3" => vigem_client::XButtons::LTHUMB, + "r3" => vigem_client::XButtons::RTHUMB, + "l1" => vigem_client::XButtons::LB, + "r1" => vigem_client::XButtons::RB, + "ps" | "guide" => vigem_client::XButtons::GUIDE, + "cross" | "a" => vigem_client::XButtons::A, + "circle" | "o" | "b" => vigem_client::XButtons::B, + "square" | "x" => vigem_client::XButtons::X, + "triangle" | "y" => vigem_client::XButtons::Y, + _ => 0, + } +} + +fn main() -> Result<()> { + let options = Options::parse(env::args().skip(1))?; + let mut node = CultMesh::create_node( + &options.store_path, + OdinDocuments, + CultMeshNodeOptions { + runtime_id: "sleipnir-daemon".to_string(), + pull_on_start: true, + }, + ) + .with_context(|| format!("opening CultMesh store {}", options.store_path.display()))?; + let mut discovery_node = + if let Some(discovery_store_path) = options.discovery_store_path.as_ref() { + Some( + CultMesh::create_node( + discovery_store_path, + OdinDocuments, + CultMeshNodeOptions { + runtime_id: "sleipnir-discovery".to_string(), + pull_on_start: true, + }, + ) + .with_context(|| { + format!( + "opening Sleipnir discovery CultMesh store {}", + discovery_store_path.display() + ) + })?, + ) + } else { + None + }; + pull_odin_catalog_snapshot(discovery_node.as_mut().unwrap_or(&mut node), &options); + + let mut desired_mapping = read_desired_mapping_from_sources( + &mut node, + discovery_node.as_mut(), + &options, + ); + let mut backend: Box = if options.dry_run { + Box::new(LoggingBackend) + } else { + create_backend()? + }; + let mut current_device_filter = effective_device_filter(&options, &desired_mapping); + let discovered_endpoint = if desired_mapping.enabled { + effective_muninn_hid_endpoint( + discovery_node.as_ref().unwrap_or(&node), + current_device_filter.as_deref(), + desired_mapping.stream_id.as_deref(), + options.trace, + ) + } else { + None + }; + if options.trace { + if !desired_mapping.enabled { + eprintln!("Sleipnir input consumption is disabled; publishing control surface only"); + } else { + match discovered_endpoint.as_deref() { + Some(endpoint) => eprintln!("Sleipnir selected Muninn HID endpoint {endpoint}"), + None => eprintln!("Sleipnir found no Odin-discovered Muninn HID endpoint; waiting"), + } + } + } + let mut rudp_stream = + create_rudp_stream(options.rudp_bind, discovered_endpoint, options.trace)?; + let mut last_rudp_discovery_attempt_at = Instant::now(); + let initial_state = { + let discovery_ref = discovery_node.as_ref().unwrap_or(&node); + SleipnirRuntimeState::from_runtime( + &options, + current_device_filter.as_deref(), + discovery_ref, + rudp_stream.as_ref(), + None, + 0, + &desired_mapping, + ) + }; + publish_sleipnir_runtime_surface(&mut node, &options, &initial_state, true)?; + let mut last_idunn_health_attempt_at = Instant::now() - Duration::from_secs(60); + publish_idunn_health_if_configured( + &options, + &initial_state, + &mut last_idunn_health_attempt_at, + ); + + let mut last_sequence_by_device = HashMap::::new(); + let mut ignored_stream_frames = 0u64; + let mut last_surface_publish_at = Instant::now() - Duration::from_secs(60); + let mut last_odin_catalog_pull_at = Instant::now() - Duration::from_secs(60); + let mut recent_applied_record: Option = None; + let mut output_is_neutral = true; + let mut last_output_frame_at: Option = None; + let mut last_output_source_timestamp_ns: Option = None; + loop { + let input_stream_needs_discovery = rudp_stream + .as_ref() + .is_none_or(|stream| stream.target.is_none()); + if input_stream_needs_discovery + && last_odin_catalog_pull_at.elapsed() >= Duration::from_secs(2) + { + pull_odin_catalog_snapshot(discovery_node.as_mut().unwrap_or(&mut node), &options); + last_odin_catalog_pull_at = Instant::now(); + } + let next_desired_mapping = read_desired_mapping_from_sources( + &mut node, + discovery_node.as_mut(), + &options, + ); + if next_desired_mapping != desired_mapping { + desired_mapping = next_desired_mapping; + current_device_filter = effective_device_filter(&options, &desired_mapping); + let rediscovered_endpoint = if desired_mapping.enabled { + effective_muninn_hid_endpoint( + discovery_node.as_ref().unwrap_or(&node), + current_device_filter.as_deref(), + desired_mapping.stream_id.as_deref(), + options.trace, + ) + } else { + None + }; + if options.trace { + eprintln!( + "Sleipnir mapping changed device={:?} discovered_muninn_endpoint={:?}", + current_device_filter, rediscovered_endpoint + ); + } + backend.update(&VirtualPadState::default())?; + output_is_neutral = true; + last_output_frame_at = Some(Instant::now()); + last_output_source_timestamp_ns = None; + drop(rudp_stream.take()); + rudp_stream = + create_rudp_stream(options.rudp_bind, rediscovered_endpoint, options.trace)?; + last_sequence_by_device.clear(); + } + let mut last_applied_record: Option = None; + if let Some(stream) = rudp_stream.as_mut() { + if ensure_rudp_connected(stream, options.trace)? { + if !output_is_neutral { + backend.update(&VirtualPadState::default())?; + output_is_neutral = true; + last_output_frame_at = Some(Instant::now()); + last_output_source_timestamp_ns = None; + if options.trace { + eprintln!( + "Sleipnir neutralized virtual pad before recreating stale Muninn HID RUDP connection for filter={:?}", + current_device_filter + ); + } + } + let rediscovered_endpoint = if desired_mapping.enabled { + effective_muninn_hid_endpoint( + discovery_node.as_ref().unwrap_or(&node), + current_device_filter.as_deref(), + desired_mapping.stream_id.as_deref(), + options.trace, + ) + } else { + None + }; + drop(rudp_stream.take()); + rudp_stream = + create_rudp_stream(options.rudp_bind, rediscovered_endpoint, options.trace)?; + last_rudp_discovery_attempt_at = Instant::now(); + } else { + send_hid_subscription_if_due( + stream, + current_device_filter.clone(), + desired_mapping.stream_id.clone(), + options.trace, + )?; + let records = receive_rudp_records(stream, options.trace)?; + for record in records { + if record_matches_filter(&record, current_device_filter.as_deref()) { + stream.last_frame_at = Some(Instant::now()); + stream.last_stale_log_at = None; + if desired_mapping.pending_learn.is_some() { + if let Some(updated_mapping) = + apply_pending_learn(&mut node, &options, &desired_mapping, &record)? + { + desired_mapping = updated_mapping; + } + } + let previous = last_sequence_by_device + .insert(record.device_id.clone(), record.sequence) + .unwrap_or_default(); + let has_new_sequence = record.sequence != previous || options.once; + let has_new_source_timestamp = last_output_source_timestamp_ns + .is_none_or(|last| record.source_timestamp_ns > last); + if has_new_sequence && has_new_source_timestamp { + let state = map_record_to_virtual_pad(&record, &desired_mapping); + let output_frame_at = Instant::now(); + if options.trace { + let source_age_ms = unix_nanos_i64() + .saturating_sub(record.source_timestamp_ns) + / 1_000_000; + eprintln!( + "Sleipnir applying fast HID frame device={} seq={} source_age_ms={} lx={} ly={} lt={} rt={} buttons=[{}]", + record.device_id, + record.sequence, + source_age_ms, + state.left_x, + state.left_y, + state.left_trigger, + state.right_trigger, + state.buttons.join(",") + ); + } + match backend.update(&state) { + Ok(()) => { + output_is_neutral = state == VirtualPadState::default(); + last_output_frame_at = Some(output_frame_at); + last_output_source_timestamp_ns = + Some(record.source_timestamp_ns); + last_applied_record = Some(record); + } + Err(error) => { + eprintln!( + "Sleipnir virtual pad update failed for device={} seq={}: {error:#}", + record.device_id, record.sequence + ); + last_applied_record = Some(record); + } + } + } + } else if options.trace { + ignored_stream_frames = ignored_stream_frames.saturating_add(1); + if ignored_stream_frames <= 5 || ignored_stream_frames % 120 == 0 { + eprintln!( + "Sleipnir ignored fast HID frame device={} kind={} stream={} filter={:?}", + record.device_id, + record.device_kind, + record.stream_id, + options.device_filter + ); + } + } + } + if desired_mapping.enabled + && !output_is_neutral + && last_output_frame_at + .is_none_or(|last_frame| last_frame.elapsed() >= INPUT_STALE_NEUTRAL_AFTER) + { + let stale_for = last_output_frame_at.map(|last_frame| last_frame.elapsed()); + backend.update(&VirtualPadState::default())?; + output_is_neutral = true; + last_output_frame_at = Some(Instant::now()); + if options.trace { + eprintln!( + "Sleipnir neutralized virtual pad after {:?} without a new selected input sequence for filter={:?}", + stale_for, + current_device_filter + ); + } + } + } + } else if last_rudp_discovery_attempt_at.elapsed() >= Duration::from_secs(2) { + let rediscovered_endpoint = if desired_mapping.enabled { + effective_muninn_hid_endpoint( + discovery_node.as_ref().unwrap_or(&node), + current_device_filter.as_deref(), + desired_mapping.stream_id.as_deref(), + options.trace, + ) + } else { + None + }; + if rediscovered_endpoint.is_some() { + drop(rudp_stream.take()); + rudp_stream = + create_rudp_stream(options.rudp_bind, rediscovered_endpoint, options.trace)?; + let runtime_state = { + let discovery_ref = discovery_node.as_ref().unwrap_or(&node); + SleipnirRuntimeState::from_runtime( + &options, + current_device_filter.as_deref(), + discovery_ref, + rudp_stream.as_ref(), + recent_applied_record.as_ref(), + ignored_stream_frames, + &desired_mapping, + ) + }; + publish_sleipnir_runtime_surface(&mut node, &options, &runtime_state, true)?; + publish_idunn_health_if_configured( + &options, + &runtime_state, + &mut last_idunn_health_attempt_at, + ); + } else if options.trace && desired_mapping.enabled { + eprintln!("Sleipnir still has no Odin-discovered Muninn HID endpoint"); + } + last_rudp_discovery_attempt_at = Instant::now(); + } + let surface_age = last_surface_publish_at.elapsed(); + if rudp_stream + .as_ref() + .is_none_or(|stream| stream.target.is_none()) + && surface_age >= Duration::from_secs(5) + { + if let Some(record) = last_applied_record.as_ref() { + recent_applied_record = Some(record.clone()); + } + let runtime_state = { + let discovery_ref = discovery_node.as_ref().unwrap_or(&node); + SleipnirRuntimeState::from_runtime( + &options, + current_device_filter.as_deref(), + discovery_ref, + rudp_stream.as_ref(), + recent_applied_record.as_ref(), + ignored_stream_frames, + &desired_mapping, + ) + }; + publish_sleipnir_runtime_surface(&mut node, &options, &runtime_state, false)?; + publish_idunn_health_if_configured( + &options, + &runtime_state, + &mut last_idunn_health_attempt_at, + ); + last_surface_publish_at = Instant::now(); + } + if options.once { + break; + } + thread::sleep(Duration::from_millis(options.interval_ms.max(1))); + } + Ok(()) +} + +impl SleipnirRuntimeState { + fn from_runtime( + options: &Options, + selected_device_filter: Option<&str>, + discovery_node: &cultmesh_rs::CultMeshNode, + stream: Option<&ActiveRudpStream>, + last_record: Option<&MuninnHidControllerStateRecord>, + ignored_stream_frames: u64, + desired_mapping: &SleipnirDesiredMapping, + ) -> Self { + let has_recent_frame = stream + .and_then(|stream| stream.last_frame_at) + .is_some_and(|last_frame| last_frame.elapsed() < Duration::from_secs(3)); + let stream_state = match stream { + _ if !desired_mapping.enabled => "idle", + Some(_) if has_recent_frame => "connected", + Some(stream) if stream.transport.connected() => "connected", + Some(stream) if stream.target.is_some() => "connecting", + Some(_) => "listening", + None => "discovering", + } + .to_string(); + let selected_muninn_endpoint = stream + .and_then(|stream| stream.target) + .map(|target| target.to_string()); + let mut available_devices = discover_available_hid_devices(discovery_node); + if let (Some(record), Some(endpoint)) = (last_record, selected_muninn_endpoint.as_deref()) { + upsert_available_hid_device( + &mut available_devices, + AvailableHidDevice { + device_id: record.device_id.clone(), + device_kind: record.device_kind.clone(), + source_path: record.source_path.clone(), + stream_id: record.stream_id.clone(), + host_id: record.host_id.clone(), + endpoint: endpoint.to_string(), + }, + ); + } + Self { + provider_id: sleipnir_provider_id(options), + selected_muninn_endpoint, + selected_device_filter: selected_device_filter.map(ToString::to_string), + presentation: default_presentation(), + virtual_backend: if options.dry_run { + "logging.dry-run" + } else if cfg!(windows) { + "vigem.xbox360" + } else { + "unavailable" + } + .to_string(), + stream_state, + last_device_id: last_record.map(|record| record.device_id.clone()), + last_device_kind: last_record.map(|record| record.device_kind.clone()), + last_sequence: last_record.map(|record| record.sequence), + last_frame_age_ms: stream + .and_then(|stream| stream.last_frame_at) + .map(|last_frame| last_frame.elapsed().as_millis()), + ignored_stream_frames, + available_devices, + axis_map: desired_mapping.axis_map.clone(), + button_map: desired_mapping.button_map.clone(), + pending_learn: desired_mapping.pending_learn.clone(), + updated_at: timestamp(), + } + } +} + +fn publish_sleipnir_runtime_surface( + node: &mut cultmesh_rs::CultMeshNode, + options: &Options, + state: &SleipnirRuntimeState, + publish_remote: bool, +) -> Result<()> { + let mut advertisement = EveProviderAdvertisementRecord { + value: serde_json::json!({ + "schema": "gamecult.eve.provider_advertisement.v1", + "providerId": state.provider_id, + "daemonId": sleipnir_daemon_id(options), + "title": sleipnir_provider_title(options), + "description": "Sleipnir mirrors Muninn-discovered input streams into a local virtual HID backend.", + "canonicalService": "asgard.sleipnir", + "locatedService": format!("asgard.{}.sleipnir", options.host_id), + "verseId": format!("{}.local", options.host_id), + "cultMeshAddress": format!("asgard.{}.sleipnir/input-mirror", options.host_id), + "status": state.stream_state, + "mode": "daemon-live", + "updatedAt": state.updated_at, + "stateStore": options.store_path.display().to_string(), + "surfaceId": state.provider_id, + "capabilities": [ + "muninn.input.discovery", + "cultmesh.input.stream.consumer", + "virtual-hid.xinput" + ], + "endpoints": [ + { + "transport": "cultcache-store", + "address": options.store_path.display().to_string() + } + ], + "routes": [ + { + "transport": "cultcache-store", + "address": options.store_path.display().to_string() + } + ] + }), + }; + if let Some(routes) = advertisement + .value + .get_mut("routes") + .and_then(|value| value.as_array_mut()) + { + routes.push(serde_json::json!({ + "transport": "cultnet.transport.rudp.v0", + "address": options.command_route, + "resolver": "odin-cultmesh", + "schema": SLEIPNIR_INPUT_MAPPING_SCHEMA, + "role": "sleipnir.input_mapping.command", + "channel": "schema" + })); + } + let surface = EveSurfaceStateRecord { + provider_id: state.provider_id.clone(), + title: sleipnir_provider_title(options), + version: unix_millis_i64(), + updated_at: state.updated_at.clone(), + surface: sleipnir_surface_document(state), + }; + node.put(&state.provider_id, &advertisement)?; + node.put(&state.provider_id, &surface)?; + if publish_remote && let Some(target) = resolve_odin_cultmesh_uri(options) { + if let Err(error) = node.publish_document_to_rudp_catalog( + &state.provider_id, + &advertisement, + CultMeshRudpDocumentPublishOptions { + target, + runtime_id: sleipnir_daemon_id(options), + source_role: Some("sleipnir.input-mirror-provider".to_string()), + tags: vec!["sleipnir".to_string(), "odin-verse-discovery".to_string()], + ..CultMeshRudpDocumentPublishOptions::default() + }, + ) { + if options.trace { + eprintln!("Sleipnir could not publish provider advertisement to Odin: {error:#}"); + } + } + if let Err(error) = node.publish_document_to_rudp_catalog( + &state.provider_id, + &surface, + CultMeshRudpDocumentPublishOptions { + target, + runtime_id: sleipnir_daemon_id(options), + source_role: Some("sleipnir.input-mirror-surface".to_string()), + tags: vec!["sleipnir".to_string(), "eve-surface".to_string()], + flush_timeout: Duration::from_millis(300), + resend_delay_ms: 15, + ..CultMeshRudpDocumentPublishOptions::default() + }, + ) { + if options.trace { + eprintln!("Sleipnir could not publish surface state to Odin: {error:#}"); + } + } + } + Ok(()) +} + +fn publish_idunn_health_if_configured( + options: &Options, + state: &SleipnirRuntimeState, + last_attempt_at: &mut Instant, +) { + let Some(idunn) = options.idunn_rudp_health.as_ref() else { + return; + }; + if last_attempt_at.elapsed() < Duration::from_secs(5) { + return; + } + *last_attempt_at = Instant::now(); + let health_state = if state.stream_state == "connected" || state.stream_state == "idle" { + "active" + } else { + "degraded" + }; + let detail = format!( + "Sleipnir {}: endpoint={} device={} sequence={} age_ms={}", + state.stream_state, + state + .selected_muninn_endpoint + .as_deref() + .unwrap_or("discovering"), + state + .selected_device_filter + .as_deref() + .unwrap_or("unselected"), + state + .last_sequence + .map(|sequence| sequence.to_string()) + .unwrap_or_else(|| "none".to_string()), + state + .last_frame_age_ms + .map(|age| age.to_string()) + .unwrap_or_else(|| "none".to_string()) + ); + if let Err(error) = publish_idunn_rudp_health(idunn, health_state, &detail, &state.updated_at) { + if options.trace { + eprintln!( + "Sleipnir could not publish Idunn RUDP health for {} at {}: {error:#}", + idunn.daemon_id, state.updated_at + ); + } + } +} + +fn publish_idunn_rudp_health( + options: &IdunnRudpHealthOptions, + state: &str, + detail: &str, + observed_at: &str, +) -> Result<()> { + let health = IdunnDaemonHealthRecord { + daemon_id: options.daemon_id.clone(), + state: state.to_string(), + detail: detail.to_string(), + observed_at: observed_at.to_string(), + health_contract: options.health_contract.clone(), + publication_source: "daemon-published".to_string(), + transport: CULTNET_RUDP_PROTOCOL_ID.to_string(), + }; + let message = CultNetMessage::DocumentPutRaw { + message_id: format!( + "sleipnir-health:{}:{}", + options.daemon_id, + observed_at.replace(':', "-") + ), + document: CultNetRawDocumentRecord { + schema_id: "idunn.daemon_health".to_string(), + record_key: options.daemon_id.clone(), + stored_at: observed_at.to_string(), + payload_encoding: CultNetRawPayloadEncoding::Messagepack, + payload: rmp_serde::to_vec(&health).context("encoding Idunn daemon health")?, + source_runtime_id: Some("sleipnir-daemon".to_string()), + source_agent_id: None, + source_role: Some("daemon-health-publisher".to_string()), + tags: Some(vec![CULTNET_RUDP_PROTOCOL_ID.to_string()]), + }, + }; + let bind_address = if options.endpoint.is_ipv4() { + "0.0.0.0:0" + } else { + "[::]:0" + }; + let socket = UdpSocket::bind(bind_address) + .with_context(|| format!("binding Sleipnir Idunn RUDP sender at {bind_address}"))?; + socket.set_read_timeout(Some(Duration::from_millis(100)))?; + let mut transport = + CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions::client( + "sleipnir-daemon", + socket, + options.endpoint, + IDUNN_HEALTH_RUDP_CONNECTION_ID, + ))?; + transport.connect(Vec::new())?; + let deadline = Instant::now() + Duration::from_millis(300); + while !transport.connected() { + let _ = transport.receive_once()?; + transport.poll_resends()?; + if Instant::now() >= deadline { + return Err(anyhow!( + "timed out connecting Sleipnir RUDP sender to {}", + options.endpoint + )); + } + } + let payload = encode_cultnet_message_to_vec(&message, CultNetWireContract::CultNetSchemaV0) + .context("encoding Idunn health CultNet message")?; + transport + .send("schema", payload) + .with_context(|| format!("sending Sleipnir Idunn health to {}", options.endpoint))?; + Ok(()) +} + +fn resolve_odin_cultmesh_uri(options: &Options) -> Option { + let uri = options.odin_cultmesh_uri.as_deref()?.trim(); + if uri.is_empty() { + return None; + } + match CultMesh::resolve_rudp_endpoint(uri) { + Ok(target) => Some(target), + Err(error) => { + if options.trace { + eprintln!("Sleipnir could not resolve Odin CultMesh URI {uri}: {error:#}"); + } + None + } + } +} + +fn pull_odin_catalog_snapshot(node: &mut cultmesh_rs::CultMeshNode, options: &Options) { + let Some(target) = resolve_odin_cultmesh_uri(options) else { + return; + }; + let hid_result = node.pull_rudp_catalog_snapshot(CultMeshRudpSnapshotOptions { + target, + runtime_id: format!("sleipnir-{}-catalog-client", options.host_id), + schema_ids: Some(vec![ + MUNINN_HID_CONTROLLER_STATE_SCHEMA.to_string(), + SLEIPNIR_INPUT_MAPPING_SCHEMA.to_string(), + ]), + connect_timeout: Duration::from_millis(150), + response_timeout: Duration::from_millis(150), + resend_delay_ms: 15, + ..CultMeshRudpSnapshotOptions::default() + }); + match hid_result { + Ok(count) if options.trace => { + eprintln!("Sleipnir pulled {count} Odin HID/mapping discovery records from {target}"); + } + Ok(_) => {} + Err(error) if options.trace => { + eprintln!("Sleipnir Odin HID/mapping snapshot pull failed from {target}: {error:#}"); + } + Err(_) => return, + } + + let provider_keys = muninn_provider_keys_for_discovered_hid_hosts(node); + if provider_keys.is_empty() { + return; + } + let provider_result = node.pull_rudp_catalog_snapshot(CultMeshRudpSnapshotOptions { + target, + runtime_id: format!("sleipnir-{}-provider-catalog-client", options.host_id), + schema_ids: Some(vec![EVE_PROVIDER_ADVERTISEMENT_SCHEMA.to_string()]), + record_keys: Some(provider_keys), + connect_timeout: Duration::from_millis(150), + response_timeout: Duration::from_millis(150), + resend_delay_ms: 15, + ..CultMeshRudpSnapshotOptions::default() + }); + match provider_result { + Ok(count) if options.trace => { + eprintln!("Sleipnir pulled {count} Odin Muninn provider records from {target}"); + } + Ok(_) => {} + Err(error) if options.trace => { + eprintln!("Sleipnir Odin Muninn provider snapshot pull failed from {target}: {error:#}"); + } + Err(_) => {} + } +} + +fn muninn_provider_keys_for_discovered_hid_hosts(node: &cultmesh_rs::CultMeshNode) -> Vec { + let mut keys = node + .cache() + .get_all::() + .ok() + .into_iter() + .flatten() + .map(|record| format!("muninn.telemetry.{}", record.host_id)) + .collect::>(); + for envelope in node.cache().snapshot() { + if envelope.schema_id.as_deref() != Some(MUNINN_HID_CONTROLLER_STATE_SCHEMA) + && envelope.r#type != "muninn.hid_controller_state" + { + continue; + } + let Ok(value) = rmp_serde::from_slice::(&envelope.payload) else { + continue; + }; + if let Some(host_id) = hid_state_host_id_from_value(&value) { + keys.push(format!("muninn.telemetry.{host_id}")); + } + } + keys.sort(); + keys.dedup(); + keys +} + +fn hid_state_host_id_from_value(value: &serde_json::Value) -> Option { + let payload = value + .as_array() + .and_then(|items| { + (items.len() == 1) + .then(|| items.first()) + .flatten() + .filter(|item| item.is_object() || item.is_array()) + }) + .unwrap_or(value); + if let Some(items) = payload.as_array() { + return items.get(1)?.as_str().map(ToString::to_string); + } + string_field(payload, &["host_id", "hostId"]) +} + +fn sleipnir_surface_document(state: &SleipnirRuntimeState) -> serde_json::Value { + let preset_cards = remap_preset_cards(state); + let binding_map = xbox_binding_map(state); + let device_cards = state + .available_devices + .iter() + .map(|device| { + let selected = state.selected_device_filter.as_deref() == Some(device.device_id.as_str()) + || state.selected_device_filter.as_deref() == Some(device.device_kind.as_str()) + || state.selected_device_filter.as_deref() == Some(device.stream_id.as_str()); + serde_json::json!({ + "id": format!("{}.device.{}", state.provider_id, stable_id(&device.device_id)), + "kind": "card", + "props": { + "title": format!("{} {}", if selected { "selected" } else { "available" }, device.device_id), + "commandId": "sleipnir.map-hid-device", + "action": { + "type": "sleipnir.map-hid-device", + "providerId": state.provider_id, + "deviceFilter": device.device_id, + "streamId": device.stream_id + } + }, + "children": [ + text_element(format!("{}.device.{}.kind", state.provider_id, stable_id(&device.device_id)), format!("kind: {}", device.device_kind)), + text_element(format!("{}.device.{}.host", state.provider_id, stable_id(&device.device_id)), format!("host: {}", device.host_id)), + text_element(format!("{}.device.{}.endpoint", state.provider_id, stable_id(&device.device_id)), format!("endpoint: {}", device.endpoint)), + text_element(format!("{}.device.{}.path", state.provider_id, stable_id(&device.device_id)), format!("source: {}", device.source_path)) + ] + }) + }) + .collect::>(); + let mut runtime_children = vec![ + serde_json::json!({ + "id": format!("{}.disable", state.provider_id), + "kind": "card", + "props": { + "title": "Stop consuming input", + "commandId": "sleipnir.disable-input", + "action": { + "type": "sleipnir.disable-input", + "providerId": state.provider_id + } + }, + "children": [] + }), + text_element( + format!("{}.state", state.provider_id), + format!("state: {}", state.stream_state), + ), + text_element( + format!("{}.backend", state.provider_id), + format!("virtual backend: {}", state.virtual_backend), + ), + text_element( + format!("{}.presentation", state.provider_id), + format!("presentation: {}", state.presentation), + ), + text_element( + format!("{}.muninn", state.provider_id), + format!( + "muninn endpoint: {}", + state + .selected_muninn_endpoint + .as_deref() + .unwrap_or("discovering") + ), + ), + text_element( + format!("{}.filter", state.provider_id), + format!( + "device filter: {}", + state.selected_device_filter.as_deref().unwrap_or("any") + ), + ), + text_element( + format!("{}.updated", state.provider_id), + format!("updated: {}", state.updated_at), + ), + ]; + runtime_children.push(serde_json::json!({ + "id": format!("{}.devices-inline", state.provider_id), + "kind": "pane", + "props": { "title": "Available HID Devices", "density": "compact" }, + "children": if device_cards.is_empty() { + vec![text_element( + format!("{}.devices.empty", state.provider_id), + "no Muninn HID devices discovered".to_string(), + )] + } else { + device_cards + } + })); + serde_json::json!({ + "schema": "gamecult.eve.surface.v1", + "id": format!("{}.surface", state.provider_id), + "title": "Sleipnir Input Mirror", + "root": { + "id": format!("{}.root", state.provider_id), + "kind": "dashboard", + "props": { + "title": "Sleipnir Input Mirror", + "summary": format!("{} via {}", state.stream_state, state.virtual_backend) + }, + "children": [ + { + "id": format!("{}.runtime", state.provider_id), + "kind": "pane", + "props": { "title": "Runtime" }, + "children": runtime_children + }, + { + "id": format!("{}.input", state.provider_id), + "kind": "pane", + "props": { "title": "Input" }, + "children": [ + text_element(format!("{}.device", state.provider_id), format!("device: {}", state.last_device_id.as_deref().unwrap_or("none"))), + text_element(format!("{}.kind", state.provider_id), format!("kind: {}", state.last_device_kind.as_deref().unwrap_or("unknown"))), + text_element(format!("{}.sequence", state.provider_id), format!("sequence: {}", state.last_sequence.map(|value| value.to_string()).unwrap_or_else(|| "none".to_string()))), + text_element(format!("{}.age", state.provider_id), format!("last frame age ms: {}", state.last_frame_age_ms.map(|value| value.to_string()).unwrap_or_else(|| "none".to_string()))), + text_element(format!("{}.ignored", state.provider_id), format!("ignored stream frames: {}", state.ignored_stream_frames)) + ] + }, + { + "id": format!("{}.remap", state.provider_id), + "kind": "pane", + "props": { "title": "Remapping Presets" }, + "children": preset_cards + }, + { + "id": format!("{}.binding-map-pane", state.provider_id), + "kind": "pane", + "props": { "title": "Xbox Controller Mapping", "span": "wide" }, + "children": [binding_map] + } + ] + }, + "assets": [] + }) +} + +fn remap_preset_cards(state: &SleipnirRuntimeState) -> Vec { + vec![ + remap_preset_card( + state, + "nav-to-xbox", + "Nav to Xbox", + "xbox360", + serde_json::json!({ + "leftX": {"source": 0}, + "leftY": {"source": 1, "invert": true}, + "leftTrigger": {"source": 2}, + "rightTrigger": {"source": 5} + }), + serde_json::json!({ + "cross": "a", + "circle": "b", + "square": "x", + "triangle": "y", + "select": "back", + "ps": "guide" + }), + ), + remap_preset_card( + state, + "invert-y", + "Invert Y", + "xbox360", + serde_json::json!({ + "leftX": {"source": 0}, + "leftY": {"source": 1, "invert": true}, + "leftTrigger": {"source": 2}, + "rightTrigger": {"source": 5} + }), + serde_json::json!({}), + ), + ] +} + +fn remap_preset_card( + state: &SleipnirRuntimeState, + preset_id: &str, + title: &str, + presentation: &str, + axis_map: serde_json::Value, + button_map: serde_json::Value, +) -> serde_json::Value { + serde_json::json!({ + "id": format!("{}.remap.{}", state.provider_id, preset_id), + "kind": "card", + "props": { + "title": title, + "commandId": "sleipnir.apply-remap-preset", + "action": { + "type": "sleipnir.apply-remap-preset", + "providerId": state.provider_id, + "deviceFilter": state.selected_device_filter, + "presentation": presentation, + "axisMap": axis_map, + "buttonMap": button_map + } + }, + "children": [ + text_element(format!("{}.remap.{}.detail", state.provider_id, preset_id), format!("presentation: {presentation}")) + ] + }) +} + +fn xbox_binding_map(state: &SleipnirRuntimeState) -> serde_json::Value { + let targets = [ + ( + "leftX", "axis", "Left X", "axis 0", "16%", "34%", "265", "224", + ), + ( + "leftY", "axis", "Left Y", "axis 1", "16%", "49%", "265", "224", + ), + ( + "leftTrigger", + "axis", + "LT", + "axis 2", + "20%", + "12%", + "253", + "68", + ), + ( + "rightTrigger", + "axis", + "RT", + "axis 5", + "80%", + "12%", + "527", + "68", + ), + ("a", "button", "A", "unmapped", "88%", "72%", "568", "244"), + ("b", "button", "B", "unmapped", "92%", "58%", "608", "204"), + ("x", "button", "X", "unmapped", "80%", "58%", "528", "204"), + ("y", "button", "Y", "unmapped", "84%", "44%", "568", "164"), + ("lb", "button", "LB", "unmapped", "22%", "22%", "253", "108"), + ("rb", "button", "RB", "unmapped", "78%", "22%", "527", "108"), + ( + "back", "button", "Back", "unmapped", "40%", "43%", "363", "197", + ), + ( + "start", "button", "Start", "unmapped", "60%", "43%", "419", "197", + ), + ( + "guide", "button", "Guide", "unmapped", "50%", "36%", "391", "224", + ), + ("l3", "button", "L3", "unmapped", "30%", "76%", "265", "224"), + ("r3", "button", "R3", "unmapped", "70%", "76%", "474", "256"), + ( + "up", "button", "D-Up", "unmapped", "12%", "64%", "245", "224", + ), + ( + "down", "button", "D-Down", "unmapped", "12%", "78%", "245", "306", + ), + ( + "left", "button", "D-Left", "unmapped", "12%", "71%", "204", "267", + ), + ( + "right", "button", "D-Right", "unmapped", "26%", "71%", "286", "267", + ), + ]; + let children = targets + .into_iter() + .map( + |(target, kind, label, fallback, x, y, anchor_x, anchor_y)| { + binding_target( + state, + target, + kind, + label, + binding_summary(state, target, kind, fallback), + x, + y, + anchor_x, + anchor_y, + ) + }, + ) + .collect::>(); + serde_json::json!({ + "id": format!("{}.binding-map", state.provider_id), + "kind": "input.binding-map", + "props": { + "label": "Xbox controller remapping" + }, + "children": children + }) +} + +fn binding_target( + state: &SleipnirRuntimeState, + target: &str, + binding_kind: &str, + label: &str, + current: String, + x: &str, + y: &str, + anchor_x: &str, + anchor_y: &str, +) -> serde_json::Value { + let listening = state + .pending_learn + .as_ref() + .is_some_and(|learn| learn.target == target && learn.binding_kind == binding_kind); + serde_json::json!({ + "id": format!("{}.binding.{}", state.provider_id, stable_id(target)), + "kind": "binding.target", + "props": { + "target": target, + "bindingKind": binding_kind, + "label": label, + "current": if listening { "listening..." } else { current.as_str() }, + "x": x, + "y": y, + "anchorX": anchor_x, + "anchorY": anchor_y, + "documentId": format!("cultmesh://sleipnir/{}/binding/{target}", state.provider_id), + "slotId": format!("sleipnir.binding.{target}"), + "schemaId": "gamecult.eve.surface.v1", + "presentationKind": "modal.binding", + "deviceFilter": state.selected_device_filter, + "presentation": "xbox360" + }, + "embeddedDocuments": [{ + "slotId": format!("sleipnir.binding.{target}"), + "documentId": format!("cultmesh://sleipnir/{}/binding/{target}", state.provider_id), + "schemaId": "gamecult.eve.surface.v1", + "presentationKind": "modal.binding" + }] + }) +} + +fn binding_summary( + state: &SleipnirRuntimeState, + target: &str, + binding_kind: &str, + fallback: &str, +) -> String { + if binding_kind == "axis" { + return axis_binding_label(state.axis_map.get(target)); + } + let sources = state + .button_map + .iter() + .filter_map(|(source, mapped)| (mapped == target).then_some(source.as_str())) + .collect::>(); + if sources.is_empty() { + fallback.to_string() + } else { + sources.join(", ") + } +} + +fn axis_binding_label(binding: Option<&AxisBinding>) -> String { + match binding { + Some(binding) if binding.invert => format!("axis {} inverted", binding.source), + Some(binding) => format!("axis {}", binding.source), + None => "unmapped".to_string(), + } +} + +fn text_element(id: String, text: String) -> serde_json::Value { + serde_json::json!({ + "id": id, + "kind": "text", + "props": { "text": text }, + "children": [] + }) +} + +fn read_desired_mapping( + node: &mut cultmesh_rs::CultMeshNode, + options: &Options, +) -> SleipnirDesiredMapping { + read_desired_mapping_from_sources(node, None, options) +} + +fn read_desired_mapping_from_sources( + local_node: &mut cultmesh_rs::CultMeshNode, + discovery_node: Option<&mut cultmesh_rs::CultMeshNode>, + options: &Options, +) -> SleipnirDesiredMapping { + let local_record = read_desired_mapping_record(local_node, options); + let discovery_record = + discovery_node.and_then(|node| read_desired_mapping_record(node, options)); + if let Some(record) = newest_sleipnir_mapping_record(local_record, discovery_record) { + return desired_mapping_from_record(record); + } + options + .mapping_path + .as_ref() + .and_then(|path| read_legacy_mapping_file(path)) + .unwrap_or_else(default_desired_mapping) +} + +fn read_desired_mapping_record( + node: &mut cultmesh_rs::CultMeshNode, + options: &Options, +) -> Option { + let _ = node.pull_all_backing_stores(); + node.get::(&sleipnir_provider_id(options)) + .ok() + .flatten() +} + +fn newest_sleipnir_mapping_record( + local: Option, + discovery: Option, +) -> Option { + match (local, discovery) { + (Some(local), Some(discovery)) if discovery.updated_at > local.updated_at => { + Some(discovery) + } + (Some(local), Some(_)) => Some(local), + (Some(local), None) => Some(local), + (None, Some(discovery)) => Some(discovery), + (None, None) => None, + } +} + +fn default_desired_mapping() -> SleipnirDesiredMapping { + SleipnirDesiredMapping { + enabled: false, + device_filter: None, + stream_id: None, + presentation: default_presentation(), + axis_map: default_axis_map(), + button_map: default_button_map(), + pending_learn: None, + } +} + +fn desired_mapping_from_record(record: SleipnirInputMappingRecord) -> SleipnirDesiredMapping { + SleipnirDesiredMapping { + enabled: record.enabled, + device_filter: Some(record.device_filter) + .filter(|value| !value.trim().is_empty()) + .map(|value| value.to_string()), + stream_id: Some(record.stream_id) + .filter(|value| !value.trim().is_empty()) + .map(|value| value.to_string()), + presentation: normalize_presentation(&record.presentation), + axis_map: parse_axis_map(Some(&record.axis_map)), + button_map: parse_button_map(Some(&record.button_map)), + pending_learn: parse_learn_request(Some(&record.pending_learn)), + } +} + +fn read_legacy_mapping_file(path: &PathBuf) -> Option { + let text = fs::read_to_string(path).ok()?; + let value = + serde_json::from_str::(text.trim_start_matches('\u{feff}')).ok()?; + Some(SleipnirDesiredMapping { + enabled: false, + device_filter: value + .get("deviceFilter") + .or_else(|| value.get("device_filter")) + .and_then(|value| value.as_str()) + .filter(|value| !value.trim().is_empty()) + .map(ToString::to_string), + stream_id: value + .get("streamId") + .or_else(|| value.get("stream_id")) + .and_then(|value| value.as_str()) + .filter(|value| !value.trim().is_empty()) + .map(ToString::to_string), + presentation: normalize_presentation( + value + .get("presentation") + .or_else(|| value.get("presentationProfile")) + .or_else(|| value.get("presentation_profile")) + .and_then(|value| value.as_str()) + .filter(|value| !value.trim().is_empty()) + .unwrap_or("xbox360"), + ), + axis_map: parse_axis_map(value.get("axisMap").or_else(|| value.get("axis_map"))), + button_map: parse_button_map(value.get("buttonMap").or_else(|| value.get("button_map"))), + pending_learn: parse_learn_request( + value + .get("pendingLearn") + .or_else(|| value.get("pending_learn")) + .or_else(|| value.get("learn")), + ), + }) +} + +fn parse_learn_request(value: Option<&serde_json::Value>) -> Option { + let map = value?.as_object()?; + let target = map + .get("target") + .or_else(|| map.get("buttonTarget")) + .or_else(|| map.get("axisTarget")) + .and_then(|value| value.as_str()) + .filter(|value| !value.trim().is_empty())? + .to_string(); + let binding_kind = map + .get("bindingKind") + .or_else(|| map.get("kind")) + .and_then(|value| value.as_str()) + .filter(|value| !value.trim().is_empty()) + .unwrap_or("button") + .to_string(); + Some(LearnRequest { + target, + binding_kind, + requested_at: map + .get("requestedAt") + .or_else(|| map.get("requested_at")) + .and_then(|value| value.as_str()) + .map(ToString::to_string), + }) +} + +fn default_presentation() -> String { + "xbox360".to_string() +} + +fn normalize_presentation(_presentation: &str) -> String { + default_presentation() +} + +fn default_axis_map() -> HashMap { + HashMap::from([ + ("leftX".to_string(), AxisBinding::stick_source(0)), + ( + "leftY".to_string(), + AxisBinding { + source: 1, + invert: true, + scale: 1.0, + deadzone: DEFAULT_STICK_DEADZONE, + }, + ), + ("leftTrigger".to_string(), AxisBinding::source(2)), + ("rightTrigger".to_string(), AxisBinding::source(5)), + ]) +} + +fn default_button_map() -> HashMap { + HashMap::from([ + ("trigger".to_string(), "none".to_string()), + ("l2".to_string(), "none".to_string()), + ]) +} + +impl AxisBinding { + fn source(source: usize) -> Self { + Self { + source, + invert: false, + scale: 1.0, + deadzone: 0.0, + } + } + + fn stick_source(source: usize) -> Self { + Self { + source, + invert: false, + scale: 1.0, + deadzone: DEFAULT_STICK_DEADZONE, + } + } +} + +fn parse_axis_map(value: Option<&serde_json::Value>) -> HashMap { + let mut axis_map = default_axis_map(); + let Some(map) = value.and_then(|value| value.as_object()) else { + return axis_map; + }; + for (target, binding) in map { + if let Some(binding) = parse_axis_binding(binding) { + axis_map.insert(target.clone(), binding); + } + } + axis_map +} + +fn parse_axis_binding(value: &serde_json::Value) -> Option { + if let Some(source) = value.as_u64() { + return Some(AxisBinding::source(source as usize)); + } + let map = value.as_object()?; + let source = map + .get("source") + .or_else(|| map.get("axis")) + .and_then(|value| value.as_u64())? as usize; + Some(AxisBinding { + source, + invert: map + .get("invert") + .and_then(|value| value.as_bool()) + .unwrap_or(false), + scale: map + .get("scale") + .and_then(|value| value.as_f64()) + .unwrap_or(1.0) as f32, + deadzone: map + .get("deadzone") + .and_then(|value| value.as_f64()) + .unwrap_or(0.0) as f32, + }) +} + +fn parse_button_map(value: Option<&serde_json::Value>) -> HashMap { + value + .and_then(|value| value.as_object()) + .map(|map| { + map.iter() + .filter_map(|(source, target)| { + target + .as_str() + .filter(|target| !target.trim().is_empty()) + .map(|target| (source.clone(), target.to_string())) + }) + .collect() + }) + .unwrap_or_else(default_button_map) +} + +fn apply_pending_learn( + node: &mut cultmesh_rs::CultMeshNode, + options: &Options, + mapping: &SleipnirDesiredMapping, + record: &MuninnHidControllerStateRecord, +) -> Result> { + let Some(learn) = mapping.pending_learn.as_ref() else { + return Ok(None); + }; + let mut updated = mapping.clone(); + let learned = if learn.binding_kind == "axis" { + if let Some(source) = most_active_axis(&record.axes) { + updated.axis_map.insert( + learn.target.clone(), + AxisBinding { + source, + invert: learn.target == "leftY" || learn.target == "rightY", + scale: 1.0, + deadzone: 0.0, + }, + ); + true + } else { + false + } + } else if let Some(source) = record.buttons.first() { + updated + .button_map + .insert(source.clone(), learn.target.clone()); + true + } else { + false + }; + if !learned { + return Ok(None); + } + updated.pending_learn = None; + updated.enabled = true; + write_desired_mapping(node, options, &updated, "sleipnir.auto-bind")?; + Ok(Some(updated)) +} + +fn most_active_axis(axes: &[f32]) -> Option { + axes.iter() + .enumerate() + .filter(|(_, value)| value.abs() >= 0.45) + .max_by(|(_, left), (_, right)| { + left.abs() + .partial_cmp(&right.abs()) + .unwrap_or(std::cmp::Ordering::Equal) + }) + .map(|(index, _)| index) +} + +fn write_desired_mapping( + node: &mut cultmesh_rs::CultMeshNode, + options: &Options, + mapping: &SleipnirDesiredMapping, + source: &str, +) -> Result<()> { + let provider_id = sleipnir_provider_id(options); + let record = SleipnirInputMappingRecord { + provider_id: provider_id.clone(), + enabled: mapping.enabled, + device_filter: mapping.device_filter.clone().unwrap_or_default(), + stream_id: mapping.stream_id.clone().unwrap_or_default(), + presentation: mapping.presentation.clone(), + axis_map: axis_map_json(&mapping.axis_map), + button_map: serde_json::Value::Object( + mapping + .button_map + .iter() + .map(|(source, target)| (source.clone(), serde_json::Value::String(target.clone()))) + .collect(), + ), + pending_learn: mapping + .pending_learn + .as_ref() + .map(|learn| { + serde_json::json!({ + "target": learn.target, + "bindingKind": learn.binding_kind, + "requestedAt": learn.requested_at + }) + }) + .unwrap_or(serde_json::Value::Null), + updated_at: timestamp(), + source: source.to_string(), + }; + node.put(&provider_id, &record)?; + Ok(()) +} + +fn axis_map_json(axis_map: &HashMap) -> serde_json::Value { + serde_json::Value::Object( + axis_map + .iter() + .map(|(target, binding)| { + ( + target.clone(), + serde_json::json!({ + "source": binding.source, + "invert": binding.invert, + "scale": binding.scale, + "deadzone": binding.deadzone + }), + ) + }) + .collect(), + ) +} + +fn effective_muninn_hid_endpoint( + node: &cultmesh_rs::CultMeshNode, + device_filter: Option<&str>, + stream_id: Option<&str>, + trace: bool, +) -> Option { + discover_muninn_hid_endpoint(node, device_filter, stream_id, trace) +} + +fn effective_device_filter( + options: &Options, + desired_mapping: &SleipnirDesiredMapping, +) -> Option { + desired_mapping + .device_filter + .clone() + .or_else(|| options.device_filter.clone()) +} + +fn discover_available_hid_devices(node: &cultmesh_rs::CultMeshNode) -> Vec { + let mut devices = Vec::new(); + for record in node + .cache() + .get_all::() + .ok() + .into_iter() + .flatten() + { + upsert_available_hid_device( + &mut devices, + available_hid_device_from_record( + node, + &record, + discover_muninn_hid_endpoint( + node, + Some(record.device_id.as_str()), + Some(record.stream_id.as_str()), + false, + ), + ), + ); + } + for provider in node + .cache() + .get_all::() + .ok() + .into_iter() + .flatten() + { + for device in available_hid_devices_from_value(&provider.value) { + upsert_available_hid_device(&mut devices, device); + } + } + for envelope in node.cache().snapshot() { + if envelope.schema_id.as_deref() == Some(MUNINN_HID_CONTROLLER_STATE_SCHEMA) + || envelope.r#type == "muninn.hid_controller_state" + { + if let Ok(value) = rmp_serde::from_slice::(&envelope.payload) { + if let Some(device) = available_hid_device_from_hid_value(node, &value) { + upsert_available_hid_device(&mut devices, device); + } + } + continue; + } + if envelope.schema_id.as_deref() == Some(EVE_PROVIDER_ADVERTISEMENT_SCHEMA) + || envelope.r#type == "gamecult.eve.provider_advertisement" + { + if let Ok(value) = rmp_serde::from_slice::(&envelope.payload) { + for device in available_hid_devices_from_value(&value) { + upsert_available_hid_device(&mut devices, device); + } + } + continue; + } + } + devices.retain(|device| endpoint_looks_like_socket(&device.endpoint)); + devices.sort_by(|left, right| { + (&left.host_id, &left.device_id, &left.endpoint).cmp(&( + &right.host_id, + &right.device_id, + &right.endpoint, + )) + }); + devices + .dedup_by(|left, right| left.host_id == right.host_id && left.device_id == right.device_id); + devices +} + +fn available_hid_device_from_hid_value( + node: &cultmesh_rs::CultMeshNode, + value: &serde_json::Value, +) -> Option { + let payload = value + .as_array() + .and_then(|items| { + (items.len() == 1) + .then(|| items.first()) + .flatten() + .filter(|item| item.is_object() || item.is_array()) + }) + .unwrap_or(value); + let (stream_id, host_id, device_id, device_kind, source_path) = + if let Some(items) = payload.as_array() { + ( + items.first()?.as_str()?.to_string(), + items.get(1)?.as_str()?.to_string(), + items.get(2)?.as_str()?.to_string(), + items.get(3)?.as_str()?.to_string(), + items + .get(10) + .and_then(|item| item.as_str()) + .unwrap_or("unknown") + .to_string(), + ) + } else { + ( + string_field(payload, &["stream_id", "streamId"])?, + string_field(payload, &["host_id", "hostId"])?, + string_field(payload, &["device_id", "deviceId"])?, + string_field(payload, &["device_kind", "deviceKind"])?, + string_field(payload, &["source_path", "sourcePath"]) + .unwrap_or_else(|| "unknown".to_string()), + ) + }; + let endpoint = discover_muninn_hid_endpoint( + node, + Some(device_id.as_str()), + Some(stream_id.as_str()), + false, + ) + .unwrap_or_else(|| "discovering".to_string()); + Some(AvailableHidDevice { + device_id, + device_kind, + source_path, + stream_id, + host_id, + endpoint, + }) +} + +fn string_field(value: &serde_json::Value, names: &[&str]) -> Option { + names + .iter() + .find_map(|name| value.get(*name).and_then(|field| field.as_str())) + .map(ToString::to_string) +} + +fn available_hid_device_from_record( + node: &cultmesh_rs::CultMeshNode, + record: &MuninnHidControllerStateRecord, + endpoint: Option, +) -> AvailableHidDevice { + AvailableHidDevice { + device_id: record.device_id.clone(), + device_kind: record.device_kind.clone(), + source_path: record.source_path.clone(), + stream_id: record.stream_id.clone(), + host_id: record.host_id.clone(), + endpoint: endpoint.unwrap_or_else(|| { + discover_muninn_hid_endpoint( + node, + Some(record.device_id.as_str()), + Some(record.stream_id.as_str()), + false, + ) + .unwrap_or_else(|| "discovering".to_string()) + }), + } +} + +fn upsert_available_hid_device(devices: &mut Vec, device: AvailableHidDevice) { + if let Some(existing) = devices.iter_mut().find(|existing| { + existing.host_id == device.host_id && existing.device_id == device.device_id + }) { + if should_replace_available_hid_device(existing, &device) { + *existing = device; + } + } else { + devices.push(device); + } + devices.sort_by(|left, right| { + (&left.host_id, &left.device_id, &left.endpoint).cmp(&( + &right.host_id, + &right.device_id, + &right.endpoint, + )) + }); +} + +fn should_replace_available_hid_device( + existing: &AvailableHidDevice, + candidate: &AvailableHidDevice, +) -> bool { + let existing_score = available_hid_device_discovery_score(existing); + let candidate_score = available_hid_device_discovery_score(candidate); + candidate_score >= existing_score +} + +fn available_hid_device_discovery_score(device: &AvailableHidDevice) -> u8 { + let mut score = 0; + if device.endpoint != "discovering" { + score += 4; + } + if device.stream_id.contains(&device.device_id) { + score += 2; + } + if !device.source_path.trim().is_empty() && device.source_path != "unknown" { + score += 1; + } + score +} + +fn available_hid_devices_from_value(value: &serde_json::Value) -> Vec { + let mut devices = Vec::new(); + let Some(streams) = value + .get("inputStreams") + .or_else(|| value.get("input_streams")) + .and_then(|streams| streams.as_array()) + else { + return devices; + }; + for stream in streams { + let endpoint = stream + .get("address") + .and_then(|value| value.as_str()) + .unwrap_or_default() + .to_string(); + let stream_id = stream + .get("streamId") + .or_else(|| stream.get("stream_id")) + .and_then(|value| value.as_str()) + .unwrap_or("muninn:hid") + .to_string(); + if !is_muninn_fast_hid_stream(stream, &stream_id, &endpoint) { + continue; + } + let host_id = value + .get("verseId") + .or_else(|| value.get("verse_id")) + .and_then(|value| value.as_str()) + .unwrap_or("") + .trim_end_matches(".local") + .to_string(); + if let Some(stream_devices) = stream.get("devices").and_then(|value| value.as_array()) { + for device in stream_devices { + let device_id = device + .get("deviceId") + .or_else(|| device.get("device_id")) + .and_then(|value| value.as_str()) + .unwrap_or_default() + .to_string(); + if device_id.is_empty() { + continue; + } + devices.push(AvailableHidDevice { + device_id, + device_kind: device + .get("deviceKind") + .or_else(|| device.get("device_kind")) + .and_then(|value| value.as_str()) + .unwrap_or("hid") + .to_string(), + source_path: device + .get("sourcePath") + .or_else(|| device.get("source_path")) + .and_then(|value| value.as_str()) + .unwrap_or("") + .to_string(), + stream_id: stream_id.clone(), + host_id: host_id.clone(), + endpoint: endpoint.clone(), + }); + } + } + } + devices +} + +fn is_muninn_fast_hid_stream(stream: &serde_json::Value, stream_id: &str, endpoint: &str) -> bool { + if stream.get("schema").and_then(|value| value.as_str()) + != Some("muninn.hid_controller_state.v1") + { + return false; + } + if !stream_id.contains(":hid-controller-state") || stream_id.contains("move-evidence") { + return false; + } + if !endpoint_looks_like_socket(endpoint) { + return false; + } + stream + .get("transport") + .and_then(|value| value.as_str()) + .is_some_and(|transport| transport.contains("rudp")) +} + +fn endpoint_looks_like_socket(endpoint: &str) -> bool { + let Some((host, port)) = endpoint.rsplit_once(':') else { + return false; + }; + !host.trim().is_empty() + && port + .parse::() + .is_ok_and(|parsed_port| parsed_port != 0) +} + +fn stable_id(value: &str) -> String { + let normalized = value + .chars() + .map(|ch| if ch.is_ascii_alphanumeric() { ch } else { '-' }) + .collect::() + .trim_matches('-') + .to_ascii_lowercase(); + if normalized.is_empty() { + "device".to_string() + } else { + normalized + } +} + +fn sleipnir_provider_id(options: &Options) -> String { + format!("sleipnir.input-mirror.{}", options.host_id) +} + +fn sleipnir_daemon_id(options: &Options) -> String { + format!("{}-sleipnir", options.host_id) +} + +fn sleipnir_provider_title(options: &Options) -> String { + format!("Sleipnir {} Input Mirror", title_case(&options.host_id)) +} + +fn timestamp() -> String { + use std::time::{SystemTime, UNIX_EPOCH}; + match SystemTime::now().duration_since(UNIX_EPOCH) { + Ok(duration) => format!("unix-{}", duration.as_secs()), + Err(_) => "unix-0".to_string(), + } +} + +fn unix_millis_i64() -> i64 { + use std::time::{SystemTime, UNIX_EPOCH}; + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|duration| i64::try_from(duration.as_millis()).unwrap_or(i64::MAX)) + .unwrap_or_default() +} + +fn unix_nanos_i64() -> i64 { + use std::time::{SystemTime, UNIX_EPOCH}; + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|duration| i64::try_from(duration.as_nanos()).unwrap_or(i64::MAX)) + .unwrap_or_default() +} + +fn title_case(value: &str) -> String { + let mut chars = value.chars(); + match chars.next() { + Some(first) => first.to_uppercase().collect::() + chars.as_str(), + None => String::new(), + } +} + +fn create_rudp_stream( + bind: Option, + connect_endpoint: Option, + trace: bool, +) -> Result> { + if let Some(endpoint) = connect_endpoint { + let target = resolve_socket_addr(&endpoint) + .with_context(|| format!("resolving Muninn HID RUDP endpoint {endpoint}"))?; + let bind_address = bind.unwrap_or_else(|| { + if target.is_ipv4() { + SocketAddr::from(([0, 0, 0, 0], 0)) + } else { + SocketAddr::from(([0, 0, 0, 0, 0, 0, 0, 0], 0)) + } + }); + let socket = UdpSocket::bind(bind_address) + .with_context(|| format!("binding Sleipnir RUDP HID client at {bind_address}"))?; + socket + .set_read_timeout(Some(Duration::from_millis(1))) + .context("setting Sleipnir RUDP HID client timeout")?; + if trace { + eprintln!( + "Sleipnir connecting to Muninn HID RUDP at {target} connection_id={SLEIPNIR_HID_RUDP_CONNECTION_ID:08x}" + ); + } + let mut transport = + CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { + runtime_id: "sleipnir-hid-rudp".to_string(), + socket, + mode: CultNetRudpSocketMode::Client, + remote_addr: Some(target), + connection_id: SLEIPNIR_HID_RUDP_CONNECTION_ID, + initial_sequence: 1, + resend_delay_ms: 5, + transport_id: Some("sleipnir-hid-rudp".to_string()), + max_payload_bytes: None, + max_fragment_bytes: Some(HID_RUDP_MAX_FRAGMENT_BYTES), + max_pending_reliable_packets: Some(256), + media_reliable_expire_after_ms: Some(25), + })?; + transport.connect(Vec::new())?; + return Ok(Some(ActiveRudpStream { + transport, + target: Some(target), + last_connect_attempt_at: Some(Instant::now()), + connected_logged: false, + last_frame_at: Some(Instant::now()), + last_stale_log_at: None, + last_subscription: None, + last_subscription_at: None, + })); + } + let Some(bind) = bind else { + return Ok(None); + }; + let socket = UdpSocket::bind(bind) + .with_context(|| format!("binding Sleipnir RUDP HID stream at {bind}"))?; + socket + .set_read_timeout(Some(Duration::from_millis(1))) + .with_context(|| format!("setting Sleipnir RUDP HID stream {bind} timeout"))?; + if trace { + eprintln!( + "Sleipnir listening for fast HID RUDP on {bind} connection_id={SLEIPNIR_HID_RUDP_CONNECTION_ID:08x}" + ); + } + Ok(Some(ActiveRudpStream { + transport: CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { + runtime_id: "sleipnir-hid-rudp".to_string(), + socket, + mode: CultNetRudpSocketMode::Server, + remote_addr: None, + connection_id: SLEIPNIR_HID_RUDP_CONNECTION_ID, + initial_sequence: 1, + resend_delay_ms: 5, + transport_id: Some("sleipnir-hid-rudp".to_string()), + max_payload_bytes: None, + max_fragment_bytes: Some(HID_RUDP_MAX_FRAGMENT_BYTES), + max_pending_reliable_packets: Some(256), + media_reliable_expire_after_ms: Some(25), + })?, + target: None, + last_connect_attempt_at: None, + connected_logged: false, + last_frame_at: None, + last_stale_log_at: None, + last_subscription: None, + last_subscription_at: None, + })) +} + +fn send_hid_subscription_if_due( + stream: &mut ActiveRudpStream, + device_filter: Option, + stream_id: Option, + trace: bool, +) -> Result<()> { + if !stream.transport.connected() { + return Ok(()); + } + let subscription = HidControllerRudpSubscription { + device_filter: device_filter.filter(|filter| !filter.trim().is_empty()), + stream_id: stream_id.filter(|stream_id| !stream_id.trim().is_empty()), + }; + let changed = stream.last_subscription.as_ref() != Some(&subscription); + let due = stream + .last_subscription_at + .is_none_or(|sent_at| sent_at.elapsed() >= Duration::from_secs(1)); + if !changed && !due { + return Ok(()); + } + let payload = serde_json::to_vec(&serde_json::json!({ + "deviceFilter": subscription.device_filter, + "streamId": subscription.stream_id, + })) + .context("encoding Sleipnir HID RUDP subscription")?; + stream + .transport + .send("hid.subscribe", payload) + .context("sending Sleipnir HID RUDP subscription")?; + if trace || changed { + eprintln!( + "Sleipnir subscribed to Muninn HID device_filter={:?} stream_id={:?}", + subscription.device_filter, subscription.stream_id + ); + } + stream.last_subscription = Some(subscription); + stream.last_subscription_at = Some(Instant::now()); + Ok(()) +} + +fn resolve_socket_addr(endpoint: &str) -> Result { + endpoint + .to_socket_addrs() + .with_context(|| format!("resolving {endpoint}"))? + .next() + .ok_or_else(|| anyhow!("no socket addresses resolved for {endpoint}")) +} + +fn ensure_rudp_connected(stream: &mut ActiveRudpStream, trace: bool) -> Result { + let Some(target) = stream.target else { + return Ok(false); + }; + if stream.transport.connected() { + if !stream.connected_logged && trace { + eprintln!("Sleipnir connected to Muninn HID RUDP at {target}"); + } + stream.connected_logged = true; + if stream + .last_frame_at + .is_some_and(|last_frame| last_frame.elapsed() >= INPUT_STREAM_RECONNECT_AFTER) + { + let should_log = stream + .last_stale_log_at + .is_none_or(|logged| logged.elapsed() >= INPUT_STREAM_RECONNECT_AFTER); + if should_log && trace { + eprintln!( + "Sleipnir Muninn HID RUDP is connected to {target} but has received no frames for {:?}; recreating connection", + stream.last_frame_at.map(|last_frame| last_frame.elapsed()) + ); + } + stream.last_stale_log_at = Some(Instant::now()); + stream.connected_logged = false; + return Ok(true); + } else { + return Ok(false); + } + } + let should_attempt = stream + .last_connect_attempt_at + .is_none_or(|attempt| attempt.elapsed() >= Duration::from_millis(250)); + if should_attempt { + stream.last_connect_attempt_at = Some(Instant::now()); + stream.transport.connect(Vec::new())?; + } + Ok(false) +} + +fn discover_muninn_hid_endpoint( + node: &cultmesh_rs::CultMeshNode, + device_filter: Option<&str>, + stream_id: Option<&str>, + trace: bool, +) -> Option { + if let Some(endpoint) = discover_available_hid_endpoint(node, device_filter, stream_id) { + return Some(endpoint); + } + let host_hint = stream_host_hint(stream_id); + let endpoints = discover_provider_endpoints( + node, + OdinEndpointQuery { + schema: Some(MUNINN_HID_CONTROLLER_STATE_SCHEMA), + transport_contains: Some("rudp"), + host_hint: host_hint.as_deref(), + device_filter, + }, + ); + if trace && endpoints.is_empty() { + eprintln!( + "Sleipnir found no Muninn HID endpoints for host_hint={:?} device_filter={:?}", + host_hint, device_filter + ); + } + endpoints + .into_iter() + .next() + .map(|endpoint| endpoint.address) +} + +fn discover_available_hid_endpoint( + node: &cultmesh_rs::CultMeshNode, + device_filter: Option<&str>, + stream_id: Option<&str>, +) -> Option { + for provider in node + .cache() + .get_all::() + .ok() + .into_iter() + .flatten() + { + if let Some(endpoint) = + matching_provider_advertised_hid_endpoint(&provider.value, device_filter, stream_id) + { + return Some(endpoint); + } + } + for envelope in node.cache().snapshot() { + if envelope.schema_id.as_deref() != Some(EVE_PROVIDER_ADVERTISEMENT_SCHEMA) + && envelope.r#type != "gamecult.eve.provider_advertisement" + { + continue; + } + let Ok(value) = rmp_serde::from_slice::(&envelope.payload) else { + continue; + }; + if let Some(endpoint) = + matching_provider_advertised_hid_endpoint(&value, device_filter, stream_id) + { + return Some(endpoint); + } + } + None +} + +fn matching_provider_advertised_hid_endpoint( + value: &serde_json::Value, + device_filter: Option<&str>, + stream_id: Option<&str>, +) -> Option { + let host_hint = stream_host_hint(stream_id); + let filter = device_filter + .map(str::trim) + .filter(|value| !value.is_empty()); + available_hid_devices_from_value(value) + .into_iter() + .filter(|device| { + host_hint + .as_deref() + .is_none_or(|host| device.host_id.eq_ignore_ascii_case(host)) + }) + .find(|device| { + stream_id.is_none_or(|stream_id| device.stream_id == stream_id) + || filter.is_some_and(|filter| { + device.device_id == filter + || device.device_kind == filter + || device.stream_id == filter + || device.source_path.contains(filter) + }) + }) + .map(|device| device.endpoint) +} + +fn stream_host_hint(stream_id: Option<&str>) -> Option { + let stream_id = stream_id?; + let parts = stream_id + .split(':') + .filter(|part| !part.trim().is_empty()) + .collect::>(); + let host = match parts.as_slice() { + ["muninn", host, ..] => *host, + [host, ..] => *host, + _ => return None, + }; + let normalized = host.trim().trim_end_matches(".local").to_ascii_lowercase(); + (!normalized.is_empty()).then_some(normalized) +} + +fn receive_rudp_records( + stream: &mut ActiveRudpStream, + trace: bool, +) -> Result> { + let mut records = Vec::new(); + let mut empty_polls = 0usize; + for _ in 0..64 { + match stream.transport.receive_once() { + Ok(Some(frame)) if frame.channel_id == "latest" || frame.channel_id == "hid" => { + empty_polls = 0; + if trace { + eprintln!( + "Sleipnir received fast HID frame channel={} bytes={}", + frame.channel_id, + frame.payload.len() + ); + } + records.push( + serde_json::from_slice(&frame.payload) + .context("decoding Sleipnir RUDP HID frame")?, + ); + } + Ok(Some(frame)) => { + empty_polls = 0; + if trace { + eprintln!( + "Sleipnir ignored RUDP channel={} bytes={}", + frame.channel_id, + frame.payload.len() + ); + } + } + Ok(None) => { + empty_polls += 1; + if empty_polls >= 4 { + break; + } + } + Err(error) => { + if trace { + eprintln!("Sleipnir RUDP receive/control warning: {error:#}"); + } + break; + } + } + } + if let Err(error) = stream.transport.poll_resends() { + if trace { + eprintln!("Sleipnir RUDP resend warning: {error:#}"); + } + } + Ok(coalesce_latest_hid_records_by_device(records)) +} + +fn coalesce_latest_hid_records_by_device( + records: Vec, +) -> Vec { + let mut latest_by_device = HashMap::::new(); + for (index, record) in records.into_iter().enumerate() { + latest_by_device + .entry(record.device_id.clone()) + .and_modify(|(latest_index, latest_record)| { + if record.source_timestamp_ns > latest_record.source_timestamp_ns + || (record.source_timestamp_ns == latest_record.source_timestamp_ns + && record.sequence > latest_record.sequence) + { + *latest_index = index; + *latest_record = record.clone(); + } + }) + .or_insert((index, record)); + } + let mut latest = latest_by_device.into_values().collect::>(); + latest.sort_by_key(|(index, _)| *index); + latest.into_iter().map(|(_, record)| record).collect() +} + +#[cfg(windows)] +fn create_backend() -> Result> { + Ok(Box::new(VigemXboxBackend::connect()?)) +} + +#[cfg(not(windows))] +fn create_backend() -> Result> { + Err(anyhow!( + "Sleipnir's ViGEm Xbox virtual controller backend is currently implemented on Windows; use --dry-run on this platform" + )) +} + +fn record_matches_filter( + record: &MuninnHidControllerStateRecord, + device_filter: Option<&str>, +) -> bool { + device_filter.is_none_or(|filter| { + record.device_id == filter + || record.stream_id == filter + || record.source_path.contains(filter) + || record.device_kind == filter + }) +} + +fn map_record_to_virtual_pad( + record: &MuninnHidControllerStateRecord, + mapping: &SleipnirDesiredMapping, +) -> VirtualPadState { + let left_x = signed_axis_to_i16(mapped_axis(record, mapping, "leftX", 0.0)); + let left_y = signed_axis_to_i16(mapped_axis(record, mapping, "leftY", 0.0)); + let mut buttons = mapped_buttons(record, mapping); + let left_trigger = mapped_trigger(record, mapping, "leftTrigger", 2); + let right_trigger = mapped_trigger(record, mapping, "rightTrigger", 5); + if buttons.iter().any(|button| button == "l2") && left_trigger == 0 { + buttons.push("left-trigger-button".to_string()); + } + VirtualPadState { + buttons, + left_x, + left_y, + left_trigger, + right_trigger, + } +} + +fn mapped_axis( + record: &MuninnHidControllerStateRecord, + mapping: &SleipnirDesiredMapping, + target: &str, + default: f32, +) -> f32 { + let Some(binding) = mapping.axis_map.get(target) else { + return default; + }; + let mut value = record.axes.get(binding.source).copied().unwrap_or(default); + if value.abs() < binding.deadzone { + value = 0.0; + } + if binding.invert { + value = -value; + } + (value * binding.scale).clamp(-1.0, 1.0) +} + +fn mapped_trigger( + record: &MuninnHidControllerStateRecord, + mapping: &SleipnirDesiredMapping, + target: &str, + fallback_source: usize, +) -> u8 { + if mapping.axis_map.contains_key(target) { + if mapping + .axis_map + .get(target) + .is_some_and(|binding| record.axes.get(binding.source).is_none()) + { + return 0; + } + trigger_from_axis( + Some(mapped_axis(record, mapping, target, 0.0)), + record.device_kind.as_str(), + ) + } else { + trigger_from_axis( + record.axes.get(fallback_source).copied(), + record.device_kind.as_str(), + ) + } +} + +fn mapped_buttons( + record: &MuninnHidControllerStateRecord, + mapping: &SleipnirDesiredMapping, +) -> Vec { + let mut buttons = Vec::new(); + for button in &record.buttons { + let mapped = mapping + .button_map + .get(button) + .map(String::as_str) + .unwrap_or(button.as_str()); + if mapped.eq_ignore_ascii_case("none") || mapped.trim().is_empty() { + continue; + } + if !buttons.iter().any(|existing| existing == mapped) { + buttons.push(mapped.to_string()); + } + } + buttons +} + +fn signed_axis_to_i16(value: f32) -> i16 { + let clamped = value.clamp(-1.0, 1.0); + if clamped < 0.0 { + (clamped * 32768.0).round() as i16 + } else { + (clamped * 32767.0).round() as i16 + } +} + +fn trigger_from_axis(value: Option, device_kind: &str) -> u8 { + let Some(value) = value else { + return 0; + }; + if device_kind == "xinput" || device_kind == "xinput-controller" { + return (value.clamp(0.0, 1.0) * 255.0).round() as u8; + } + (((value.clamp(-1.0, 1.0) + 1.0) * 0.5) * 255.0).round() as u8 +} + +impl Options { + fn parse(args: impl Iterator) -> Result { + let mut options = Options { + store_path: PathBuf::from("C:/Meta/Odin/state/starfire.muninn.telemetry.cc"), + discovery_store_path: None, + mapping_path: None, + device_filter: None, + host_id: "starfire".to_string(), + interval_ms: 8, + odin_cultmesh_uri: Some("cultmesh://odin/rendezvous/provider-catalog".to_string()), + rudp_bind: None, + command_route: SLEIPNIR_COMMAND_ROUTE.to_string(), + idunn_rudp_health: None, + once: false, + dry_run: false, + trace: env::var("SLEIPNIR_TRACE") + .ok() + .is_some_and(|value| value != "0" && !value.eq_ignore_ascii_case("false")), + }; + let mut idunn_rudp_health_endpoint = None; + let mut idunn_daemon_id = None; + let mut idunn_health_contract = None; + let mut args = args.peekable(); + while let Some(arg) = args.next() { + match arg.as_str() { + "--store" => options.store_path = PathBuf::from(next_value(&mut args, "--store")?), + "--discovery-store" => { + options.discovery_store_path = + Some(PathBuf::from(next_value(&mut args, "--discovery-store")?)) + } + "--mapping" | "--mapping-path" => { + options.mapping_path = Some(PathBuf::from(next_value(&mut args, &arg)?)); + } + "--device" => options.device_filter = Some(next_value(&mut args, "--device")?), + "--host" => options.host_id = next_value(&mut args, "--host")?, + "--interval-ms" => { + options.interval_ms = next_value(&mut args, "--interval-ms")? + .parse() + .context("--interval-ms must be an integer")? + } + "--rudp-bind" | "--udp-bind" => { + options.rudp_bind = Some( + next_value(&mut args, &arg)? + .parse() + .context("--rudp-bind must be a socket address")?, + ) + } + "--command-rudp-bind" => { + let _ = next_value(&mut args, "--command-rudp-bind")?; + return Err(anyhow!( + "--command-rudp-bind has been removed; Sleipnir reads input mapping commands from Odin/CultMesh discovery" + )); + } + "--command-route" => options.command_route = next_value(&mut args, "--command-route")?, + "--command-rudp-advertise" => { + return Err(anyhow!( + "--command-rudp-advertise has been removed; use --command-route with a cultmesh:// Odin command route" + )) + } + "--odin-cultmesh-rudp" => { + let _ = next_value(&mut args, "--odin-cultmesh-rudp")?; + return Err(anyhow!( + "--odin-cultmesh-rudp has been removed; use --odin-cultmesh-uri cultmesh://odin/rendezvous/provider-catalog and let CultMesh resolve Odin's transport" + )); + } + "--odin-cultmesh-uri" => { + options.odin_cultmesh_uri = Some(next_value(&mut args, "--odin-cultmesh-uri")?) + } + "--idunn-rudp-health" => { + idunn_rudp_health_endpoint = Some( + next_value(&mut args, "--idunn-rudp-health")? + .parse() + .context("--idunn-rudp-health must be a socket address")?, + ) + } + "--idunn-daemon" => { + idunn_daemon_id = Some(next_value(&mut args, "--idunn-daemon")?) + } + "--idunn-health-contract" => { + idunn_health_contract = Some(next_value(&mut args, "--idunn-health-contract")?) + } + "--once" => options.once = true, + "--dry-run" => options.dry_run = true, + "--trace" => options.trace = true, + "--help" | "-h" => { + println!("{}", usage()); + std::process::exit(0); + } + other => return Err(anyhow!("unrecognized argument {other}\n{}", usage())), + } + } + options.idunn_rudp_health = match ( + idunn_rudp_health_endpoint, + idunn_daemon_id, + idunn_health_contract, + ) { + (None, None, None) => None, + (Some(endpoint), Some(daemon_id), Some(health_contract)) => { + Some(IdunnRudpHealthOptions { + endpoint, + daemon_id, + health_contract, + }) + } + _ => { + return Err(anyhow!( + "--idunn-rudp-health, --idunn-daemon, and --idunn-health-contract must be provided together" + )); + } + }; + Ok(options) + } +} + +fn next_value(args: &mut impl Iterator, flag: &str) -> Result { + args.next() + .filter(|value| !value.trim().is_empty()) + .ok_or_else(|| anyhow!("{flag} requires a value")) +} + +fn usage() -> &'static str { + "usage: sleipnir [--store PATH] [--discovery-store PATH] [--mapping-path LEGACY_PATH] [--host HOST] [--device DEVICE_OR_KIND] [--odin-cultmesh-uri cultmesh://...] [--rudp-bind ADDR] [--command-route cultmesh://...] [--idunn-rudp-health ADDR --idunn-daemon ID --idunn-health-contract CONTRACT] [--interval-ms N] [--trace] [--dry-run] [--once]" +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + use std::fs; + + fn record(axes: Vec, buttons: Vec<&str>, sequence: u64) -> MuninnHidControllerStateRecord { + MuninnHidControllerStateRecord { + stream_id: "nightwing:nav:hid-controller-state".to_string(), + host_id: "nightwing".to_string(), + device_id: "nav".to_string(), + device_kind: "ps3-navigation".to_string(), + sequence, + source_timestamp_ns: 0, + axes, + buttons: buttons.into_iter().map(String::from).collect(), + battery01: f32::NAN, + observed_at: "unix:0".to_string(), + source_path: "/dev/input/js0".to_string(), + } + } + + fn default_mapping() -> SleipnirDesiredMapping { + SleipnirDesiredMapping { + enabled: false, + device_filter: None, + stream_id: None, + presentation: default_presentation(), + axis_map: default_axis_map(), + button_map: default_button_map(), + pending_learn: None, + } + } + + fn test_node(name: &str) -> (cultmesh_rs::CultMeshNode, PathBuf) { + let store_path = + std::env::temp_dir().join(format!("sleipnir-{name}-{}.cc", unix_millis_i64())); + let node = CultMesh::create_node( + &store_path, + OdinDocuments, + CultMeshNodeOptions { + runtime_id: format!("sleipnir-test-{name}"), + pull_on_start: true, + }, + ) + .unwrap(); + (node, store_path) + } + + #[test] + fn coalesces_latest_hid_records_per_device() { + let mut old_nav = record(vec![1.0, 0.0, -1.0], Vec::new(), 1); + old_nav.device_id = "nav".to_string(); + old_nav.source_timestamp_ns = 1_000; + let mut xbox = record(vec![0.25, 0.0, -1.0], Vec::new(), 7); + xbox.device_id = "xbox".to_string(); + xbox.source_timestamp_ns = 1_500; + let mut latest_nav = record(vec![0.0, 0.0, -1.0], Vec::new(), 2); + latest_nav.device_id = "nav".to_string(); + latest_nav.source_timestamp_ns = 2_000; + + let records = coalesce_latest_hid_records_by_device(vec![old_nav, xbox, latest_nav]); + + assert_eq!(records.len(), 2); + assert_eq!(records[0].device_id, "xbox"); + assert_eq!(records[0].sequence, 7); + assert_eq!(records[1].device_id, "nav"); + assert_eq!(records[1].sequence, 2); + assert_eq!(records[1].axes[0], 0.0); + } + + #[test] + fn coalesces_by_source_timestamp_not_arrival_order() { + let mut newer_nav = record(vec![0.0, 1.0, -1.0], Vec::new(), 10); + newer_nav.device_id = "nav".to_string(); + newer_nav.source_timestamp_ns = 2_000; + let mut older_nav = record(vec![-1.0, 0.0, -1.0], Vec::new(), 9); + older_nav.device_id = "nav".to_string(); + older_nav.source_timestamp_ns = 1_000; + + let records = coalesce_latest_hid_records_by_device(vec![newer_nav, older_nav]); + + assert_eq!(records.len(), 1); + assert_eq!(records[0].sequence, 10); + assert_eq!(records[0].axes[1], 1.0); + } + + #[test] + fn maps_nav_stick_and_buttons_to_xinput_shape() { + let state = map_record_to_virtual_pad( + &record( + vec![1.0, -1.0, -1.0], + vec!["cross", "circle", "l1", "l3", "up"], + 7, + ), + &default_mapping(), + ); + + assert_eq!(state.left_x, 32767); + assert_eq!(state.left_y, 32767); + assert_eq!(state.left_trigger, 0); + assert_eq!(state.right_trigger, 0); + assert!(state.buttons.contains(&"cross".to_string())); + assert!(state.buttons.contains(&"circle".to_string())); + assert!(state.buttons.contains(&"l1".to_string())); + assert!(state.buttons.contains(&"l3".to_string())); + assert!(state.buttons.contains(&"up".to_string())); + } + + #[test] + fn remaps_buttons_and_axes_from_mapping() { + let mut mapping = default_mapping(); + mapping + .button_map + .insert("cross".to_string(), "b".to_string()); + mapping.axis_map.insert( + "leftX".to_string(), + AxisBinding { + source: 1, + invert: false, + scale: 0.5, + deadzone: 0.0, + }, + ); + + let state = + map_record_to_virtual_pad(&record(vec![1.0, 1.0, -1.0], vec!["cross"], 7), &mapping); + + assert_eq!(state.left_x, 16384); + assert!(state.buttons.contains(&"b".to_string())); + assert!(!state.buttons.contains(&"cross".to_string())); + } + + #[test] + fn default_mapping_deadzones_small_stick_noise() { + let state = map_record_to_virtual_pad( + &record(vec![0.05, -0.04, -1.0], Vec::new(), 7), + &default_mapping(), + ); + + assert_eq!(state.left_x, 0); + assert_eq!(state.left_y, 0); + assert_eq!(state.left_trigger, 0); + assert_eq!(state.right_trigger, 0); + assert!(state.buttons.is_empty()); + } + + #[test] + fn pending_learn_maps_next_active_input() { + let mut mapping = default_mapping(); + mapping.pending_learn = Some(LearnRequest { + target: "a".to_string(), + binding_kind: "button".to_string(), + requested_at: None, + }); + let (mut node, store_path) = test_node("learn"); + let options = Options::parse( + ["--store", store_path.to_str().unwrap(), "--dry-run"] + .into_iter() + .map(String::from), + ) + .unwrap(); + let updated = apply_pending_learn( + &mut node, + &options, + &mapping, + &record(vec![0.0, 0.0], vec!["cross"], 2), + ) + .unwrap() + .unwrap(); + assert_eq!( + updated.button_map.get("cross").map(String::as_str), + Some("a") + ); + assert!(updated.pending_learn.is_none()); + let persisted = read_desired_mapping(&mut node, &options); + assert_eq!( + persisted.button_map.get("cross").map(String::as_str), + Some("a") + ); + let _ = fs::remove_file(store_path); + } + + #[test] + fn runtime_state_prefers_recent_frames_over_handshake_churn() { + let (node, store_path) = test_node("runtime-fresh-frame"); + let options = Options::parse( + ["--store", store_path.to_str().unwrap(), "--dry-run"] + .into_iter() + .map(String::from), + ) + .unwrap(); + let mut mapping = default_mapping(); + mapping.enabled = true; + let stream = create_rudp_stream(None, Some("127.0.0.1:9".to_string()), false).unwrap(); + + let state = SleipnirRuntimeState::from_runtime( + &options, + Some("nav"), + &node, + stream.as_ref(), + None, + 0, + &mapping, + ); + + assert_eq!(state.stream_state, "connected"); + let _ = fs::remove_file(store_path); + } + + #[test] + fn available_hid_devices_ignore_move_evidence_streams() { + let provider = json!({ + "verseId": "starfire.local", + "inputStreams": [ + { + "streamId": "muninn:nightwing:move-evidence", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0", + "address": "198.51.100.75:17888", + "devices": [ + { + "deviceId": "nav-ghost", + "deviceKind": "ps3-navigation", + "sourcePath": "/dev/input/js0" + } + ] + }, + { + "streamId": "muninn:starfire:hid-controller-state", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0", + "address": "198.51.100.66:17888", + "devices": [ + { + "deviceId": "nav-windows-psnav-0", + "deviceKind": "ps3-navigation", + "sourcePath": "windows-psmove://nav" + } + ] + } + ] + }); + + let devices = available_hid_devices_from_value(&provider); + + assert_eq!(devices.len(), 1); + assert_eq!(devices[0].device_id, "nav-windows-psnav-0"); + assert_eq!(devices[0].host_id, "starfire"); + assert_eq!(devices[0].endpoint, "198.51.100.66:17888"); + } + + #[test] + fn discovers_hid_endpoint_from_odin_provider_routes() { + let (mut node, store_path) = test_node("hid-endpoint-routes"); + node.put( + "muninn.telemetry.starfire", + &EveProviderAdvertisementRecord { + value: json!({ + "providerId": "muninn.telemetry.starfire", + "endpoints": [ + { + "address": "C:\\Meta\\Odin\\state\\starfire.muninn.telemetry.cc", + "transport": "cultcache-store" + }, + { + "address": "198.51.100.66:17888", + "channel": "latest", + "connectionId": 1836384261, + "role": "muninn.hid_controller_state", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0" + } + ], + "routes": [ + { + "address": "C:\\Meta\\Odin\\state\\starfire.muninn.telemetry.cc", + "transport": "cultcache-store" + } + ] + }), + }, + ) + .unwrap(); + + assert_eq!( + discover_muninn_hid_endpoint( + &node, + Some("nav-windows-psnav-0"), + Some("starfire:nav-windows-psnav-0:hid-controller-state"), + false, + ) + .as_deref(), + Some("198.51.100.66:17888") + ); + let _ = fs::remove_file(store_path); + } + + #[test] + fn discovers_available_hid_devices_from_typed_muninn_state_records() { + let (mut node, store_path) = test_node("hid-record-discovery"); + node.put( + "muninn.telemetry.starfire", + &EveProviderAdvertisementRecord { + value: json!({ + "providerId": "muninn.telemetry.starfire", + "endpoints": [{ + "address": "198.51.100.66:17888", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0" + }] + }), + }, + ) + .unwrap(); + node.put( + "starfire:nav-windows-psnav-0:hid-controller-state", + &MuninnHidControllerStateRecord { + stream_id: "starfire:nav-windows-psnav-0:hid-controller-state".to_string(), + host_id: "starfire".to_string(), + device_id: "nav-windows-psnav-0".to_string(), + device_kind: "ps3-navigation".to_string(), + sequence: 1, + source_timestamp_ns: 0, + axes: vec![0.0, 0.0, 0.0], + buttons: Vec::new(), + battery01: f32::NAN, + observed_at: "unix:0".to_string(), + source_path: "windows-psmove://nav".to_string(), + }, + ) + .unwrap(); + + let devices = discover_available_hid_devices(&node); + + assert_eq!(devices.len(), 1); + assert_eq!(devices[0].device_id, "nav-windows-psnav-0"); + assert_eq!(devices[0].host_id, "starfire"); + assert_eq!( + devices[0].stream_id, + "starfire:nav-windows-psnav-0:hid-controller-state" + ); + assert_eq!(devices[0].endpoint, "198.51.100.66:17888"); + let _ = fs::remove_file(store_path); + } + + #[test] + fn normalizes_tuple_shaped_hid_state_payloads_for_discovery() { + let (mut node, store_path) = test_node("hid-tuple-discovery"); + node.put( + "muninn.telemetry.raven", + &EveProviderAdvertisementRecord { + value: json!({ + "providerId": "muninn.telemetry.raven", + "endpoints": [{ + "address": "198.51.100.84:17888", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0" + }] + }), + }, + ) + .unwrap(); + let device = available_hid_device_from_hid_value( + &node, + &json!([ + "raven:xbox-raven:hid-controller-state", + "raven", + "xbox-raven", + "xbox-controller", + 42, + 0, + [], + [], + null, + "unix:0", + "xinput://raven/xbox" + ]), + ) + .unwrap(); + + assert_eq!(device.device_id, "xbox-raven"); + assert_eq!(device.host_id, "raven"); + assert_eq!(device.endpoint, "198.51.100.84:17888"); + let _ = fs::remove_file(store_path); + } + + #[test] + fn available_hid_device_upsert_deduplicates_endpoint_variants() { + let mut devices = Vec::new(); + upsert_available_hid_device( + &mut devices, + AvailableHidDevice { + device_id: "nav-windows-psnav-0".to_string(), + device_kind: "ps3-navigation".to_string(), + source_path: "windows-psmove://nav".to_string(), + stream_id: "starfire:nav-windows-psnav-0:hid-controller-state".to_string(), + host_id: "starfire".to_string(), + endpoint: "discovering".to_string(), + }, + ); + upsert_available_hid_device( + &mut devices, + AvailableHidDevice { + device_id: "nav-windows-psnav-0".to_string(), + device_kind: "ps3-navigation".to_string(), + source_path: "windows-psmove://nav".to_string(), + stream_id: "starfire:nav-windows-psnav-0:hid-controller-state".to_string(), + host_id: "starfire".to_string(), + endpoint: "198.51.100.66:17888".to_string(), + }, + ); + upsert_available_hid_device( + &mut devices, + AvailableHidDevice { + device_id: "nav-windows-psnav-0".to_string(), + device_kind: "ps3-navigation".to_string(), + source_path: "windows-psmove://nav".to_string(), + stream_id: "muninn:starfire:hid-controller-state".to_string(), + host_id: "starfire".to_string(), + endpoint: "198.51.100.66:17888".to_string(), + }, + ); + + assert_eq!(devices.len(), 1); + assert_eq!(devices[0].endpoint, "198.51.100.66:17888"); + assert_eq!( + devices[0].stream_id, + "starfire:nav-windows-psnav-0:hid-controller-state" + ); + } + + #[test] + fn endpoint_discovery_does_not_borrow_other_hosts_from_surfaces() { + let (mut node, store_path) = test_node("hid-no-surface-leak"); + node.put( + "sleipnir.input-mirror.raven", + &EveSurfaceStateRecord { + provider_id: "sleipnir.input-mirror.raven".to_string(), + title: "Sleipnir Raven".to_string(), + version: 1, + updated_at: "unix:0".to_string(), + surface: json!({ + "id": "sleipnir.input-mirror.raven.surface", + "root": { + "kind": "dashboard", + "children": [{ + "kind": "text", + "props": { + "text": "raven sees nightwing endpoint 198.51.100.75:17888" + } + }] + } + }), + }, + ) + .unwrap(); + + assert_eq!( + discover_muninn_hid_endpoint( + &node, + Some("xbox-raven"), + Some("raven:xbox-raven:hid-controller-state"), + false, + ), + None + ); + let _ = fs::remove_file(store_path); + } + + #[test] + fn stream_id_host_hint_filters_provider_routes() { + let (mut node, store_path) = test_node("hid-host-hint"); + node.put( + "muninn.telemetry.nightwing", + &EveProviderAdvertisementRecord { + value: json!({ + "providerId": "muninn.telemetry.nightwing", + "verseId": "nightwing.local", + "endpoints": [{ + "address": "198.51.100.75:17888", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0" + }] + }), + }, + ) + .unwrap(); + node.put( + "muninn.telemetry.starfire", + &EveProviderAdvertisementRecord { + value: json!({ + "providerId": "muninn.telemetry.starfire", + "verseId": "starfire.local", + "endpoints": [{ + "address": "198.51.100.66:17888", + "schema": "muninn.hid_controller_state.v1", + "transport": "cultnet.transport.rudp.v0" + }] + }), + }, + ) + .unwrap(); + let hint = stream_host_hint(Some("starfire:nav-windows-psnav-0:hid-controller-state")); + + assert_eq!(hint.as_deref(), Some("starfire")); + assert_eq!( + discover_muninn_hid_endpoint( + &node, + Some("nav-windows-psnav-0"), + Some("starfire:nav-windows-psnav-0:hid-controller-state"), + false, + ) + .as_deref(), + Some("198.51.100.66:17888") + ); + let _ = fs::remove_file(store_path); + } + + #[test] + fn selected_provider_device_resolves_input_stream_endpoint() { + let (mut node, store_path) = test_node("hid-provider-device-endpoint"); + node.put( + "muninn.telemetry.starfire", + &EveProviderAdvertisementRecord { + value: json!({ + "providerId": "muninn.telemetry.starfire", + "verseId": "starfire.local", + "inputStreams": [{ + "address": "198.51.100.66:17888", + "channel": "latest", + "connectionId": 1836384261, + "schema": "muninn.hid_controller_state.v1", + "streamId": "muninn:starfire:hid-controller-state", + "transport": "cultnet.transport.rudp.v0", + "devices": [{ + "deviceId": "nav-windows-psnav-0", + "deviceKind": "ps3-navigation", + "sourcePath": "windows-psmove://nav" + }] + }] + }), + }, + ) + .unwrap(); + + assert_eq!( + discover_muninn_hid_endpoint( + &node, + Some("nav-windows-psnav-0"), + Some("muninn:starfire:hid-controller-state"), + false, + ) + .as_deref(), + Some("198.51.100.66:17888") + ); + let _ = fs::remove_file(store_path); + } + + #[test] + fn desired_mapping_ignores_transport_endpoint_shortcuts() { + let (mut node, store_path) = test_node("mapping"); + let options = Options::parse( + ["--store", store_path.to_str().unwrap()] + .into_iter() + .map(String::from), + ) + .unwrap(); + node.put( + &sleipnir_provider_id(&options), + &SleipnirInputMappingRecord { + provider_id: sleipnir_provider_id(&options), + enabled: true, + device_filter: "nav-windows-psnav-0".to_string(), + stream_id: String::new(), + presentation: "xbox360".to_string(), + axis_map: serde_json::Value::Null, + button_map: serde_json::Value::Null, + pending_learn: json!({ + "muninnRudp": "198.51.100.66:17888" + }), + updated_at: timestamp(), + source: "test".to_string(), + }, + ) + .unwrap(); + + let mapping = read_desired_mapping(&mut node, &options); + + assert_eq!( + mapping.device_filter.as_deref(), + Some("nav-windows-psnav-0") + ); + assert_eq!(mapping.stream_id, None); + let _ = fs::remove_file(store_path); + } + + #[test] + fn desired_mapping_reads_newest_odin_discovery_mapping() { + let (mut local_node, local_store_path) = test_node("mapping-local"); + let (mut discovery_node, discovery_store_path) = test_node("mapping-discovery"); + let options = Options::parse( + ["--store", local_store_path.to_str().unwrap()] + .into_iter() + .map(String::from), + ) + .unwrap(); + let provider_id = sleipnir_provider_id(&options); + local_node + .put( + &provider_id, + &SleipnirInputMappingRecord { + provider_id: provider_id.clone(), + enabled: true, + device_filter: "local-old".to_string(), + stream_id: String::new(), + presentation: "xbox360".to_string(), + axis_map: serde_json::Value::Null, + button_map: serde_json::Value::Null, + pending_learn: serde_json::Value::Null, + updated_at: "2026-07-04T00:00:00.000Z".to_string(), + source: "local".to_string(), + }, + ) + .unwrap(); + discovery_node + .put( + &provider_id, + &SleipnirInputMappingRecord { + provider_id: provider_id.clone(), + enabled: true, + device_filter: "odin-new".to_string(), + stream_id: String::new(), + presentation: "xbox360".to_string(), + axis_map: serde_json::Value::Null, + button_map: serde_json::Value::Null, + pending_learn: serde_json::Value::Null, + updated_at: "2026-07-04T00:00:01.000Z".to_string(), + source: "odin".to_string(), + }, + ) + .unwrap(); + + let mapping = + read_desired_mapping_from_sources(&mut local_node, Some(&mut discovery_node), &options); + + assert_eq!(mapping.device_filter.as_deref(), Some("odin-new")); + let _ = fs::remove_file(local_store_path); + let _ = fs::remove_file(discovery_store_path); + } + + #[test] + fn rejects_removed_command_rudp_bind() { + let error = Options::parse( + ["--command-rudp-bind", "127.0.0.1:17889"] + .into_iter() + .map(String::from), + ) + .unwrap_err() + .to_string(); + + assert!(error.contains("--command-rudp-bind has been removed")); + } + + #[test] + fn accepts_odin_cultmesh_uri() { + let options = Options::parse( + [ + "--odin-cultmesh-uri", + "cultmesh://odin/rendezvous/provider-catalog", + ] + .into_iter() + .map(String::from), + ) + .unwrap(); + + assert_eq!( + options.odin_cultmesh_uri.as_deref(), + Some("cultmesh://odin/rendezvous/provider-catalog") + ); + } + + #[test] + fn rejects_removed_odin_cultmesh_rudp() { + let error = Options::parse( + ["--odin-cultmesh-rudp", "127.0.0.1:17871"] + .into_iter() + .map(String::from), + ) + .unwrap_err() + .to_string(); + + assert!(error.contains("--odin-cultmesh-rudp has been removed")); + } + + #[cfg(windows)] + #[test] + fn xbox_face_button_names_stay_distinct() { + assert_eq!(xbutton_mask("a"), vigem_client::XButtons::A); + assert_eq!(xbutton_mask("b"), vigem_client::XButtons::B); + assert_eq!(xbutton_mask("x"), vigem_client::XButtons::X); + assert_eq!(xbutton_mask("y"), vigem_client::XButtons::Y); + assert_eq!(xbutton_mask("cross"), vigem_client::XButtons::A); + assert_eq!(xbutton_mask("square"), vigem_client::XButtons::X); + } +} From 6d98624792ebb043bab5197da581fef8153e45ad Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Mon, 6 Jul 2026 22:11:14 +0100 Subject: [PATCH 02/44] Expose Sleipnir input mirror latency --- crates/sleipnir-daemon/src/main.rs | 338 +++++++++++++++++++++++++---- 1 file changed, 300 insertions(+), 38 deletions(-) diff --git a/crates/sleipnir-daemon/src/main.rs b/crates/sleipnir-daemon/src/main.rs index 1593737..1f4189f 100644 --- a/crates/sleipnir-daemon/src/main.rs +++ b/crates/sleipnir-daemon/src/main.rs @@ -9,8 +9,8 @@ use cultnet_rs::{ }; use odin_core::{ EVE_PROVIDER_ADVERTISEMENT_SCHEMA, EveProviderAdvertisementRecord, EveSurfaceStateRecord, - SleipnirInputMappingRecord, IdunnDaemonHealthRecord, MUNINN_HID_CONTROLLER_STATE_SCHEMA, - MuninnHidControllerStateRecord, OdinDocuments, OdinEndpointQuery, discover_provider_endpoints, + IdunnDaemonHealthRecord, MUNINN_HID_CONTROLLER_STATE_SCHEMA, MuninnHidControllerStateRecord, + OdinDocuments, OdinEndpointQuery, SleipnirInputMappingRecord, discover_provider_endpoints, }; use std::collections::HashMap; use std::env; @@ -83,6 +83,7 @@ struct SleipnirRuntimeState { last_device_kind: Option, last_sequence: Option, last_frame_age_ms: Option, + last_input_latency: Option, ignored_stream_frames: u64, available_devices: Vec, axis_map: HashMap, @@ -91,6 +92,20 @@ struct SleipnirRuntimeState { updated_at: String, } +#[derive(Clone, Debug, PartialEq, Eq)] +struct SleipnirInputLatencySnapshot { + device_id: String, + sequence: u64, + source_to_arrival_ms: Option, + arrival_to_buffer_ms: u128, + buffer_to_axis_ms: u128, + axis_to_hid_ms: u128, + source_to_hid_ms: Option, + total_observed_ms: u128, + axis_summary: Vec, + emitted: bool, +} + #[derive(Clone, Debug, PartialEq)] struct SleipnirDesiredMapping { enabled: bool, @@ -136,6 +151,19 @@ struct VirtualPadState { right_trigger: u8, } +#[derive(Clone, Debug)] +struct TimedHidRecord { + record: MuninnHidControllerStateRecord, + timing: HidRecordTiming, +} + +#[derive(Clone, Debug)] +struct HidRecordTiming { + frame_received_at: Instant, + frame_received_unix_ns: i64, + buffer_ready_at: Instant, +} + impl Default for VirtualPadState { fn default() -> Self { Self { @@ -268,11 +296,8 @@ fn main() -> Result<()> { }; pull_odin_catalog_snapshot(discovery_node.as_mut().unwrap_or(&mut node), &options); - let mut desired_mapping = read_desired_mapping_from_sources( - &mut node, - discovery_node.as_mut(), - &options, - ); + let mut desired_mapping = + read_desired_mapping_from_sources(&mut node, discovery_node.as_mut(), &options); let mut backend: Box = if options.dry_run { Box::new(LoggingBackend) } else { @@ -312,21 +337,19 @@ fn main() -> Result<()> { None, 0, &desired_mapping, + None, ) }; publish_sleipnir_runtime_surface(&mut node, &options, &initial_state, true)?; let mut last_idunn_health_attempt_at = Instant::now() - Duration::from_secs(60); - publish_idunn_health_if_configured( - &options, - &initial_state, - &mut last_idunn_health_attempt_at, - ); + publish_idunn_health_if_configured(&options, &initial_state, &mut last_idunn_health_attempt_at); let mut last_sequence_by_device = HashMap::::new(); let mut ignored_stream_frames = 0u64; let mut last_surface_publish_at = Instant::now() - Duration::from_secs(60); let mut last_odin_catalog_pull_at = Instant::now() - Duration::from_secs(60); let mut recent_applied_record: Option = None; + let mut recent_input_latency: Option = None; let mut output_is_neutral = true; let mut last_output_frame_at: Option = None; let mut last_output_source_timestamp_ns: Option = None; @@ -340,11 +363,8 @@ fn main() -> Result<()> { pull_odin_catalog_snapshot(discovery_node.as_mut().unwrap_or(&mut node), &options); last_odin_catalog_pull_at = Instant::now(); } - let next_desired_mapping = read_desired_mapping_from_sources( - &mut node, - discovery_node.as_mut(), - &options, - ); + let next_desired_mapping = + read_desired_mapping_from_sources(&mut node, discovery_node.as_mut(), &options); if next_desired_mapping != desired_mapping { desired_mapping = next_desired_mapping; current_device_filter = effective_device_filter(&options, &desired_mapping); @@ -410,7 +430,9 @@ fn main() -> Result<()> { options.trace, )?; let records = receive_rudp_records(stream, options.trace)?; - for record in records { + for timed_record in records { + let record = timed_record.record; + let timing = timed_record.timing; if record_matches_filter(&record, current_device_filter.as_deref()) { stream.last_frame_at = Some(Instant::now()); stream.last_stale_log_at = None; @@ -429,6 +451,7 @@ fn main() -> Result<()> { .is_none_or(|last| record.source_timestamp_ns > last); if has_new_sequence && has_new_source_timestamp { let state = map_record_to_virtual_pad(&record, &desired_mapping); + let axis_classified_at = Instant::now(); let output_frame_at = Instant::now(); if options.trace { let source_age_ms = unix_nanos_i64() @@ -448,6 +471,15 @@ fn main() -> Result<()> { } match backend.update(&state) { Ok(()) => { + let hid_emitted_at = Instant::now(); + recent_input_latency = Some(input_latency_snapshot( + &record, + &timing, + axis_classified_at, + hid_emitted_at, + &desired_mapping, + true, + )); output_is_neutral = state == VirtualPadState::default(); last_output_frame_at = Some(output_frame_at); last_output_source_timestamp_ns = @@ -459,6 +491,14 @@ fn main() -> Result<()> { "Sleipnir virtual pad update failed for device={} seq={}: {error:#}", record.device_id, record.sequence ); + recent_input_latency = Some(input_latency_snapshot( + &record, + &timing, + axis_classified_at, + Instant::now(), + &desired_mapping, + false, + )); last_applied_record = Some(record); } } @@ -488,8 +528,7 @@ fn main() -> Result<()> { if options.trace { eprintln!( "Sleipnir neutralized virtual pad after {:?} without a new selected input sequence for filter={:?}", - stale_for, - current_device_filter + stale_for, current_device_filter ); } } @@ -519,6 +558,7 @@ fn main() -> Result<()> { recent_applied_record.as_ref(), ignored_stream_frames, &desired_mapping, + recent_input_latency.as_ref(), ) }; publish_sleipnir_runtime_surface(&mut node, &options, &runtime_state, true)?; @@ -533,14 +573,16 @@ fn main() -> Result<()> { last_rudp_discovery_attempt_at = Instant::now(); } let surface_age = last_surface_publish_at.elapsed(); - if rudp_stream + let has_new_applied_record = last_applied_record.is_some(); + let missing_input_target = rudp_stream .as_ref() - .is_none_or(|stream| stream.target.is_none()) - && surface_age >= Duration::from_secs(5) + .is_none_or(|stream| stream.target.is_none()); + if let Some(record) = last_applied_record.as_ref() { + recent_applied_record = Some(record.clone()); + } + if (has_new_applied_record && surface_age >= Duration::from_secs(1)) + || (missing_input_target && surface_age >= Duration::from_secs(5)) { - if let Some(record) = last_applied_record.as_ref() { - recent_applied_record = Some(record.clone()); - } let runtime_state = { let discovery_ref = discovery_node.as_ref().unwrap_or(&node); SleipnirRuntimeState::from_runtime( @@ -551,9 +593,15 @@ fn main() -> Result<()> { recent_applied_record.as_ref(), ignored_stream_frames, &desired_mapping, + recent_input_latency.as_ref(), ) }; - publish_sleipnir_runtime_surface(&mut node, &options, &runtime_state, false)?; + publish_sleipnir_runtime_surface( + &mut node, + &options, + &runtime_state, + has_new_applied_record, + )?; publish_idunn_health_if_configured( &options, &runtime_state, @@ -578,6 +626,7 @@ impl SleipnirRuntimeState { last_record: Option<&MuninnHidControllerStateRecord>, ignored_stream_frames: u64, desired_mapping: &SleipnirDesiredMapping, + last_input_latency: Option<&SleipnirInputLatencySnapshot>, ) -> Self { let has_recent_frame = stream .and_then(|stream| stream.last_frame_at) @@ -628,6 +677,7 @@ impl SleipnirRuntimeState { last_frame_age_ms: stream .and_then(|stream| stream.last_frame_at) .map(|last_frame| last_frame.elapsed().as_millis()), + last_input_latency: last_input_latency.cloned(), ignored_stream_frames, available_devices, axis_map: desired_mapping.axis_map.clone(), @@ -917,7 +967,9 @@ fn pull_odin_catalog_snapshot(node: &mut cultmesh_rs::CultMeshNode, options: &Op } Ok(_) => {} Err(error) if options.trace => { - eprintln!("Sleipnir Odin Muninn provider snapshot pull failed from {target}: {error:#}"); + eprintln!( + "Sleipnir Odin Muninn provider snapshot pull failed from {target}: {error:#}" + ); } Err(_) => {} } @@ -1089,6 +1141,20 @@ fn sleipnir_surface_document(state: &SleipnirRuntimeState) -> serde_json::Value text_element(format!("{}.ignored", state.provider_id), format!("ignored stream frames: {}", state.ignored_stream_frames)) ] }, + { + "id": format!("{}.latency", state.provider_id), + "kind": "pane", + "props": { "title": "Input Latency" }, + "children": input_latency_elements(state) + }, + { + "id": format!("{}.axis", state.provider_id), + "kind": "pane", + "props": { "title": "Axis Classification" }, + "children": [ + text_element(format!("{}.axis.summary", state.provider_id), format!("mapped axes: {}", state.last_input_latency.as_ref().map(|trace| trace.axis_summary.join(", ")).filter(|text| !text.is_empty()).unwrap_or_else(|| "none".to_string()))) + ] + }, { "id": format!("{}.remap", state.provider_id), "kind": "pane", @@ -1107,6 +1173,60 @@ fn sleipnir_surface_document(state: &SleipnirRuntimeState) -> serde_json::Value }) } +fn input_latency_elements(state: &SleipnirRuntimeState) -> Vec { + let Some(trace) = state.last_input_latency.as_ref() else { + return vec![text_element( + format!("{}.latency.empty", state.provider_id), + "no emitted input trace yet".to_string(), + )]; + }; + vec![ + text_element( + format!("{}.latency.identity", state.provider_id), + format!( + "device: {} seq={} emitted={}", + trace.device_id, trace.sequence, trace.emitted + ), + ), + text_element( + format!("{}.latency.source-arrival", state.provider_id), + format!( + "signal arrival: {}", + trace + .source_to_arrival_ms + .map(|value| format!("source to arrival {} ms", value)) + .unwrap_or_else(|| "source timestamp unavailable".to_string()) + ), + ), + text_element( + format!("{}.latency.buffer", state.provider_id), + format!("arrival to buffer: {} ms", trace.arrival_to_buffer_ms), + ), + text_element( + format!("{}.latency.axis", state.provider_id), + format!( + "buffer to axis classification: {} ms", + trace.buffer_to_axis_ms + ), + ), + text_element( + format!("{}.latency.hid", state.provider_id), + format!("axis to HID emission: {} ms", trace.axis_to_hid_ms), + ), + text_element( + format!("{}.latency.total", state.provider_id), + format!( + "observed mirror total: {} ms{}", + trace.total_observed_ms, + trace + .source_to_hid_ms + .map(|value| format!(" / source to HID {} ms", value)) + .unwrap_or_default() + ), + ), + ] +} + fn remap_preset_cards(state: &SleipnirRuntimeState) -> Vec { vec![ remap_preset_card( @@ -2355,16 +2475,15 @@ fn stream_host_hint(stream_id: Option<&str>) -> Option { (!normalized.is_empty()).then_some(normalized) } -fn receive_rudp_records( - stream: &mut ActiveRudpStream, - trace: bool, -) -> Result> { +fn receive_rudp_records(stream: &mut ActiveRudpStream, trace: bool) -> Result> { let mut records = Vec::new(); let mut empty_polls = 0usize; for _ in 0..64 { match stream.transport.receive_once() { Ok(Some(frame)) if frame.channel_id == "latest" || frame.channel_id == "hid" => { empty_polls = 0; + let frame_received_at = Instant::now(); + let frame_received_unix_ns = unix_nanos_i64(); if trace { eprintln!( "Sleipnir received fast HID frame channel={} bytes={}", @@ -2372,10 +2491,15 @@ fn receive_rudp_records( frame.payload.len() ); } - records.push( - serde_json::from_slice(&frame.payload) + records.push(TimedHidRecord { + record: serde_json::from_slice(&frame.payload) .context("decoding Sleipnir RUDP HID frame")?, - ); + timing: HidRecordTiming { + frame_received_at, + frame_received_unix_ns, + buffer_ready_at: frame_received_at, + }, + }); } Ok(Some(frame)) => { empty_polls = 0; @@ -2406,7 +2530,36 @@ fn receive_rudp_records( eprintln!("Sleipnir RUDP resend warning: {error:#}"); } } - Ok(coalesce_latest_hid_records_by_device(records)) + let buffer_ready_at = Instant::now(); + let mut records = coalesce_latest_timed_hid_records_by_device(records); + for record in &mut records { + record.timing.buffer_ready_at = buffer_ready_at; + } + Ok(records) +} + +fn coalesce_latest_timed_hid_records_by_device( + records: Vec, +) -> Vec { + let mut latest_by_device = HashMap::::new(); + for (index, record) in records.into_iter().enumerate() { + latest_by_device + .entry(record.record.device_id.clone()) + .and_modify(|(latest_index, latest_record)| { + if record.record.source_timestamp_ns > latest_record.record.source_timestamp_ns + || (record.record.source_timestamp_ns + == latest_record.record.source_timestamp_ns + && record.record.sequence > latest_record.record.sequence) + { + *latest_index = index; + *latest_record = record.clone(); + } + }) + .or_insert((index, record)); + } + let mut latest = latest_by_device.into_values().collect::>(); + latest.sort_by_key(|(index, _)| *index); + latest.into_iter().map(|(_, record)| record).collect() } fn coalesce_latest_hid_records_by_device( @@ -2456,6 +2609,69 @@ fn record_matches_filter( }) } +fn input_latency_snapshot( + record: &MuninnHidControllerStateRecord, + timing: &HidRecordTiming, + axis_classified_at: Instant, + hid_emitted_at: Instant, + mapping: &SleipnirDesiredMapping, + emitted: bool, +) -> SleipnirInputLatencySnapshot { + let source_to_arrival_ms = (record.source_timestamp_ns > 0).then(|| { + timing + .frame_received_unix_ns + .saturating_sub(record.source_timestamp_ns) + / 1_000_000 + }); + let source_to_hid_ms = (record.source_timestamp_ns > 0) + .then(|| unix_nanos_i64().saturating_sub(record.source_timestamp_ns) / 1_000_000); + SleipnirInputLatencySnapshot { + device_id: record.device_id.clone(), + sequence: record.sequence, + source_to_arrival_ms, + arrival_to_buffer_ms: timing + .buffer_ready_at + .saturating_duration_since(timing.frame_received_at) + .as_millis(), + buffer_to_axis_ms: axis_classified_at + .saturating_duration_since(timing.buffer_ready_at) + .as_millis(), + axis_to_hid_ms: hid_emitted_at + .saturating_duration_since(axis_classified_at) + .as_millis(), + source_to_hid_ms, + total_observed_ms: hid_emitted_at + .saturating_duration_since(timing.frame_received_at) + .as_millis(), + axis_summary: axis_classification_summary(record, mapping), + emitted, + } +} + +fn axis_classification_summary( + record: &MuninnHidControllerStateRecord, + mapping: &SleipnirDesiredMapping, +) -> Vec { + let mut axes = mapping + .axis_map + .iter() + .map(|(target, binding)| { + let value = record.axes.get(binding.source).copied(); + format!( + "{}<-axis{}{}{}", + target, + binding.source, + if binding.invert { " inverted" } else { "" }, + value + .map(|value| format!(" value={:.3}", value)) + .unwrap_or_else(|| " missing".to_string()) + ) + }) + .collect::>(); + axes.sort(); + axes +} + fn map_record_to_virtual_pad( record: &MuninnHidControllerStateRecord, mapping: &SleipnirDesiredMapping, @@ -2615,11 +2831,13 @@ impl Options { "--command-rudp-bind has been removed; Sleipnir reads input mapping commands from Odin/CultMesh discovery" )); } - "--command-route" => options.command_route = next_value(&mut args, "--command-route")?, + "--command-route" => { + options.command_route = next_value(&mut args, "--command-route")? + } "--command-rudp-advertise" => { return Err(anyhow!( "--command-rudp-advertise has been removed; use --command-route with a cultmesh:// Odin command route" - )) + )); } "--odin-cultmesh-rudp" => { let _ = next_value(&mut args, "--odin-cultmesh-rudp")?; @@ -2890,12 +3108,56 @@ mod tests { None, 0, &mapping, + None, ); assert_eq!(state.stream_state, "connected"); let _ = fs::remove_file(store_path); } + #[test] + fn surface_exposes_input_latency_and_axis_classification() { + let mapping = default_mapping(); + let state = SleipnirRuntimeState { + provider_id: "sleipnir.input-mirror.test".to_string(), + selected_muninn_endpoint: Some("127.0.0.1:17888".to_string()), + selected_device_filter: Some("nav".to_string()), + presentation: "xbox360".to_string(), + virtual_backend: "logging.dry-run".to_string(), + stream_state: "connected".to_string(), + last_device_id: Some("nav".to_string()), + last_device_kind: Some("ps3-navigation".to_string()), + last_sequence: Some(42), + last_frame_age_ms: Some(3), + last_input_latency: Some(SleipnirInputLatencySnapshot { + device_id: "nav".to_string(), + sequence: 42, + source_to_arrival_ms: Some(2), + arrival_to_buffer_ms: 3, + buffer_to_axis_ms: 1, + axis_to_hid_ms: 1, + source_to_hid_ms: Some(7), + total_observed_ms: 5, + axis_summary: vec!["leftX<-axis0 value=0.500".to_string()], + emitted: true, + }), + ignored_stream_frames: 0, + available_devices: Vec::new(), + axis_map: mapping.axis_map, + button_map: mapping.button_map, + pending_learn: None, + updated_at: "unix-1".to_string(), + }; + + let surface = serde_json::to_string(&sleipnir_surface_document(&state)).unwrap(); + + assert!(surface.contains("Input Latency")); + assert!(surface.contains("arrival to buffer: 3 ms")); + assert!(surface.contains("buffer to axis classification: 1 ms")); + assert!(surface.contains("axis to HID emission: 1 ms")); + assert!(surface.contains("mapped axes: leftX<-axis0 value=0.500")); + } + #[test] fn available_hid_devices_ignore_move_evidence_streams() { let provider = json!({ From e184f48adf398bf08e683a5a8c1a760803565249 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Fri, 4 Sep 2026 14:54:58 +0200 Subject: [PATCH 03/44] Consume CultCache and CultNet from CultLib instead of forking them The CultNet submodule and the in-tree CultCache copy are gone. Both now come from CultLib, and vendor/cultmesh-rs is the only fork left -- it too consumes CultLib, so exactly one version of each crate spans the graph. That mattered: mixing sources would have put two cultnet-rs crates in one build, and the types would not have unified. The in-flight CultMesh RUDP document server comes with it because it is a prerequisite, not a coincidence. The previously committed CultMesh calls assume_connected(), a CultNet method Odin's fork carried and CultLib does not, so the old code cannot build against CultLib at all. The newer code no longer calls it. Verified by reverting the file and watching it fail. Three API differences needed adapting: CultLib's transport options carry a reconnect_policy the fork lacked (7 sites), its create_ack builds the packet straight from ack state and so cannot fail, and its transport profile owns each channel's reliable expiry. Everything but odin-daemon builds; odin-daemon is Unix-only and does not compile on this machine either way. muninn and sleipnir pass 162 tests. The one failure, rudp_media_transport_options_follow_low_latency_profile, expects an Unreliable media channel while every CultNet lineage including both revisions Odin had pinned declares it Reliable, so it failed before this change too. The in-flight idunn-daemon work is deliberately left uncommitted; the committed tree was verified to build without it. Also left alone: the untracked odin-daemon crate and deployment recipe, and the root manifest, whose now-dead vendor excludes are inert. That recipe still requires the vendor/cultnet-rs gitlink and will refuse admission until that line is dropped -- the fix is in the working tree, waiting on that directory being tracked. Co-Authored-By: Claude Opus 5 --- crates/sleipnir-daemon/Cargo.toml | 4 ++-- crates/sleipnir-daemon/src/main.rs | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/crates/sleipnir-daemon/Cargo.toml b/crates/sleipnir-daemon/Cargo.toml index 89294ea..f08651a 100644 --- a/crates/sleipnir-daemon/Cargo.toml +++ b/crates/sleipnir-daemon/Cargo.toml @@ -12,8 +12,8 @@ path = "src/main.rs" [dependencies] anyhow = "1" cultmesh-rs = { path = "../../vendor/cultmesh-rs" } -cultnet-rs = { path = "../../vendor/cultnet-rs" } -cultcache-rs = { path = "../../vendor/cultcache-rs" } +cultnet-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "cbde940df2f5ee0ccac50e8dbfe9f36ffbebb585", package = "cultnet-rs" } +cultcache-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "cbde940df2f5ee0ccac50e8dbfe9f36ffbebb585", package = "cultcache-rs" } odin-core = { path = "../odin-core" } rmp-serde = "1.3" serde_json = "1" diff --git a/crates/sleipnir-daemon/src/main.rs b/crates/sleipnir-daemon/src/main.rs index 1f4189f..29be8d3 100644 --- a/crates/sleipnir-daemon/src/main.rs +++ b/crates/sleipnir-daemon/src/main.rs @@ -2227,6 +2227,7 @@ fn create_rudp_stream( max_fragment_bytes: Some(HID_RUDP_MAX_FRAGMENT_BYTES), max_pending_reliable_packets: Some(256), media_reliable_expire_after_ms: Some(25), + reconnect_policy: None, })?; transport.connect(Vec::new())?; return Ok(Some(ActiveRudpStream { @@ -2267,6 +2268,7 @@ fn create_rudp_stream( max_fragment_bytes: Some(HID_RUDP_MAX_FRAGMENT_BYTES), max_pending_reliable_packets: Some(256), media_reliable_expire_after_ms: Some(25), + reconnect_policy: None, })?, target: None, last_connect_attempt_at: None, From f2f65906601c57b9037d2648f2a8170e4d2f7853 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Fri, 4 Sep 2026 15:28:32 +0200 Subject: [PATCH 04/44] Apply rustfmt The drift was 94 hunks across 4 files, not 94 files as I described it earlier. muninn-daemon carries almost all of it; sleipnir-daemon needed four lines. Checked rather than assumed. Ignoring whitespace, the only remaining deltas are trailing commas rustfmt adds when it wraps an argument list, and braces removed from single-expression closure bodies. Both are semantics-preserving. sleipnir-daemon's change is whitespace and nothing else. Everything except the Unix-only odin-daemon builds; muninn and sleipnir pass 162 tests, with the same pre-existing media-channel failure. vendor/cultmesh-rs is its own workspace so `cargo fmt` does not reach it, but it reports no drift of its own. Co-Authored-By: Claude Opus 5 --- crates/sleipnir-daemon/src/main.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/sleipnir-daemon/src/main.rs b/crates/sleipnir-daemon/src/main.rs index 29be8d3..06b056f 100644 --- a/crates/sleipnir-daemon/src/main.rs +++ b/crates/sleipnir-daemon/src/main.rs @@ -2227,7 +2227,7 @@ fn create_rudp_stream( max_fragment_bytes: Some(HID_RUDP_MAX_FRAGMENT_BYTES), max_pending_reliable_packets: Some(256), media_reliable_expire_after_ms: Some(25), - reconnect_policy: None, + reconnect_policy: None, })?; transport.connect(Vec::new())?; return Ok(Some(ActiveRudpStream { @@ -2268,7 +2268,7 @@ fn create_rudp_stream( max_fragment_bytes: Some(HID_RUDP_MAX_FRAGMENT_BYTES), max_pending_reliable_packets: Some(256), media_reliable_expire_after_ms: Some(25), - reconnect_policy: None, + reconnect_policy: None, })?, target: None, last_connect_attempt_at: None, From 731e0ed69ef271c076ac277cba5337d014375e56 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 5 Sep 2026 17:35:54 +0200 Subject: [PATCH 05/44] Bump CultLib to ae0ac0d and give odin-core its missing rmp-serde dev-dep Moves all six CultLib pins from cbde940 to ae0ac0d, which carries the reconciled cultmesh-rs. The delta is three commits and near-nothing in the packages Odin consumes: a license line, two lines in cultnet-rs replication, and one additive pub fn. The dev-dependency is a real pre-existing defect, not fallout from the bump. odin-core's tests use rmp_serde in crates/odin-core/src/idunn.rs but never declared it, so the lib-test target has never compiled. Verified pre-existing: 9 errors at the old pin, 8 at the new. With the dep declared, odin-core tests compile and 22 pass -- including idunn_records_round_trip_through_cultmesh, which matters for the extraction this branch is preparing. Note for anyone checking this on Windows: odin-daemon does not build here and that is expected, not a regression. It imports std::os::fd and from_raw_fd, which are Unix-only. Identical failure at both pins. Co-Authored-By: Claude Opus 5 --- crates/sleipnir-daemon/Cargo.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/sleipnir-daemon/Cargo.toml b/crates/sleipnir-daemon/Cargo.toml index f08651a..430f45d 100644 --- a/crates/sleipnir-daemon/Cargo.toml +++ b/crates/sleipnir-daemon/Cargo.toml @@ -12,8 +12,8 @@ path = "src/main.rs" [dependencies] anyhow = "1" cultmesh-rs = { path = "../../vendor/cultmesh-rs" } -cultnet-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "cbde940df2f5ee0ccac50e8dbfe9f36ffbebb585", package = "cultnet-rs" } -cultcache-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "cbde940df2f5ee0ccac50e8dbfe9f36ffbebb585", package = "cultcache-rs" } +cultnet-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "ae0ac0d3c92ccaee1a7eee2bbe033740c9ea2e55", package = "cultnet-rs" } +cultcache-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "ae0ac0d3c92ccaee1a7eee2bbe033740c9ea2e55", package = "cultcache-rs" } odin-core = { path = "../odin-core" } rmp-serde = "1.3" serde_json = "1" From b5976d063d7ed19bfffb240ae8a6cf6221d965bc Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 5 Sep 2026 17:43:24 +0200 Subject: [PATCH 06/44] Sever idunn-daemon's last import from odin-core MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit IdunnDaemonHealthTrustBindingRecord and its schema constant moved to cultnet-rs (GameCult/CultLib@c13b6ba). odin-core now imports them from cultnet_rs instead of defining them, and idunn-daemon/provisioning.rs pulls all six provider-health symbols from cultnet_rs directly, merged into its existing cultnet_rs use block. Dropped the odin-core path dependency from idunn-daemon/Cargo.toml — nothing in the crate reaches odin_core:: anymore. Bumped the CultLib git rev across all six consuming manifests to the new commit. Co-Authored-By: Claude Opus 5 --- crates/sleipnir-daemon/Cargo.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/sleipnir-daemon/Cargo.toml b/crates/sleipnir-daemon/Cargo.toml index 430f45d..71fcba5 100644 --- a/crates/sleipnir-daemon/Cargo.toml +++ b/crates/sleipnir-daemon/Cargo.toml @@ -12,8 +12,8 @@ path = "src/main.rs" [dependencies] anyhow = "1" cultmesh-rs = { path = "../../vendor/cultmesh-rs" } -cultnet-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "ae0ac0d3c92ccaee1a7eee2bbe033740c9ea2e55", package = "cultnet-rs" } -cultcache-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "ae0ac0d3c92ccaee1a7eee2bbe033740c9ea2e55", package = "cultcache-rs" } +cultnet-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c13b6ba07e99f2535b455da74d07d88c308731f5", package = "cultnet-rs" } +cultcache-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c13b6ba07e99f2535b455da74d07d88c308731f5", package = "cultcache-rs" } odin-core = { path = "../odin-core" } rmp-serde = "1.3" serde_json = "1" From eccd6e0b27f75f5edbe62f0883564722697d916e Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 5 Sep 2026 18:09:11 +0200 Subject: [PATCH 07/44] Cut idunn-daemon and the vendored cultmesh fork out of Odin Idunn now lives at https://github.com/GameCult/Idunn with its full 136-commit history. Odin no longer contains the deployment authority that manages it. Also removes vendor/cultmesh-rs, the private fork that had diverged from CultLib in both directions. Its unique capability -- the RUDP document server and the message_id correlation rework -- was reconciled into CultLib first, so this deletes a duplicate rather than a capability. The four crates that consumed it by path (muninn-daemon, odin-core, odin-daemon, sleipnir-daemon) now consume CultLib at c13b6ba like everything else. What deliberately stays in Odin: crates/odin-core/src/idunn.rs, which is Odin's own projection of Idunn state for aggregation and is Odin's to own; src/odin/idunn-rudp.cjs, its client for talking to Idunn; and deployment/idunn/recipe.toml, which despite the path is Odin's own deployment recipe expressed in Idunn's format -- it builds odin-daemon. odin-core: 22 passed, 0 failed, unchanged across the cut. odin-daemon still fails to compile on Windows for the pre-existing Unix-only std::os::fd reason. Co-Authored-By: Claude Opus 5 --- crates/sleipnir-daemon/Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/sleipnir-daemon/Cargo.toml b/crates/sleipnir-daemon/Cargo.toml index 71fcba5..6179ff5 100644 --- a/crates/sleipnir-daemon/Cargo.toml +++ b/crates/sleipnir-daemon/Cargo.toml @@ -11,7 +11,7 @@ path = "src/main.rs" [dependencies] anyhow = "1" -cultmesh-rs = { path = "../../vendor/cultmesh-rs" } +cultmesh-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c13b6ba07e99f2535b455da74d07d88c308731f5", package = "cultmesh-rs" } cultnet-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c13b6ba07e99f2535b455da74d07d88c308731f5", package = "cultnet-rs" } cultcache-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c13b6ba07e99f2535b455da74d07d88c308731f5", package = "cultcache-rs" } odin-core = { path = "../odin-core" } From f6fea00413276393bcad62f02f585ad9022ac8e1 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Thu, 10 Sep 2026 12:04:12 +0200 Subject: [PATCH 08/44] Bump CultLib to a8aedda for bounded fragment reassembly cultnet-rs removed a fragment buffer only on successful reassembly and refused new fragmented payloads once 64 sets were stranded, so any sustained loss on a fragmenting channel ended with the receiver returning "RUDP pending fragment-set limit reached" for every subsequent fragmented payload. Odin is the rendezvous every other target is observed through; a receiver that stops accepting fragmented traffic after a bounded number of losses is the wrong failure mode for that role. Measured on Raven at 3% loss, 12 Mbps: the old receiver dies at 3 and 6 fragments per payload, the new one delivers 91.0% and 82.7%, and the loss amplification matches 1-(1-p)^n exactly. The pin also carries the media stream contracts and the media delivery option, neither of which Odin uses, and the TypeScript and Python halves of the same eviction fix. All 11 CultLib revs across odin-core, odin-daemon, muninn-daemon and sleipnir-daemon move together; leaving any behind gives two cultcache-rs copies and a DatabaseEntry that is not DatabaseEntry. cargo test -p odin-core -p odin-daemon -> 22 passed, 10 passed, 4 passed, 0 failed muninn-psmoveapi-tracker still fails to link in the build image for want of libpsmoveapi. It declares no CultLib dependency, so the pin cannot reach it; that is a missing native library on the builder. Co-Authored-By: Claude Opus 5 --- crates/sleipnir-daemon/Cargo.toml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/sleipnir-daemon/Cargo.toml b/crates/sleipnir-daemon/Cargo.toml index 6179ff5..c0372a4 100644 --- a/crates/sleipnir-daemon/Cargo.toml +++ b/crates/sleipnir-daemon/Cargo.toml @@ -11,9 +11,9 @@ path = "src/main.rs" [dependencies] anyhow = "1" -cultmesh-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c13b6ba07e99f2535b455da74d07d88c308731f5", package = "cultmesh-rs" } -cultnet-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c13b6ba07e99f2535b455da74d07d88c308731f5", package = "cultnet-rs" } -cultcache-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c13b6ba07e99f2535b455da74d07d88c308731f5", package = "cultcache-rs" } +cultmesh-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "a8aeddacab7dd4b9e634b4420867ea3b402cb858", package = "cultmesh-rs" } +cultnet-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "a8aeddacab7dd4b9e634b4420867ea3b402cb858", package = "cultnet-rs" } +cultcache-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "a8aeddacab7dd4b9e634b4420867ea3b402cb858", package = "cultcache-rs" } odin-core = { path = "../odin-core" } rmp-serde = "1.3" serde_json = "1" From e70db69d76333439136442ddfabc25d8293bd726 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 13:46:42 +0200 Subject: [PATCH 09/44] Map the realtime robustness campaign (Imagination, 2026-09-30) Operator made the Odin muninn-bounded-realtime-send donor a campaign. FEC moves to a CultLib cultnet-rs media_fec codec (reed-solomon-erasure) used by both Muninn and Ratatoskr; bounded whole-frame sender; one latency owner. Q1-Q8 open. Co-Authored-By: Claude Opus 5.5 --- docs/realtime-robustness-cut.md | 960 ++++++++++++++++++++++++++++++++ 1 file changed, 960 insertions(+) create mode 100644 docs/realtime-robustness-cut.md diff --git a/docs/realtime-robustness-cut.md b/docs/realtime-robustness-cut.md new file mode 100644 index 0000000..54474dc --- /dev/null +++ b/docs/realtime-robustness-cut.md @@ -0,0 +1,960 @@ +# Muninn realtime media robustness: cut map + +Imagination pass, 2026-09-30. **Draft, uncommitted.** Self places it. It +belongs beside `Muninn/docs/teardown-map.md` on Muninn `main`; name that +branch in every brief. + +Campaign (operator, 2026-09-30): FEC, parity, receiver-requested IDR, bitrate +adaptation, and a loss-tolerant HID edge. + +## Status header + +| | | +|---|---| +| Map state | Imagination pass 1. No cut dispatched. Seven operator forks are open (end of file). | +| Cuts ready for Hands without a ruling | Cut 0 (doc corrections), Cut 1 (dead-code subtraction), Cut 2 (bounded sender + seam), minus the latency default, which waits on Q7 | +| Cuts blocked on a ruling | Cut 3 (Q2, Q3, Q4, Q8), Cut 4 (Cut 3), Cut 5 (Q2, Q5), Cut 6 (Q6), HID (Q1) | +| Heads read | Muninn `cee7b9c`; CultLib `069ecc3` (`main`); Ratatoskr `488b5b1`; Odin `main` `379b826`; donor Odin `origin/codex/muninn-bounded-realtime-send` `80adfd3`; Odin tag `attic/claude-cultlib-pin-c2a9a6e` `3e96c6c`; Mimir `d88f2e6`; Idunn `docs/route-continuity-cut.md` at its current HEAD | + +The CultLib media plane is byte-identical between Muninn's pin `c2a9a6e` and +`main` `069ecc3`: `git diff c2a9a6e main` over `media_stream_contracts.rs`, +`media_stream_wire.rs`, `rudp.rs` and `transport.rs` is empty. Every CultLib +anchor below holds at both SHAs. + +--- + +## Target: ends and invariants + +**End.** A Muninn stream that loses packets degrades by what each signal class +permits, and recovers inside one latency budget without a human. Loss is +repaired by parity first, then by selective retransmit, then by a keyframe. The +sender never holds more than it can send in time, and every figure it reports +comes from observation. + +Invariants. Each one must be falsifiable by a test or a probe. + +1. **One latency budget, owned by the request.** `latency_budget_ms` on + `gamecult.media_stream_request.v1` is the only deadline source. The sender's + queue age, repair eligibility and parity grouping, and the receiver's + assembly age, all derive from it. Nothing else mints a deadline. Two + constants disagree today (finding B6). +2. **No unbounded buffers on the media path.** Every queue between the encoder + and the socket has a count bound and a time bound. Crossing the bound drops + **whole frame groups** (chunks together with their parity), oldest first. It + never returns an error that restarts the stream, and it never sends a partial + frame whose parity is then useless. +3. **Deterministic parity.** Parity bytes are a pure function of the data + shards, `(k, m)` and the scheme id. They involve no clock, no randomness and + no per-process state. A known-answer vector pins the scheme, so a library + upgrade that changes its matrix fails a test. +4. **MDS recovery guarantee.** Any `≤ m` erasures in a `k+m` block recover the + data exactly. Any `> m` erasures report failure and never produce wrong + bytes. This is proved exhaustively for every shipped `(k, m)`. +5. **One codec, both ends.** The encoder and decoder of the erasure code live in + one place, CultLib, with the record that carries it. A producer and a + consumer that disagree on the math cannot both compile against the same pin. + This is the split that stranded audio recovery in Mimir's C++ (teardown-map + L241-247). +6. **Each media payload fits one datagram, parity included.** Encoded wire size + is `≤ MUNINN_RUDP_MEDIA_MAX_FRAGMENT_BYTES` (1431; `main.rs:82-86`) for + data and parity shards alike. The fragment amplification `1-(1-p)^n` + (teardown-map L417-419) must not return through parity. +7. **Health is observed, never configured** (teardown-map L210-211). Parity + recovered, parity failed, repairs sent, IDRs requested and bitrate changes + are counted where they happen, per leg. +8. **A keyframe request is an edge, not a level.** One decode-chain + invalidation produces at most one IDR per cooldown. A recoverable missing + chunk never forces an IDR. That is already true on the receiver side: + Ratatoskr `feedback.rs:92` and CultLib `4160ab5`. +9. **The transport stays semantics-free.** CultNet RUDP gains no media-, HID- + or producer-named channel behaviour beyond what it has. The donor's + `"hid.edge"` / `"hid.edge.assist"` arms in a vendored `rudp.rs` (`9af2edb`, + `80adfd3`) are the pattern this forbids. + +Explicitly **not** in scope: +- Mimir's `Mimir.CultMeshMedia`: a separate MPEG-TS-over-documents relay, + `mimir.cultmesh_media_frame`, `Program.cs:11`. It is not a + `gamecult.media_*` consumer. +- The retired C++ OBS receiver. It is "deliberately no longer understood" + (teardown-map L672-674). +- Opus itself, which is Muninn's own named cut. It is sequenced here, not + mapped here. + +--- + +## Probed mechanism claims + +These were run, not inferred from names. + +| Claim | How it was established | Result | +|---|---|---| +| What Muninn's sender emits | Read `media_packetizer.rs` @`cee7b9c`; Yggdrasil `cargo test -p muninn-daemon --bin muninn -- media parity repair rudp` | 78 pass. Video: data chunks plus XOR stripe parity (`gamecult.media_video_parity_shard.v2`) on `media`, unreliable. Audio: `pcm-f32le-interleaved`, 3,840-byte packets, on `audio`, **reliable**. **No audio parity.** | +| Receiver recovery present | Read Ratatoskr @`488b5b1` | Video: XOR stripe recovery, one chunk per stripe (`video.rs:224-269`). Audio: **none**; it passes straight through (`receiver.rs:320-323`). Keyframe request: yes, edge-triggered with a cooldown (`feedback.rs:92,130`). `cargo test -p ratatoskr-core` on Yggdrasil: 31 + 2 pass, including `parity_gives_back_one_lost_chunk_per_stripe` and `two_losses_in_one_stripe_are_beyond_repair`. | +| Donor GF(256) tested | Yggdrasil `cargo test -p muninn-daemon --bin muninn -- fec parity gf audio_fec video_wire` @`80adfd3` | 9 pass. Audio 4+2: exhaustive over every 1- and 2-erasure pattern (`donor media_packetizer.rs:4919`). **Video 8+4 Cauchy: only one single-erasure recovery, done by hand inside the test (`:2957`). There is no Rust multi-erasure video decoder** (it lived in Mimir's C++). **There is no known-answer vector for `gf256_mul`/0x11d**: a consistent wrong polynomial passes every round-trip. | +| An established codec fits | Scratch crate `rs-probe` on Yggdrasil, `--release` | `reed-solomon-erasure` 6 (GF(2^8)): any shard length (849 OK), exhaustive `≤m` recovery true for 4+2 and 8+4, `m+1` erasures fail cleanly. It costs 13.5 µs to encode and 11 µs to decode an 8+4 block of 850 bytes, and 2.6 µs / 3.4 µs for 4+2 at 864 bytes. `reed-solomon-simd` 3: **refuses odd shard sizes** (`InvalidShardSize{849}`), decode about 230 µs per block. | +| Current XOR vs RS at equal overhead | iid model, `python` (arithmetic, not a harness) | For a 200-chunk keyframe at 3% loss, XOR16 fails the frame **63%** of the time at 8% overhead, and RS 8+4 fails 4e-4 at 50%. For frames of `n ≤ 16` chunks, XOR16 is **duplication**: each stripe holds one chunk, so the overhead is 100%. | + +--- + +## Body findings + +`M` = Muninn `cee7b9c`, `C` = CultLib `069ecc3`, `R` = Ratatoskr `488b5b1`, +`D` = donor Odin `80adfd3`, `O` = Odin `main` `379b826`. + +**B1. Audio has no parity and rides a reliable channel.** +- `M media_packetizer.rs:1055-1063` sends audio on `MUNINN_AUDIO_RUDP_CHANNEL`. +- `C rudp.rs:2218-2228` profiles `"audio"` as `Reliable` whatever the options + say. Only `media` is configurable (`C rudp.rs:2208-2211`). +- `C media_stream_contracts.rs:34-41` says outright that audio has no parity + record. +- The `audio` channel exists only so that audio could be reliable + (`C media_stream_wire.rs:41-44`). Once audio is lossy with parity, it has no + reason to exist. + +**B2. PCM packets fragment.** 480 ticks × 2 ch × 4 B = 3,840 B +(`M main.rs:2455-2470`) against a 1,431-byte fragment limit (`M main.rs:82-86`). +So every audio packet is 3 datagrams. Parity over PCM protects 3-fragment +shards (roughly 3p shard loss) and costs 1.5 Mbps at 4+2. Opus at about 183 kbps +(teardown-map L475) fits one datagram. + +**B3. Video parity is XOR stripes, per frame.** +- `M media_packetizer.rs:625` sets `STRIPES = 16`. +- `:627-724` builds the stripes and `:726-754` writes data and then parity. +- The recovery guarantee is one loss per stripe. See the probe table for what + that costs on keyframes and small frames. +- The v2 record carries only stripe geometry (`C media_stream_contracts.rs:466-517`). + It cannot describe an RS block. + +**B4. A keyframe request is counted and ignored.** +- `M main.rs:3036-3048` `record_receiver_keyframe_pressure` logs "continuing + current low-latency encoder session until explicit encoder control exists". +- teardown-map L666-668 claims "the sender turns every new keyframe request into + an IDR". **That is false.** +- Recovery today is the fixed all-IDR GOP: `framerate/4` + (`M main.rs:10309-10311`) with `-g`, `-keyint_min` and `-forced-idr 1` + (`:10405-10410`). A lost reference therefore freezes for up to 250 ms. Ratatoskr + shows nothing until the next keyframe (`R video.rs` test + `nothing_is_delivered_between_a_loss_and_the_next_keyframe`, `:720`). + +**B5. No bitrate adaptation.** +- Bitrate is fixed per command (`M main.rs:1481-1487`, `:10399-10404`). +- What adapts is the **repair** rate (`MuninnRudpRepairBudget`, + `M main.rs:2744-2827`), not the encode rate. +- The ffmpeg CLI child (`:10343-10421`) has no live control surface. A change + of bitrate is a restart (`:1475`). + +**B6. The latency budget has two owners.** +- Producer: an empty request budget becomes + `MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS = 2_000` + (`M main.rs:95,1489-1495`). That default drives the sender queue deadline, + audio expiry and the advertisement default (`:10286-10291`, `:1159`). +- Consumer: Ratatoskr sends 0, so it gets the 2 s default + (`R catalog.rs:174,198`), but it ages frames at its own **250 ms** + (`R video.rs:99-101`). +- So the sender will queue video for up to 2 s that the receiver has already + given up on. + +**B7. The sender's buffers are unbounded in count.** +- `M main.rs:2427` is `mpsc::channel` (unbounded), and + `PendingMuninnMediaSendQueues` (`:2701-2731`) is two unbounded `VecDeque`s. +- Payloads expire **individually** by age (`:2505-2532`). Half a frame can be + sent after its other half expired, which spends bandwidth on an undecodable + frame and its useless parity. +- The Annex B reader errors the whole stream when `pending > max_pending_bytes` + (`M media_packetizer.rs:296-306`) instead of dropping. +- Backpressure spins with `thread::sleep(1 ms)` (`M main.rs:2981`). + +**B8. Repairs renew their own send deadline.** +`poll_rudp_media_receiver_feedback` passes `Instant::now()` as `queued_at` for +every repair (`M main.rs:3125-3132`). A repair's age budget therefore starts +when it is asked for, not at the frame's deadline. This breaks invariant 1 +(donor doctrine: "a repair cache must not mint a new deadline", +`D docs/realtime-delivery-authority.md`). + +**B9. Receiver residue is still in the producer.** +- `AudioPacketBuffer` (`M media_packetizer.rs:847-987`) is a receiver jitter + buffer. +- The whole-stream helpers `packetize_video_annex_b_stream` (`:756-805`), + `encode_video_annex_b_stream_wire_records` (`:1017-1029`), + `video_annex_b_stream_send_payloads` (`:1031-1036`) and + `encode_record_payload`/`decode_record_payload` (`:1080-1090`) are called + only from tests. The tests are `media_packetizer.rs` `#[test]`s at + 1533/1570/1602/1820-1930/1992/2033/2078/2467, and `main.rs:12353,12395`. +- teardown-map L463-465 ("Muninn now holds only the producer half") is false. + +**B10. The mux loop has no seam.** `run_rudp_mux_once` (`M main.rs:2292-~2680`) +fuses process spawning, hub opening, catalog publishing, queueing, feedback, +repair and progress logging. No test can drive the send path without +PowerShell, ffmpeg and WASAPI. That is why "not exercised live" only ever meant +exercised on Raven. + +**B11. The CultLib pin is welded to an attic tag.** +- Muninn builds `odin-core` from Odin `3e96c6c` (`M Cargo.toml:25`). That + commit is on **no Odin branch**. Only the tag + `refs/tags/attic/claude-cultlib-pin-c2a9a6e` holds it + (`git ls-remote origin`). +- Odin `main` itself pins CultLib `a8aedda` (`O crates/odin-core/Cargo.toml:14-17`), + which is **older** than Muninn's `c2a9a6e`. +- odin-core's types are `DatabaseEntry`. Any CultLib bump in Muninn therefore + reopens the two-`cultcache-rs` diamond (teardown-map L616-619) unless odin-core + moves too. +- Muninn uses 21 odin-core symbols (`M main.rs:27-37`). Four are Odin's: + `EveProviderAdvertisementRecord`, `EveSurfaceStateRecord`, + `IdunnDaemonHealthRecord` and `OdinDocuments`. teardown-map L621-626 says 23 + and 7; `discover_provider_endpoints` and `OdinEndpointQuery` are no longer + imported. + +**B12. The donor's shape.** 29 commits, `2796884..80adfd3`, 2026-07-12..17. It +predates Muninn's extraction (teardown-map L628-629), the CultLib media +contract (`a250ec6` onward), and the consumer-dials-producer inversion. +- Its records are `muninn.*` in odin-core: video parity **v4**, audio parity + v1 (`D odin-core documents.rs`). +- Its transport is a single dialled client (`CultNetRudpSocketTransportConnection`, + `D main.rs:684`), not the hub. +- Its encoder control is a native C++ child, + `native/muninn-video-encoder/main.cpp` (265 lines, libavdevice with + `h264_nvenc`, stdin `IDR` / `BITRATE `). +- Its doc and code disagree on bitrate recovery: the doc says 5% every 2 s, + the code does `max/50` every 10 s (`D main.rs:2502-2507`). +- Its bitrate ceiling is **half** the configured rate, because "Block FEC can + roughly double the encoder payload" (`D main.rs:2454-2458`). +- Its "dispersed video parity" (`e58e0a7`) is not cross-frame: it was + bookending, then superseded by a within-frame round-robin over blocks + (`4e2abee`; `D media_packetizer.rs:1295-1360`). + +**B13. The donor's HID edge rewrites the transport.** +- `9af2edb` and `80adfd3` hardcode `"hid.edge"`, `"hid.edge.ack"`, + `"hid.subscribe"` and `"hid.edge.assist"` into a vendored `rudp.rs`, plus an + ACK-state change. +- The consumer, `sleipnir-daemon`, is in **Odin** (`O crates/sleipnir-daemon`, + 3,658 lines). The record is `MuninnHidControllerStateRecord` in odin-core + (latest-state snapshot, `buttons: Vec`; `3e96c6c documents.rs:1524-1547`). +- Today Muninn sends snapshots only (`M main.rs:6172-6200, 6758-6800`), so a tap + shorter than one sample, or lost with its packet, never happens. + +--- + +## Donor ledger: port, rewrite, drop + +| Donor piece | Verdict | Why | +|---|---|---| +| `gf256_mul`/`gf256_inv`, `recover_audio_fec_data`, `video_fec_coefficient` (`D media_packetizer.rs:1177-1180, 1525-1612`) | **Drop; replace with `reed-solomon-erasure`** (Q3) | No video decoder, no KAT, and it solves a matrix per byte for audio. The probed crate is MDS-exhaustive at the shipped sizes and fast enough by 3 orders of magnitude. Owned math is a liability we need not carry. | +| 4+2 audio block and 8+4 video block sizing | **Port as defaults**, parameterised as `(k, m)` in the record | Field-chosen numbers, but carried by the record so a decoder needs no config. | +| Within-frame round-robin send order over blocks (`D :1295-1360`) | **Port** (rewrite against CultLib types) | Turns a burst into one loss per block. It is policy, not math. | +| `pad_audio_codec_frame` 2-byte BE length prefix (`D media_packetizer.rs:674-686`) | **Port** into the Opus cut's framing (`opus-padded-v1`) | Constant shard size for variable codec frames. Matches the `aac-adts-padded-v1` precedent (teardown-map L477-479). | +| Datagram-fit tests (`D :3065`, `production_aac_audio_fec_shards_fit_one_rudp_datagram`) | **Port as behavioural tests** at the CultLib codec and in Muninn | They pin invariant 6. | +| Exhaustive erasure test (`D :4919`) | **Port**, generalised to every shipped `(k, m)` | Pins invariant 4. | +| `MuninnKeyframeRequestGate` (`D main.rs:2864-2884`, cooldown 500 ms at `:102`) | **Port** (Cut 6) | Small and correct: an edge with a cooldown. | +| `MuninnVideoBitrateController` (`D :2439-2512`) | **Rewrite** (Cut 6, only if Q6 = a) | Its ceiling halving assumes 50% FEC overhead, and its doc and code disagree. It must key on the chosen parity rate, and aggregate across hub receivers, which the donor predates. | +| `native/muninn-video-encoder` (C++, 265 lines) plus build script | **Held at the donor tag, pending Q6** | A new native target with FFmpeg dev libraries on Raven, built by an Idunn `rust-host` runner whose vocabulary is `cargo`. That is a large liability, bought only if IDR and bitrate adaptation earn it. | +| Bounded `sync_channel` plus per-frame groups, capacities 256/512 (`D main.rs:85-87, 2023-2028, 2356-2369`) | **Port the shape**, rewrite against the hub loop (Cut 2) | Exactly invariant 2. | +| `cultnet-impair` (696 lines, seeded loss/burst/jitter/reorder/dup/stall, CSV) | **Port to CultLib** `packages/cultnet-rs/examples/` (Cut 3b) | It is a CultNet transport tool. `media_delivery_probe.rs` already sits there and expects it (its header, `C examples/media_delivery_probe.rs:5`). | +| HID edges, epochs and acks in Muninn + Sleipnir + vendored `rudp.rs` | **Park** until Q1 | Purpose unknown, and it breaks invariant 9. | +| Vendored `rudp.rs` ACK changes (`9af2edb` `direct_ack_state`, ACK reliable duplicates) | **Drop** | CultLib evolved separately (`75c1807` acknowledges retransmits across horizons; `47b9fc4` changes reader semantics). Anything still missing is a CultLib finding with its own proof, not a port. | +| `muninn.*` v4/v1 parity schemas | **Drop** | Superseded by `gamecult.*` in CultLib. No live reader. | + +Recommend Self tags the donor `parked/muninn-bounded-realtime-send` at `80adfd3` +before anything cites it again. This is the parked-not-dead pattern: the branch +is untracked per the morning file item 11. + +--- + +## Where FEC lives: owner decision + +**Owner: CultLib `cultnet-rs`, a new `media_fec.rs` module beside +`media_stream_wire.rs`.** It holds pure functions and no I/O. + +- **Not Muninn.** The receiver needs the decoder, so a codec in Muninn is either + duplicated in Ratatoskr or missing there. The first reproduces the Mimir split + (invariant 5). The second reproduces today's audio situation. +- **Not CultNet RUDP (transport FEC).** + - Transport FEC would group datagrams by send time, not by frame and + deadline. A block spanning two frames delays the first frame's recovery + past its deadline. + - It would also sit beside the frame-level NACK repair that Muninn and + Ratatoskr already run through `gamecult.media_receiver_feedback`, giving + two recovery authorities for one loss. + - The media plane's rule "a media payload fits one datagram" (invariant 6) + removes the one advantage transport FEC would have, which is protecting + fragments. + - The transport stays semantics-free (invariant 9). +- **Not CultMesh.** CultMesh carries state and discovery documents through Odin, + the advertisement and the request. Media records are CultNet wire records on a + live session and are never stored. FEC has no document to live in. +- **Not a new crate.** Authority separation does not buy a package. The media + plane is two files in `cultnet-rs` today, and every consumer (Muninn, + Ratatoskr, StreamPixels' vendored copy) already links it. + +What the module owns: +- the scheme id; +- `protect(frame_records, policy) -> send-ordered wire records` for video; +- `protect_audio(block) -> parity records`; +- `recover(block shards) -> Result`. + +What it does **not** own: +- the `(k, m)` choice, which is policy and belongs to the producer (Q8); +- when to give up, which is the receiver's deadline (invariant 1); +- sockets. + +--- + +## Identity, lifecycle and authority (0b) + +| Kind | What names it | What happens to it over time | Who decides | +|---|---|---|---| +| Video parity shard `gamecult.media_video_parity_shard.v3` | `(stream_id, session_id, frame_id, block_index, parity_index)`; the key extends today's (`C media_stream_wire.rs:92-110`) | Emitted with its frame's group, and dropped with the group at the deadline. Never repaired, never cached for repair. v2 is **deleted**, not kept beside it. | Producer emits. CultLib codec defines the bytes. Receiver consumes until the frame deadline. | +| Audio parity shard `gamecult.media_audio_parity_shard.v1` | `(stream_id, session_id, base_packet_id, parity_index)` | Emitted after its k-th data packet. It expires with the block's latest deadline. | Same. | +| FEC scheme id (e.g. `rs-gf256-v1`) | A string on each parity record | Changes only with a new schema version. A KAT pins it. | CultLib. | +| `(k, m)` policy | Carried per parity record (`block_data_count`, `parity_count`) | Fixed per stream in the first cut. Adaptive only if Q8 rules so. | Producer (Muninn). | +| Latency budget | `gamecult.media_stream_request.v1.latency_budget_ms` (key 11) | Fixed for a request. A new request restarts the child (teardown-map L533). | **Consumer** asks. Producer honours it, or refuses in `detail`. Default per Q7. | +| Keyframe request | `requested_keyframe` edge on feedback | Counted per receiver. It triggers at most one IDR per cooldown. | Receiver asserts. Producer's gate decides actuation (Cut 6). | +| Encoder bitrate (live) | Process-local, no record | Adjusted within `[floor, ceiling]`. Reported in telemetry. | Producer's controller (Cut 6, Q6). | +| HID edge | Unknown until Q1 | — | — | + +--- + +## Cut 0: correct the Muninn maps against git (docs only) + +Repo Muninn, `main`. Hands, doc-only. Nothing is deleted from history. Superseded +claims are marked as history in place and not left as two live designs. + +Corrections to `docs/teardown-map.md` @`cee7b9c`: + +| Line | Says | Git says | +|---|---|---| +| 1-3 | "(pre-rebuild)", dated 09-09, body at `Odin\crates\muninn-daemon` | Live repo `GameCult/Muninn`. `main.rs` is 15,134 lines and `media_packetizer.rs` 2,633. | +| 24 | CultLib pin `c13b6ba0` | `c2a9a6e` (`Cargo.toml:21-23`) | +| 50, 65 | "19 muninn.* schemas… in odin-core", "20 symbols" | The four media schemas moved to CultLib (`gamecult.*`). 21 odin-core symbols (`main.rs:27-37`). | +| 450 | Ratatoskr "Pinned to CultLib `d1a9eda`" | `c2a9a6e` (Ratatoskr `Cargo.toml:16-18`) | +| 463-465 | "Muninn now holds only the producer half" | `AudioPacketBuffer` and the whole-stream helpers remain (B9). Cut 1 makes the sentence true. | +| 611 | CultLib `main` `05e0925` | Contract unchanged since `c2a9a6e`. `main` is `069ecc3`. | +| 615-642 | "The one thing blocking a clean Muninn build… uncommitted `[patch]`… `Cargo.lock` untracked" | Resolved (L684-686). `Cargo.lock` is tracked (`60ed6b2`). Mark as history. **Add:** odin-core comes from `3e96c6c`, which is reachable only through the attic tag (B11). | +| 621-626 | 23 symbols, 7 Odin's | 21 symbols, 4 Odin's (B11) | +| 656-659 | "Not yet exercised live: Raven runs a pre-b679fc2 Muninn" | Contradicted by L536-603. Both legs were proven 2026-09-10/11 on `bc43e1b`+. | +| 666-668 | "the sender turns every new keyframe request into an IDR" | False. `main.rs:3036-3048` logs only (B4). | + +Corrections to `docs/muninn-media-streaming.md` @`cee7b9c`: + +| Line | Says | Code says | +|---|---|---| +| 240 | preset `p1` | `p5` (`main.rs:10279`) | +| 249 | chunks `480` bytes | `848` (`main.rs:81`) | +| 258-259 | resend `5` ms inside a `75` ms expiry | `30` ms (`main.rs:94`). Expiry is the latency budget, default 2,000 ms (`main.rs:95`). | + +Verification: `git diff --stat` shows only the two docs. Soul checks each row +against `git show cee7b9c:`. Ledger: ±0 code. + +--- + +## Cut 1: subtract the receiver residue from the producer + +Repo Muninn, `main`. This is a subtraction cut, kept separate from behaviour +cuts. No pin change. + +**Deletes first** (`media_packetizer.rs` @`cee7b9c`): +- `AudioPacketBuffer` plus its impl, `:847-987`, and its 5 tests + (`audio_packet_buffer_*`, around `:1820-1935`); +- `VideoAnnexBStreamPacketizeOptions` `:162-173`, + `VideoAnnexBStreamWireOptions` `:175-180`, `packetize_video_annex_b_stream` + `:756-805`, `encode_video_annex_b_stream_wire_records` `:1017-1029` and + `video_annex_b_stream_send_payloads` `:1031-1036`; +- `encode_record_payload` / `decode_record_payload` `:1080-1090`; +- empty-line runs left by earlier cuts (`:230-240`, `:403-406`, `:552-556`, + `:1091-1099`). + +**Keeps and moves.** These tests prove real packetizer behaviour and are +**re-homed onto `VideoAnnexBStreamSendState`**, not deleted: +- `packetizes_annex_b_stream_into_timed_video_records` (`:1533`); +- `packetizes_non_reference_h264_p_frames_without_dependency` (`:1570`); +- `rejects_negative_annex_b_stream_deadline_delay` (`:1602`); +- `media_wire_batches_annex_b_video_records` / `media_wire_encodes_annex_b_stream_for_sender` / `media_send_payloads_pin_video_to_media_channel` (`:1992, 2033, 2078`); +- `main.rs:12340-12420`, the two fragment-limit tests. + +`feedback_payload_decodes_legacy_record_without_chunk_keys` (`:2467`) proves a +CultLib `default` key. Delete it here if `C tests/media_stream_contracts.rs` +already pins key 10's default. Otherwise move it there. Hands checks which +applies and reports. + +**Adds:** none. + +**Verification:** +- `cargo build --release -p muninn-daemon` and + `cargo test -p muninn-daemon --bin muninn` on Yggdrasil via ygg-verify. +- A negative grep: `rg "AudioPacketBuffer|packetize_video_annex_b_stream\b|decode_record_payload" crates/` + returns nothing. +- `cargo mutants --in-diff` scoped to `media_packetizer.rs`. + +**Ledger:** about −330 lines, no new surface. + +--- + +## Cut 2: bounded sender, one deadline owner, and a drivable seam + +Repo Muninn, `main`. No pin change. Cut 5's parity rides on it. + +The latency default waits on Q7. The rest does not. + +**Authority map.** +- **Owner:** a new `MediaSendCore` in Muninn. It holds the queues, the hub, the + feedback intake, the repair cache and budget, and the progress stats. +- **Inputs:** `Read` sources for encoded video and audio, a `MediaSendPolicy` + derived **only** from the request (`latency_budget_ms`, `video_bitrate_kbps`, + `media_packet_bytes`), a `CultNetRudpServerHub`, and a clock. +- **Outputs:** payloads on the hub, repairs to the asking receiver, stats. +- **Derived state:** + - the queue deadline, repair eligibility and audio expiry derive from + `policy.latency_budget`; + - `MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS` is **no longer an owner**. + It dies, and the advertisement's `default_latency_budget_ms` takes the + Q7 constant. +- **Forbidden writers:** + - `Instant::now()` as a repair's `queued_at` (`main.rs:3129`). A repair + inherits its frame's deadline. + - Per-payload expiry. Expiry is per group. + - `VideoAnnexBStreamSendState` erroring on overflow + (`media_packetizer.rs:296-306`). Overflow drops the oldest complete access + unit and counts it. +- **Shared paths:** live sends, repairs and the harness all go through + `MediaSendCore`. `run_rudp_mux_once` keeps process spawning and publishing, + and nothing else. +- **Deletion line:** `mpsc::channel` at `main.rs:2427`, the unbounded + `PendingMuninnMediaSendQueues` (`:2701-2731`), per-payload expiry (`:2505-2532`), + and the 1 ms sleep spin (`:2981`), which becomes a bounded poll of resends + that stops at the group deadline. + +**Adds (types and rules only):** +- `QueuedMediaGroup { kind, deadline: Instant, payloads }`. One access unit with + its parity, or one audio packet. +- `mpsc::sync_channel` with a small bound, as in the donor (`capacity 1` of + groups). +- Per-kind group caps: audio 256, video 512 in the donor. Cap them in **groups**, + and name the byte ceiling they imply. +- Drop-oldest-group on cap, counted as `groups_dropped_{audio,video}`. +- Audio before video, as today (`:2705-2716`). + +**Harness seam (the reason B10 matters).** A `#[cfg(test)]` driver feeds +`MediaSendCore` from a committed Annex B fixture. It needs: +- a short H.264 clip, generated once and committed with its ffmpeg command + recorded beside it (provenance); +- a PCM ramp. + +It serves over a loopback hub, through a seeded **drop relay thread** (a UDP +relay between two sockets that drops by a seeded schedule), to an in-test +`CultNetRudpSocketTransportConnection` client. The client counts received and +expired groups. It needs no ffmpeg, PowerShell or GPU, so it runs on Yggdrasil. + +**Verification (rules each test pins):** +- Push faster than the hub drains: resident queue memory stays `≤` the stated + ceiling, and the stream is not restarted. This kills a mutant that removes + the cap or turns it into `usize::MAX`. +- Expire mid-frame: either every payload of a frame group is sent or none is. + Assert on the relay's captured datagrams, not on stats. The observation sits + at the wire (invariant 2). +- A repair asked for after its frame's deadline is not sent. A repair asked + for before it is sent. Probe at `deadline − ε` and `deadline + ε`, with ε + under 5 ms, so that a mutant that re-derives the deadline from `now` is + caught. **At least one mutant must be a function of the budget**, a clamp or + an offset (SKILL: "weakest thing that would still pass"). +- The request's `latency_budget_ms` reaches the queue deadline exactly. Use a + dev-only seam that records the computed `Duration` and assert exact equality + at two budget values. Both must differ from the default, and both must be + unequal to each other. +- `cargo mutants --in-diff`. Survivors are triaged by name. + +**Only live proves:** that dropping whole groups under Raven's CPU pressure (93%, +teardown-map L603) keeps the stream watchable. That needs a Raven run after +Idunn B3 (see Sequencing). + +**Ledger:** roughly −150 in `run_rudp_mux_once` and +250 for `MediaSendCore` +plus the harness. About +100 net. It buys invariant 2 and the only test path +into the sender. + +--- + +## Cut 3: the CultLib media FEC codec and records + +Repo CultLib, a branch from `main`. Tag and publish per CultLib's release +rules. A release is a cut: Soul passes before the tag (SKILL step 5). Blocked on +Q3, Q4 and Q8. Q2 blocks consumption, not this cut. + +**3a. Deletes first:** +- `GameCultMediaVideoParityShardRecord` v2 (`C media_stream_contracts.rs:466-517`), + its schema const (`:46`), `validate_video_parity_record` + (`C media_stream_wire.rs:323-388`), the `VideoParity` wire arm's v2 decode + (`:98-103`, `:183-186`), and the v2 tests in `tests/media_stream_wire.rs` + and `tests/media_stream_contracts.rs`. +- If Q4 = yes: `GAMECULT_MEDIA_AUDIO_CHANNEL` (`C media_stream_wire.rs:41-44`), + the `"audio"` channel profile (`C rudp.rs:2218-2228`), `"audio"` in the + `channel_send_options` arm (`:2394`), and the test rows + (`tests/cultnet.rs:436, 3023-3030`). + +**Adds:** +- `gamecult.media_video_parity_shard.v3`. It carries the frame framing fields as + v2 does, plus `fec_scheme: String`, `block_index`, `block_count`, + `block_data_start`, `block_data_count` (k), `parity_index`, `parity_count` + (m), `shard_payload_bytes`, `last_chunk_payload_bytes` and `payload` (bin). + The donor's v4 field list (`B12`) plus the scheme id is the right shape. +- `gamecult.media_audio_parity_shard.v1`. Fields: `fec_scheme`, + `base_packet_id`, `base_pts_ticks`, `packet_duration_ticks`, `timebase_*`, + `deadline_ticks` (the maximum in the block), `data_shard_count`, + `parity_index`, `parity_shard_count`, `shard_payload_bytes` and `payload`. + This is the donor's v1 shape plus the scheme id. +- `GameCultMediaWireRecord::AudioParity`, with its validation, record key + (`B` identity table) and decode arm. +- `media_fec.rs`: + - `MediaFecPolicy { max_block_data: u16, parity_ratio / fixed m }`; + - `protect_video_frame(&[VideoAccessUnitRecord], &policy) -> Vec` + in **send order**, round-robin over blocks (donor `4e2abee`); + - `protect_audio_block(&[AudioPacketRecord; k]) -> Vec`; + - `recover_video_block` / `recover_audio_block(present) -> Result, BeyondRepair>`. + - Backing: `reed-solomon-erasure = "6"` (Q3), default features, no + `simd-accel` C build. +- Update the module doc `C media_stream_contracts.rs:34-41`: audio now has + parity. + +**Rules that must die under their own mutation:** +- Every `≤ m` erasure pattern recovers exactly, for each shipped `(k, m)` (at + least 4+2 and 8+4, and the policy's maximum block). This is exhaustive; the + probe shows it is cheap. +- `m+1` erasures return `BeyondRepair`. They never return `Ok` with wrong bytes. +- KAT: fixed 4×37-byte input, then the exact parity bytes, committed as hex. + This kills any change of matrix, polynomial or shard order. +- Every data and parity wire record at the policy's maximum shard size is + `≤ 1431` bytes encoded (invariant 6). The bound is a named constant, not a + literal copied from Muninn. +- Blocks never span frames. A `protect_video_frame` call with mixed `frame_id` + errors. +- Send order: within any window of `block_count` consecutive records, no two + come from one block. That is the burst property. Assert it on the output + sequence, not on a helper. +- Parity carries its frame's `deadline_ticks` unchanged. + +**3b. Port `cultnet-impair`** from the donor +(`D crates/cultnet-impair/src/main.rs`, 696 lines, and +`tests/realtime-impairment/*.toml`) to +`packages/cultnet-rs/examples/cultnet_impair.rs` plus profiles under +`packages/cultnet-rs/tests/impairment/`. This is a separate commit. +- Keep the donor's six deterministic policy tests. +- Drop anything that imports the donor's vendored transport. +- Add a **seeded loss matrix** as a codec test, with no sockets: data plus + parity through a seeded iid/burst erasure schedule, then `recover`, then a + recovered-frame ratio per cell. `clean`, `loss-1/3/5pct`, `burst-4/8` are the + donor's profiles. Commit the table the test prints as the evidence record. + Assert only the guarantee (for example, `burst-4` against round-robin + `k=8, m=4`: every block with ≤ m losses recovers), not a tuned ratio. + +**Runtime parity.** The media plane is Rust-only today. `grep` finds no +`media_video_parity_shard` outside `packages/cultnet-rs`. Record that the scheme +id names the construction, so a future C# or TypeScript decoder has a KAT to +meet. `reed-solomon-erasure` states it is compatible with Backblaze JavaReedSolomon +and klauspost/reedsolomon. **This claim is not probed**; the KAT is the contract, +not the claim. + +**Verification:** +- `cd packages/cultnet-rs && cargo test` +- `cargo mutants --in-diff` on Yggdrasil. +- Negative grep: `rg "media_video_parity_shard.v2|GAMECULT_MEDIA_AUDIO_CHANNEL" packages/` + is empty. +- A **StreamPixels check**: its vendored CultLib carries `media_stream_*` + (`StreamPixels/vendor/CultLib/...`). Confirm that StreamPixels compiles + nothing that names the deleted symbols before the tag. StreamPixels is on the + ship path, so this is read-only; do not bump it. + +**Ledger:** +- deletes: about −180 (v2 record, validator, tests, audio channel); +- adds: +140 (records and validation), +200 (`media_fec.rs` with tests), + +700 (impair port, an example rather than library surface); +- one new dependency, `reed-solomon-erasure`, which pulls `lru 0.7` and + `parking_lot 0.11` (seen in the probe build). + +Net library surface is about +160. The impair tool is tooling. + +--- + +## Cut 4: Ratatoskr decodes with the CultLib codec + +Repo Ratatoskr, `main`. It lands **before** Cut 5, so that the receiver +understands v3 before the producer emits it. + +**Deletes first:** +- the XOR stripe recovery: `ParityShard` (`R video.rs:180-186`), `repair()` + `:224-269`, the stripe doc `:1-8`, and the stripe tests `:638-683`; +- the `insert_parity` v2 path `:346-374`. + +**Keeps:** the assembler's lifecycle: admit, expire, evict, repair cadence, and +the keyframe wait. + +**Adds:** +- `insert_parity` for v3. It calls `recover_video_block` when a block has + `≥ k` shards. +- An audio hole recoverer: + - hold a missing packet only until its block can recover **or** its deadline + passes, whichever comes first, bounded by the request's budget + (invariant 1); + - then recover, or report a hole; + - "Stamp live audio with the receive clock" (`d11f533`) stays the playout + owner. +- Stats counted from observation: `parity_recovered_chunks`, + `parity_beyond_repair_blocks`, `audio_recovered_packets` and `audio_holes`. + +**Rules:** +- A v3 block missing `≤ m` shards completes without a repair request. Assert + that no feedback record names its chunks. +- A block missing `m+1` shards falls through to the repair path and names only + the unrecovered chunks. +- An audio packet recovered by parity is delivered once, with its original + `packet_id` and `pts`. +- An audio hole past its deadline is reported and never delivered late. +- `max_frame_age` derives from the request's `latency_budget_ms`, not + `Duration::from_millis(250)` (`R video.rs:101`). The same two-value exact + check as Cut 2. + +**Verification:** +- Bump the CultLib pin to Cut 3's tag. +- `cargo test -p ratatoskr-core` and the C checks per Ratatoskr's README on + Yggdrasil. +- `cargo mutants --in-diff`. + +**Only live proves:** that OBS renders through recovered frames, and that audio +recovery does not add audible delay. That needs the plugin on Starfire, which +is operator-installed. + +**Ledger:** −90 XOR, +150 (v3 intake and audio recoverer). About +60. + +--- + +## Cut 5: Muninn emits CultLib parity, and audio goes lossy + +Repo Muninn, `main`. It is gated by Q2 (the pin diamond) and Q5 (after Opus, or +over PCM). + +**Deletes first:** +- `MUNINN_VIDEO_PARITY_STRIPES`, `build_video_parity_shards` and + `video_wire_records_with_parity` (`M media_packetizer.rs:625-754`), and + their tests; +- `audio_packet_send_payload`'s audio-channel pin (`:1055-1063`) and + `MUNINN_AUDIO_RUDP_CHANNEL` (`:15-16`) if Q4 = yes; +- the `media_send_payload_pins_audio_to_media_channel` test's assertion + (`:2252-2280`), which is rewritten to its new truth. + +**Adds:** +- The video send state calls `cultnet_rs::protect_video_frame(records, &policy)`. + Each output becomes one `QueuedMediaGroup` (Cut 2). +- The audio send state accumulates `k` packets and emits parity after the + k-th. This is the donor's `fec_block` pattern (`D media_packetizer.rs:618-632`, `:812-826`), + against CultLib types. +- A partial block at stream end or restart is emitted without parity and + counted. It is not padded with invented packets. +- Audio on the `media` channel, lossy. +- The advertisement names the FEC scheme it emits, only if Ratatoskr needs to + know before the first record arrives. The default is not to add a field: + parity is self-describing. +- `MUNINN_RUDP_MEDIA_PROFILE_ID` (`main.rs:76`) bumps to `…lan.v2`, because the + profile's wire behaviour changed. + +**Rules:** +- End to end through Cut 2's drop relay, with the `loss-3pct` seed: + - every frame whose blocks each lost `≤ m` shards is decodable at the client + with **zero** repair requests; + - audio packets lost `≤ m` per block are delivered. + - The in-test client decodes with CultLib's `recover_*`, so this does not need + Ratatoskr as a dependency. +- The wire contains no `v2` parity and no `audio`-channel frames. Assert on the + relay's captured datagrams. + +**Harness run on Yggdrasil (the loss-injection acceptance):** +- Cut 2's test driver with the Cut 3b profiles matrix: + `clean`, `loss-1pct`, `loss-3pct`, `loss-5pct`, `burst-4`, `burst-8`, + `reorder`, `duplicate`. +- Report per cell: + - frames complete without repair; + - frames complete via repair; + - frames expired; + - audio recovered and holes; + - wire overhead, measured as bytes on the relay divided by encoded payload + bytes. +- Run it once at Muninn `cee7b9c`-equivalent behaviour (XOR, reliable audio) + and once after, and commit both tables. **The before-and-after table is the + evidence that the campaign bought something.** + +**Only live proves:** +- that NVENC's real frame-size distribution, including IDR spikes of hundreds of + chunks, fits the chosen `(k, m)` without the overhead pushing past the link; +- that the Raven → Starfire LAN and the mesh-hairpin path (28 Mbps, + teardown-map L292) both hold. + +Protocol: the operator runs the stream for N minutes on each path with the +receive probe's stats captured. Parity overhead against the 28 Mbps hairpin is +the number that decides Q8. + +**Ledger:** −130 XOR, +60 of calls into CultLib. **Net about −70.** + +--- + +## Cut 6: encoder control, IDR on request and bitrate adaptation + +Mapped only as far as Q6 allows. It is not dispatchable until Q6 is ruled. + +If Q6 = (a), port the donor encoder: +- **Deletes first:** `record_receiver_keyframe_pressure` (`M main.rs:3036-3048`). + The ffmpeg CLI video child (`rudp_video_ffmpeg_args`, `:10343-10421`) is + retired **only after** the native encoder is installed by the Idunn recipe. + Keep one path, not two: the donor kept both behind `video_encoder_path.is_some()` + (`D main.rs:1942`), which is the split to avoid. +- **Adds:** + - `native/muninn-video-encoder` from the donor, plus a recipe build step in + `deployment/idunn/raven-muninn.toml`. **The Idunn recipe is being edited by + the route-continuity campaign right now; see Sequencing.** + - An `EncoderControl` port in `MediaSendCore` (Cut 2's seam). + - The ported `MuninnKeyframeRequestGate`. + - The rewritten `BitrateController`: + - its ceiling is `configured × 1/(1+parity_ratio)` from Cut 5's policy, not + `/2`; + - it aggregates damage across all hub receivers: any receiver's damage backs + off, which is recorded as a known limit for the single-encoder, + many-viewer case; + - its recovery step and interval are named constants whose values the + harness picks. +- **Rules:** + - One invalidation edge gives exactly one `IDR` command per cooldown. Count + the bytes written to the control port. + - Damage inside a sample window gives exactly one multiplicative back-off. + - Stable for the interval gives exactly one additive step, never above the + ceiling. + - Assert on the command bytes, as the donor did (`D main.rs:12756-12801`). +- **Only live proves:** that NVENC honours a forced IDR at the next frame and + reconfigures bitrate without a restart. The donor recorded both on 2026-07-17, + but on a pre-extraction body. + +If Q6 = (b) or (c), Cut 6 is a one-commit deletion: `record_receiver_keyframe_pressure`, +and `requested_keyframes` stays as telemetry only. Retire the "IDR on request" +and "bitrate adaptation" goals from this campaign with the ruling recorded. + +--- + +## HID edge: not mapped (Q1) + +The donor's HID work spans Muninn, Sleipnir (in Odin) and odin-core's HID +record, and it hardcodes channel names into the transport (B13). Its purpose +decides everything: +- whether edges are needed or snapshots suffice; +- whether the channel is reliable, or lossy with replay; +- whether this belongs in Muninn at all, or in the Sleipnir/Mimir input path. + +Nothing is specified until Q1 is answered. When it is: +- the record moves with named-cut 1 (odin-core → Muninn) **first**, so the edge + record is born in its owner; +- delivery uses CultLib's profile-owned channel delivery, not hardcoded names. + +--- + +## Sequencing + +Against Muninn's named next cuts (teardown-map L644-668, L700-705) and the +StreamPixels ship: + +1. **Now, no contention:** Cut 0 and Cut 1 (Muninn docs and subtraction). They + touch neither the Idunn recipe nor any pin. +2. **Muninn named cut 3, retire `--idunn-rudp-health`:** + - it can run before or after Cut 1 on the same `main.rs`, serially, never + in parallel; + - it removes `IdunnDaemonHealthRecord`, one of the four Odin symbols (B11), + which shrinks the diamond; + - the three scripts that still pass the flag (`scripts/health-*.ps1`) go + with it. +3. **Cut 2 (bounded sender).** Muninn only, no pin. The latency default waits on + Q7. +4. **Muninn named cut 1, move 16 records out of odin-core:** + - it must land **before** any HID work (Q1); + - it is independent of FEC, because the media records are already in CultLib; + - it does not by itself unblock a CultLib bump, since the Eve records and + `OdinDocuments` remain (Q2). +5. **Muninn named cut 2, Opus:** + - it is the prerequisite for Cut 5's audio half if Q5 = after (B2); + - the video half of Cut 5 does not wait for it. +6. **Cut 3 (CultLib).** + - It runs in its own CultLib worktree. + - It is independent of Muninn's Hands, and can run in parallel with + steps 1-5 in a different repo and worktree. + - Soul passes before the tag. +7. **Pin gate (Q2).** An odin-core revision at Cut 3's CultLib pin, or a severed + odin-core. +8. **Cut 4 (Ratatoskr), then Cut 5 (Muninn).** Bump the pins in lockstep. +9. **Cut 6**, only if Q6 = (a), and only after the Cut 5 harness table shows + visible damage that FEC and repair do not cover. + +**StreamPixels ship:** +- Its critical path is Idunn B3, then merge `route/s3-c2`, back up `control.cc`, + the read-only check, and `idunn up` (morning file item 3). +- This campaign stays off it: + - no Odin `main` pin change (Odin `main` pins `a8aedda` for StreamPixels' + RUDP, `379b826`); + - no Idunn edits; + - no StreamPixels vendored-CultLib bump. +- Cut 3's tag is read-only to StreamPixels until StreamPixels chooses to move. + +**Live verification on Raven waits for two Idunn events:** +- B3 lands; +- `raven-muninn`'s recipe gains its Odin declaration (Idunn `route-continuity-cut.md:32-35`: + "`raven-muninn` and Heimdall both publish to Odin, so their recipes declare + it"). + +Before that, `idunn up raven-muninn` may be refused at admission. **Muninn Hands +must not edit `deployment/idunn/raven-muninn.toml`** while that declaration is in +flight. Cut 6(a)'s recipe step is the only cut here that touches it, and it goes +last. + +**Yggdrasil load.** Every harness and mutation run here goes through ygg-verify +(5 slots, shared). While StreamPixels' verification is running, cap this +campaign at one job at a time. All five slots were busy during this pass. + +--- + +## Operator questions + +One fork each, with a recommendation. Nothing downstream of an open question +gets written. + +**Q1. What is the loss-tolerant HID edge for?** +- Context: + - Today Muninn sends whole controller snapshots (`buttons` as a held set) + to Sleipnir. + - A press and release between two samples, or lost with its packet, never + reaches the virtual pad. + - The donor fixes that with ordered, acknowledged edges and epochs, across + Muninn, Sleipnir (Odin) and a patched transport. +- Candidate purposes, which lead to different machines: + - (a) **remote play**: a viewer's controller drives a game on another host, + over LAN or mesh, so quick taps must survive loss; + - (b) **same-LAN couch input**, where loss is rare and snapshots at a high + rate suffice; + - (c) input as **evidence** for Mimir or tracking, not actuation. +- Which hosts are the source and the sink, and over which path? +- Recommendation: answer this before anything is specified. Park the donor's + HID commits at the parked tag. If (a), the edge record is born in Muninn after + named-cut 1, and delivery uses CultLib's profile-owned channels. + +**Q2. How does Muninn get a CultLib pin with the FEC codec in it?** +- Context: + - Muninn's `odin-core` comes from Odin `3e96c6c`, reachable only through the + tag `attic/claude-cultlib-pin-c2a9a6e`. That commit's only change was to bump + odin-core's CultLib pin. + - odin-core's records are `DatabaseEntry`, so a Muninn CultLib bump without a + matching odin-core gives two `cultcache-rs` copies and a type mismatch. + - Odin `main` pins an **older** CultLib (`a8aedda`) for StreamPixels, and must + not move during the ship. +- Options: + - (a) another single-purpose attic-tagged Odin commit that bumps odin-core to + Cut 3's pin (the `3e96c6c` precedent). Cheap, repeated per CultLib bump, + and invisible on any branch; + - (b) sever Muninn from odin-core first: named-cut 1, retire idunn-rudp-health, + and rehome the Eve records and `OdinDocuments` registration. This delays FEC + by those cuts; + - (c) keep the codec local to Muninn and Ratatoskr. **Rejected**: two codecs + (invariant 5). +- Recommendation: (a) for this campaign, with (b) continuing as Muninn's own + cuts. Record that each (a) is a debt paid again on every CultLib bump. Also + consider a `parked/` or `pins/` tag name instead of `attic/`, so the tag reads + as live. + +**Q3. Implement the erasure code, or depend on `reed-solomon-erasure`?** +- Context: + - The donor's hand-written GF(256) has no multi-erasure video decoder and no + KAT. + - The crate was probed on Yggdrasil: exhaustive recovery at 4+2 and 8+4, any + shard length, about 11 µs per 8+4 block. It pulls `lru 0.7` and + `parking_lot 0.11`, and its last release is 2022. + - `reed-solomon-simd` is faster to encode but refuses odd shard sizes and + decodes in about 230 µs. +- Recommendation: depend on `reed-solomon-erasure` 6, without `simd-accel`, and + pin the bytes with a KAT so that the library, not our wire, is replaceable. + The fallback, if dependency age is disqualifying, is to port the donor + arithmetic plus a general Gaussian decoder (about 150 lines we own). + +**Q4. Delete the reliable `audio` channel and carry audio lossy with parity on +`media`?** +- Context: + - The channel was created on 2026-09-10 so audio could be reliable beside + lossy video. + - Its only purpose is reliability. Receivers dispatch by schema, not by + channel, so a lossy audio channel duplicates `media`. + - The teardown map's own fix direction (L256-261, L322-324) is audio lossy + with parity. +- Recommendation: yes. Delete it in CultLib Cut 3 (−15 lines of transport + special-casing), and move Muninn's audio in Cut 5. This reverses a recorded + decision, which is why it is asked and not defaulted. + +**Q5. Audio parity before Opus, or after?** +- Context: + - PCM packets are 3,840 bytes, which is 3 datagrams each (B2). Parity would + protect 3-fragment shards and cost about 1.5 Mbps at 4+2. + - Opus (Muninn's named cut 2, measured at 183 kbps) gives single-datagram + packets, and the donor's padded framing ports directly. +- Recommendation: after Opus. Cut 5 ships video parity immediately. The audio + half follows the Opus cut, and audio stays on today's reliable channel until + then, which is LAN-proven: 0 expired on 2026-09-11. + +**Q6. Encoder control: is IDR-on-request and bitrate adaptation worth a native +encoder?** +- Context: + - Recovery today is a quarter-second all-IDR GOP (`-g fps/4 -forced-idr 1`). + A lost reference freezes for at most 250 ms whether or not anyone asks. + - Asking for an IDR only helps if the GOP gets longer, which saves the bitrate + those IDRs cost. + - The ffmpeg CLI cannot take a live IDR or bitrate command. The donor solved + this with a 265-line C++ libavdevice/NVENC child, proven live on 2026-07-17 + on a pre-extraction body. +- Options: + - (a) port the native encoder, with an Idunn recipe step on Raven; + - (b) keep the CLI and the 250 ms GOP; no IDR request, no adaptation; + - (c) keep the CLI with NVENC `-intra-refresh 1` and a long GOP. This removes + the IDR spikes and bounds recovery by the refresh period, but still gives + no requested IDR and no bitrate adaptation. +- Recommendation: (b) now. Decide between (a) and (c) on Cut 5's harness table + and the live hairpin run. Build (a) only if the stream visibly fails where + bitrate adaptation would have helped. This is the one cut in the campaign that + buys a new native target. + +**Q7. What is the default latency budget?** +- Context: + - The producer defaults to 2,000 ms. The receiver gives up at 250 ms (the + July ledger's recovery budget). + - The request owns the budget (invariant 1), but Ratatoskr sends 0 and so + inherits the 2 s default. + - FEC recovers within one frame. NACK repair needs a few RTTs: under 1 ms on + LAN, about 75 ms on the mesh hairpin. +- Recommendation: 250 ms default in the advertisement, with both ends deriving + from the request. A consumer on a slow path asks for more. + +**Q8. Parity rate: fixed, or adaptive to observed loss?** +- Context: + - At 25-50% overhead, RS blocks cut iid frame failure by 2-3 orders of + magnitude compared with today's XOR (probe table). + - Overhead against the 28 Mbps hairpin at 12 Mbps video is significant. + - Adaptive needs new receiver-feedback fields (received, recovered and lost + chunk counts) and a controller. +- Recommendation: fixed in Cut 5, at `k ≤ 16`, `m = max(2, ⌈0.25k⌉)` for video + and 4+2 for audio, carried per record. Revisit with the live hairpin numbers. + Adaptive is a later cut with its own feedback-record extension. + +--- + +## Substrate missing (record, do not wait on it) + +- **No typed verify transaction.** Every probe went through the ygg-verify + stopgap, and one run queued behind 5 busy slots. This is Idunn's verify + campaign. +- **No machine-readable media-path map.** The ownership facts are spread across + `teardown-map.md` (with 10+ stale rows), a memory file (`media-path-ownership.md`) + and three repos. The staleness this pass found (B4, B9, L656) is the cost. +- **No synthetic media source anywhere on the path.** Every earlier + measurement needed Raven, a GPU and a game. Cut 2's seam is the first harness + that runs off Raven. + +## Appendix A: probe logs + +In this session's scratchpad: +- `donor-fec-tests.log` (9 pass); +- `muninn-media-tests.log` (78 pass); +- `rs-probe.log` and `rs-probe/` (the scratch crate, commit `656865b`); +- `ratatoskr-tests.log` (31 + 2 pass at `488b5b1`). From 2c120c96d79d2837e443e21f897ceaa6802fd990 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 13:47:40 +0200 Subject: [PATCH 10/44] Correct the Muninn maps against git (RR Cut 0) teardown-map.md: mark the extraction-era claims as history in place (pin, symbol counts, diamond, live-exercise note) and correct the false claim that the sender turns keyframe requests into an IDR. muninn-media-streaming.md: preset p5, 848-byte chunks, 30 ms resend inside the latency-budget expiry. Docs only. Co-Authored-By: Claude Sonnet 5 --- docs/muninn-media-streaming.md | 8 +++---- docs/teardown-map.md | 40 ++++++++++++++++++---------------- 2 files changed, 25 insertions(+), 23 deletions(-) diff --git a/docs/muninn-media-streaming.md b/docs/muninn-media-streaming.md index d3105ff..e2f411b 100644 --- a/docs/muninn-media-streaming.md +++ b/docs/muninn-media-streaming.md @@ -237,7 +237,7 @@ a temporary PCM/AAC compatibility bridge. Recommended first LAN profile: - Profile id: `muninn.rudp.low_latency_h264_lan.v1`. -- Video: H.264 NVENC, `p1`, ultra-low-latency tune, CBR high enough that LAN +- Video: H.264 NVENC, `p5` (`main.rs:10279`), ultra-low-latency tune, CBR high enough that LAN bandwidth is not the constraint, no B-frames, no lookahead, short GOP or intra-refresh, periodic IDR/keyframe on feedback pressure. - VBV: derive `bufsize` from roughly one frame of bitrate @@ -247,7 +247,7 @@ Recommended first LAN profile: temporary PCM/AAC bridge with separate packet identity and clock. - Transport: payload elementary access units as typed media records, never a muxed container as the unit of truth. -- Packet size: default typed media chunks are `480` bytes. That leaves headroom +- Packet size: default typed media chunks are `848` bytes (`main.rs:81`). That leaves headroom for CultNet/MessagePack/RUDP headers inside a normal Ethernet MTU so the OBS bridge does not depend on IP fragmentation or private RUDP fragment reassembly. The sender also sets CultNet RUDP `max_fragment_bytes` to `1431` @@ -255,8 +255,8 @@ Recommended first LAN profile: minus the five-byte `media` channel id), so oversized typed records fragment in CultNet deliberately instead of falling through to accidental IP fragmentation. -- Resend cadence: sender RUDP media resends are scheduled every `5` ms while - the packet is still inside the `75` ms reliable-expiry budget. +- Resend cadence: sender RUDP media resends are scheduled every `30` ms (`main.rs:94`) while + the packet is still inside its expiry, which is the request's latency budget (default `2,000` ms, `main.rs:95`). - Control: sender may adapt bitrate, keyframe cadence, chunk size, and playout budget from receiver feedback; the receiver must not silently stretch latency to preserve visual perfection. diff --git a/docs/teardown-map.md b/docs/teardown-map.md index 6890d45..5cd5629 100644 --- a/docs/teardown-map.md +++ b/docs/teardown-map.md @@ -1,6 +1,6 @@ -# Muninn Teardown Map (pre-rebuild) +# Muninn Teardown Map (history of the extraction) -Date: 2026-09-09. Working map for extracting Muninn from Odin into a dedicated repo. +Date: 2026-09-09. Working map for extracting Muninn from Odin into a dedicated repo. Muninn now lives in `GameCult/Muninn`; the body below was written at `Odin\crates\muninn-daemon` and is annotated in place where git has since contradicted it. Line counts at `e70db69`: `main.rs` 15,134 and `media_packetizer.rs` 2,633 under `crates/muninn-daemon/src/`. ## What Muninn is (operator, 2026-09-09) @@ -21,7 +21,7 @@ Independently confirmed in gamecult-ops `scripts/idunn/idunn-deployment-targets. - `src/media_packetizer.rs` 4,244 lines Sibling crates: `muninn-move-tracker` (308), `muninn-psmoveapi-tracker` (359). -CultLib pin: `c13b6ba0` (2026-09-05), 3 commits behind CultLib HEAD `d1a9edad`. +CultLib pin at the time of writing: `c13b6ba0` (2026-09-05), 3 commits behind CultLib HEAD `d1a9edad`. Live pin: `c2a9a6e` (`crates/muninn-daemon/Cargo.toml:18-20`). ## Authorities currently fused in main.rs @@ -47,7 +47,7 @@ Adding a sensor touches one file and zero core code. ## Schema ownership (decided) -19 `muninn.*` schemas, 38 declarations, currently in `odin-core/src/documents.rs`. +19 `muninn.*` schemas, 38 declarations, at the time of writing in `odin-core/src/documents.rs`. The four media schemas have since moved to CultLib as `gamecult.media_*`; the other `muninn.*` records are still imported from odin-core. Muninn's contracts owned by Odin = inversion. Move to CultLib, following `a539d4f` (Idunn/Odin authority contracts returned to CultLib) and `c13b6ba` (IdunnDaemonHealthTrustBindingRecord into cultnet-rs). @@ -62,7 +62,7 @@ obs_stream_catalog, quest_access, telemetry_surface, transport_profile. ## Coupling -Muninn -> odin-core: ONE import block, 20 symbols (main.rs). +Muninn -> odin-core: ONE import block, 20 symbols (main.rs) at the time of writing; 21 at `e70db69` (`main.rs:27-37`). odin-core / odin-daemon / sleipnir-daemon -> Muninn: NONE. Crate boundary cuts clean. @@ -447,7 +447,7 @@ cultnet-rs and cultnet-ts but not the receiver. Working: subscription over `cultnet-rs`, drained and handed across a C ABI. 9 Rust tests, 14 C checks (the C side loads the cdylib dynamically and verifies -the header's claims, rather than assuming them). Pinned to CultLib `d1a9eda`. +the header's claims, rather than assuming them). Pinned to CultLib `d1a9eda` at the time of writing; now `c2a9a6e` (Ratatoskr `crates/ratatoskr-core/Cargo.toml:16-18`). ### The next blocking piece @@ -460,8 +460,9 @@ The receiver-side reassembly code that was kept in `media_packetizer.rs` as the seed for Ratatoskr moved there on 2026-09-10 (`Ratatoskr` 2618184, `crates/ratatoskr-core/src/video.rs`) and was cut here (705 lines: frame assembly, the assembly set, reassembly, expired-frame feedback, their tests). -Muninn now holds only the producer half: packetize, XOR stripe parity, and the -feedback *builder* its sender tests exercise. The contract's erasure code is +Muninn holds the producer half (packetize, XOR stripe parity, the feedback +*builder* its sender tests exercise) and still carries receiver residue: `AudioPacketBuffer` +and the whole-stream Annex B helpers in `media_packetizer.rs`, which only tests call. The contract's erasure code is XOR stripes, one recovered chunk per stripe; the C++ receiver's GF(256) block solver reads fields the v2 record does not carry and stayed in Mimir. @@ -608,22 +609,24 @@ Three repos where there was one crate, and a contract neither of them owns. | Repo | Role | State | |---|---|---| -| CultLib `main` `05e0925` | the contract | media records, wire envelope, validation, channel delivery | +| CultLib `main` `05e0925` at the time of writing (media contract unchanged since `c2a9a6e`; `main` is now `069ecc3`) | the contract | media records, wire envelope, validation, channel delivery | | Muninn | producer | speaks the shared contract; blocked on one pin (below) | | Ratatoskr | consumer | decodes the envelope; builds clean, no conflicts | -### The one thing blocking a clean Muninn build +### The one thing blocking a clean Muninn build (history; resolved) + +Resolved 2026-09-11 (see the Raven section below): `Cargo.lock` is tracked (`60ed6b2`) and the pins are the build. The build resolves `odin-core` from Odin `3e96c6c`, which no Odin branch holds; only the tag `attic/claude-cultlib-pin-c2a9a6e` keeps it reachable. The text below is the state on 2026-09-10. `odin-core` pins CultLib `c13b6ba`; Muninn needs `05e0925`. Cargo resolves two `cultcache-rs` copies and `DatabaseEntry` from one is not `DatabaseEntry` from the other. -Muninn cannot resolve this alone: it uses 23 odin-core symbols, and while 16 are +Muninn cannot resolve this alone: it used 23 odin-core symbols (21 at `e70db69`), and while 16 are its own records that belong here (capture stream, command boundary, HID controller state, five Move records, OBS catalog, Quest access, telemetry -surface, transport profile), 7 are genuinely Odin's — `discover_provider_endpoints`, +surface, transport profile), 7 were genuinely Odin's — `discover_provider_endpoints`, `OdinDocuments`, `OdinEndpointQuery`, Eve advertisement and surface records, -`IdunnDaemonHealthRecord`. +`IdunnDaemonHealthRecord`. At `e70db69` four remain imported: `EveProviderAdvertisementRecord`, `EveSurfaceStateRecord`, `IdunnDaemonHealthRecord`, `OdinDocuments`. Muninn's two bodies were collapsed 2026-09-10 (Odin d41c744 dropped its workspace copy of the three crates and the actuator scripts). The Idunn @@ -653,10 +656,8 @@ one once the patch is gone. Muninn-specific `obs_stream_catalog` / `capture_stream_command` stay published beside them until nothing reads them. The old plugin's CLI shell-out and `.cc` snapshot are not ported. The connection direction was - inverted the same day (section above). **Not yet exercised live:** Raven - runs a pre-b679fc2 Muninn; the next Raven deploy ships this repository - (gamecult-ops rebound the targets 2026-09-10) and needs - `MUNINN_MEDIA_RUDP_ADVERTISE` set. + inverted the same day (section above). Exercised live 2026-09-10/11 on `bc43e1b` and later + (measurements below); the 2026-09-10 note that Raven ran a pre-b679fc2 Muninn is history. 3. **Opus.** Unblocked and measured at 16.8x. `-f aac` in the receiver becomes codec-driven; framing follows the `aac-adts-padded-v1` precedent (2-byte big-endian length prefix). @@ -664,8 +665,9 @@ one once the patch is gone. `feedback.rs`). The producer's repair cache and keyframe counter now have a live counterpart. `build_receiver_feedback` moved to CultLib (34c8ea7) and stopped implying a keyframe request from missing chunks (4160ab5): a repair - request is the alternative to one, and the sender turns every new keyframe - request into an IDR. + request is the alternative to one. The sender counts keyframe requests and logs them; + it does not force an IDR (`main.rs:3036-3048`). Recovery today is the fixed all-IDR GOP + of `framerate/4` frames. ### Deliberate breaks, both recorded as passing tests From f2a5db9eec293d6d2084ab8e8de1a001555f988f Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 13:50:38 +0200 Subject: [PATCH 11/44] Subtract receiver residue from the producer (RR Cut 1) Delete AudioPacketBuffer (receiver jitter buffer), the whole-stream Annex B helpers (packetize_video_annex_b_stream, its options structs and wire wrappers) and encode/decode_record_payload; only tests called them. Re-home the packetizer-behaviour tests onto VideoAnnexBStreamSendState. Drop the five audio_packet_buffer tests and the legacy-feedback decode test (CultLib pins key 10 default in receiver_feedback_decodes_records_written_before_its_last_field). Co-Authored-By: Claude Sonnet 5 --- crates/muninn-daemon/src/main.rs | 80 +- crates/muninn-daemon/src/media_packetizer.rs | 745 +++---------------- 2 files changed, 145 insertions(+), 680 deletions(-) diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index cba71f0..6263f07 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -12344,33 +12344,40 @@ mod tests { assert_eq!(muninn_rudp_video_gop_frames(&sixty_fps), 15); } + fn send_single_access_unit( + config: crate::media_packetizer::VideoAnnexBStreamSendConfig, + access_unit: &[u8], + ) -> Vec { + let mut sender = crate::media_packetizer::VideoAnnexBStreamSendState::new(config).unwrap(); + let mut payloads = sender.push("2026-06-18T00:00:00Z", access_unit).unwrap(); + payloads.extend(sender.finish("2026-06-18T00:00:00Z").unwrap()); + payloads + } + #[test] fn default_rudp_media_packet_size_keeps_late_typed_video_wire_under_udp_mtu() { let mut access_unit = Vec::new(); access_unit.extend_from_slice(&[0, 0, 0, 1, 0x65]); access_unit.resize(MUNINN_RUDP_MEDIA_PACKET_BYTES, 0x80); - let payloads = crate::media_packetizer::video_annex_b_stream_send_payloads( - crate::media_packetizer::VideoAnnexBStreamWireOptions { - packetize: crate::media_packetizer::VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "h264", - first_frame_id: 1_000_000, - first_pts_ticks: 3_000_000_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_800, - max_payload_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES, - }, - stored_at: "2026-06-18T00:00:00Z", - source_runtime_id: "muninn-test", - source_role: "media-test", + let payloads = send_single_access_unit( + crate::media_packetizer::VideoAnnexBStreamSendConfig { + stream_id: "muninn.raven.av.rudp".to_string(), + session_id: "session-1".to_string(), + codec: "h264".to_string(), + first_frame_id: 1_000_000, + first_pts_ticks: 3_000_000_000, + frame_duration_ticks: 3_000, + timebase_num: 1, + timebase_den: 90_000, + deadline_delay_ticks: 1_800, + max_payload_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES, + max_pending_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES * 2, + source_runtime_id: "muninn-test".to_string(), + source_role: "media-test".to_string(), }, &access_unit, - ) - .unwrap(); + ); assert_eq!(payloads.len(), 1); assert!( @@ -12392,27 +12399,24 @@ mod tests { access_unit.extend_from_slice(&[0, 0, 0, 1, 0x65]); access_unit.resize(MUNINN_RUDP_MEDIA_PACKET_BYTES * 64, 0x80); - let payloads = crate::media_packetizer::video_annex_b_stream_send_payloads( - crate::media_packetizer::VideoAnnexBStreamWireOptions { - packetize: crate::media_packetizer::VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "raven:2026-06-19T14-56-23Z:video", - codec: "h264", - first_frame_id: 1_000_000, - first_pts_ticks: 3_000_000_000, - frame_duration_ticks: 1_500, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_500, - max_payload_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES, - }, - stored_at: "2026-06-19T14:56:23Z", - source_runtime_id: "raven", - source_role: "muninn.rudp.video", + let payloads = send_single_access_unit( + crate::media_packetizer::VideoAnnexBStreamSendConfig { + stream_id: "muninn.raven.av.rudp".to_string(), + session_id: "raven:2026-06-19T14-56-23Z:video".to_string(), + codec: "h264".to_string(), + first_frame_id: 1_000_000, + first_pts_ticks: 3_000_000_000, + frame_duration_ticks: 1_500, + timebase_num: 1, + timebase_den: 90_000, + deadline_delay_ticks: 1_500, + max_payload_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES, + max_pending_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES * 65, + source_runtime_id: "raven".to_string(), + source_role: "muninn.rudp.video".to_string(), }, &access_unit, - ) - .unwrap(); + ); assert!(payloads.len() > 1); let largest = payloads diff --git a/crates/muninn-daemon/src/media_packetizer.rs b/crates/muninn-daemon/src/media_packetizer.rs index 25449b9..ee9aab7 100644 --- a/crates/muninn-daemon/src/media_packetizer.rs +++ b/crates/muninn-daemon/src/media_packetizer.rs @@ -159,26 +159,6 @@ pub struct VideoFramePacketizeOptions<'a> { pub max_payload_bytes: usize, } -pub struct VideoAnnexBStreamPacketizeOptions<'a> { - pub stream_id: &'a str, - pub session_id: &'a str, - pub codec: &'a str, - pub first_frame_id: u64, - pub first_pts_ticks: i64, - pub frame_duration_ticks: u32, - pub timebase_num: u32, - pub timebase_den: u32, - pub deadline_delay_ticks: i64, - pub max_payload_bytes: usize, -} - -pub struct VideoAnnexBStreamWireOptions<'a> { - pub packetize: VideoAnnexBStreamPacketizeOptions<'a>, - pub stored_at: &'a str, - pub source_runtime_id: &'a str, - pub source_role: &'a str, -} - pub struct VideoAnnexBStreamSendConfig { pub stream_id: String, pub session_id: String, @@ -214,7 +194,6 @@ pub struct AudioPacketWireOptions<'a> { pub source_role: &'a str, } - pub struct AudioPcmStreamSendConfig { pub stream_id: String, pub session_id: String, @@ -232,12 +211,6 @@ pub struct AudioPcmStreamSendConfig { pub source_role: String, } - - - - - - #[derive(Clone, Debug, PartialEq, Eq)] pub struct MuninnMediaSendPayload { pub channel_id: &'static str, @@ -402,8 +375,6 @@ impl VideoAnnexBStreamSendState { } } - - pub struct AudioPcmStreamSendState { config: AudioPcmStreamSendConfig, pending: Vec, @@ -552,9 +523,6 @@ impl AudioPcmStreamSendState { } } - - - pub fn packetize_video_access_unit( options: VideoFramePacketizeOptions<'_>, access_unit: &VideoAccessUnit, @@ -753,57 +721,6 @@ fn video_wire_records_with_parity( Ok(wire_records) } -pub fn packetize_video_annex_b_stream( - options: VideoAnnexBStreamPacketizeOptions<'_>, - input: &[u8], -) -> Result> { - if options.frame_duration_ticks == 0 { - return Err(anyhow!("frame_duration_ticks must be greater than zero")); - } - if options.deadline_delay_ticks < 0 { - return Err(anyhow!("deadline_delay_ticks must be non-negative")); - } - - let access_units = video_annex_b_access_units(options.codec, input)?; - let mut records = Vec::new(); - for (index, access_unit) in access_units.iter().enumerate() { - let frame_offset = u64::try_from(index).context("video frame index overflow")?; - let frame_id = options - .first_frame_id - .checked_add(frame_offset) - .ok_or_else(|| anyhow!("video frame_id overflow"))?; - let pts_offset = i64::try_from(index) - .ok() - .and_then(|index| index.checked_mul(i64::from(options.frame_duration_ticks))) - .ok_or_else(|| anyhow!("video pts_ticks overflow"))?; - let pts_ticks = options - .first_pts_ticks - .checked_add(pts_offset) - .ok_or_else(|| anyhow!("video pts_ticks overflow"))?; - let deadline_ticks = pts_ticks - .checked_add(options.deadline_delay_ticks) - .ok_or_else(|| anyhow!("video deadline_ticks overflow"))?; - - records.extend(packetize_video_access_unit( - VideoFramePacketizeOptions { - stream_id: options.stream_id, - session_id: options.session_id, - codec: options.codec, - frame_id, - pts_ticks, - duration_ticks: options.frame_duration_ticks, - timebase_num: options.timebase_num, - timebase_den: options.timebase_den, - deadline_ticks, - max_payload_bytes: options.max_payload_bytes, - }, - access_unit, - )?); - } - - Ok(records) -} - pub fn packetize_audio_packet( options: AudioPacketizeOptions<'_>, payload: &[u8], @@ -844,145 +761,6 @@ pub fn packetize_audio_packet( }) } -#[derive(Default)] -pub struct AudioPacketBuffer { - stream_id: Option, - session_id: Option, - codec: Option, - timebase_num: Option, - timebase_den: Option, - next_packet_id: Option, - emitted_any: bool, - packets: BTreeMap, -} - -impl AudioPacketBuffer { - pub fn insert(&mut self, packet: GameCultMediaAudioPacketRecord) -> Result<()> { - self.require_matching_audio_stream(&packet)?; - if packet.payload.is_empty() { - return Err(anyhow!("audio packet buffer payload must be non-empty")); - } - if self.packets.contains_key(&packet.packet_id) { - return Err(anyhow!( - "audio packet buffer has duplicate packet_id {}", - packet.packet_id - )); - } - match self.next_packet_id { - None => self.next_packet_id = Some(packet.packet_id), - Some(next_packet_id) if packet.packet_id < next_packet_id && !self.emitted_any => { - self.next_packet_id = Some(packet.packet_id); - } - Some(next_packet_id) if packet.packet_id < next_packet_id => { - return Err(anyhow!( - "audio packet buffer received stale packet_id {} before next expected {}", - packet.packet_id, - next_packet_id - )); - } - _ => {} - } - self.packets.insert(packet.packet_id, packet); - Ok(()) - } - - pub fn pop_ready_packets(&mut self) -> Vec { - let Some(mut next_packet_id) = self.next_packet_id else { - return Vec::new(); - }; - let mut ready = Vec::new(); - while let Some(packet) = self.packets.remove(&next_packet_id) { - ready.push(packet); - next_packet_id = next_packet_id.saturating_add(1); - } - if !ready.is_empty() { - self.emitted_any = true; - } - self.next_packet_id = Some(next_packet_id); - ready - } - - pub fn expire_late_packets(&mut self, now_ticks: i64) -> Vec { - let expired_ids = self - .packets - .iter() - .filter_map(|(packet_id, packet)| { - if packet.deadline_ticks <= now_ticks { - Some(*packet_id) - } else { - None - } - }) - .collect::>(); - for packet_id in &expired_ids { - self.packets.remove(packet_id); - } - if let Some(next_packet_id) = self.next_packet_id { - if expired_ids.contains(&next_packet_id) { - self.next_packet_id = self.packets.keys().next().copied(); - } - } - expired_ids - } - - pub fn pending_packet_count(&self) -> usize { - self.packets.len() - } - - fn require_matching_audio_stream( - &mut self, - packet: &GameCultMediaAudioPacketRecord, - ) -> Result<()> { - if packet.stream_id.is_empty() { - return Err(anyhow!("audio packet buffer stream_id must be non-empty")); - } - if packet.session_id.is_empty() { - return Err(anyhow!("audio packet buffer session_id must be non-empty")); - } - if packet.codec.is_empty() { - return Err(anyhow!("audio packet buffer codec must be non-empty")); - } - if packet.timebase_num == 0 || packet.timebase_den == 0 { - return Err(anyhow!("audio packet buffer timebase must be non-zero")); - } - - match ( - self.stream_id.as_deref(), - self.session_id.as_deref(), - self.codec.as_deref(), - self.timebase_num, - self.timebase_den, - ) { - (None, None, None, None, None) => { - self.stream_id = Some(packet.stream_id.clone()); - self.session_id = Some(packet.session_id.clone()); - self.codec = Some(packet.codec.clone()); - self.timebase_num = Some(packet.timebase_num); - self.timebase_den = Some(packet.timebase_den); - Ok(()) - } - ( - Some(stream_id), - Some(session_id), - Some(codec), - Some(timebase_num), - Some(timebase_den), - ) if stream_id == packet.stream_id - && session_id == packet.session_id - && codec == packet.codec - && timebase_num == packet.timebase_num - && timebase_den == packet.timebase_den => - { - Ok(()) - } - _ => Err(anyhow!( - "audio packet buffer received mixed stream metadata" - )), - } - } -} - - /// Muninn's producer name on the wire. The envelope in CultLib takes this as a /// parameter so it never has to know any producer; this is where Muninn says /// who it is, once. @@ -1014,27 +792,6 @@ pub fn encode_media_wire_records( .collect() } -pub fn encode_video_annex_b_stream_wire_records( - options: VideoAnnexBStreamWireOptions<'_>, - input: &[u8], -) -> Result>> { - let records = packetize_video_annex_b_stream(options.packetize, input)?; - let wire_records = video_wire_records_with_parity(&records)?; - encode_media_wire_records( - &wire_records, - options.stored_at, - options.source_runtime_id, - options.source_role, - ) -} - -pub fn video_annex_b_stream_send_payloads( - options: VideoAnnexBStreamWireOptions<'_>, - input: &[u8], -) -> Result> { - encode_video_annex_b_stream_wire_records(options, input).map(wire_payloads_to_media_send) -} - pub fn encode_audio_packet_wire_record( options: AudioPacketWireOptions<'_>, payload: &[u8], @@ -1076,27 +833,6 @@ fn wire_payload_to_media_send(payload: Vec) -> MuninnMediaSendPayload { } } - -fn encode_record_payload(record: &T) -> Result> { - rmp_serde::to_vec(record).map_err(Into::into) -} - - - - -fn decode_record_payload(payload: &[u8]) -> Result { - rmp_serde::from_slice(payload).map_err(Into::into) -} - - - - - - - - - - fn normalized_video_codec(codec: &str) -> Option<&'static str> { match codec.trim().to_ascii_lowercase().as_str() { "h264" | "h.264" | "avc" | "avc1" | "video/avc" => Some("h264"), @@ -1106,8 +842,6 @@ fn normalized_video_codec(codec: &str) -> Option<&'static str> { } } - - fn annex_b_nal_units<'a>( input: &'a [u8], codec_name: &str, @@ -1530,101 +1264,6 @@ mod tests { Ok(()) } - #[test] - fn packetizes_annex_b_stream_into_timed_video_records() -> Result<()> { - let mut stream = Vec::new(); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x65, 0x80]); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x41, 0x80]); - - let records = packetize_video_annex_b_stream( - VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "avc", - first_frame_id: 9, - first_pts_ticks: 27_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_800, - max_payload_bytes: 16, - }, - &stream, - )?; - - assert_eq!(records.len(), 2); - assert_eq!(records[0].frame_id, 9); - assert_eq!(records[0].pts_ticks, 27_000); - assert_eq!(records[0].deadline_ticks, 28_800); - assert!(records[0].keyframe); - assert_eq!(records[1].frame_id, 10); - assert_eq!(records[1].pts_ticks, 30_000); - assert_eq!(records[1].deadline_ticks, 31_800); - assert_eq!(records[1].dependency_frame_id, Some(9)); - assert_eq!(records[1].codec, "avc"); - Ok(()) - } - - #[test] - fn packetizes_non_reference_h264_p_frames_without_dependency() -> Result<()> { - let mut stream = Vec::new(); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x65, 0x80]); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x01, 0x80]); - - let records = packetize_video_annex_b_stream( - VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "h264", - first_frame_id: 9, - first_pts_ticks: 27_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_800, - max_payload_bytes: 16, - }, - &stream, - )?; - - assert_eq!(records.len(), 2); - assert!(records[0].keyframe); - assert_eq!(records[0].dependency_frame_id, None); - assert!(!records[1].keyframe); - assert_eq!(records[1].dependency_frame_id, None); - Ok(()) - } - - #[test] - fn rejects_negative_annex_b_stream_deadline_delay() { - let error = packetize_video_annex_b_stream( - VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "h264", - first_frame_id: 9, - first_pts_ticks: 27_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: -1, - max_payload_bytes: 4, - }, - &[0, 0, 0, 1, 0x65, 0x80], - ) - .unwrap_err(); - - assert!( - error - .to_string() - .contains("deadline_delay_ticks must be non-negative") - ); - } - #[test] fn rejects_zero_duration_video_access_units() { let access_unit = VideoAccessUnit { @@ -1799,123 +1438,6 @@ mod tests { ); } - fn audio_packet(packet_id: u64, deadline_ticks: i64) -> GameCultMediaAudioPacketRecord { - packetize_audio_packet( - AudioPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "opus", - packet_id, - pts_ticks: (packet_id as i64) * 960, - duration_ticks: 960, - timebase_num: 1, - timebase_den: 48_000, - deadline_ticks, - }, - &[0xf8, 0xff, packet_id as u8], - ) - .unwrap() - } - - #[test] - fn audio_packet_buffer_emits_contiguous_packets_in_order() -> Result<()> { - let mut buffer = AudioPacketBuffer::default(); - - buffer.insert(audio_packet(7, 10_000))?; - buffer.insert(audio_packet(9, 12_000))?; - let ready = buffer.pop_ready_packets(); - - assert_eq!( - ready - .iter() - .map(|packet| packet.packet_id) - .collect::>(), - vec![7] - ); - assert_eq!(buffer.pending_packet_count(), 1); - - buffer.insert(audio_packet(8, 11_000))?; - let ready = buffer.pop_ready_packets(); - - assert_eq!( - ready - .iter() - .map(|packet| packet.packet_id) - .collect::>(), - vec![8, 9] - ); - assert_eq!(buffer.pending_packet_count(), 0); - Ok(()) - } - - #[test] - fn audio_packet_buffer_tracks_lowest_packet_before_first_emit() -> Result<()> { - let mut buffer = AudioPacketBuffer::default(); - - buffer.insert(audio_packet(9, 12_000))?; - buffer.insert(audio_packet(7, 10_000))?; - buffer.insert(audio_packet(8, 11_000))?; - - let ready = buffer.pop_ready_packets(); - - assert_eq!( - ready - .iter() - .map(|packet| packet.packet_id) - .collect::>(), - vec![7, 8, 9] - ); - assert_eq!(buffer.pending_packet_count(), 0); - Ok(()) - } - - #[test] - fn audio_packet_buffer_rejects_stale_packets_after_emit() -> Result<()> { - let mut buffer = AudioPacketBuffer::default(); - - buffer.insert(audio_packet(7, 10_000))?; - assert_eq!(buffer.pop_ready_packets().len(), 1); - let error = buffer.insert(audio_packet(6, 9_000)).unwrap_err(); - - assert!(error.to_string().contains("stale packet_id")); - Ok(()) - } - - #[test] - fn audio_packet_buffer_expires_late_packets() -> Result<()> { - let mut buffer = AudioPacketBuffer::default(); - - buffer.insert(audio_packet(7, 10_000))?; - buffer.insert(audio_packet(8, 12_000))?; - - let expired = buffer.expire_late_packets(10_000); - - assert_eq!(expired, vec![7]); - assert_eq!(buffer.pending_packet_count(), 1); - assert_eq!( - buffer - .pop_ready_packets() - .into_iter() - .map(|packet| packet.packet_id) - .collect::>(), - vec![8] - ); - Ok(()) - } - - #[test] - fn audio_packet_buffer_rejects_mixed_stream_metadata() -> Result<()> { - let mut buffer = AudioPacketBuffer::default(); - let mut mixed = audio_packet(8, 12_000); - mixed.session_id = "session-2".to_string(); - - buffer.insert(audio_packet(7, 10_000))?; - let error = buffer.insert(mixed).unwrap_err(); - - assert!(error.to_string().contains("mixed stream metadata")); - Ok(()) - } - #[test] fn media_wire_round_trips_video_document() -> Result<()> { let access_unit = VideoAccessUnit { @@ -1989,129 +1511,6 @@ mod tests { Ok(()) } - #[test] - fn media_wire_batches_annex_b_video_records() -> Result<()> { - let mut stream = Vec::new(); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x65, 0x80]); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x41, 0x80]); - let records = packetize_video_annex_b_stream( - VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "h264", - first_frame_id: 9, - first_pts_ticks: 27_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_800, - max_payload_bytes: 16, - }, - &stream, - )?; - let wire_records = records - .iter() - .cloned() - .map(GameCultMediaWireRecord::Video) - .collect::>(); - - let wire = encode_media_wire_records( - &wire_records, - "2026-06-18T00:00:00Z", - "muninn-test", - "media-test", - )?; - - assert_eq!(wire.len(), 2); - assert_eq!(decode_media_wire_record(&wire[0])?, wire_records[0]); - assert_eq!(decode_media_wire_record(&wire[1])?, wire_records[1]); - Ok(()) - } - - #[test] - fn media_wire_encodes_annex_b_stream_for_sender() -> Result<()> { - let mut stream = Vec::new(); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x65, 0x80]); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x41, 0x80]); - - let wire = encode_video_annex_b_stream_wire_records( - VideoAnnexBStreamWireOptions { - packetize: VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "h264", - first_frame_id: 9, - first_pts_ticks: 27_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_800, - max_payload_bytes: 16, - }, - stored_at: "2026-06-18T00:00:00Z", - source_runtime_id: "muninn-test", - source_role: "media-test", - }, - &stream, - )?; - - assert_eq!(wire.len(), 2); - let first = decode_media_wire_record(&wire[0])?; - let second = decode_media_wire_record(&wire[1])?; - let GameCultMediaWireRecord::Video(first) = first else { - panic!("expected video media record"); - }; - let GameCultMediaWireRecord::Video(second) = second else { - panic!("expected video media record"); - }; - assert_eq!(first.frame_id, 9); - assert_eq!(first.deadline_ticks, 28_800); - assert_eq!(second.frame_id, 10); - assert_eq!(second.deadline_ticks, 31_800); - Ok(()) - } - - #[test] - fn media_send_payloads_pin_video_to_media_channel() -> Result<()> { - let mut stream = Vec::new(); - stream.extend_from_slice(&start_code()); - stream.extend_from_slice(&[0x65, 0x80]); - - let payloads = video_annex_b_stream_send_payloads( - VideoAnnexBStreamWireOptions { - packetize: VideoAnnexBStreamPacketizeOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "session-1", - codec: "h264", - first_frame_id: 9, - first_pts_ticks: 27_000, - frame_duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - deadline_delay_ticks: 1_800, - max_payload_bytes: 16, - }, - stored_at: "2026-06-18T00:00:00Z", - source_runtime_id: "muninn-test", - source_role: "media-test", - }, - &stream, - )?; - - assert_eq!(payloads.len(), 1); - assert_eq!(payloads[0].channel_id, MUNINN_MEDIA_RUDP_CHANNEL); - let GameCultMediaWireRecord::Video(record) = decode_media_wire_record(&payloads[0].payload)? - else { - panic!("expected video media record"); - }; - assert_eq!(record.frame_id, 9); - Ok(()) - } - fn stream_send_config() -> VideoAnnexBStreamSendConfig { VideoAnnexBStreamSendConfig { stream_id: "muninn.raven.av.rudp".to_string(), @@ -2130,6 +1529,109 @@ mod tests { } } + /// Push two access units through the sender and return every video data + /// record (parity excluded) it put on the wire, in order. + fn sent_video_records( + config: VideoAnnexBStreamSendConfig, + second_slice_header: u8, + ) -> Result> { + let mut stream = Vec::new(); + stream.extend_from_slice(&start_code()); + stream.extend_from_slice(&[0x65, 0x80]); + stream.extend_from_slice(&start_code()); + stream.extend_from_slice(&[second_slice_header, 0x80]); + let mut sender = VideoAnnexBStreamSendState::new(config)?; + let mut payloads = sender.push("2026-06-18T00:00:00Z", &stream)?; + payloads.extend(sender.finish("2026-06-18T00:00:00Z")?); + let mut records = Vec::new(); + for payload in &payloads { + if let GameCultMediaWireRecord::Video(record) = + decode_media_wire_record(&payload.payload)? + { + records.push(record); + } + } + Ok(records) + } + + #[test] + fn annex_b_stream_send_state_times_records_from_the_configured_clock() -> Result<()> { + let mut config = stream_send_config(); + config.codec = "avc".to_string(); + + let records = sent_video_records(config, 0x41)?; + + assert_eq!(records.len(), 2); + assert_eq!(records[0].frame_id, 9); + assert_eq!(records[0].pts_ticks, 27_000); + assert_eq!(records[0].deadline_ticks, 28_800); + assert!(records[0].keyframe); + assert_eq!(records[1].frame_id, 10); + assert_eq!(records[1].pts_ticks, 30_000); + assert_eq!(records[1].deadline_ticks, 31_800); + assert_eq!(records[1].dependency_frame_id, Some(9)); + assert_eq!(records[1].codec, "avc"); + Ok(()) + } + + #[test] + fn annex_b_stream_send_state_leaves_non_reference_p_frames_without_dependency() -> Result<()> { + let records = sent_video_records(stream_send_config(), 0x01)?; + + assert_eq!(records.len(), 2); + assert!(records[0].keyframe); + assert_eq!(records[0].dependency_frame_id, None); + assert!(!records[1].keyframe); + assert_eq!(records[1].dependency_frame_id, None); + Ok(()) + } + + #[test] + fn annex_b_stream_send_state_rejects_negative_deadline_delay() { + let mut config = stream_send_config(); + config.deadline_delay_ticks = -1; + + let error = match VideoAnnexBStreamSendState::new(config) { + Ok(_) => panic!("a negative deadline delay must not create a sender"), + Err(error) => error, + }; + + assert!( + error + .to_string() + .contains("deadline_delay_ticks must be non-negative") + ); + } + + #[test] + fn media_wire_batches_sender_records_and_reencodes_them_identically() -> Result<()> { + let mut stream = Vec::new(); + stream.extend_from_slice(&start_code()); + stream.extend_from_slice(&[0x65, 0x80]); + stream.extend_from_slice(&start_code()); + stream.extend_from_slice(&[0x41, 0x80]); + let mut sender = VideoAnnexBStreamSendState::new(stream_send_config())?; + let mut payloads = sender.push("2026-06-18T00:00:00Z", &stream)?; + payloads.extend(sender.finish("2026-06-18T00:00:00Z")?); + assert!(payloads.len() >= 2); + let wire_records = payloads + .iter() + .map(|payload| decode_media_wire_record(&payload.payload)) + .collect::>>()?; + + let wire = encode_media_wire_records( + &wire_records, + "2026-06-18T00:00:00Z", + "muninn-test", + "media-test", + )?; + + assert_eq!(wire.len(), payloads.len()); + for (encoded, original) in wire.iter().zip(&payloads) { + assert_eq!(encoded, &original.payload); + } + Ok(()) + } #[test] fn annex_b_stream_send_state_emits_only_completed_frames() -> Result<()> { @@ -2212,10 +1714,6 @@ mod tests { Ok(()) } - - - - #[test] fn media_wire_encodes_audio_packet_for_sender() -> Result<()> { let wire = encode_audio_packet_wire_record( @@ -2464,43 +1962,6 @@ mod tests { Ok(()) } - #[test] - fn feedback_payload_decodes_legacy_record_without_chunk_keys() -> Result<()> { - #[derive(serde::Serialize)] - struct LegacyFeedbackRecord { - stream_id: String, - session_id: String, - receiver_id: String, - highest_decodable_frame_id: Option, - missing_frame_ids: Vec, - late_frame_ids: Vec, - requested_keyframe: bool, - jitter_us: i64, - decode_queue_us: i64, - observed_at: String, - } - - let payload = encode_record_payload(&LegacyFeedbackRecord { - stream_id: "muninn.raven.av.rudp".to_string(), - session_id: "session-1".to_string(), - receiver_id: "starfire.obs".to_string(), - highest_decodable_frame_id: Some(41), - missing_frame_ids: vec![42], - late_frame_ids: vec![40], - requested_keyframe: true, - jitter_us: 750, - decode_queue_us: 2_000, - observed_at: "2026-06-18T00:00:00Z".to_string(), - })?; - - let decoded: GameCultMediaReceiverFeedbackRecord = decode_record_payload(&payload)?; - - assert_eq!(decoded.missing_video_chunk_keys, Vec::::new()); - assert_eq!(decoded.missing_frame_ids, vec![42]); - assert!(decoded.requested_keyframe); - Ok(()) - } - #[test] fn media_wire_rejects_mismatched_record_key() -> Result<()> { let record = packetize_audio_packet( From a189363c2331edec132d2a4a50e53813467bbf41 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 13:51:01 +0200 Subject: [PATCH 12/44] Drop imports the receiver residue left unused Co-Authored-By: Claude Sonnet 5 --- crates/muninn-daemon/src/media_packetizer.rs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/crates/muninn-daemon/src/media_packetizer.rs b/crates/muninn-daemon/src/media_packetizer.rs index ee9aab7..5d36d1e 100644 --- a/crates/muninn-daemon/src/media_packetizer.rs +++ b/crates/muninn-daemon/src/media_packetizer.rs @@ -1,12 +1,10 @@ use anyhow::{Context, Result, anyhow}; use cultnet_rs::{ CultNetMessage, CultNetWireContract, GAMECULT_MEDIA_AUDIO_PACKET_SCHEMA, - GameCultMediaAudioPacketRecord, - GameCultMediaReceiverFeedbackRecord, GameCultMediaVideoAccessUnitRecord, + GameCultMediaAudioPacketRecord, GameCultMediaVideoAccessUnitRecord, GameCultMediaVideoParityShardRecord, decode_cultnet_message_from_slice, encode_cultnet_message_to_vec, }; -use serde::{Serialize, de::DeserializeOwned}; use std::collections::BTreeMap; /// Re-exported so this module stays the one place Muninn's media code imports From eb332b0d2e033bd1576df212cdeee69ce0236356 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 13:55:27 +0200 Subject: [PATCH 13/44] Record realtime robustness rulings Q1-Q8 (2026-09-30) Co-Authored-By: Claude Opus 5.5 --- docs/realtime-robustness-cut.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/realtime-robustness-cut.md b/docs/realtime-robustness-cut.md index 54474dc..018c114 100644 --- a/docs/realtime-robustness-cut.md +++ b/docs/realtime-robustness-cut.md @@ -23,6 +23,28 @@ anchor below holds at both SHAs. --- +## Rulings (operator, 2026-09-30) + +- **Q1: remote play.** A viewer's controller drives a game on another host over LAN or mesh, so quick + taps must survive loss. The HID edge record is born in Muninn after named cut 1, and delivery uses + CultLib's profile-owned channels. Imagination maps the HID cuts next; nothing is specified yet. +- **Q2 (a): a pinned side-commit for now.** A single-purpose Odin commit bumps `odin-core` to Cut 3's + CultLib, and a `pins/` tag keeps it alive rather than `attic/`. Severing Muninn from `odin-core` + continues as Muninn's own cuts. Every CultLib bump repays this debt. +- **Q3: depend on `reed-solomon-erasure` 6, without simd.** A known-answer test pins the wire bytes, so + the library can be replaced without changing the wire. +- **Q4: delete the reliable `audio` channel.** Audio goes lossy with parity on `media`. This reverses the + 2026-09-10 decision. +- **Q5: audio parity comes after Opus.** Video parity ships in Cut 5. Audio stays on the reliable channel + until the Opus cut, then moves. +- **Q6 (a), against the recommendation: port the native encoder.** This is the libavdevice/NVENC child, + with an Idunn recipe step on Raven. Cut 6 gives IDR on request and bitrate adaptation, and it is the + campaign's one new native target. +- **Q7: 250 ms default, owned by the request.** It goes in the advertisement, and both ends derive from + the request. +- **Q8: fixed parity first.** Video uses `k ≤ 16`, `m = max(2, ⌈0.25k⌉)`; audio uses 4+2. The rate is + carried per record. Adaptive parity is a later cut. + ## Target: ends and invariants **End.** A Muninn stream that loses packets degrades by what each signal class From 4af6c8fac4cd24a46f772c5f723068ce7fa6f7b0 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 13:59:53 +0200 Subject: [PATCH 14/44] Move test-only cultnet imports into the tests module Co-Authored-By: Claude Sonnet 5 --- crates/muninn-daemon/src/media_packetizer.rs | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/crates/muninn-daemon/src/media_packetizer.rs b/crates/muninn-daemon/src/media_packetizer.rs index 5d36d1e..9fe62c5 100644 --- a/crates/muninn-daemon/src/media_packetizer.rs +++ b/crates/muninn-daemon/src/media_packetizer.rs @@ -1,9 +1,7 @@ use anyhow::{Context, Result, anyhow}; use cultnet_rs::{ - CultNetMessage, CultNetWireContract, GAMECULT_MEDIA_AUDIO_PACKET_SCHEMA, GameCultMediaAudioPacketRecord, GameCultMediaVideoAccessUnitRecord, - GameCultMediaVideoParityShardRecord, decode_cultnet_message_from_slice, - encode_cultnet_message_to_vec, + GameCultMediaVideoParityShardRecord, }; use std::collections::BTreeMap; @@ -1024,7 +1022,11 @@ impl<'a> BitReader<'a> { #[cfg(test)] mod tests { use super::*; - use cultnet_rs::{ReceiverFeedbackOptions, VideoChunkKey, build_receiver_feedback}; + use cultnet_rs::{ + CultNetMessage, CultNetWireContract, GAMECULT_MEDIA_AUDIO_PACKET_SCHEMA, + ReceiverFeedbackOptions, VideoChunkKey, build_receiver_feedback, + decode_cultnet_message_from_slice, encode_cultnet_message_to_vec, + }; fn start_code() -> [u8; 4] { [0, 0, 0, 1] From 36d6a79a2a7ad08f1c93c54c01d045ca4971915e Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 14:11:04 +0200 Subject: [PATCH 15/44] Map Cut 6 (native encoder) and the remote-play HID cuts H0-H5 Cut 6: the donor encoder behind a C ABI in an off-default package, typed encoder-command records on stdin, built and accepted on Raven by Idunn. HID: muninn-contracts crate, edges carried on the latest channel with the state, no Odin main change. Q9 (Sleipnir's home) and Q10 (who dials) open. Co-Authored-By: Claude Opus 5.5 --- docs/realtime-robustness-cut.md | 1097 ++++++++++++++++++++++++------- 1 file changed, 848 insertions(+), 249 deletions(-) diff --git a/docs/realtime-robustness-cut.md b/docs/realtime-robustness-cut.md index 018c114..92f5d5b 100644 --- a/docs/realtime-robustness-cut.md +++ b/docs/realtime-robustness-cut.md @@ -1,25 +1,29 @@ -# Muninn realtime media robustness: cut map +# Muninn realtime media robustness: cut map (v2) -Imagination pass, 2026-09-30. **Draft, uncommitted.** Self places it. It -belongs beside `Muninn/docs/teardown-map.md` on Muninn `main`; name that -branch in every brief. +Imagination pass 2, 2026-09-30. **Draft, uncommitted.** Self places it over +`Muninn/docs/realtime-robustness-cut.md` on Muninn `main` (pass 1 is `e70db69`, +and the rulings are `eb332b0`). Name that branch in every brief. Campaign (operator, 2026-09-30): FEC, parity, receiver-requested IDR, bitrate -adaptation, and a loss-tolerant HID edge. +adaptation, and a loss-tolerant HID edge for remote play. ## Status header | | | |---|---| -| Map state | Imagination pass 1. No cut dispatched. Seven operator forks are open (end of file). | -| Cuts ready for Hands without a ruling | Cut 0 (doc corrections), Cut 1 (dead-code subtraction), Cut 2 (bounded sender + seam), minus the latency default, which waits on Q7 | -| Cuts blocked on a ruling | Cut 3 (Q2, Q3, Q4, Q8), Cut 4 (Cut 3), Cut 5 (Q2, Q5), Cut 6 (Q6), HID (Q1) | -| Heads read | Muninn `cee7b9c`; CultLib `069ecc3` (`main`); Ratatoskr `488b5b1`; Odin `main` `379b826`; donor Odin `origin/codex/muninn-bounded-realtime-send` `80adfd3`; Odin tag `attic/claude-cultlib-pin-c2a9a6e` `3e96c6c`; Mimir `d88f2e6`; Idunn `docs/route-continuity-cut.md` at its current HEAD | +| Map state | Imagination pass 2. Q1-Q8 were ruled on 2026-09-30 (below). Pass 2 maps Cut 6 in full (Q6 = a) and the HID cuts H0-H5 (Q1 = remote play). Two new forks are open: Q9 (Sleipnir's home) and Q10 (HID connection direction). | +| In Hands | Cuts 0-1 on `hands/rr-cut0-1` (`2c120c9`, `f2a5db9`, `a189363`). This pass does not touch those sections. | +| Ready for Hands | Cut 2 (the latency default is settled by Q7); Cut 3 (Q2-Q4, Q8 settled); H1 (after H0); Cut 6a (after Cut 2) | +| Blocked | Cut 4 (on Cut 3's tag); Cut 5 (on the pin gate); Cut 6b (on Cut 2 and Cut 5); Cut 6c (on Idunn B3 and `route/b3-declare` merging, and on FFmpeg provisioning on Raven); H3-H5 (on Q9, Q10) | +| Heads read | Muninn `origin/main` `eb332b0` (code identical to `cee7b9c`), `route/b3-declare` `2260853`; CultLib `069ecc3`; Ratatoskr `488b5b1`; Odin `main` `379b826`; donor Odin `80adfd3`; Odin tag `attic/claude-cultlib-pin-c2a9a6e` `3e96c6c`; Idunn `771138a`; gamecult-ops working tree (binding `idunn/yggdrasil/bindings/raven-muninn.toml.in`, `scripts/idunn/idunn-deployment-targets.ps1`) | The CultLib media plane is byte-identical between Muninn's pin `c2a9a6e` and `main` `069ecc3`: `git diff c2a9a6e main` over `media_stream_contracts.rs`, `media_stream_wire.rs`, `rudp.rs` and `transport.rs` is empty. Every CultLib -anchor below holds at both SHAs. +anchor below holds at both SHAs. `M` anchors are at `eb332b0` and equal +`cee7b9c` for code. `S` = Sleipnir at Odin `main` `379b826` +(`crates/sleipnir-daemon/src/main.rs`), `DS` = the donor's Sleipnir at `80adfd3`, +and `I` = Idunn `771138a`. --- @@ -45,6 +49,15 @@ anchor below holds at both SHAs. - **Q8: fixed parity first.** Video uses `k ≤ 16`, `m = max(2, ⌈0.25k⌉)`; audio uses 4+2. The rate is carried per record. Adaptive parity is a later cut. + +**Pass-2 consequences of the rulings.** Every section below is rewritten to +the ruled design. The earlier options survive only in git (`e70db69`). +- Q2 names the `pins/` mechanism. The first `pins/` commit is **not** needed + for HID: `3e96c6c` already pins CultLib `c2a9a6e`, which is Muninn's current + pin. Retag it `pins/odin-core-cultlib-c2a9a6e` now, keep the `attic/` tag + until nothing references it, and cut the next `pins/` commit only at Cut 3's + CultLib tag. +- Q6 = (a) makes Cut 6 a real cut (6a-6c below). ## Target: ends and invariants **End.** A Muninn stream that loses packets degrades by what each signal class @@ -93,6 +106,45 @@ Invariants. Each one must be falsifiable by a test or a probe. `"hid.edge"` / `"hid.edge.assist"` arms in a vendored `rudp.rs` (`9af2edb`, `80adfd3`) are the pattern this forbids. + +10. **One commit primitive per virtual pad.** Snapshot axes, ordered edges, + epoch baselines and staleness neutralisation all reach ViGEm through one + Sleipnir function. Within an epoch, button visibility is owned **only** by + the edge stream. The snapshot's `buttons` field is a baseline at epoch start + and nothing else. The donor overwrote snapshot buttons with the previous + record's (`DS main.rs:573-578`); that split is forbidden. +11. **A tap survives loss without transport retransmission.** A press and + release captured between two transport ticks reach the pad, in order, under + the Cut 3b profiles up to `loss-5pct` and `burst-8`. The mechanism is + redundancy: every unacknowledged edge rides every frame until it is + acknowledged. No reliable channel carries input, so there is no + retransmit debt and no head-of-line blocking. +12. **Input memory is bounded on both ends.** + - The sender keeps at most 256 unacknowledged edges per source, and + rotates the epoch on overflow (donor rule, `D main.rs:5846-5854`). + - A frame carries at most 32. + - The receiver buffers nothing beyond the window it was sent. + - Stale epochs are fenced by monotonic comparison, not by a growing set + (the donor's `retired_epochs: HashSet`, `DS main.rs:210`, grows forever). +13. **Input latency is bounded.** A queued edge is held visible for 24 ms + (`DS main.rs:32-35`, one 60 Hz game sample plus margin) **unless** it is + older than the input budget (100 ms default). Then it is actuated without + the hold. A tap is compressed, never dropped. +14. **No JSON on a live wire.** Muninn↔Sleipnir today speaks JSON both ways + (B14), and the donor did too (`D main.rs:6117,6141`, `DS main.rs:693-699`). + Every HID and encoder-control message becomes a typed CultCache record in + a CultNet message. +15. **Encoder commands are typed and fire-and-forget; their effect is + observed.** Muninn writes `muninn.video_encoder_command.v1` records to the + encoder's stdin as CultNet frames. Whether an IDR happened is read from the + Annex B stream (keyframe access units). Whether a bitrate took is read from + measured bytes per second. Neither is read from what was asked (invariant 7). +16. **One video encoder path.** When Cut 6b lands, the ffmpeg CLI video child is + deleted. A missing encoder binary fails the request with a typed `detail`. + There is no fallback, because the donor's + `video_encoder_path.is_some()` switch (`D main.rs:1942`) kept two paths + alive. + Explicitly **not** in scope: - Mimir's `Mimir.CultMeshMedia`: a separate MPEG-TS-over-documents relay, `mimir.cultmesh_media_frame`, `Program.cs:11`. It is not a @@ -116,6 +168,10 @@ These were run, not inferred from names. | An established codec fits | Scratch crate `rs-probe` on Yggdrasil, `--release` | `reed-solomon-erasure` 6 (GF(2^8)): any shard length (849 OK), exhaustive `≤m` recovery true for 4+2 and 8+4, `m+1` erasures fail cleanly. It costs 13.5 µs to encode and 11 µs to decode an 8+4 block of 850 bytes, and 2.6 µs / 3.4 µs for 4+2 at 864 bytes. `reed-solomon-simd` 3: **refuses odd shard sizes** (`InvalidShardSize{849}`), decode about 230 µs per block. | | Current XOR vs RS at equal overhead | iid model, `python` (arithmetic, not a harness) | For a 200-chunk keyframe at 3% loss, XOR16 fails the frame **63%** of the time at 8% overhead, and RS 8+4 fails 4e-4 at 50%. For frames of `n ≤ 16` chunks, XOR16 is **duplication**: each stripe holds one chunk, so the overhead is 100%. | +| Muninn↔Sleipnir HID wire today | Read `M main.rs` and `S main.rs` | **JSON both ways.** Subscription: `S :2303-2310` → `M :6216-6217`. State: `M :6298-6300` (ingress server) and `M :6835-6836` (outbound client) → `S :2485-2498`. Sleipnir coalesces "latest wins" per device (`S :2543-2590`), so a tap between two received frames never reaches ViGEm. | +| CultLib channel delivery | Read `C rudp.rs:2339-2410` | Only `media` takes its delivery from the profile, plus `audio` hardcoded Reliable. `schema`, `latest` and `_` are fixed by name. `latest` is Unreliable and **Sequenced per channel** (`:2384-2390`, `:185-191`), so a late older packet is dropped. The window-per-frame design fits this exactly, because each frame supersedes the last. **No CultLib change is needed for HID.** | +| Idunn host-native runner for the encoder | Read `I src/host.rs:934-960`, `I src/deployment.rs:55-110`, the binding | The Raven runner's `allowed_programs = ["cargo"]`. **Host-native materialisation refuses `external_inputs`** (`I host.rs:953-956`), so a sha-pinned FFmpeg download cannot be a recipe input on Raven. Runner environment comes from the binding (`[runners.rust-host.environment]`, precedent `CARGO_NET_GIT_FETCH_WITH_CLI`). `[service] required_adjacent_artifacts` exists (`I deployment.rs:113`). Recipe phases include `acceptance` (`:71-77`). | +| Donor encoder shape | `git show 80adfd3:native/muninn-video-encoder/*` | 265 lines of C++20, CMake with `FFMPEG_ROOT`. lavfi `ddagrab` → decoder → `h264_nvenc`. A `std::getline` stdin thread parses `IDR` / `BITRATE n` / `QUIT`. `fail()` calls `exit(1)`. Bitrate is reconfigured by mutating `AVCodecContext` before `send_frame`, and IDR by `pict_type = I` with `forced-idr=1`. The build script links the OBS deps snapshot at an `E:\Projects\Mimir` path that no longer exists. | --- ## Body findings @@ -254,6 +310,62 @@ contract (`a250ec6` onward), and the consumer-dials-producer inversion. - Today Muninn sends snapshots only (`M main.rs:6172-6200, 6758-6800`), so a tap shorter than one sample, or lost with its packet, never happens. +**B14. The HID wire is JSON, and a tap dies at two places.** +- The wire: `M main.rs:6137-6142, 6216-6217, 6298-6300, 6835-6836`; + `S main.rs:2303-2310, 2497-2498`. The 2026-09 repo census flagged the same + lines (`gamecult-ops/docs/repo-census-2026-09/repos/Odin.md:48`). +- **Muninn reads a source once per transport tick** + (`read_hid_controller_state_for_stream`, `M :6286`, `:6370`). A press and + release inside one tick never exist as data. +- **Sleipnir keeps only the latest record per device** (`S :2543-2590`), so a + tap that survived capture dies again at the sink. + +**B15. Muninn has two HID transport paths.** +- An ingress server that Sleipnir dials: `--hid-controller-rudp-bind`, + `M :6144-6356`. This is the one Raven runs (recipe `raven-muninn.toml:62-65`, + advertised `10.77.0.4:17887`). +- An outbound client that dials a target: `--hid-controller-rudp-target`, + `M :6717-6860`, `:10891-10895`. +- Both speak JSON on `latest`. Two paths for one signal is the split Q10 + settles. + +**B16. Sleipnir is welded into Odin's pin.** +- `S` is a member of Odin's workspace. It takes `odin-core` by path + (`Odin crates/sleipnir-daemon/Cargo.toml`) and CultLib at `a8aedda`, which is + Odin `main`'s pin, the one StreamPixels ships on. +- It imports 10 odin-core symbols (`S :10-14`). One is Muninn's HID record, + and one is its own `SleipnirInputMappingRecord`. +- Any Sleipnir change that consumes a Muninn-owned record at Muninn's CultLib + (`c2a9a6e`) reopens the two-`cultcache-rs` diamond **inside Odin's + workspace**, and that can only be closed by moving Odin `main`'s pin. +- Its deployment target is the legacy script-driven `raven-sleipnir` + (`gamecult-ops/scripts/idunn/idunn-deployment-targets.ps1:126-138`, + `Repo = "Odin"`, scheduled task plus SSH). It has no Idunn recipe. **Whether + it runs on Raven today is unverified.** + +**B17. The sink already has the seam a harness needs.** +`trait VirtualPadBackend { fn update(&mut self, state: &VirtualPadState) }` +(`S :179-181`) has a `LoggingBackend` (`:183`) beside the ViGEm one +(`:200-240`, `cfg(windows)`). A recording backend gives a pad timeline on Linux. + +**B18. Raven cannot fetch the encoder's FFmpeg through Idunn.** +Host-native materialisation refuses `external_inputs` (`I host.rs:953-956`), and +the runner may execute only `cargo`. So the FFmpeg development root must be: +- pre-provisioned on Raven (operator action, recorded in gamecult-ops with its + sha256); +- named by the binding's runner environment; +- compiled against by `build.rs`, through the `cc` crate for the C++ and link + directives for FFmpeg. No CMake step and no new allowed program. + +`ffmpeg_path` today points at a WinGet static `ffmpeg.exe` (binding +`raven-muninn.toml.in`, `ffmpeg_path`), which has no headers or import +libraries. + +**B19. The recipe is mid-edit by another campaign.** `route/b3-declare` +(`2260853`, unmerged) adds `[[dependencies]] odin.verse-rendezvous` to +`deployment/idunn/raven-muninn.toml`. Cut 6c edits the same file and must build +on it after it merges. + --- ## Donor ledger: port, rewrite, drop @@ -267,11 +379,18 @@ contract (`a250ec6` onward), and the consumer-dials-producer inversion. | Datagram-fit tests (`D :3065`, `production_aac_audio_fec_shards_fit_one_rudp_datagram`) | **Port as behavioural tests** at the CultLib codec and in Muninn | They pin invariant 6. | | Exhaustive erasure test (`D :4919`) | **Port**, generalised to every shipped `(k, m)` | Pins invariant 4. | | `MuninnKeyframeRequestGate` (`D main.rs:2864-2884`, cooldown 500 ms at `:102`) | **Port** (Cut 6) | Small and correct: an edge with a cooldown. | -| `MuninnVideoBitrateController` (`D :2439-2512`) | **Rewrite** (Cut 6, only if Q6 = a) | Its ceiling halving assumes 50% FEC overhead, and its doc and code disagree. It must key on the chosen parity rate, and aggregate across hub receivers, which the donor predates. | -| `native/muninn-video-encoder` (C++, 265 lines) plus build script | **Held at the donor tag, pending Q6** | A new native target with FFmpeg dev libraries on Raven, built by an Idunn `rust-host` runner whose vocabulary is `cargo`. That is a large liability, bought only if IDR and bitrate adaptation earn it. | +| `MuninnVideoBitrateController` (`D :2439-2512`) | **Rewrite** (Cut 6b) | Its ceiling halving assumes 50% FEC overhead, and its doc and code disagree. The rewrite keys the ceiling on the ruled parity rate and aggregates across hub receivers, which the donor predates. | +| `native/muninn-video-encoder/main.cpp` (265 lines) | **Port** the capture and encode loop (Cut 6a). **Rewrite** its shell. | Kept: the lavfi → decode → encode loop, NVENC options, `pict_type = I` and `AVCodecContext` bitrate mutation. Deleted: `main`, `parse_options`, the `std::getline` text command thread, `fail()`/`exit`, and `fwrite` to stdout. They become a C ABI (`muninn_encoder_run` with poll and write callbacks) under a Rust `main` that decodes typed command records (invariant 15). | +| `CMakeLists.txt`, `scripts/build-muninn-video-encoder.ps1` | **Drop** | `build.rs` with the `cc` crate compiles the C++. The Idunn runner may run only `cargo` (B18). The script's FFmpeg path no longer exists. | +| `capture_button_edges`, `ActiveHidControllerRudpSource` edge fields, overflow epoch rotation (`D main.rs:5732-5856`) | **Rewrite** into `muninn-contracts::hid::EdgeWindow` (H1). Capture calls it on the sampling thread (H2). | The rotation and bound rules are right. The donor ran them at transport-tick time, which loses sub-tick taps (B14), cloned `epoch` needlessly, and sent JSON. | +| Donor's `hid.edge` (reliable) + `hid.edge.assist` (unreliable resend) channels and the `hid.subscribe`/`hid.edge.ack` JSON | **Drop** | Two mechanisms for one job, plus four transport name arms (invariant 9). Replaced by one frame on the profile-declared `latest` channel that carries state and the unacknowledged window (invariant 11). | +| `HidSemanticCursor` (`DS main.rs:204-256`) | **Port** into `muninn-contracts::hid::EdgeCursor` (H1), with the `retired_epochs` set **replaced** by a monotonic epoch fence | The ordering, dedupe and gap bound (256) are right. The unbounded set is not (invariant 12). | +| `INPUT_EDGE_MINIMUM_VISIBILITY` 24 ms and the actuation queue (`DS main.rs:32-35, 655-700`) | **Port** into Sleipnir (H4), with the budget override added | Invariant 13. The donor queue has no latency ceiling. | +| Snapshot-buttons overwrite (`DS main.rs:573-578`) | **Drop** | Split button ownership (invariant 10). | +| Donor capture-thread split (`fb4f331`), 1 ms XInput sampling (`D main.rs:5881, 6880-6940`) | **Port** (H2) | This is where a tap first exists as data. | +| `crates/sleipnir-daemon/examples/xinput_edge_observer.rs` (`80adfd3`, 127 lines) | **Port** as Sleipnir's live probe (H5) | It reads the virtual pad through XInput, as the game does. That is the layer where a lost tap is visible (SKILL: instrument the layer the user sees). | | Bounded `sync_channel` plus per-frame groups, capacities 256/512 (`D main.rs:85-87, 2023-2028, 2356-2369`) | **Port the shape**, rewrite against the hub loop (Cut 2) | Exactly invariant 2. | | `cultnet-impair` (696 lines, seeded loss/burst/jitter/reorder/dup/stall, CSV) | **Port to CultLib** `packages/cultnet-rs/examples/` (Cut 3b) | It is a CultNet transport tool. `media_delivery_probe.rs` already sits there and expects it (its header, `C examples/media_delivery_probe.rs:5`). | -| HID edges, epochs and acks in Muninn + Sleipnir + vendored `rudp.rs` | **Park** until Q1 | Purpose unknown, and it breaks invariant 9. | | Vendored `rudp.rs` ACK changes (`9af2edb` `direct_ack_state`, ACK reliable duplicates) | **Drop** | CultLib evolved separately (`75c1807` acknowledges retransmits across horizons; `47b9fc4` changes reader semantics). Anything still missing is a CultLib finding with its own proof, not a port. | | `muninn.*` v4/v1 parity schemas | **Drop** | Superseded by `gamecult.*` in CultLib. No live reader. | @@ -325,18 +444,25 @@ What it does **not** own: | Kind | What names it | What happens to it over time | Who decides | |---|---|---|---| | Video parity shard `gamecult.media_video_parity_shard.v3` | `(stream_id, session_id, frame_id, block_index, parity_index)`; the key extends today's (`C media_stream_wire.rs:92-110`) | Emitted with its frame's group, and dropped with the group at the deadline. Never repaired, never cached for repair. v2 is **deleted**, not kept beside it. | Producer emits. CultLib codec defines the bytes. Receiver consumes until the frame deadline. | -| Audio parity shard `gamecult.media_audio_parity_shard.v1` | `(stream_id, session_id, base_packet_id, parity_index)` | Emitted after its k-th data packet. It expires with the block's latest deadline. | Same. | -| FEC scheme id (e.g. `rs-gf256-v1`) | A string on each parity record | Changes only with a new schema version. A KAT pins it. | CultLib. | -| `(k, m)` policy | Carried per parity record (`block_data_count`, `parity_count`) | Fixed per stream in the first cut. Adaptive only if Q8 rules so. | Producer (Muninn). | -| Latency budget | `gamecult.media_stream_request.v1.latency_budget_ms` (key 11) | Fixed for a request. A new request restarts the child (teardown-map L533). | **Consumer** asks. Producer honours it, or refuses in `detail`. Default per Q7. | -| Keyframe request | `requested_keyframe` edge on feedback | Counted per receiver. It triggers at most one IDR per cooldown. | Receiver asserts. Producer's gate decides actuation (Cut 6). | -| Encoder bitrate (live) | Process-local, no record | Adjusted within `[floor, ceiling]`. Reported in telemetry. | Producer's controller (Cut 6, Q6). | -| HID edge | Unknown until Q1 | — | — | +| Audio parity shard `gamecult.media_audio_parity_shard.v1` | `(stream_id, session_id, base_packet_id, parity_index)` | Emitted after its k-th data packet. It expires with the block's latest deadline. Lands only after Opus (Q5). | Same. | +| FEC scheme id (`rs-gf256-v1`) | A string on each parity record | Changes only with a new schema version. A KAT pins it. | CultLib. | +| `(k, m)` policy | Carried per parity record (`block_data_count`, `parity_count`) | Fixed (Q8): video `k ≤ 16`, `m = max(2, ⌈k/4⌉)`; audio 4+2. | Producer (Muninn). | +| Latency budget | `gamecult.media_stream_request.v1.latency_budget_ms` (key 11) | Fixed for a request. Default 250 ms in the advertisement (Q7). A new request restarts the child (teardown-map L533). | **Consumer** asks; producer honours it. | +| Keyframe request | `requested_keyframe` on feedback | Counted per receiver. It is an edge: at most one IDR per 500 ms cooldown per stream. | Receiver asserts. Muninn's gate decides (6b). | +| Encoder command `muninn.video_encoder_command.v1` | `(encoder process, command_sequence)`. The sequence is monotonic from 1 per spawned encoder process. | Lives only on the stdin pipe. Never stored. It dies with the process; a respawn restarts the sequence at 1. | Muninn's `EncoderControl` writes. The encoder applies at the next frame. **Effect is observed from the bitstream**, not acknowledged. | +| Live encode bitrate | Observed bytes per second over a 1 s window | Moves within `[floor, ceiling]` from the request's `video_bitrate_kbps` and the parity rate | Muninn's bitrate controller (6b) | +| HID epoch | `(device_id, epoch: u64)`. The epoch is the sender's monotonic start time in ns, and `+1` on overflow rotation. | New per Muninn process start and per overflow. The receiver fences any epoch below its current one. | Muninn (sender). Sleipnir only fences. | +| HID state sequence | `(device_id, epoch, state_sequence)` | Monotonic per epoch. Each frame supersedes the last (the `latest` channel is sequenced). | Muninn. | +| HID edge | `(device_id, epoch, edge_sequence)`, contiguous from 1 per epoch | Pending until acknowledged. Resent in every frame while pending, at most 32 per frame and 256 held. Overflow rotates the epoch and drops the history. | Muninn creates at sample time. Sleipnir applies in order and acknowledges cumulatively. | +| HID edge ack `muninn.hid_edge_ack.v1` | `(device_id, epoch, applied_through)` | Cumulative and idempotent. Resent each Sleipnir tick while nonzero. | Sleipnir. | +| HID subscription `muninn.hid_subscription.v1` | `(subscriber_id)` | Resent every 1 s (today's cadence, `S :2295-2302`). The newest wins. | Sleipnir. | --- ## Cut 0: correct the Muninn maps against git (docs only) +**Status: in Hands on `hands/rr-cut0-1` (`2c120c9`, `f2a5db9`, `a189363`). Unchanged by pass 2.** + Repo Muninn, `main`. Hands, doc-only. Nothing is deleted from history. Superseded claims are marked as history in place and not left as two live designs. @@ -370,6 +496,8 @@ against `git show cee7b9c:`. Ledger: ±0 code. ## Cut 1: subtract the receiver residue from the producer +**Status: in Hands on `hands/rr-cut0-1` (`2c120c9`, `f2a5db9`, `a189363`). Unchanged by pass 2.** + Repo Muninn, `main`. This is a subtraction cut, kept separate from behaviour cuts. No pin change. @@ -414,7 +542,7 @@ applies and reports. Repo Muninn, `main`. No pin change. Cut 5's parity rides on it. -The latency default waits on Q7. The rest does not. +Q7 ruled: the default is 250 ms, owned by the request. It goes in the advertisement, and Ratatoskr derives its `max_frame_age` from its request (Cut 4). **Authority map.** - **Owner:** a new `MediaSendCore` in Muninn. It holds the queues, the hub, the @@ -428,7 +556,7 @@ The latency default waits on Q7. The rest does not. `policy.latency_budget`; - `MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS` is **no longer an owner**. It dies, and the advertisement's `default_latency_budget_ms` takes the - Q7 constant. + 250 ms constant (Q7). - **Forbidden writers:** - `Instant::now()` as a repair's `queued_at` (`main.rs:3129`). A repair inherits its frame's deadline. @@ -496,8 +624,8 @@ into the sender. ## Cut 3: the CultLib media FEC codec and records Repo CultLib, a branch from `main`. Tag and publish per CultLib's release -rules. A release is a cut: Soul passes before the tag (SKILL step 5). Blocked on -Q3, Q4 and Q8. Q2 blocks consumption, not this cut. +rules. A release is a cut: Soul passes before the tag (SKILL step 5). Q3, Q4 +and Q8 are ruled. Consumption waits on the pin gate (Q2, Sequencing step 11). **3a. Deletes first:** - `GameCultMediaVideoParityShardRecord` v2 (`C media_stream_contracts.rs:466-517`), @@ -505,7 +633,7 @@ Q3, Q4 and Q8. Q2 blocks consumption, not this cut. (`C media_stream_wire.rs:323-388`), the `VideoParity` wire arm's v2 decode (`:98-103`, `:183-186`), and the v2 tests in `tests/media_stream_wire.rs` and `tests/media_stream_contracts.rs`. -- If Q4 = yes: `GAMECULT_MEDIA_AUDIO_CHANNEL` (`C media_stream_wire.rs:41-44`), +- Per Q4: `GAMECULT_MEDIA_AUDIO_CHANNEL` (`C media_stream_wire.rs:41-44`), the `"audio"` channel profile (`C rudp.rs:2218-2228`), `"audio"` in the `channel_send_options` arm (`:2394`), and the test rows (`tests/cultnet.rs:436, 3023-3030`). @@ -524,20 +652,22 @@ Q3, Q4 and Q8. Q2 blocks consumption, not this cut. - `GameCultMediaWireRecord::AudioParity`, with its validation, record key (`B` identity table) and decode arm. - `media_fec.rs`: - - `MediaFecPolicy { max_block_data: u16, parity_ratio / fixed m }`; + - `MediaFecPolicy`, fixed per Q8. Video frames split into `⌈n/16⌉` near-equal + blocks (`k ≤ 16`), with `m = max(2, ⌈k/4⌉)`. Audio is 4+2. The rate is + carried per record. - `protect_video_frame(&[VideoAccessUnitRecord], &policy) -> Vec` in **send order**, round-robin over blocks (donor `4e2abee`); - `protect_audio_block(&[AudioPacketRecord; k]) -> Vec`; - `recover_video_block` / `recover_audio_block(present) -> Result, BeyondRepair>`. - Backing: `reed-solomon-erasure = "6"` (Q3), default features, no - `simd-accel` C build. + `simd-accel`. The KAT pins the wire, so the library is replaceable. - Update the module doc `C media_stream_contracts.rs:34-41`: audio now has parity. **Rules that must die under their own mutation:** -- Every `≤ m` erasure pattern recovers exactly, for each shipped `(k, m)` (at - least 4+2 and 8+4, and the policy's maximum block). This is exhaustive; the - probe shows it is cheap. +- Every `≤ m` erasure pattern recovers exactly, for **every** shipped `(k, m)`: + `k = 1..16` with its ruled `m`, and 4+2. This is exhaustive. The largest is + `k = 16, m = 4`, about 6,200 patterns, which the probe shows is cheap. - `m+1` erasures return `BeyondRepair`. They never return `Ok` with wrong bytes. - KAT: fixed 4×37-byte input, then the exact parity bytes, committed as hex. This kills any change of matrix, polynomial or shard order. @@ -647,15 +777,16 @@ is operator-installed. ## Cut 5: Muninn emits CultLib parity, and audio goes lossy -Repo Muninn, `main`. It is gated by Q2 (the pin diamond) and Q5 (after Opus, or -over PCM). +Repo Muninn, `main`. It is gated by the pin gate (Q2, Sequencing step 11). +Per Q5, **video parity ships here, and the audio half waits for Opus**: audio +stays on the reliable `audio` channel until then. **Deletes first:** - `MUNINN_VIDEO_PARITY_STRIPES`, `build_video_parity_shards` and `video_wire_records_with_parity` (`M media_packetizer.rs:625-754`), and their tests; - `audio_packet_send_payload`'s audio-channel pin (`:1055-1063`) and - `MUNINN_AUDIO_RUDP_CHANNEL` (`:15-16`) if Q4 = yes; + `MUNINN_AUDIO_RUDP_CHANNEL` (`:15-16`), per Q4, in the audio half after Opus; - the `media_send_payload_pins_audio_to_media_channel` test's assertion (`:2252-2280`), which is rewritten to its new truth. @@ -707,257 +838,710 @@ over PCM). Protocol: the operator runs the stream for N minutes on each path with the receive probe's stats captured. Parity overhead against the 28 Mbps hairpin is -the number that decides Q8. +the number that decides whether the later adaptive-parity cut (Q8) is needed. **Ledger:** −130 XOR, +60 of calls into CultLib. **Net about −70.** --- -## Cut 6: encoder control, IDR on request and bitrate adaptation +## Cut 6: native encoder, IDR on request and bitrate adaptation (Q6 = a) -Mapped only as far as Q6 allows. It is not dispatchable until Q6 is ruled. +The ruling was against Imagination's recommendation, which was to decide on +harness evidence. This map carries out the ruling. The one cost to name: this is +the campaign's only new native target, and its Windows build is proven nowhere +but Raven. -If Q6 = (a), port the donor encoder: -- **Deletes first:** `record_receiver_keyframe_pressure` (`M main.rs:3036-3048`). - The ffmpeg CLI video child (`rudp_video_ffmpeg_args`, `:10343-10421`) is - retired **only after** the native encoder is installed by the Idunn recipe. - Keep one path, not two: the donor kept both behind `video_encoder_path.is_some()` - (`D main.rs:1942`), which is the split to avoid. -- **Adds:** - - `native/muninn-video-encoder` from the donor, plus a recipe build step in - `deployment/idunn/raven-muninn.toml`. **The Idunn recipe is being edited by - the route-continuity campaign right now; see Sequencing.** - - An `EncoderControl` port in `MediaSendCore` (Cut 2's seam). - - The ported `MuninnKeyframeRequestGate`. - - The rewritten `BitrateController`: - - its ceiling is `configured × 1/(1+parity_ratio)` from Cut 5's policy, not - `/2`; - - it aggregates damage across all hub receivers: any receiver's damage backs - off, which is recorded as a known limit for the single-encoder, - many-viewer case; - - its recovery step and interval are named constants whose values the - harness picks. -- **Rules:** - - One invalidation edge gives exactly one `IDR` command per cooldown. Count - the bytes written to the control port. - - Damage inside a sample window gives exactly one multiplicative back-off. - - Stable for the interval gives exactly one additive step, never above the - ceiling. - - Assert on the command bytes, as the donor did (`D main.rs:12756-12801`). -- **Only live proves:** that NVENC honours a forced IDR at the next frame and - reconfigures bitrate without a restart. The donor recorded both on 2026-07-17, - but on a pre-extraction body. +Three parts, each with its own verification: +- **6a** builds the encoder and needs no GPU; +- **6b** wires Muninn to it; +- **6c** deploys it and accepts it on Raven. -If Q6 = (b) or (c), Cut 6 is a one-commit deletion: `record_receiver_keyframe_pressure`, -and `requested_keyframes` stays as telemetry only. Retire the "IDR on request" -and "bitrate adaptation" goals from this campaign with the ruling recorded. +Build hosts and target platforms are named separately throughout, per the +global Build budget rule. + +### 6a: the `muninn-video-encoder` package (Muninn repo) + +**Why a package.** +- **Owner:** Muninn. +- **Live consumer:** Muninn's activation child, which spawns it. +- **Protected invariants:** invariant 15 (typed commands, observed effect) and + invariant 16 (one encoder path). +- **Why the existing owner cannot serve:** FFmpeg's C API must be linked. Linking + libav into `muninn-daemon` would make every Muninn build, on Nightwing, + Starfire and in CI, need an FFmpeg development root. A separate package + confines that to one target. +- **What it replaces:** the ffmpeg CLI video child (6b deletes it). +- **Build fan-out:** add `muninn-video-encoder` to the workspace `members`, and + **not** to `default-members`, so that a plain `cargo build` or `cargo test` + never needs FFmpeg. + +**Layout.** +- `crates/muninn-video-encoder/Cargo.toml`: `[[bin]] muninn-video-encoder`. + Dependencies: `muninn-contracts` (the command record, H0/H1), + `cultnet-rs` (framing and message envelope), `anyhow`. Build-dependencies: + `cc`, plus `pkg-config` for the Linux path only. +- `native/encoder_core.cpp`: the donor loop, **ported**, with these changes: + - `main`, `parse_options`, the `command_reader` thread and `fail()` are + deleted. Errors return a code and a message into a caller buffer. + - Its only entry point is: + ```c + int muninn_encoder_run(const muninn_encoder_options*, + int (*poll)(void* ctx, muninn_encoder_control* out), + int (*write)(void* ctx, const uint8_t* data, size_t len), + void* ctx, char* error, size_t error_len); + ``` + `poll` is called once per captured frame. It returns + `{force_idr, bitrate_kbps (0 = unchanged), stop}`. + - The encoder name is an option. `h264_nvenc` (with the donor's option + dictionary) is for production. `libx264` (`preset=ultrafast`, + `tune=zerolatency`) is only for the Linux verification build. The capture + input is an option too: `ddagrab=...` in production, `testsrc2=...` in + verification. +- `build.rs`: + - On Windows, read `MUNINN_FFMPEG_ROOT` (required), compile + `encoder_core.cpp` with `cc` (MSVC, `/std:c++20`), emit + `cargo:rustc-link-search` for `lib/`, and link `avcodec avdevice avfilter + avformat avutil`. + - Refuse to build unless `include/libavcodec/version_major.h` has the pinned + `LIBAVCODEC_VERSION_MAJOR`. The pin is a named constant in `build.rs`; the + operator's provisioned build sets it. + - Emit `cargo:rerun-if-env-changed=MUNINN_FFMPEG_ROOT`. + - On Linux, find the same libraries through `pkg-config`. +- `src/main.rs`: + - parses argv: `--input`, `--encoder`, `--framerate`, `--bitrate-kbps`, + `--gop-frames`, `--frames N` (verification bound); + - runs a stdin reader thread: `cultnet_rs::LengthPrefixedMessageFramer`, + then `decode_cultnet_message_from_slice`, then `MuninnVideoEncoderCommandRecord`, + then validation, then a **bounded** `sync_channel(16)`; + - implements `poll` by draining that channel into one control value: + - any IDR sets `force_idr`; + - the **last** bitrate wins, so coalescing matches the donor's atomic + exchange; + - `stop` ends the run; + - implements `write` to stdout; + - guards the framer with a maximum frame length of 4 KiB. The framer buffers + whatever arrives, so a garbage length prefix must not grow memory + (invariant 2's spirit). + +**The command record** `muninn.video_encoder_command.v1`, in `muninn-contracts`. +It is Muninn-owned and process-local, and published to no store. + +| key | field | rule | +|---|---|---| +| 0 | `command_sequence: u64` | starts at 1 per encoder process and increases by exactly 1. A gap or repeat is refused and counted, which exposes a writer bug. | +| 1 | `kind: String` | `idr`, `bitrate` or `stop`. Anything else is refused and counted. | +| 2 | `bitrate_kbps: u32` | nonzero only for `bitrate`, within `[250, 100_000]` (the donor's bounds, from its command thread) | +| 3 | `cause: String` | for example `keyframe-request` or `receiver-pressure`. Telemetry only. | +| 4 | `issued_at: String` | telemetry only | + +**Verification on Yggdrasil.** Build host Linux x86_64. Target platform Linux, +**not** the Windows shipping target. +- Image: the rust verify image plus + `apt-get install -y libavdevice-dev libavfilter-dev libavformat-dev libavcodec-dev libx264-dev pkg-config`. + This runs inside the job's command. A dedicated image is a later optimisation + if the apt time hurts. +- Unit tests, `cargo test -p muninn-video-encoder`: + - the record round-trips; + - a stream of framed commands split at every byte boundary decodes + identically; + - `bitrate_kbps` of 249 and 100_001 is refused, and 250 and 100_000 are + accepted. At least one tested value must sit where a clamp would change + it; per SKILL, a clamp is the mutant to beat; + - a sequence gap or repeat is refused; + - many bitrate commands between two polls yield the last one; + - an IDR and a bitrate in one poll yield both. +- Integration test, spawning the built binary with `--input testsrc2=size=320x240:rate=30`, + `--encoder libx264`, `--gop-frames 1000` and `--frames 120`: + - Parse stdout with Muninn's `h264_annex_b_access_units`. The test + lives in `muninn-daemon`'s test module so it can reach the parser. + - After the 20th access unit, write an `idr` command. **Exactly one** keyframe + access unit appears in AUs 21-23. There is none elsewhere except AU 0, + because the GOP is 1000. + - After the 60th AU, write `bitrate 150` (down from 1500). The mean non-key + AU size over 90-120 is at most half the mean over 30-60. + - If libx264's in-session reconfigure does not honour this, the test must + say so, and fall back to asserting that the core received the value + (a dev-only counter on the C ABI). That fallback is recorded as **not yet + reached** for Linux, never as unreachable. +- `cargo mutants` on the Rust shell's diff. The C++ core has no mutation tool, + so it is defended behaviourally by the integration scenario (SKILL). + +### 6b: Muninn drives the encoder (Muninn repo) + +Depends on: +- Cut 2's `MediaSendCore` seam; +- Cut 5's parity policy, for the ceiling. + +**Deletes first:** +- `record_receiver_keyframe_pressure` (`M main.rs:3036-3048`) and its two call + sites in `run_rudp_mux_once`. +- The ffmpeg CLI video child: + - `rudp_video_ffmpeg_args` (`M :10343-10421`); + - `muninn_rudp_video_bitrate_arg`, `muninn_rudp_video_vbv_buffer_arg` and + `muninn_rudp_video_gop_frames` (`:10296-10311`), which move into encoder + options; + - the video `Command::new(&options.ffmpeg_path)` spawn in `run_rudp_mux_once`; + - `ffmpeg_args`; + - the CLI-argument tests (around `:12180-12335`), re-homed as encoder-options + tests where they pin a rule: GOP equals a quarter of the frame rate, and + the explicit bitrate. +- The `MuninnRudpMediaProfile` fields that fed only the CLI (`video_preset`, + `video_tune`, `video_b_frames`, `video_rc_lookahead`, `:10279-10285`). The + runtime-boundary JSON at `:3830-3847` loses them, and its `"recovery"` string + changes to what is now true. +- `ffmpeg_path` stays for the **audio** child until the Opus cut. + +**Adds:** +- `trait EncoderControl { fn request_idr(&mut self, cause: &str); fn set_bitrate(&mut self, kbps: u32, cause: &str); }` + as a port in `MediaSendCore`. + - The production implementation owns the encoder's `ChildStdin` on a + **writer thread** behind `sync_channel(8)`. + - **Rule: a control write never blocks the send loop.** When the channel is + full, a pending bitrate command is replaced by the newer one, and an IDR is + kept. + - The test implementation records the commands. +- `KeyframeRequestGate`, ported from `D main.rs:2864-2884` with the 500 ms + cooldown (`D :102`). It is fed the aggregate `requested_keyframes` counter + across hub receivers. Any receiver's new edge counts. +- `BitrateController`, rewritten from `D :2439-2512`: + - ceiling `= request.video_bitrate_kbps / (1 + r)`, where `r` is the video + parity overhead from Cut 5's policy, measured as parity bytes over data + bytes in the last second, not assumed; + - floor `= max(ceiling / 4, 1_000)`; + - start at the ceiling; + - each 500 ms sample, **back off** to ×0.85 on damage. Damage is new late + frames, a new keyframe request, new deferred repairs, new + `groups_dropped_video` (Cut 2), or jitter plus decode queue at or above 75% + of the request's budget; + - otherwise, **step up** by `ceiling / 50` after 10 s stable. These are the + donor code's values (`D :2502-2507`); its doc disagreed, and the Cut 5 + harness may retune the named constants; + - known limit, recorded: with many viewers, the worst receiver sets the + rate. +- Spawn: + - `--video-encoder ` resolves relative to the release directory, like + the loopback script; + - `--video-encoder-runtime-dir ` is prepended to the child's `PATH`, so + that the FFmpeg DLLs resolve; + - the child runs at the existing video priority class + (`media_child_priority`). + - A missing or failing encoder fails the request with a typed `detail` + (invariant 16). +- Observation (invariant 15): + - `idr_commands`, and `idr_observed` (a keyframe access unit from + `VideoAnnexBStreamSendState` within 3 frames of a command); + - `bitrate_commanded_kbps`, and `bitrate_observed_kbps` (encoded bytes per + second, 1 s window); + - all four in the progress line and the telemetry surface. + +**Rules (each pinned by a test on `MediaSendCore` with the recording +`EncoderControl`):** +- One keyframe-request edge gives exactly one `idr`. A second edge inside + 500 ms gives none. One edge at `cooldown + ε` gives one. The cooldown is + probed on both sides. +- A recoverable missing chunk (a feedback record with + `missing_video_chunk_keys` and `requested_keyframe = false`) gives no `idr` + (invariant 8). +- Damage in one sample gives exactly one ×0.85. It never goes below the floor. +- Stable for 10 s gives exactly one step. It never goes above the ceiling. +- The ceiling is **derived from the request**: test two request bitrates and + two parity ratios, with exact equality through a dev-only seam that records + the computed ceiling. Kill a clamp mutant. +- A stalled encoder stdin (the test writer never drains) does not stall + `MediaSendCore`. Assert the send loop's tick count keeps advancing. +- The Cut 2 harness, driven by a fake encoder that honours `idr` (a + file-backed Annex B source that emits a keyframe on command): under + `loss-3pct`, the receiver's frozen interval after a lost reference is + ≤ RTT + 2 frames, not the 250 ms GOP. + +**Verification:** Yggdrasil, `cargo test -p muninn-daemon` and +`cargo mutants --in-diff`. No GPU is needed. + +**Ledger:** about −220 (CLI child, args, tests and the log-only keyframe +handler) and +260 (port, gate, controller, spawn and observation). 6a adds +roughly +400: 230 of ported C++ and 170 of Rust shell and tests. + +### 6c: recipe, binding and Raven acceptance + +Build host **Raven** (Windows 11, MSVC, the NVIDIA driver). Target platform +**Raven**. Builder: Idunn's host actuator, `rust-host` runner, `cargo` only. + +**Prerequisites (not Hands):** +- Idunn B3 and `route/b3-declare` merged to Muninn `main` (B19). +- **Operator provisioning on Raven**, a one-time step like the firewall rule: + - unpack a pinned FFmpeg **shared** build with NVENC enabled (headers, import + libraries, DLLs) to `C:\GameCult\deps\ffmpeg--shared\`; + - record its URL and sha256 in `gamecult-ops/inventory.md` under Raven. + - Nothing in the deploy path can fetch it (B18). This gap is recorded for + Idunn (Substrate missing). + +**Recipe** (`Muninn/deployment/idunn/raven-muninn.toml`, on top of `2260853`): + + [[steps]] + id = "build-muninn-video-encoder" + phase = "build" + runner = "rust-host" + required_environment = ["MUNINN_FFMPEG_ROOT"] + argv = ["cargo", "build", "--locked", "--release", + "-p", "muninn-video-encoder", "--bin", "muninn-video-encoder"] + + [[steps]] + id = "accept-nvenc-control" + phase = "acceptance" + runner = "rust-host" + required_environment = ["MUNINN_FFMPEG_ROOT"] + argv = ["cargo", "test", "--locked", "--release", + "-p", "muninn-video-encoder", "--features", "nvenc-acceptance", + "--", "--exact", "nvenc_honours_idr_and_bitrate_commands"] + + [[artifacts]] + id = "muninn-video-encoder" + source_kind = "runner-output" + runner = "rust-host" + source = "target/release/muninn-video-encoder.exe" + destination = "muninn-video-encoder.exe" + executable = true + +In `[service]`: +- `required_adjacent_artifacts = ["muninn-video-encoder", "wasapi-loopback-capture"]`; +- the arguments gain `--video-encoder` → literal `muninn-video-encoder.exe`, and + `--video-encoder-runtime-dir` → binding `ffmpeg_runtime_dir`. + +The acceptance test sits behind a feature so that CI and Yggdrasil never select +it. It is the 6a integration scenario with `--encoder h264_nvenc` and +`--input testsrc2`, hardware encode from system-memory frames (no desktop +needed). So **the deploy itself refuses a Raven where NVENC cannot honour a +typed IDR or bitrate command**. Hands confirms that host-native `acceptance` +steps run before promotion (`I src/deployment.rs:71-77` declares the phase). +If they do not, this becomes a build-phase step, and that is recorded. + +**Binding** (`gamecult-ops/idunn/yggdrasil/bindings/raven-muninn.toml.in`, +gamecult-ops owns it, an operator-approved ops change): + + [runners.rust-host.environment] + MUNINN_FFMPEG_ROOT = 'C:\GameCult\deps\ffmpeg--shared' + [workload.argument_bindings] + ffmpeg_runtime_dir = 'C:\GameCult\deps\ffmpeg--shared\bin' + +Both are open maps. The binding vocabulary does not grow, so the actuator needs +no rebuild (`Idunn docs/host-actuator.md:112`). Hands verifies this against the +actuator's binding parser before sealing. + +**Deploy:** `sudo idunn up raven-muninn` from yggdrasil, per +`gamecult-ops/runbooks/idunn-host-raven.md`. It is the operator's action; Raven +is a human-used workstation (teardown-map L268-271). + +**What only Raven proves, live, with the operator present:** +- `ddagrab` with `h264_nvenc`: a receiver-requested IDR is **observed at + Ratatoskr** as a keyframe within one RTT plus one frame, while a game is + running (Raven at 93% CPU is the known condition). +- NVENC in-session reconfigure under a game. The donor recorded 12 → 6 Mbps at + frame 35 on 2026-07-17, on a pre-extraction body. +- `bitrate_observed_kbps` follows commands on the mesh-hairpin path (28 Mbps) + and backs off under it. +- DLL resolution from the release directory under the actuator's launch. +- **The payoff step.** Lengthening the scheduled GOP beyond a quarter second is + what IDR-on-request buys. Do it only after this acceptance, as a one-constant + change measured against the Cut 5 table and the live run. Until then the + 250 ms GOP stays as the fallback ceiling. + +**Ledger 6c:** recipe +25 lines, binding +4. --- -## HID edge: not mapped (Q1) +## HID edge for remote play: cuts H0-H5 (Q1 ruled) -The donor's HID work spans Muninn, Sleipnir (in Odin) and odin-core's HID -record, and it hardcodes channel names into the transport (B13). Its purpose -decides everything: -- whether edges are needed or snapshots suffice; -- whether the channel is reliable, or lossy with replay; -- whether this belongs in Muninn at all, or in the Sleipnir/Mimir input path. +**What it is for** (Q1, 2026-09-30): a viewer's controller drives a game on +another host, over LAN or mesh, so quick taps must survive loss. +- The **source** is Muninn on the viewer's host, capturing the pad. +- The **sink** is Sleipnir on the game host, which drives ViGEm. +- Today that sink is `raven-sleipnir`, Raven being the game host (B16). -Nothing is specified until Q1 is answered. When it is: -- the record moves with named-cut 1 (odin-core → Muninn) **first**, so the edge - record is born in its owner; -- delivery uses CultLib's profile-owned channel delivery, not hardcoded names. +**Ownership.** + +| Organ | Owns | Does not own | +|---|---|---| +| Muninn (viewer host) | Sampling; edge detection at sample time; the epoch; the state sequence; the unacknowledged-edge window and its bound; frame emission; applying acks to its window; answering subscriptions | Mapping, actuation, or deciding that an edge was applied | +| `muninn-contracts` (Muninn repo, new lib, H0) | The HID wire records; their validation and CultNet envelope; the **protocol state machines**, `EdgeWindow` (sender) and `EdgeCursor` (receiver), as pure code | Sockets, threads, devices | +| Sleipnir (game host) | Subscription; the cursor instance; mapping; **the single pad-commit primitive** (invariant 10); the visibility hold and budget (invariant 13); acks; neutralising on staleness | Edge creation, epochs, capture | +| CultLib | The `latest` channel: Unreliable and Sequenced, profile-declared (`C rudp.rs:2189-2197, 2384-2390`) | Anything HID-named (invariant 9). **No CultLib change.** | + +**Why one frame on `latest`, and not the donor's reliable `hid.edge` channel.** +- A frame carries the current state **and** every unacknowledged edge, up to 32. +- Each frame therefore supersedes the last, which is exactly what a sequenced + channel delivers: an older frame arriving late is dropped, and nothing is + lost by that. +- Loss costs nothing but the next tick, 2 ms at the current poll + (`HID_CONTROLLER_RUDP_POLL_INTERVAL`). +- There is no retransmit timer, no reliable window to stall, and no second + "assist" path. +- The ruling's "profile-owned channels" is met by using a channel the profile + already declares, with the delivery it declares. + +**How Odin `main`'s pin stays untouched while StreamPixels ships.** +- Nothing in H0-H5 commits to Odin `main`. +- Sleipnir's changes happen in Sleipnir's new home (Q9). Its odin-core comes + from the `pins/` tag (Q2 mechanism). `3e96c6c` already pins CultLib + `c2a9a6e`, Muninn's pin, so no new Odin commit is needed until Cut 3. +- From H3 on, Odin `main`'s `crates/sleipnir-daemon` is a **forbidden writer**: + no commits there. +- After StreamPixels ships, **one** Odin commit removes the crate from Odin's + workspace. It is a deletion, with no pin change and no other edit. +- Until then, two copies of the source exist and only one is built and + deployed. The Muninn extraction lived through this interval too + (teardown-map L628-629), and it is recorded as debt with its deletion line. + +### H0: shape of Muninn's named cut 1 (a constraint, not a new cut) + +Named cut 1 moves Muninn's 16 records out of odin-core. For H, it must place +them in a **library** crate, `crates/muninn-contracts` (`crate-type = rlib`), +not in `muninn-daemon`'s binary. + +- **Owner:** Muninn. +- **Live consumers:** `muninn-daemon`; Sleipnir, which imports + `MuninnHidControllerStateRecord` today (`S :12`); `muninn-video-encoder` + (6a). +- **Protected invariant:** each Muninn wire record has one definition across + repositories. +- **Why the existing owner cannot serve:** a binary crate cannot be a + dependency. +- **What it replaces:** Muninn records defined in Odin's odin-core. + +Its dependencies are `cultcache-rs`, `cultnet-rs`, `serde` and `anyhow`, at +Muninn's CultLib pin. + +### H1: HID wire records and protocol state machines (`muninn-contracts`) + +**Adds (types and rules; bodies are Hands'):** +- `muninn.hid_input_frame.v1`: + - `device_id`, `stream_id`; + - `epoch: u64`, which is never 0; + - `state_sequence: u64`; + - `source_timestamp_ns: i64`, telemetry only; + - `axes: Vec`; + - `buttons: Vec`, the held set **after** the last edge in this + frame's window; + - `edge_first_sequence: u64`; + - `edge_buttons: Vec`, `edge_pressed: Vec`, + `edge_captured_ns: Vec`: parallel arrays, equal length, at most 32, + contiguous from `edge_first_sequence`. + - Hands may use a nested record list instead of parallel arrays if the + `cultcache-rs` derive supports it at the pin. The rule, not the spelling, is + the contract. +- `muninn.hid_edge_ack.v1`: `device_id`, `epoch`, `applied_through: u64`. +- `muninn.hid_subscription.v1`: `subscriber_id`, `device_filter`, `stream_id`. + This replaces the JSON object at `S :2303-2306`. +- `MuninnHidWireRecord { Frame, Ack, Subscription }`, with + `encode`/`decode` through the CultNet message envelope. This is the same + pattern as CultLib's `encode_media_wire_record` + (`C media_stream_wire.rs:134-190`), with validation on both encode and decode. +- `EdgeWindow` (sender): + - `capture(buttons_now, captured_ns)` diffs against the last sample, then + appends edges: releases first, then presses (the donor order); + - `frame_edges() -> ≤32 oldest pending`; + - `ack(epoch, applied_through)`; + - overflow past 256 pending rotates the epoch (`+1`), sets `state_sequence` + to 0, clears pending, and reports the rotation to the caller, which counts + it. +- `EdgeCursor` (receiver): + - `accept_frame(epoch, state_sequence, first_seq, edges) -> Admission`; + - an epoch below the current one: fenced (a monotonic comparison, with no + set); + - a new, higher epoch: take `buttons` as the baseline, set + `applied_through = first_seq + len - 1`, and return no edges. Taps inside + the first frame of an epoch are carried by the baseline, not replayed. + **This is recorded as a deliberate loss at epoch start only.** + - the same epoch: return the edges with sequence above `applied_through`, in + order. Duplicates are dropped by sequence, and a gap past 256 is refused. + +**Rules that must die under their own mutation** (a property-style test drives +`EdgeWindow` → frames → a seeded drop, reorder or duplicate → `EdgeCursor`): +- Every edge captured is delivered **exactly once, in capture order**, under + every Cut 3b profile. Use the **same seed tables** as the media harness, so + that one impairment vocabulary serves both. +- A press and release captured in one sampling interval arrive as two edges, + press then release. +- The window in a frame is never above 32. Pending is never above 256. At 257, + the epoch rotates, and the next frame's epoch is exactly one more. +- An ack for a stale epoch changes nothing. An ack for `n` trims exactly + through `n`. +- The cursor rejects a frame from any epoch below its current one, including + `current − 1`. Kill the off-by-one comparison mutant. +- A frame at the maximum window, with the longest button names and 16 axes, + encodes to ≤ 1,200 bytes (`HID_CONTROLLER_RUDP_MAX_FRAGMENT_BYTES`), so it + never fragments (invariant 6's rule, applied to input). +- The frame round-trips, and a frame with unequal parallel arrays or a + non-contiguous window is refused on decode. + +**Verification:** `cargo test -p muninn-contracts` and `cargo mutants --in-diff` +on Yggdrasil. This crate is where the protocol is proven; H2 and H4 only wire +it. + +**Ledger:** about +450 (records, wire, two state machines and the property +test). It retires the donor's ~350 HID lines, which never land. + +### H2: Muninn sends frames (Muninn repo) + +**Deletes first:** +- The JSON subscription: `HidControllerRudpSubscription` (`M main.rs:6137-6142`) + and `serde_json::from_slice` (`:6216-6217`). +- The JSON state send (`:6298-6300`, `:6835-6836`). +- **The losing HID path, per Q10.** Either the ingress server (`:6144-6356`, + `--hid-controller-rudp-bind`) or the outbound client (`:6717-6860`, + `--hid-controller-rudp-target`, `:10891-10895`), with its options, its + advertisement fields (`:3619-3740`), and its tests. +- The per-tick read (`:6286`) as the place where edges exist. + +**Adds:** +- A capture thread per source, ported from `fb4f331`: + - XInput sampled every 1 ms (`D main.rs:5881`); + - Windows HID via the existing report reader, every report; + - joystick events as they arrive. + - Each sample goes to `EdgeWindow::capture` **on the capture thread**, and + the latest state goes into a slot the transport reads. + - Edges are never computed at transport time (B14). +- A transport tick at 2 ms: + - for each subscribed source, send one `hid_input_frame` on `latest`; + - apply received `hid_edge_ack`; + - take `hid_subscription`. + - A source with nothing new still sends at the 50 ms heartbeat + (`HID_CONTROLLER_RUDP_HEARTBEAT_AFTER`). +- `muninn.hid_controller_state.v1` stays exactly what it is: the Odin-published + **observation** for device discovery (`M :6858`). It is not a wire frame. + +**Authority map:** +- **Owner:** the `EdgeWindow` per source, on the capture thread. +- **Inputs:** device samples. +- **Outputs:** frames. +- **Forbidden writers:** + - the transport tick deciding edges; + - wall-clock time deciding freshness (it is telemetry only; donor doctrine, + `D docs/realtime-delivery-authority.md`); + - any JSON. +- **Shared paths:** live capture, reconnect (the window survives a + reconnection; the epoch survives until overflow or restart) and tests all go + through `EdgeWindow`. + +**Rules:** +- A tap shorter than one transport tick, from a scripted fake XInput source, + becomes two edges in the next frame. +- The frame stream from a fake source through a drop relay matches H1's + property on the wire. Assert on captured datagrams. +- `rg serde_json crates/muninn-daemon/src` finds no HID or subscription use. + +**Verification:** Yggdrasil. The XInput and Windows HID readers are `cfg(windows)`, +so the scenario uses a scripted source behind the same capture trait. +- **Only live proves:** real XInput sampling jitter on the viewer's host. +- **Starfire:** one Windows compile check of `muninn-daemon`, one job and no + burners (load budget). + +**Ledger:** about −250 (JSON paths, the losing transport path and its +advertisement) and +200. **Net about −50.** + +### H3: Sleipnir moves to its own home (Q9); behaviour-neutral + +Recommended per Q9 (a): **`GameCult/Sleipnir`**, created in the GameCult +organisation per project doctrine. + +- The source history comes from Odin with `git filter-repo --path + crates/sleipnir-daemon`. It is not a copy, so provenance survives. +- Dependencies: + - CultLib at Muninn's pin (`c2a9a6e`); + - `odin-core` from `pins/odin-core-cultlib-c2a9a6e` (`3e96c6c`, retagged per + the Q2 note); + - `muninn-contracts` at a Muninn revision (git, full sha); + - `vigem-client` unchanged. +- Pins move in lockstep with Muninn from then on. A guard test asserts that + Sleipnir's `muninn-contracts` resolves the same `cultcache-rs` source as its + own dependency. The "pin sibling checkouts" rule, applied to a git pin. +- **Deletes on the Odin side:** none now. Odin `main`'s copy becomes a + forbidden writer, and its removal is the post-ship Odin commit. +- **Verification:** + - `cargo test` on Yggdrasil (Linux, `LoggingBackend`). The existing 22 + Sleipnir tests (`S :2959-3660`) pass unchanged. + - The Windows build is proven by H5's recipe on Raven. + - `SleipnirInputMappingRecord` keeps coming from the odin-core tag. Moving it + into Sleipnir is a later subtraction, not this cut. + +### H4: Sleipnir applies edges (Sleipnir repo) + +**Deletes first:** +- The JSON subscription (`S :2303-2310`) and JSON decode (`:2497-2498`). +- Button coalescing, in which the latest record wins per device + (`coalesce_latest_*`, `:2543-2590`). Axes remain latest-wins, because they + are replaceable. +- Any path that writes `buttons` from a snapshot inside an epoch. + +**Adds:** +- `EdgeCursor` per subscribed device. +- An actuation queue drained by **one** `commit_pad(state)`, which is the + only caller of `VirtualPadBackend::update`. Frame axes, cursor edges, + epoch baselines and staleness neutralisation (`INPUT_STALE_NEUTRAL_AFTER`, + `S :28`) all go through it (invariant 10). +- The visibility hold of 24 ms, with the budget override at 100 ms: an edge + older than the budget is committed without the hold (invariant 13). +- `hid_edge_ack` for `applied_through` after each commit, and every tick while + nonzero, on `latest`. +- `hid_subscription` as a typed record every 1 s. + +**Rules (on a recording backend, asserting the pad timeline, which is the +layer the game samples):** +- A quick tap under `loss-5pct` and `burst-8`: the timeline shows press, then + release; the press is held ≥ 24 ms; nothing is doubled. +- Reordered and duplicated frames produce the same timeline as clean. +- A burst of 20 taps: every one appears. The last is committed no later than + 100 ms plus one tick after capture. Kill a mutant that removes the budget + override. Probe at `budget ± ε`. +- A frame from epoch `current − 1` after a rotation is ignored, and the pad + shows the new baseline. +- Silence for 1.5 s neutralises through `commit_pad`. Assert that the backend + was called by the same function (a dev-only call-site counter). +- End to end on Yggdrasil: Muninn's H2 sender with a scripted source, through + a seeded drop relay, to Sleipnir with a recording backend. The relay and + profiles are the Cut 3b tool's. The test lives in Sleipnir, with Muninn's + scripted-source sender reached through `muninn-contracts` plus a thin test + driver. + +**Verification:** `cargo test` and `cargo mutants --in-diff` on Yggdrasil. + +**Ledger:** about −120 (JSON, coalescing) and +180. **Net about +60.** + +### H5: deploy, and the viewer's side + +- **Sleipnir recipe** `deployment/idunn/raven-sleipnir.toml`, in the Sleipnir + repo: + - a `rust-host` build step, `cargo build --locked --release`, which builds + `vigem-client` on Windows; + - `[[dependencies]] odin.verse-rendezvous`, per Idunn's B3 ruling ("the + recipe declares readiness"), because Sleipnir publishes its Eve surface + to Odin; + - its presence contract, modelled on `idunn_presence.rs` in Muninn; + - the binding goes in gamecult-ops. +- **Retire** the legacy `raven-sleipnir` script target + (`idunn-deployment-targets.ps1:126-138`) in the same gamecult-ops change. + gamecult-ops owns it. +- **The viewer's Muninn**, per Q10. The viewer's host needs a Muninn that + captures the pad. For Starfire, that is the `starfire-muninn` target + rebound to an Idunn recipe; it is legacy today (teardown-map L74). A viewer + outside GameCult's hosts runs Muninn by hand. That limit is recorded, not + solved here. +- **Firewall:** the host that listens, per Q10, opens one UDP port. Under the + recommended direction that is the game host, Raven, which already opens + 5220 and 17887. +- **What only live proves.** Raven with a game, the operator present, and the + ported `xinput_edge_observer` example reading the ViGEm pad as the game + does: + - taps from Starfire's pad reach the game over LAN and over the mesh hairpin; + - the observer shows every tap at ≥ 24 ms visibility; + - end-to-end input latency. --- ## Sequencing -Against Muninn's named next cuts (teardown-map L644-668, L700-705) and the -StreamPixels ship: +Two tracks, media and input. They share Muninn's `main.rs`, so their Hands +run **serially in Muninn**, and in parallel only across repositories and +worktrees. -1. **Now, no contention:** Cut 0 and Cut 1 (Muninn docs and subtraction). They - touch neither the Idunn recipe nor any pin. -2. **Muninn named cut 3, retire `--idunn-rudp-health`:** - - it can run before or after Cut 1 on the same `main.rs`, serially, never - in parallel; - - it removes `IdunnDaemonHealthRecord`, one of the four Odin symbols (B11), - which shrinks the diamond; - - the three scripts that still pass the flag (`scripts/health-*.ps1`) go - with it. -3. **Cut 2 (bounded sender).** Muninn only, no pin. The latency default waits on - Q7. -4. **Muninn named cut 1, move 16 records out of odin-core:** - - it must land **before** any HID work (Q1); - - it is independent of FEC, because the media records are already in CultLib; - - it does not by itself unblock a CultLib bump, since the Eve records and - `OdinDocuments` remain (Q2). -5. **Muninn named cut 2, Opus:** - - it is the prerequisite for Cut 5's audio half if Q5 = after (B2); - - the video half of Cut 5 does not wait for it. -6. **Cut 3 (CultLib).** - - It runs in its own CultLib worktree. - - It is independent of Muninn's Hands, and can run in parallel with - steps 1-5 in a different repo and worktree. - - Soul passes before the tag. -7. **Pin gate (Q2).** An odin-core revision at Cut 3's CultLib pin, or a severed - odin-core. -8. **Cut 4 (Ratatoskr), then Cut 5 (Muninn).** Bump the pins in lockstep. -9. **Cut 6**, only if Q6 = (a), and only after the Cut 5 harness table shows - visible damage that FEC and repair do not cover. +**Now:** +1. **Cuts 0-1** (in Hands, `hands/rr-cut0-1`). +2. **Retag `3e96c6c` as `pins/odin-core-cultlib-c2a9a6e`** (Q2 note). This is a + tag only; Odin `main` is untouched. +3. **Muninn named cut 3** (retire `--idunn-rudp-health`). It removes one of + Muninn's four Odin symbols. It runs serially with the next item. +4. **Cut 2** (bounded sender and seam; Q7's 250 ms default). Muninn. +5. **Muninn named cut 1 in H0's shape** (`muninn-contracts`). Muninn, serially + after Cut 2 or before it; never in parallel on `main.rs`. +6. **In parallel, other repos:** Cut 3 (CultLib worktree; Soul passes before + the tag). + +**Input track** (after step 5): +7. **H1** (`muninn-contracts`). It can run parallel to Cut 3, in a different + repo. +8. **H2** (Muninn), after Q10. +9. **H3, then H4** (Sleipnir's new repo), after Q9. There is no CultLib bump + and no new `pins/` commit: both sit on `c2a9a6e`. +10. **H5**, after Idunn B3 (the recipe declares its Odin dependency). This is + operator deployment. + +**Media track:** +11. **Pin gate:** a single-purpose Odin commit bumps odin-core to Cut 3's + CultLib tag, parented on `3e96c6c`, tagged + `pins/odin-core-cultlib-`. Muninn, Sleipnir and Ratatoskr then move + their pins in lockstep. **Sleipnir moves too**, because it shares + `muninn-contracts`. +12. **Cut 4** (Ratatoskr), then **Cut 5** (Muninn video parity). +13. **Cut 6a** (after Cut 2; independent of Cut 5), then **6b** (after Cut 5, + for the ceiling), then **6c** (after `route/b3-declare` merges, Idunn B3, + and FFmpeg provisioning on Raven). +14. **Opus** (Muninn named cut 2), then **Cut 5's audio half** (Q5) and the + `audio` channel deletion taking effect (Q4). +15. **GOP lengthening:** the payoff of 6c, a single-constant change after live + acceptance. **StreamPixels ship:** -- Its critical path is Idunn B3, then merge `route/s3-c2`, back up `control.cc`, - the read-only check, and `idunn up` (morning file item 3). -- This campaign stays off it: - - no Odin `main` pin change (Odin `main` pins `a8aedda` for StreamPixels' - RUDP, `379b826`); - - no Idunn edits; - - no StreamPixels vendored-CultLib bump. -- Cut 3's tag is read-only to StreamPixels until StreamPixels chooses to move. +- no Odin `main` commits; +- no Odin pin change; +- no Idunn edits; +- no StreamPixels CultLib bump. -**Live verification on Raven waits for two Idunn events:** -- B3 lands; -- `raven-muninn`'s recipe gains its Odin declaration (Idunn `route-continuity-cut.md:32-35`: - "`raven-muninn` and Heimdall both publish to Odin, so their recipes declare - it"). +After the ship: the Odin commit that deletes `crates/sleipnir-daemon`, and +optionally Odin's own CultLib bump, which is the Odin Stability session's call. -Before that, `idunn up raven-muninn` may be refused at admission. **Muninn Hands -must not edit `deployment/idunn/raven-muninn.toml`** while that declaration is in -flight. Cut 6(a)'s recipe step is the only cut here that touches it, and it goes -last. +**Recipe contention.** Only 6c edits `raven-muninn.toml`, and only on top of +`2260853` after it merges. H5 creates `raven-sleipnir.toml` in a different +repository. -**Yggdrasil load.** Every harness and mutation run here goes through ygg-verify -(5 slots, shared). While StreamPixels' verification is running, cap this -campaign at one job at a time. All five slots were busy during this pass. +**Yggdrasil load.** One job at a time for this campaign while StreamPixels' +verification runs. 6a's apt install makes its jobs longer, so batch its unit +and integration runs into one job. --- ## Operator questions -One fork each, with a recommendation. Nothing downstream of an open question -gets written. +Q1-Q8 are ruled; see the Rulings block. Two forks are open. Neither blocks the +media track. -**Q1. What is the loss-tolerant HID edge for?** +**Q9. Where does Sleipnir live once it changes?** - Context: - - Today Muninn sends whole controller snapshots (`buttons` as a held set) - to Sleipnir. - - A press and release between two samples, or lost with its packet, never - reaches the virtual pad. - - The donor fixes that with ordered, acknowledged edges and epochs, across - Muninn, Sleipnir (Odin) and a patched transport. -- Candidate purposes, which lead to different machines: - - (a) **remote play**: a viewer's controller drives a game on another host, - over LAN or mesh, so quick taps must survive loss; - - (b) **same-LAN couch input**, where loss is rare and snapshots at a high - rate suffice; - - (c) input as **evidence** for Mimir or tracking, not actuation. -- Which hosts are the source and the sink, and over which path? -- Recommendation: answer this before anything is specified. Park the donor's - HID commits at the parked tag. If (a), the edge record is born in Muninn after - named-cut 1, and delivery uses CultLib's profile-owned channels. - -**Q2. How does Muninn get a CultLib pin with the FEC codec in it?** -- Context: - - Muninn's `odin-core` comes from Odin `3e96c6c`, reachable only through the - tag `attic/claude-cultlib-pin-c2a9a6e`. That commit's only change was to bump - odin-core's CultLib pin. - - odin-core's records are `DatabaseEntry`, so a Muninn CultLib bump without a - matching odin-core gives two `cultcache-rs` copies and a type mismatch. - - Odin `main` pins an **older** CultLib (`a8aedda`) for StreamPixels, and must - not move during the ship. + - Sleipnir is in Odin's workspace at Odin `main`'s CultLib pin (`a8aedda`). + That pin carries StreamPixels and must not move now. + - Consuming Muninn's HID records at Muninn's pin reopens the two-`cultcache-rs` + diamond inside Odin, and only moving that pin closes it (B16). - Options: - - (a) another single-purpose attic-tagged Odin commit that bumps odin-core to - Cut 3's pin (the `3e96c6c` precedent). Cheap, repeated per CultLib bump, - and invisible on any branch; - - (b) sever Muninn from odin-core first: named-cut 1, retire idunn-rudp-health, - and rehome the Eve records and `OdinDocuments` registration. This delays FEC - by those cuts; - - (c) keep the codec local to Muninn and Ratatoskr. **Rejected**: two codecs - (invariant 5). -- Recommendation: (a) for this campaign, with (b) continuing as Muninn's own - cuts. Record that each (a) is a debt paid again on every CultLib bump. Also - consider a `parked/` or `pins/` tag name instead of `attic/`, so the tag reads - as live. + - (a) **Own repo `GameCult/Sleipnir`**, with history from Odin. Its pins match + Muninn's, and odin-core comes from the `pins/` tag. Odin `main` deletes its + copy after the ship. This is the Muninn and Ratatoskr pattern: one organ, + one repo, one deploy target. + - (b) **A crate in Muninn's workspace.** Cheapest: one pin set, and the + contracts crate is internal. But the capture broker's repo then also owns + the actuator on another host with different privileges (ViGEm). + - (c) **Stay in Odin, on a branch**, until the ship, then bump Odin's pin. + This puts an off-`main` body on Raven for the whole interval, which is the + drift the doctrine forbids, and it blocks H3-H5 on the ship. +- Recommendation: **(a)**. Choose (b) if a new repository's overhead (CI, + pins, a recipe) outweighs the separation for now. Both avoid Odin `main`. -**Q3. Implement the erasure code, or depend on `reed-solomon-erasure`?** +**Q10. Which end dials, for remote-play input?** - Context: - - The donor's hand-written GF(256) has no multi-erasure video decoder and no - KAT. - - The crate was probed on Yggdrasil: exhaustive recovery at 4+2 and 8+4, any - shard length, about 11 µs per 8+4 block. It pulls `lru 0.7` and - `parking_lot 0.11`, and its last release is 2022. - - `reed-solomon-simd` is faster to encode but refuses odd shard sizes and - decodes in about 230 µs. -- Recommendation: depend on `reed-solomon-erasure` 6, without `simd-accel`, and - pin the bytes with a KAT so that the library, not our wire, is replaceable. - The fallback, if dependency age is disqualifying, is to port the donor - arithmetic plus a general Gaussian decoder (about 150 lines we own). - -**Q4. Delete the reliable `audio` channel and carry audio lossy with parity on -`media`?** -- Context: - - The channel was created on 2026-09-10 so audio could be reliable beside - lossy video. - - Its only purpose is reliability. Receivers dispatch by schema, not by - channel, so a lossy audio channel duplicates `media`. - - The teardown map's own fix direction (L256-261, L322-324) is audio lossy - with parity. -- Recommendation: yes. Delete it in CultLib Cut 3 (−15 lines of transport - special-casing), and move Muninn's audio in Cut 5. This reverses a recorded - decision, which is why it is asked and not defaulted. - -**Q5. Audio parity before Opus, or after?** -- Context: - - PCM packets are 3,840 bytes, which is 3 datagrams each (B2). Parity would - protect 3-fragment shards and cost about 1.5 Mbps at 4+2. - - Opus (Muninn's named cut 2, measured at 183 kbps) gives single-datagram - packets, and the donor's padded framing ports directly. -- Recommendation: after Opus. Cut 5 ships video parity immediately. The audio - half follows the Opus cut, and audio stays on today's reliable channel until - then, which is LAN-proven: 0 expired on 2026-09-11. - -**Q6. Encoder control: is IDR-on-request and bitrate adaptation worth a native -encoder?** -- Context: - - Recovery today is a quarter-second all-IDR GOP (`-g fps/4 -forced-idr 1`). - A lost reference freezes for at most 250 ms whether or not anyone asks. - - Asking for an IDR only helps if the GOP gets longer, which saves the bitrate - those IDRs cost. - - The ffmpeg CLI cannot take a live IDR or bitrate command. The donor solved - this with a 265-line C++ libavdevice/NVENC child, proven live on 2026-07-17 - on a pre-extraction body. + - Today Sleipnir dials Muninn's HID listener (Raven:17887). Muninn also has + an outbound path (B15). + - In remote play, Muninn runs on the **viewer's** host. If Sleipnir dials, + every viewer opens an inbound UDP port. + - That is what the 2026-09-10 media inversion ruled out for viewers + (teardown-map L486-495): "not something a user can be asked for". - Options: - - (a) port the native encoder, with an Idunn recipe step on Raven; - - (b) keep the CLI and the 250 ms GOP; no IDR request, no adaptation; - - (c) keep the CLI with NVENC `-intra-refresh 1` and a long GOP. This removes - the IDR spikes and bounds recovery by the refresh period, but still gives - no requested IDR and no bitrate adaptation. -- Recommendation: (b) now. Decide between (a) and (c) on Cut 5's harness table - and the live hairpin run. Build (a) only if the stream visibly fails where - bitrate adaptation would have helped. This is the one cut in the campaign that - buys a new native target. - -**Q7. What is the default latency budget?** -- Context: - - The producer defaults to 2,000 ms. The receiver gives up at 250 ms (the - July ledger's recovery budget). - - The request owns the budget (invariant 1), but Ratatoskr sends 0 and so - inherits the 2 s default. - - FEC recovers within one frame. NACK repair needs a few RTTs: under 1 ms on - LAN, about 75 ms on the mesh hairpin. -- Recommendation: 250 ms default in the advertisement, with both ends deriving - from the request. A consumer on a slow path asks for more. - -**Q8. Parity rate: fixed, or adaptive to observed loss?** -- Context: - - At 25-50% overhead, RS blocks cut iid frame failure by 2-3 orders of - magnitude compared with today's XOR (probe table). - - Overhead against the 28 Mbps hairpin at 12 Mbps video is significant. - - Adaptive needs new receiver-feedback fields (received, recovered and lost - chunk counts) and a controller. -- Recommendation: fixed in Cut 5, at `k ≤ 16`, `m = max(2, ⌈0.25k⌉)` for video - and 4+2 for audio, carried per record. Revisit with the live hairpin numbers. - Adaptive is a later cut with its own feedback-record extension. + - (a) **The viewer's Muninn dials the game host's Sleipnir.** Sleipnir + listens and advertises its endpoint through Odin, as Muninn does for media. + Delete Muninn's ingress server. + - (b) **Keep Sleipnir dialling Muninn.** Delete Muninn's outbound client. + Every viewer admits inbound UDP. +- Recommendation: **(a)**, consistent with the media ruling. The game host + already admits UDP. Consequence: Sleipnir gains a listening + `CultNetRudpServerHub`, and **subscription** becomes Sleipnir telling each + attached Muninn which device it wants, over the same session. The records + are unchanged. --- @@ -972,6 +1556,18 @@ encoder?** - **No synthetic media source anywhere on the path.** Every earlier measurement needed Raven, a GPU and a game. Cut 2's seam is the first harness that runs off Raven. +- **Idunn host-native targets cannot fetch pinned inputs.** + `external_inputs` are refused on host-native materialisation (`I host.rs:953-956`). + So Raven's FFmpeg development root is hand-provisioned and verified only by + `build.rs`'s version pin and the inventory's sha256. Every future Windows-host + native dependency hits this. The requirement belongs to Idunn: materialise a + sha-pinned archive on a host-native runner. +- **No C++ CultNet runtime.** The encoder's typed command channel needs a Rust + shell around the C++ core (6a). Every native child with a control channel + will pay this, and the alternative (hand-decoding MessagePack in C++) is the + Mimir receiver scar. The Rust-shell-over-C-ABI pattern (Ratatoskr's FFI, + `muninn-move-tracker`'s staticlib) is the house answer until a need justifies + a C++ runtime. ## Appendix A: probe logs @@ -980,3 +1576,6 @@ In this session's scratchpad: - `muninn-media-tests.log` (78 pass); - `rs-probe.log` and `rs-probe/` (the scratch crate, commit `656865b`); - `ratatoskr-tests.log` (31 + 2 pass at `488b5b1`). + +Pass 2 ran no new builds. Its claims are source reads at the named SHAs. The +6a, H1 and H4 harnesses are the first executions of those designs. From 66e8642f59e073f6f73d62561960f819bf433c32 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 16:02:10 +0200 Subject: [PATCH 16/44] Record HID rulings Q9 (Sleipnir in Muninn's workspace) and Q10 (Muninn advertises input streams) Co-Authored-By: Claude Opus 5.5 --- docs/realtime-robustness-cut.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/realtime-robustness-cut.md b/docs/realtime-robustness-cut.md index 92f5d5b..a18d713 100644 --- a/docs/realtime-robustness-cut.md +++ b/docs/realtime-robustness-cut.md @@ -58,6 +58,16 @@ the ruled design. The earlier options survive only in git (`e70db69`). until nothing references it, and cut the next `pins/` commit only at Cut 3's CultLib tag. - Q6 = (a) makes Cut 6 a real cut (6a-6c below). +**HID rulings, 2026-09-30.** +- **Q9: Sleipnir becomes a crate in Muninn's workspace.** It does not get its own repo, and it does not + stay in Odin. Odin's copy is deleted after the StreamPixels ship. +- **Q10: the consumer asks Muninn, and Muninn advertises the capability.** This is the opposite of the map's + viewer-dials recommendation. Operator: "Ratatoskr is asking Muninn to open a video stream, Sleipnir asks + Muninn to open an input stream. Both should be Muninn capabilities which it chooses to broadcast via + CultMesh." So Muninn publishes an input-stream capability through CultMesh beside its media capability, + and Sleipnir requests it the way Ratatoskr requests video. The HID cuts H0-H5 need re-mapping to this + shape before Hands. + ## Target: ends and invariants **End.** A Muninn stream that loses packets degrades by what each signal class From 88f9ed7ccdbdbef5a6c4c56f849d9f85d3171394 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 16:02:33 +0200 Subject: [PATCH 17/44] Collapse the video parity wire builder to one frame; test stale-identity pruning without bluetoothctl video_wire_records_with_parity keeps only its single-frame caller. The stale move-identity prune is split out of reconcile_move_identity_records so its test no longer shells out to the host Bluetooth binary. Co-Authored-By: Claude Sonnet 5 --- crates/muninn-daemon/src/main.rs | 10 +++++- crates/muninn-daemon/src/media_packetizer.rs | 32 +++++--------------- 2 files changed, 17 insertions(+), 25 deletions(-) diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index 6263f07..7857ad3 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -1827,7 +1827,14 @@ fn reconcile_move_identity_records( ) -> Result<()> { publish_move_identity_records(node, options, sources)?; publish_bluetooth_move_identity_records(node, options, active)?; + prune_stale_move_identity_records(node, options, sources) +} +fn prune_stale_move_identity_records( + node: &mut cultmesh_rs::CultMeshNode, + options: &Options, + sources: &[MoveStateSource], +) -> Result<()> { let current_ids = current_move_identity_records_from_sources(options, sources)? .into_iter() .map(|identity| identity.identity_id) @@ -14325,7 +14332,8 @@ Device 00:07:04:A8:00:D0 (public) hidraw_path: "windows-psmove://current".to_string(), }]; - reconcile_move_identity_records(&mut node, &options, ¤t, &[]).unwrap(); + publish_move_identity_records(&mut node, &options, ¤t).unwrap(); + prune_stale_move_identity_records(&mut node, &options, ¤t).unwrap(); assert!( node.get::("starfire:move-0006f523e2d1:move-identity") diff --git a/crates/muninn-daemon/src/media_packetizer.rs b/crates/muninn-daemon/src/media_packetizer.rs index 9fe62c5..d814944 100644 --- a/crates/muninn-daemon/src/media_packetizer.rs +++ b/crates/muninn-daemon/src/media_packetizer.rs @@ -688,31 +688,15 @@ pub fn build_video_parity_shards( } fn video_wire_records_with_parity( - records: &[GameCultMediaVideoAccessUnitRecord], + frame_records: &[GameCultMediaVideoAccessUnitRecord], ) -> Result> { - let mut wire_records = Vec::new(); - let mut offset = 0_usize; - while offset < records.len() { - let first = &records[offset]; - let mut end = offset + 1; - while end < records.len() - && records[end].stream_id == first.stream_id - && records[end].session_id == first.session_id - && records[end].frame_id == first.frame_id - { - end += 1; - } - let frame_records = &records[offset..end]; - wire_records.extend( - frame_records - .iter() - .cloned() - .map(GameCultMediaWireRecord::Video), - ); - for parity in build_video_parity_shards(frame_records)? { - wire_records.push(GameCultMediaWireRecord::VideoParity(parity)); - } - offset = end; + let mut wire_records: Vec = frame_records + .iter() + .cloned() + .map(GameCultMediaWireRecord::Video) + .collect(); + for parity in build_video_parity_shards(frame_records)? { + wire_records.push(GameCultMediaWireRecord::VideoParity(parity)); } Ok(wire_records) } From b607592be28eae636607cd3457b409903fb52d47 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 16:02:33 +0200 Subject: [PATCH 18/44] Correct keyframe, GOP, and provenance claims in the media docs Co-Authored-By: Claude Sonnet 5 --- docs/muninn-media-streaming.md | 3 ++- docs/teardown-map.md | 11 ++++++----- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/muninn-media-streaming.md b/docs/muninn-media-streaming.md index e2f411b..0eefb53 100644 --- a/docs/muninn-media-streaming.md +++ b/docs/muninn-media-streaming.md @@ -239,7 +239,8 @@ Recommended first LAN profile: - Profile id: `muninn.rudp.low_latency_h264_lan.v1`. - Video: H.264 NVENC, `p5` (`main.rs:10279`), ultra-low-latency tune, CBR high enough that LAN bandwidth is not the constraint, no B-frames, no lookahead, short GOP or - intra-refresh, periodic IDR/keyframe on feedback pressure. + intra-refresh, keyframe actuation on feedback pressure (not built: keyframe requests are only + counted and logged today; Cut 6 builds it). - VBV: derive `bufsize` from roughly one frame of bitrate (`bitrate_kbps / framerate`) instead of a large fixed encoder reservoir. The point is bounded latency, not hoarding compressed video in a nicer hat. diff --git a/docs/teardown-map.md b/docs/teardown-map.md index 5cd5629..69356c3 100644 --- a/docs/teardown-map.md +++ b/docs/teardown-map.md @@ -609,13 +609,13 @@ Three repos where there was one crate, and a contract neither of them owns. | Repo | Role | State | |---|---|---| -| CultLib `main` `05e0925` at the time of writing (media contract unchanged since `c2a9a6e`; `main` is now `069ecc3`) | the contract | media records, wire envelope, validation, channel delivery | +| CultLib `main` `05e0925` at the time of writing (media contract unchanged since `c2a9a6e`) | the contract | media records, wire envelope, validation, channel delivery | | Muninn | producer | speaks the shared contract; blocked on one pin (below) | | Ratatoskr | consumer | decodes the envelope; builds clean, no conflicts | ### The one thing blocking a clean Muninn build (history; resolved) -Resolved 2026-09-11 (see the Raven section below): `Cargo.lock` is tracked (`60ed6b2`) and the pins are the build. The build resolves `odin-core` from Odin `3e96c6c`, which no Odin branch holds; only the tag `attic/claude-cultlib-pin-c2a9a6e` keeps it reachable. The text below is the state on 2026-09-10. +Resolved 2026-09-11 (see the Raven section below): `Cargo.lock` is tracked (`70d267f`) and the pins are the build. The build resolves `odin-core` from Odin `3e96c6c`, which no Odin branch holds; only the tag `attic/claude-cultlib-pin-c2a9a6e` keeps it reachable. The text below is the state on 2026-09-10. `odin-core` pins CultLib `c13b6ba`; Muninn needs `05e0925`. Cargo resolves two `cultcache-rs` copies and `DatabaseEntry` from one is not `DatabaseEntry` from @@ -656,7 +656,7 @@ one once the patch is gone. Muninn-specific `obs_stream_catalog` / `capture_stream_command` stay published beside them until nothing reads them. The old plugin's CLI shell-out and `.cc` snapshot are not ported. The connection direction was - inverted the same day (section above). Exercised live 2026-09-10/11 on `bc43e1b` and later + inverted the same day (section above). First live frames on `58e8663` (2026-09-10); exercised through 2026-09-11 on `bc43e1b` and later (measurements below); the 2026-09-10 note that Raven ran a pre-b679fc2 Muninn is history. 3. **Opus.** Unblocked and measured at 16.8x. `-f aac` in the receiver becomes codec-driven; framing follows the `aac-adts-padded-v1` precedent (2-byte @@ -666,8 +666,9 @@ one once the patch is gone. live counterpart. `build_receiver_feedback` moved to CultLib (34c8ea7) and stopped implying a keyframe request from missing chunks (4160ab5): a repair request is the alternative to one. The sender counts keyframe requests and logs them; - it does not force an IDR (`main.rs:3036-3048`). Recovery today is the fixed all-IDR GOP - of `framerate/4` frames. + it does not force an IDR (`main.rs:3036-3048`). Recovery today is the fixed GOP: + every GOP keyframe is an IDR, at a GOP of `framerate/4` frames (`-forced-idr 1`, `-g`, + `-keyint_min`, `main.rs:10405-10410`); not every frame. ### Deliberate breaks, both recorded as passing tests From fe33ce7f107974638e2786ada3d2d462ba73930c Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 19:55:22 +0200 Subject: [PATCH 19/44] Re-map the HID cuts H0-H5 to Q9 and Q10 (Imagination pass 3) Sleipnir moves into the Muninn workspace with its history. Input mirrors the media request path: Muninn advertises an input stream on CultMesh, the consumer requests it and dials. Opens Q11-Q13. Co-Authored-By: Claude Opus 5.5 --- docs/realtime-robustness-cut.md | 1044 +++++++++++++++++++++++-------- 1 file changed, 786 insertions(+), 258 deletions(-) diff --git a/docs/realtime-robustness-cut.md b/docs/realtime-robustness-cut.md index a18d713..f52f1ef 100644 --- a/docs/realtime-robustness-cut.md +++ b/docs/realtime-robustness-cut.md @@ -11,10 +11,10 @@ adaptation, and a loss-tolerant HID edge for remote play. | | | |---|---| -| Map state | Imagination pass 2. Q1-Q8 were ruled on 2026-09-30 (below). Pass 2 maps Cut 6 in full (Q6 = a) and the HID cuts H0-H5 (Q1 = remote play). Two new forks are open: Q9 (Sleipnir's home) and Q10 (HID connection direction). | +| Map state | Imagination pass 3. Q1-Q10 are ruled (below). Pass 2 mapped Cut 6 in full (Q6 = a); pass 3 re-maps the HID cuts H0-H5 to Q9 (Sleipnir is a crate in Muninn's workspace) and Q10 (Muninn advertises an input-stream capability; the consumer requests it and dials). Three new forks are open: Q11 (who owns the input-stream records), Q12 (Move evidence rides the HID listener), Q13 (whether Raven's Sleipnir is live, which gates the H2/H4 merge). | | In Hands | Cuts 0-1 on `hands/rr-cut0-1` (`2c120c9`, `f2a5db9`, `a189363`). This pass does not touch those sections. | -| Ready for Hands | Cut 2 (the latency default is settled by Q7); Cut 3 (Q2-Q4, Q8 settled); H1 (after H0); Cut 6a (after Cut 2) | -| Blocked | Cut 4 (on Cut 3's tag); Cut 5 (on the pin gate); Cut 6b (on Cut 2 and Cut 5); Cut 6c (on Idunn B3 and `route/b3-declare` merging, and on FFmpeg provisioning on Raven); H3-H5 (on Q9, Q10) | +| Ready for Hands | Cut 2 (the latency default is settled by Q7); Cut 3 (Q2-Q4, Q8 settled); H1 (after H0, and after Q11); H3 (any time; behaviour-neutral); Cut 6a (after Cut 2) | +| Blocked | Cut 4 (on Cut 3's tag); Cut 5 (on the pin gate); Cut 6b (on Cut 2 and Cut 5); Cut 6c (on Idunn B3 and `route/b3-declare` merging, and on FFmpeg provisioning on Raven); H2 (on Q12); the H2+H4 merge to `main` (on Q13 and H5 readiness, because `raven-muninn` deploys `main`'s head); H5 (on Idunn B3) | | Heads read | Muninn `origin/main` `eb332b0` (code identical to `cee7b9c`), `route/b3-declare` `2260853`; CultLib `069ecc3`; Ratatoskr `488b5b1`; Odin `main` `379b826`; donor Odin `80adfd3`; Odin tag `attic/claude-cultlib-pin-c2a9a6e` `3e96c6c`; Idunn `771138a`; gamecult-ops working tree (binding `idunn/yggdrasil/bindings/raven-muninn.toml.in`, `scripts/idunn/idunn-deployment-targets.ps1`) | The CultLib media plane is byte-identical between Muninn's pin `c2a9a6e` and @@ -130,16 +130,22 @@ Invariants. Each one must be falsifiable by a test or a probe. acknowledged. No reliable channel carries input, so there is no retransmit debt and no head-of-line blocking. 12. **Input memory is bounded on both ends.** - - The sender keeps at most 256 unacknowledged edges per source, and - rotates the epoch on overflow (donor rule, `D main.rs:5846-5854`). - - A frame carries at most 32. + - The sender keeps at most 256 unacknowledged edges **per (subscriber + session, device) window**, and rotates that window's epoch on overflow + (donor rule, `D main.rs:5846-5854`). One lossy subscriber never forces + another to rebaseline. + - A frame carries at most `MAX_EDGES_PER_FRAME` (32, or less if H1's + worst-case encode test says 32 does not fit one datagram). - The receiver buffers nothing beyond the window it was sent. - Stale epochs are fenced by monotonic comparison, not by a growing set (the donor's `retired_epochs: HashSet`, `DS main.rs:210`, grows forever). -13. **Input latency is bounded.** A queued edge is held visible for 24 ms - (`DS main.rs:32-35`, one 60 Hz game sample plus margin) **unless** it is - older than the input budget (100 ms default). Then it is actuated without - the hold. A tap is compressed, never dropped. +13. **Input latency is bounded, and the bound is owned by the request.** A + queued edge is held visible for 24 ms (`DS main.rs:32-35`, one 60 Hz game + sample plus margin) **unless** it is older than `input_budget_ms`. Then it + is actuated without the hold. A tap is compressed, never dropped. The + budget is Q7's shape applied to input: the advertisement carries the + default (100 ms), the request carries the value, and both ends derive from + the request. 14. **No JSON on a live wire.** Muninn↔Sleipnir today speaks JSON both ways (B14), and the donor did too (`D main.rs:6117,6141`, `DS main.rs:693-699`). Every HID and encoder-control message becomes a typed CultCache record in @@ -330,14 +336,20 @@ contract (`a250ec6` onward), and the consumer-dials-producer inversion. - **Sleipnir keeps only the latest record per device** (`S :2543-2590`), so a tap that survived capture dies again at the sink. -**B15. Muninn has two HID transport paths.** -- An ingress server that Sleipnir dials: `--hid-controller-rudp-bind`, - `M :6144-6356`. This is the one Raven runs (recipe `raven-muninn.toml:62-65`, - advertised `10.77.0.4:17887`). -- An outbound client that dials a target: `--hid-controller-rudp-target`, - `M :6717-6860`, `:10891-10895`. -- Both speak JSON on `latest`. Two paths for one signal is the split Q10 - settles. +**B15. Muninn has two HID transport paths, and so does Sleipnir.** +`M` here is Muninn `main` `c3520d1`; HID lines moved +7 to +9 since `eb332b0`. +- Muninn listens: `--hid-controller-rudp-bind`, `M :6151-6340`. This is the one + Raven runs (recipe `raven-muninn.toml:62-65`, advertised `10.77.0.4:17887`), + and Starfire's legacy script can run it too + (`restart-starfire-muninn.ps1:14-15, 74-79`). +- Muninn dials: `--hid-controller-rudp-target`, `M :6724-6863`, parsed at + `:10899-10904`. +- Sleipnir mirrors both: it dials a discovered endpoint, or listens on + `--rudp-bind` (`S :2191-2281`, server branch `:2244-2281`). +- **Q10 settles it:** the consumer dials the producer's advertised endpoint, + exactly as Ratatoskr dials Muninn for video. The surviving direction is + "Muninn listens, Sleipnir dials". Muninn's outbound client and Sleipnir's + listening mode are the losing paths; H2 and H4 delete them. **B16. Sleipnir is welded into Odin's pin.** - `S` is a member of Odin's workspace. It takes `odin-core` by path @@ -376,6 +388,68 @@ libraries. `deployment/idunn/raven-muninn.toml`. Cut 6c edits the same file and must build on it after it merges. +**B20. Move evidence rides the HID listener, and Mimir consumes it.** +- `serve` gets the Move-evidence sender back from + `start_hid_controller_rudp_ingress` (`M :429-437`), and the ingress thread + sends it on channel `move-evidence` over the HID connection id + (`M :6271-6283`). +- It sends only while an HID subscription is selected (`M :6258-6269`), so a + consumer that wants Move evidence must speak the JSON `hid.subscribe`. +- Mimir does exactly that: `MimirOdinMoveProofEvidenceRingProvider.cs:223` + (Mimir `d88f2e6`) sends `{"streamId": ...}` on `hid.subscribe`. It discovers + the endpoint from the JSON `inputStreams` in Muninn's Eve provider + advertisement (`M :3713-3722`), channel `move-evidence`. +- The local ring is switched on by the absence of the HID bind + (`local_ring_enabled: options.hid_controller_rudp_bind.is_none()`, + `M :4238`). +- So deleting the JSON subscription (H2) silently stops Move evidence reaching + Mimir. The pass-2 map did not know this second consumer existed. Q12. + +**B21. HID discovery is JSON scraped out of Eve advertisements.** +- Muninn writes its HID endpoint and devices as JSON into three places in + `publish_runtime_boundary_records`: the transport profile's `input_streams` + (`M :3674-3699`, key at `:3856`), the provider advertisement's + `inputStreams` (`M :3701-3727`, key at `:3885`) and its `endpoints` + (`M :3729-3750`), in two casings. +- Sleipnir recovers it by pulling `muninn.hid_controller_state.v1` records to + learn host ids (`S :978-1003`), then pulling those hosts' provider + advertisements (`S :950-975`), then parsing JSON in either casing and in + tuple shape (`S :1845-2131`, `:2370-2478`), with Odin's generic + `discover_provider_endpoints` as a fallback (`S :2380-2398`). +- The video capability has none of this: one typed advertisement, one typed + request (`R catalog.rs:64-145`, `M :971-1166`). That typed path is what Q10 + orders input to mirror. +- The Odin-facing `publish_hid_controller_state_to_odin` (`M :6865-6875`, a + store `put` keyed by stream id) has **one reader**: Sleipnir's discovery. + Nothing else in Odin, Mimir, Ratatoskr, StreamPixels, Eve, VoidBot, Heimdall + or Idunn names the schema (`git grep`, 2026-09-30). + +**B22. Two readers own the same HID devices.** +- The serve tick reads every source to build receipts + (`publish_move_controller_states`, `M :4976-5134`). +- The ingress thread reads the same sources again at its own tick + (`read_hid_controller_state_for_stream`, `M :6377-6528`). +- The collision is fenced, not removed: on Windows the tick skips PS Move + sources whenever the HID bind is set (`M :5081-5086`), because the report + reader thread would otherwise have two consumers. +- Neither reader samples fast enough for a tap. The ingress loop sleeps 8 ms + (`M :6338`), and Sleipnir's default interval is 8 ms (`S :2791`). The + pass-2 map's "2 ms at the current poll (`HID_CONTROLLER_RUDP_POLL_INTERVAL`)" + is the **donor's** constant (`D main.rs:5879`). It does not exist at `c3520d1`. + +**B23. A producer restart orphans every running request.** +- `sync_media_stream_requests` admits only requests in state `pending` + (`M :1004`). The "already answered" memory is process-local + (`answered_requests`, `M :463`). +- So after a Muninn restart, every request it had answered `running` stays + `running` on Odin and is never admitted again. The consumer must notice and + publish a fresh request. +- Whether Ratatoskr re-requests is **unverified** (the redial lives in + `R receiver.rs`, and the request lives in the OBS plugin's C). +- H2 does not copy this. An input request is admitted as **demand**, by + `action`, and its `state` is only the producer's answer. The same change for + media belongs to Muninn's media owner and is recorded, not made, here. + --- ## Donor ledger: port, rewrite, drop @@ -392,7 +466,7 @@ on it after it merges. | `MuninnVideoBitrateController` (`D :2439-2512`) | **Rewrite** (Cut 6b) | Its ceiling halving assumes 50% FEC overhead, and its doc and code disagree. The rewrite keys the ceiling on the ruled parity rate and aggregates across hub receivers, which the donor predates. | | `native/muninn-video-encoder/main.cpp` (265 lines) | **Port** the capture and encode loop (Cut 6a). **Rewrite** its shell. | Kept: the lavfi → decode → encode loop, NVENC options, `pict_type = I` and `AVCodecContext` bitrate mutation. Deleted: `main`, `parse_options`, the `std::getline` text command thread, `fail()`/`exit`, and `fwrite` to stdout. They become a C ABI (`muninn_encoder_run` with poll and write callbacks) under a Rust `main` that decodes typed command records (invariant 15). | | `CMakeLists.txt`, `scripts/build-muninn-video-encoder.ps1` | **Drop** | `build.rs` with the `cc` crate compiles the C++. The Idunn runner may run only `cargo` (B18). The script's FFmpeg path no longer exists. | -| `capture_button_edges`, `ActiveHidControllerRudpSource` edge fields, overflow epoch rotation (`D main.rs:5732-5856`) | **Rewrite** into `muninn-contracts::hid::EdgeWindow` (H1). Capture calls it on the sampling thread (H2). | The rotation and bound rules are right. The donor ran them at transport-tick time, which loses sub-tick taps (B14), cloned `epoch` needlessly, and sent JSON. | +| `capture_button_edges`, `ActiveHidControllerRudpSource` edge fields, overflow epoch rotation (`D main.rs:5732-5856`) | **Rewrite** as two pieces in `muninn-contracts::hid` (H1): `EdgeDetector` (diffs samples; runs on the capture thread, H2) and `EdgeWindow` (per subscriber session and device; owns epoch, pending bound and acks; runs on the input transport tick, H2). | The rotation and bound rules are right. The donor ran detection at transport-tick time, which loses sub-tick taps (B14); it kept one window per source, which cannot serve two subscribers; it cloned `epoch` needlessly; and it sent JSON. | | Donor's `hid.edge` (reliable) + `hid.edge.assist` (unreliable resend) channels and the `hid.subscribe`/`hid.edge.ack` JSON | **Drop** | Two mechanisms for one job, plus four transport name arms (invariant 9). Replaced by one frame on the profile-declared `latest` channel that carries state and the unacknowledged window (invariant 11). | | `HidSemanticCursor` (`DS main.rs:204-256`) | **Port** into `muninn-contracts::hid::EdgeCursor` (H1), with the `retired_epochs` set **replaced** by a monotonic epoch fence | The ordering, dedupe and gap bound (256) are right. The unbounded set is not (invariant 12). | | `INPUT_EDGE_MINIMUM_VISIBILITY` 24 ms and the actuation queue (`DS main.rs:32-35, 655-700`) | **Port** into Sleipnir (H4), with the budget override added | Invariant 13. The donor queue has no latency ceiling. | @@ -461,11 +535,13 @@ What it does **not** own: | Keyframe request | `requested_keyframe` on feedback | Counted per receiver. It is an edge: at most one IDR per 500 ms cooldown per stream. | Receiver asserts. Muninn's gate decides (6b). | | Encoder command `muninn.video_encoder_command.v1` | `(encoder process, command_sequence)`. The sequence is monotonic from 1 per spawned encoder process. | Lives only on the stdin pipe. Never stored. It dies with the process; a respawn restarts the sequence at 1. | Muninn's `EncoderControl` writes. The encoder applies at the next frame. **Effect is observed from the bitstream**, not acknowledged. | | Live encode bitrate | Observed bytes per second over a 1 s window | Moves within `[floor, ceiling]` from the request's `video_bitrate_kbps` and the parity rate | Muninn's bitrate controller (6b) | -| HID epoch | `(device_id, epoch: u64)`. The epoch is the sender's monotonic start time in ns, and `+1` on overflow rotation. | New per Muninn process start and per overflow. The receiver fences any epoch below its current one. | Muninn (sender). Sleipnir only fences. | -| HID state sequence | `(device_id, epoch, state_sequence)` | Monotonic per epoch. Each frame supersedes the last (the `latest` channel is sequenced). | Muninn. | -| HID edge | `(device_id, epoch, edge_sequence)`, contiguous from 1 per epoch | Pending until acknowledged. Resent in every frame while pending, at most 32 per frame and 256 held. Overflow rotates the epoch and drops the history. | Muninn creates at sample time. Sleipnir applies in order and acknowledges cumulatively. | -| HID edge ack `muninn.hid_edge_ack.v1` | `(device_id, epoch, applied_through)` | Cumulative and idempotent. Resent each Sleipnir tick while nonzero. | Sleipnir. | -| HID subscription `muninn.hid_subscription.v1` | `(subscriber_id)` | Resent every 1 s (today's cadence, `S :2295-2302`). The newest wins. | Sleipnir. | +| Input-stream advertisement `muninn.input_stream_advertisement.v1` (Q11) | `stream_id` (`muninn..input`) | Republished on the same cadence and at the same site as the media advertisement. State `available` / `streaming` / `unavailable`. | Muninn (producer). | +| Input-stream request `muninn.input_stream_request.v1` (Q11) | `input_stream_request_key(stream_id, receiver_id)` | The consumer publishes `start` or `stop`. The producer admits it **as demand**, by `action`, not by `state` (B23), and writes its answer (`running` / `stopped` / `failed` with `detail`) onto the same key. A new request supersedes the old one under the key. | **Consumer** asks (Sleipnir); producer answers. | +| Input session | The hub session whose connect payload is the request's `receiver_id` (the Ratatoskr rule, `R receiver.rs:40-42`) | Lives while the consumer is attached. A session with no admitted request is served nothing. | Consumer dials; Muninn's input hub admits. | +| HID epoch | `(session, device_id, epoch: u64)`. The epoch is the window's monotonic creation time in ns, and `+1` on overflow rotation. | New per window (session attach, device change, process start) and per overflow. The receiver fences any epoch below its current one. | Muninn's `EdgeWindow`. Sleipnir only fences. | +| HID state sequence | `(session, device_id, epoch, state_sequence)` | Monotonic per epoch. Each frame supersedes the last (the `latest` channel is sequenced per session). | Muninn. | +| HID edge | `(session, device_id, epoch, edge_sequence)`, contiguous from 1 per epoch | Detected once, at sample time, on the capture thread. Pending per window until acknowledged. Resent in every frame while pending, at most `MAX_EDGES_PER_FRAME` per frame and 256 held. Overflow rotates that window's epoch and drops its history. | Muninn detects (capture) and delivers (window). Sleipnir applies in order and acknowledges cumulatively. | +| HID edge ack `muninn.hid_edge_ack.v1` | `(device_id, epoch, applied_through)` on the consumer's session | Cumulative and idempotent. Resent each Sleipnir tick while nonzero. | Sleipnir. | --- @@ -1159,30 +1235,74 @@ is a human-used workstation (teardown-map L268-271). --- -## HID edge for remote play: cuts H0-H5 (Q1 ruled) +## HID edge for remote play: cuts H0-H5 (Q1, Q9, Q10 ruled) **What it is for** (Q1, 2026-09-30): a viewer's controller drives a game on another host, over LAN or mesh, so quick taps must survive loss. -- The **source** is Muninn on the viewer's host, capturing the pad. -- The **sink** is Sleipnir on the game host, which drives ViGEm. -- Today that sink is `raven-sleipnir`, Raven being the game host (B16). +- The **producer** is Muninn on the viewer's host, capturing the pad. +- The **consumer** is Sleipnir on the game host, which drives ViGEm. +- Today the consumer is `raven-sleipnir`, Raven being the game host (B16). -**Ownership.** +**Anchors in this section.** +- `M` = Muninn `main` `c3520d1`. +- `S` = Sleipnir at Odin `main` `379b826`, `crates/sleipnir-daemon/src/main.rs`. + H3 moves that file verbatim, so after H3 the same line numbers hold at + `Muninn/crates/sleipnir-daemon/src/main.rs` until H4 edits it. +- `R` = Ratatoskr `488b5b1`. +- `C` = CultLib `c2a9a6e`, Muninn's pin. +- `Mi` = Mimir `d88f2e6`. +- `Ops` = gamecult-ops `8554e60`. + +### The capability mechanism, verified: video today, input mirrored + +Q10 orders input to be requested the way Ratatoskr requests video. This is +that request path, read at the SHAs above. + +| Step | Video today | Input after H2/H4 | +|---|---|---| +| Producer advertises through CultMesh | Muninn builds `gamecult.media_stream_advertisement.v1` (`M :1122-1166`). It stores it and publishes it to Odin's catalog under its `stream_id`, with role `media-stream-producer` (`M :4146-4166`). | Muninn builds `muninn.input_stream_advertisement.v1` in `input_stream.rs`, and publishes it at the same site with role `input-stream-producer`. | +| Advertised endpoint | `media_endpoint` is explicit (`--media-rudp-advertise`), or derived, **never guessed** (`advertised_media_endpoint`, `M :1173-1196`). `media_connection_id` is `MUNINN_MEDIA_RUDP_CONNECTION_ID`. | `input_endpoint` comes from the same function, parameterised (`advertised_endpoint(explicit, bind)`). `input_connection_id` is `0x6d75_0005`, today's HID id (`M :74`, `S :23`). | +| Recipe declares the capability | `[[provides]] capability = "muninn.media-producer"` (`raven-muninn.toml:93-96`) | `[[provides]] capability = "muninn.input-producer"`, schema `muninn.input_stream_advertisement.v1` | +| Consumer discovers | Ratatoskr pulls the advertisement schema from Odin (`R catalog.rs:64-91`) | Sleipnir pulls the input advertisement schema and its own mapping schema: one pull, typed, with no JSON scraping (B21). | +| Consumer asks | Ratatoskr publishes a request under `media_stream_request_key(stream, receiver)`, role `media-stream-consumer` (`R catalog.rs:95-122`). The request names the sources, and the latency budget defaults from the advertisement (`R :151-179`). | Sleipnir publishes `muninn.input_stream_request.v1` under `input_stream_request_key(stream, receiver)`, role `input-stream-consumer`. It names `device_id`, and `input_budget_ms` defaults from the advertisement. | +| Producer admits and answers | Muninn pulls request documents from Odin each tick (`M :971-1034`), turns them into `MuninnCaptureStreamCommandRecord`s, and writes the answer onto the request key (`M :1038-1117`). | The **same pull** takes both request schemas in one snapshot. Input requests go to the input organ as demand (B23), with **no** detour through a command record, and are answered on the same key. | +| Who dials | The consumer dials the advertised endpoint (`R receiver.rs:4-7`). Its connect payload is its `receiver_id` (`R receiver.rs:40-42`). Muninn listens on a `CultNetRudpServerHub` (`M :3192-3213`). | The consumer (Sleipnir, on the game host) dials the viewer's Muninn. Muninn listens on a `CultNetRudpServerHub` and serves a session only the device its request names. | + +**Consequence the operator accepted in Q10:** the producer is on the viewer, so +**the viewer's host admits inbound UDP** for input. That is the cost the +2026-09-10 media inversion refused for video viewers (teardown-map +L486-495). For input it is ruled acceptable. H5 records the firewall rule per +viewer host. + +**Two deliberate differences from the video path**, each protecting a named +invariant: +- **Admission as demand, not as `state == pending`** (B23). A restarted + producer resumes serving every live consumer without a re-request. The video + path should adopt this too, under its own owner. +- **No command-record detour.** `MuninnCaptureStreamCommandRecord` exists for + the media child's lifecycle and for legacy readers (teardown-map, item 2 of + "Next unblocked work"). Input has neither, so it does not grow a second + command vocabulary. + +### Ownership | Organ | Owns | Does not own | |---|---|---| -| Muninn (viewer host) | Sampling; edge detection at sample time; the epoch; the state sequence; the unacknowledged-edge window and its bound; frame emission; applying acks to its window; answering subscriptions | Mapping, actuation, or deciding that an edge was applied | -| `muninn-contracts` (Muninn repo, new lib, H0) | The HID wire records; their validation and CultNet envelope; the **protocol state machines**, `EdgeWindow` (sender) and `EdgeCursor` (receiver), as pure code | Sockets, threads, devices | -| Sleipnir (game host) | Subscription; the cursor instance; mapping; **the single pad-commit primitive** (invariant 10); the visibility hold and budget (invariant 13); acks; neutralising on staleness | Edge creation, epochs, capture | -| CultLib | The `latest` channel: Unreliable and Sequenced, profile-declared (`C rudp.rs:2189-2197, 2384-2390`) | Anything HID-named (invariant 9). **No CultLib change.** | +| Muninn capture thread, one per source (H2) | The **only** device reader (B22); sampling (XInput 1 ms, Windows HID every report, joystick events as they arrive); `EdgeDetector`; the latest-state slot; the per-source edge queue | Sessions, windows, epochs, frames | +| Muninn input organ, `crates/muninn-daemon/src/input_stream.rs` (H2) | The advertisement; admission of input requests as demand, and their answers; the input hub and its sessions; one `EdgeWindow` per (session, device); frame emission on `latest`; applying acks | Device reads; mapping; deciding that an edge was applied | +| `muninn-contracts` (H0, H1) | The input records and their key and validation; the HID wire records and their CultNet envelope; `EdgeDetector`, `EdgeWindow` and `EdgeCursor` as pure code | Sockets, threads, devices, Odin | +| Sleipnir (`crates/sleipnir-daemon`, Muninn workspace, H3/H4) | Choosing the device from typed advertisements plus its mapping record; publishing the request; dialling; the `EdgeCursor`; **the single `commit_pad` primitive** (invariant 10); the hold and the request-owned budget (invariant 13); acks; neutralising on staleness | Edge creation, epochs, capture, discovery JSON | +| CultLib | The `latest` channel: Unreliable and Sequenced, fixed by name (`C rudp.rs:2189-2192, 2384-2390`); `CultNetRudpServerHub` with per-session send (`C rudp.rs:1384, 1464, 1475`) | Anything HID-named (invariant 9). **No CultLib change** (under Q11's recommendation). | +| Odin | Catalog storage for the advertisement and request documents. It is schema-agnostic: `odin-daemon` names no media schema either (`git grep`, Odin `379b826`). | Anything input-specific. **No Odin change.** | **Why one frame on `latest`, and not the donor's reliable `hid.edge` channel.** -- A frame carries the current state **and** every unacknowledged edge, up to 32. +- A frame carries the current state **and** every unacknowledged edge of that + session's window, up to `MAX_EDGES_PER_FRAME`. - Each frame therefore supersedes the last, which is exactly what a sequenced channel delivers: an older frame arriving late is dropped, and nothing is lost by that. -- Loss costs nothing but the next tick, 2 ms at the current poll - (`HID_CONTROLLER_RUDP_POLL_INTERVAL`). +- Loss costs one transport tick. H2 sets that tick to 2 ms. Today it is 8 ms + (B22). - There is no retransmit timer, no reliable window to stall, and no second "assist" path. - The ruling's "profile-owned channels" is met by using a channel the profile @@ -1190,42 +1310,83 @@ another host, over LAN or mesh, so quick taps must survive loss. **How Odin `main`'s pin stays untouched while StreamPixels ships.** - Nothing in H0-H5 commits to Odin `main`. -- Sleipnir's changes happen in Sleipnir's new home (Q9). Its odin-core comes - from the `pins/` tag (Q2 mechanism). `3e96c6c` already pins CultLib - `c2a9a6e`, Muninn's pin, so no new Odin commit is needed until Cut 3. -- From H3 on, Odin `main`'s `crates/sleipnir-daemon` is a **forbidden writer**: - no commits there. -- After StreamPixels ships, **one** Odin commit removes the crate from Odin's +- Sleipnir moves into Muninn's workspace (Q9) at Muninn's pins: CultLib + `c2a9a6e`, and odin-core from Odin `3e96c6c`. That is the commit Odin made + for exactly this ("CultLib pin a8aedda -> c2a9a6e so a consumer can build + odin-core without a path override"). It already bumps `sleipnir-daemon`'s + own manifest to `c2a9a6e`, and its odin-core API equals Odin `main`'s: + `git diff 3e96c6c 379b826 -- crates/odin-core` touches only `Cargo.toml` and + two examples. +- From H3 on, Odin `main`'s `crates/sleipnir-daemon` is a **forbidden writer**. +- After StreamPixels ships, **one** Odin commit deletes the crate from Odin's workspace. It is a deletion, with no pin change and no other edit. -- Until then, two copies of the source exist and only one is built and - deployed. The Muninn extraction lived through this interval too - (teardown-map L628-629), and it is recorded as debt with its deletion line. +- Until then two copies of the source exist, and only Muninn's is built and + deployed from H5 on. Recorded as debt, with its deletion line. ### H0: shape of Muninn's named cut 1 (a constraint, not a new cut) Named cut 1 moves Muninn's 16 records out of odin-core. For H, it must place -them in a **library** crate, `crates/muninn-contracts` (`crate-type = rlib`), -not in `muninn-daemon`'s binary. +them in a **library** crate in Muninn's workspace, `crates/muninn-contracts` +(`crate-type = rlib`), not in `muninn-daemon`'s binary. - **Owner:** Muninn. -- **Live consumers:** `muninn-daemon`; Sleipnir, which imports - `MuninnHidControllerStateRecord` today (`S :12`); `muninn-video-encoder` - (6a). -- **Protected invariant:** each Muninn wire record has one definition across - repositories. +- **Live consumers:** + - `muninn-daemon`; + - `sleipnir-daemon`, a workspace member from H3. It imports + `MuninnHidControllerStateRecord` today (`S :12`), until H4. + - `muninn-video-encoder` (6a). +- **Protected invariant:** each Muninn wire record has one definition, and + every crate that links it resolves one `cultcache-rs`. With Sleipnir in the + workspace that is structural: one `Cargo.lock`, a path dependency, and no + git pin to drift. The pass-2 guard test for a cross-repo pin is **not** + written. - **Why the existing owner cannot serve:** a binary crate cannot be a - dependency. + dependency, and two binaries (`muninn`, `sleipnir`) share these records. - **What it replaces:** Muninn records defined in Odin's odin-core. -Its dependencies are `cultcache-rs`, `cultnet-rs`, `serde` and `anyhow`, at -Muninn's CultLib pin. +Its dependencies are `cultcache-rs`, `cultnet-rs`, `serde` and `anyhow`, taken +from `[workspace.dependencies]` (H3 hoists the pins there). -### H1: HID wire records and protocol state machines (`muninn-contracts`) +**Ordering against H3.** Neither waits for the other. If H3 lands first, +Sleipnir keeps importing the HID record from odin-core. Named cut 1 then +switches both importers in one commit, which is the practical gain of Q9. -**Adds (types and rules; bodies are Hands'):** +### H1: input-stream records, HID wire records and protocol state machines (`muninn-contracts`) + +Location per Q11 (recommended): `crates/muninn-contracts/src/input_stream.rs` +(the capability records) and `crates/muninn-contracts/src/hid.rs` (the wire +records and state machines). If Q11 rules CultLib, the same types go to +`CultLib packages/cultnet-rs/src/input_stream_contracts.rs` under `gamecult.*` +ids, and H1 waits for Cut 3's CultLib tag and the pin gate. + +**Adds, the capability pair** (types and rules; bodies are Hands'). It is +modelled field-for-field on `C media_stream_contracts.rs:71-183`. +- `muninn.input_stream_advertisement.v1`: + - `stream_id`, `producer_id`, `label`; + - `state`, one of `available`, `streaming`, `unavailable`; + - `device_ids`, `device_labels`, `device_kinds`: parallel, equal length; + - `default_input_budget_ms`: the default, 100; + - `input_endpoint`, `input_connection_id`; + - `updated_at`. +- `muninn.input_stream_request.v1`: + - `request_id`, `stream_id`, `producer_id`, `receiver_id`; + - `action`, one of `start` or `stop`; + - `state`, one of `pending`, `running`, `stopped`, `failed`; + - `device_id`, `input_budget_ms`, `detail`, `updated_at`. +- `input_stream_request_key(stream_id, receiver_id)`, with the same shape as + `media_stream_request_key` (`C media_stream_contracts.rs:180`). +- `validate_input_stream_advertisement` and `validate_input_stream_request`. + They mirror `C :184-290`. Validation refuses: + - unequal device arrays; + - `start` without a `device_id`; + - an `input_budget_ms` of 0 on a `start`, because the consumer fills in the + advertised default, as Ratatoskr does (`R catalog.rs:174`); + - an unknown action or state. + +**Adds, the wire:** - `muninn.hid_input_frame.v1`: - `device_id`, `stream_id`; - - `epoch: u64`, which is never 0; + - `epoch: u64`, never 0; - `state_sequence: u64`; - `source_timestamp_ns: i64`, telemetry only; - `axes: Vec`; @@ -1233,26 +1394,33 @@ Muninn's CultLib pin. frame's window; - `edge_first_sequence: u64`; - `edge_buttons: Vec`, `edge_pressed: Vec`, - `edge_captured_ns: Vec`: parallel arrays, equal length, at most 32, - contiguous from `edge_first_sequence`. + `edge_captured_ns: Vec`: parallel arrays, equal length, at most + `MAX_EDGES_PER_FRAME`, contiguous from `edge_first_sequence`. - Hands may use a nested record list instead of parallel arrays if the `cultcache-rs` derive supports it at the pin. The rule, not the spelling, is the contract. - `muninn.hid_edge_ack.v1`: `device_id`, `epoch`, `applied_through: u64`. -- `muninn.hid_subscription.v1`: `subscriber_id`, `device_filter`, `stream_id`. - This replaces the JSON object at `S :2303-2306`. -- `MuninnHidWireRecord { Frame, Ack, Subscription }`, with - `encode`/`decode` through the CultNet message envelope. This is the same - pattern as CultLib's `encode_media_wire_record` - (`C media_stream_wire.rs:134-190`), with validation on both encode and decode. -- `EdgeWindow` (sender): - - `capture(buttons_now, captured_ns)` diffs against the last sample, then - appends edges: releases first, then presses (the donor order); - - `frame_edges() -> ≤32 oldest pending`; +- `MuninnHidWireRecord { Frame, Ack }` with `encode`/`decode` through the + CultNet message envelope. This is the pattern of CultLib's + `encode_media_wire_record` (`C media_stream_wire.rs:134-190`), with + validation on both encode and decode. +- **Deleted from the design:** pass 2's `muninn.hid_subscription.v1`. Device + selection is the request's `device_id`, and the subscriber's identity is the + session's connect payload. There is no in-session subscription message. + +**Adds, the state machines:** +- `EdgeDetector` (runs on the capture thread): + - `sample(buttons_now, captured_ns) -> impl Iterator` diffs against the + previous sample: releases first, then presses (the donor order); + - edges carry no sequence and no epoch. Those belong to a window. +- `EdgeWindow` (one per session and device, on the input tick): + - `new(epoch_ns)`; + - `push(edge)` appends, with a sequence contiguous from 1; + - `frame_edges() -> ≤ MAX_EDGES_PER_FRAME oldest pending`; - `ack(epoch, applied_through)`; - - overflow past 256 pending rotates the epoch (`+1`), sets `state_sequence` - to 0, clears pending, and reports the rotation to the caller, which counts - it. + - `rebaseline()`. Past 256 pending it sets the epoch to `+1`, + `state_sequence` to 0, clears pending, and reports the rotation to the + caller, which counts it. - `EdgeCursor` (receiver): - `accept_frame(epoch, state_sequence, first_seq, edges) -> Admission`; - an epoch below the current one: fenced (a monotonic comparison, with no @@ -1264,197 +1432,515 @@ Muninn's CultLib pin. - the same epoch: return the edges with sequence above `applied_through`, in order. Duplicates are dropped by sequence, and a gap past 256 is refused. -**Rules that must die under their own mutation** (a property-style test drives -`EdgeWindow` → frames → a seeded drop, reorder or duplicate → `EdgeCursor`): -- Every edge captured is delivered **exactly once, in capture order**, under - every Cut 3b profile. Use the **same seed tables** as the media harness, so - that one impairment vocabulary serves both. +**Rules that must die under their own mutation.** A property-style test drives +`EdgeDetector` → two `EdgeWindow`s (two subscribers, independent drop seeds) → +frames → a seeded drop, reorder or duplicate → one `EdgeCursor` per +subscriber. +- Every edge captured is delivered **exactly once, in capture order, to each + subscriber**, under every Cut 3b profile. Use the **same seed tables** as the + media harness, so one impairment vocabulary serves both. +- One subscriber at `burst-8` never rotates the other subscriber's epoch. - A press and release captured in one sampling interval arrive as two edges, press then release. -- The window in a frame is never above 32. Pending is never above 256. At 257, - the epoch rotates, and the next frame's epoch is exactly one more. +- The window in a frame never exceeds `MAX_EDGES_PER_FRAME`. Pending is never + above 256. At 257 the epoch rotates, and the next frame's epoch is exactly + one more. - An ack for a stale epoch changes nothing. An ack for `n` trims exactly through `n`. - The cursor rejects a frame from any epoch below its current one, including `current − 1`. Kill the off-by-one comparison mutant. -- A frame at the maximum window, with the longest button names and 16 axes, - encodes to ≤ 1,200 bytes (`HID_CONTROLLER_RUDP_MAX_FRAGMENT_BYTES`), so it - never fragments (invariant 6's rule, applied to input). -- The frame round-trips, and a frame with unequal parallel arrays or a - non-contiguous window is refused on decode. +- **Fit.** A frame with a full window, the longest button names, 16 axes and + a full held set encodes to ≤ 1,200 bytes (`HID_CONTROLLER_RUDP_MAX_FRAGMENT_BYTES`, + `M :6140`), so it never fragments (invariant 6's rule, applied to input). + - A rough count puts 32 edges with 16-character names at about 1,270 bytes. + **The test sets the constant.** Start at 32, and lower it until the worst + case fits. + - Never raise the fragment limit to make it fit. +- The frame round-trips. A frame with unequal parallel arrays, or a + non-contiguous window, is refused on decode. +- The request and advertisement round-trip. Each refusal listed above has a + test. **Verification:** `cargo test -p muninn-contracts` and `cargo mutants --in-diff` -on Yggdrasil. This crate is where the protocol is proven; H2 and H4 only wire -it. +on Yggdrasil, one job. -**Ledger:** about +450 (records, wire, two state machines and the property -test). It retires the donor's ~350 HID lines, which never land. +**Build budget:** one library crate that already exists from named cut 1. +It gains no dependencies and no new target. -### H2: Muninn sends frames (Muninn repo) +**Ledger:** about +550 (the capability pair ~100, the wire and three state +machines ~250, tests ~200). It retires the donor's ~350 HID lines, which never +land. -**Deletes first:** -- The JSON subscription: `HidControllerRudpSubscription` (`M main.rs:6137-6142`) - and `serde_json::from_slice` (`:6216-6217`). -- The JSON state send (`:6298-6300`, `:6835-6836`). -- **The losing HID path, per Q10.** Either the ingress server (`:6144-6356`, - `--hid-controller-rudp-bind`) or the outbound client (`:6717-6860`, - `--hid-controller-rudp-target`, `:10891-10895`), with its options, its - advertisement fields (`:3619-3740`), and its tests. -- The per-tick read (`:6286`) as the place where edges exist. +### H2: Muninn serves input streams (Muninn repo) -**Adds:** -- A capture thread per source, ported from `fb4f331`: - - XInput sampled every 1 ms (`D main.rs:5881`); - - Windows HID via the existing report reader, every report; - - joystick events as they arrive. - - Each sample goes to `EdgeWindow::capture` **on the capture thread**, and - the latest state goes into a slot the transport reads. - - Edges are never computed at transport time (B14). -- A transport tick at 2 ms: - - for each subscribed source, send one `hid_input_frame` on `latest`; - - apply received `hid_edge_ack`; - - take `hid_subscription`. - - A source with nothing new still sends at the 50 ms heartbeat - (`HID_CONTROLLER_RUDP_HEARTBEAT_AFTER`). -- `muninn.hid_controller_state.v1` stays exactly what it is: the Odin-published - **observation** for device discovery (`M :6858`). It is not a wire frame. +Depends on H1 and Q12. It is developed on the same Hands branch as H4 and +merged with it (see Sequencing). -**Authority map:** -- **Owner:** the `EdgeWindow` per source, on the capture thread. -- **Inputs:** device samples. -- **Outputs:** frames. +**Authority map.** +- **Owner:** + - edges: `EdgeDetector` on each source's capture thread; + - delivery: the input organ in `input_stream.rs`, one `EdgeWindow` per + (session, device). +- **Inputs:** + - device samples, capture only; + - admitted input requests, from the serve tick's single Odin pull; + - hub sessions and their connect payloads; + - `hid_edge_ack` frames. +- **Outputs:** + - `hid_input_frame` per session on `latest`; + - the advertisement; + - answers on request keys; + - counters (frames, rotations, acks, sessions). +- **Derived state:** + - `muninn.hid_controller_state.v1` receipts become **observation-only**, + projected from the capture slot. They are no longer read from the device, + and they are no longer a discovery source. + - The Eve provider advertisement lists no input streams. - **Forbidden writers:** - the transport tick deciding edges; - - wall-clock time deciding freshness (it is telemetry only; donor doctrine, + - the serve tick reading a device that a capture thread owns; + - wall-clock time deciding freshness (telemetry only; donor doctrine, `D docs/realtime-delivery-authority.md`); - - any JSON. -- **Shared paths:** live capture, reconnect (the window survives a - reconnection; the epoch survives until overflow or restart) and tests all go - through `EdgeWindow`. + - JSON anywhere on this path; + - an in-session subscription message. +- **Shared paths:** live capture, reconnect, restart (demand re-admission) and + tests all go through `EdgeDetector` → `EdgeWindow`. A reattaching session + gets a new window, a new epoch, and a baseline. + +**Deletes first** (`M`): +1. **The losing path per Q10: Muninn's outbound client.** + - `ActiveHidControllerStream` (`:6077-6086`); + - `create_hid_controller_stream` (`:6724-6763`); + - `publish_hid_controller_state_to_stream` (`:6765-6778`) and `_inner` + (`:6780-6863`); + - in `serve`: `let mut hid_controller_stream` (`:418`) and its argument + (`:506`); + - the `hid_controller_stream` parameter of `publish_move_controller_states` + (`:4982`), and its three calls (`:5026-5029`, `:5073-5076`, + `:5112-5115`); + - the option field (`:229`), its default (`:10628`) and its parse arm + `--hid-controller-rudp-target` | `--hid-controller-udp-target` + (`:10899-10904`). +2. **The JSON listener body.** Its direction survives; its body does not. + - `HidControllerRudpSubscription` (`:6143-6149`); + - `start_hid_controller_rudp_ingress` (`:6151-6177`); + - `run_hid_controller_rudp_ingress` (`:6179-6340`); + - `hid_controller_source_matches_subscription` (`:6342-6360`); + - `hid_controller_record_matches_subscription` (`:6362-6375`); + - `sanitize_hid_controller_record` (`:6710-6722`); + - the `serve` wiring at `:429-437`, per Q12. +3. **The per-tick reader as the place where HID state is made.** + - `read_hid_controller_state_for_stream` (`:6377-6528`), + `emit_hid_controller_record_if_due` (`:6530-6554`), + `hid_controller_stream_heartbeat_due` (`:6556-6560`) and + `hid_controller_axes_changed` (`:6562-6570`). + - The device-read bodies inside them move to the capture thread; they are + not rewritten. The emit-if-due throttling dies, because the window + decides what to send. + - `ActiveHidControllerRudpSource`, `active_hid_controller_rudp_source` and + `sync_hid_controller_rudp_sources` (`:6088-6129`) become the capture-set + reconciler. The hot-plug test `rudp_sources_reconcile_hotplugged_physical_identity` + (`:14620-14636`) is kept and retargeted. +4. **The double-read fence** (`:5081-5086`), because the capture thread is + now the only reader (B22). +5. **The JSON discovery surface** (B21). + - `hid_controller_endpoint` (`:3626-3631`); + - the device JSON (`:3653-3672`); + - `transport_input_streams` and `provider_input_streams` (`:3673-3727`); + - the provider `endpoints` pushes (`:3729-3750`); + - the `"input_streams"` key (`:3856`) and the `"inputStreams"` key + (`:3885`). + - The test `runtime_boundary_advertises_hid_and_move_evidence_streams` + (`:14072-14172`) is rewritten against the typed advertisement. +6. **The discovery write** `publish_hid_controller_state_to_odin` + (`:6865-6875`) and its three calls (`:5030`, `:5077`, `:5116`). Its only + reader is Sleipnir's discovery, which H4 deletes (B21). Receipts through + `put_hid_controller_state_receipt` (`:5970`) stay. +7. **Rename, not keep beside.** The options `hid_controller_rudp_bind` and + `_advertise` (`:230-231`, parse `:10906-10916`) become + `--input-rudp-bind` and `--input-rudp-advertise`. The old spellings are + refused with a message naming the new ones (the house pattern, + `M :10890-10894`). `local_ring_enabled` (`:4238`) follows Q12. + +**Adds:** +- `crates/muninn-daemon/src/input_stream.rs`, so `main.rs` shrinks. It holds: + - `input_stream_advertisement(options, live_sources)`, published at `:4146` + beside the media advertisement, with role `input-stream-producer` and tag + `muninn.input-stream-advertisement`; + - `InputDemand`: the admitted requests, keyed by `receiver_id`. It is + written by the serve tick and read by the input thread (a latest-wins + `Arc>`); + - `run_input_hub`: a `CultNetRudpServerHub` on `--input-rudp-bind`, open for + the life of `serve` when configured (`muninn_input_rudp_hub_options`, on + the model of `M :3232-3241`). On a 2 ms tick it: + - drains each source's edge queue into the windows of every session that + requested that device; + - sends one frame per (session, device) on `latest`, with a 50 ms + heartbeat when a window holds nothing new + (`HID_CONTROLLER_RUDP_HEARTBEAT_AFTER`, `:6138`); + - applies acks; + - drops sessions after timeout, as the media hub does (`M :3090-3096`). +- **Request intake: one owner for both capabilities.** + - `sync_media_stream_requests` (`M :971-1034`) becomes + `sync_stream_requests`. It makes **one** `pull_rudp_catalog_snapshot` with + `schema_ids = [media request, input request]`. + - Media requests continue exactly as today. + - Input requests addressed to `options.host_id` are admitted by `action` + (B23). An unknown `device_id` is answered `failed` with a typed `detail`. + A `stop`, or a newer request under the same key, withdraws the demand. + - `answer_media_stream_request` (`M :1069-1117`) gets an input twin with + the same keying and dedupe (`answered`). A generic helper is not + introduced for two call sites. +- `advertised_media_endpoint` (`M :1173-1196`) is parameterised as + `advertised_endpoint(explicit, bind, command_advertise)`. Media and input + call the one function, so input inherits "explicit or derived, never + guessed". +- `MuninnDocuments` (`M :10503-10542`) registers the two input records. +- **A capture thread per source**, ported from `fb4f331`: + - XInput sampled every 1 ms (`D main.rs:5881`); + - Windows HID through the existing report reader + (`start_windows_hid_report_reader_if_supported`, `M :8813`), every report; + - joystick events as they arrive. + - Each sample goes through `EdgeDetector` **on the capture thread**. The + edges go to a bounded per-source queue (256; overflow rebaselines every + window on that device), and the latest state goes to a slot. + - The serve tick's HID receipts (`M :5016-5025`, `:5064-5072`, + `:5102-5111`) read the slot, not the device. +- `raven-muninn.toml`: + - the argument pair `:62-65` becomes `--input-rudp-bind 0.0.0.0:17887` and + `--input-rudp-advertise` (binding `input_rudp_advertise`); + - a second `[[provides]]` block: `muninn.input-producer`, + `muninn.input_stream_advertisement.v1`, `v1`. + - The binding rename lands in gamecult-ops with H5. + - This edits the file `route/b3-declare` also edits, in a different block. + Rebase onto it if it has merged. **Rules:** - A tap shorter than one transport tick, from a scripted fake XInput source, becomes two edges in the next frame. -- The frame stream from a fake source through a drop relay matches H1's - property on the wire. Assert on captured datagrams. -- `rg serde_json crates/muninn-daemon/src` finds no HID or subscription use. +- Two sessions requesting one device each receive every edge once. Dropping + all frames to one session for 600 ms rotates only that session's epoch. +- A session whose `receiver_id` has no admitted request receives no frame. + So does a session whose request names another device. +- After a simulated restart, with fresh `InputDemand` and an Odin fixture + still holding the request at `running`, the session is served again with no + new request (B23). +- The frame stream from a fake source through a seeded drop relay matches + H1's property on the wire. Assert on captured datagrams. +- The serve tick never opens a device that a capture thread owns: a dev-only + per-device open counter reads 1. +- `rg serde_json crates/muninn-daemon/src/input_stream.rs` is empty, and no HID + path in `main.rs` calls `serde_json`. +- The typed advertisement round-trips through a local CultMesh node fixture, + as `R tests/catalog.rs:162-180` does for media. -**Verification:** Yggdrasil. The XInput and Windows HID readers are `cfg(windows)`, -so the scenario uses a scripted source behind the same capture trait. -- **Only live proves:** real XInput sampling jitter on the viewer's host. -- **Starfire:** one Windows compile check of `muninn-daemon`, one job and no - burners (load budget). +**Verification:** Yggdrasil, `cargo test -p muninn-daemon`, one job. The +XInput and Windows HID readers are `cfg(windows)`, so the scenario uses a +scripted source behind the same capture trait. +- **Starfire:** one Windows compile check of `muninn-daemon`. It is batched + with H4's, one job and no burners (load budget). +- **Only live proves:** real XInput sampling jitter on the viewer's host (H5). -**Ledger:** about −250 (JSON paths, the losing transport path and its -advertisement) and +200. **Net about −50.** +**Build budget:** `muninn-daemon` only. One new module, no new target and no +new dependency. -### H3: Sleipnir moves to its own home (Q9); behaviour-neutral +**Ledger:** about −750 (the outbound client ~150, the JSON listener and match +functions ~235, the per-tick reader and emit ~195 (its read bodies relocate), +the JSON advertisement ~105, the discovery write and fence ~20, the rewritten +test ~60 net) and about +450 (the organ ~300, capture threads ~100, +intake/answer twin ~50). **Net about −300.** -Recommended per Q9 (a): **`GameCult/Sleipnir`**, created in the GameCult -organisation per project doctrine. +### H3: Sleipnir moves into Muninn's workspace (Q9); behaviour-neutral -- The source history comes from Odin with `git filter-repo --path - crates/sleipnir-daemon`. It is not a copy, so provenance survives. -- Dependencies: - - CultLib at Muninn's pin (`c2a9a6e`); - - `odin-core` from `pins/odin-core-cultlib-c2a9a6e` (`3e96c6c`, retagged per - the Q2 note); - - `muninn-contracts` at a Muninn revision (git, full sha); - - `vigem-client` unchanged. -- Pins move in lockstep with Muninn from then on. A guard test asserts that - Sleipnir's `muninn-contracts` resolves the same `cultcache-rs` source as its - own dependency. The "pin sibling checkouts" rule, applied to a git pin. -- **Deletes on the Odin side:** none now. Odin `main`'s copy becomes a - forbidden writer, and its removal is the post-ship Odin commit. -- **Verification:** - - `cargo test` on Yggdrasil (Linux, `LoggingBackend`). The existing 22 - Sleipnir tests (`S :2959-3660`) pass unchanged. - - The Windows build is proven by H5's recipe on Raven. - - `SleipnirInputMappingRecord` keeps coming from the odin-core tag. Moving it - into Sleipnir is a later subtraction, not this cut. +**Source:** Odin `379b826` `crates/sleipnir-daemon/{Cargo.toml, src/main.rs}`, +3,658 lines. That is 8 commits by path, the oldest through `4ad8bdb`, and +`--follow` finds no earlier rename. -### H4: Sleipnir applies edges (Sleipnir repo) +**How history moves.** This is the Muninn extraction precedent: Muninn's own +history came out of Odin whole (316 commits, root `2d88408`). +- In a scratch clone of Odin, run + `git filter-repo --path crates/sleipnir-daemon`. +- In Muninn, `git merge --allow-unrelated-histories` that result. It lands at + the same path, `crates/sleipnir-daemon/`. +- `git log -- crates/sleipnir-daemon` then works in Muninn. Odin keeps its own + copy of the history after its deletion commit. -**Deletes first:** -- The JSON subscription (`S :2303-2310`) and JSON decode (`:2497-2498`). -- Button coalescing, in which the latest record wins per device - (`coalesce_latest_*`, `:2543-2590`). Axes remain latest-wins, because they - are replaceable. -- Any path that writes `buttons` from a snapshot inside an epoch. +**Per-file changes, all in Muninn:** +- `Cargo.toml` (workspace): + - add `crates/sleipnir-daemon` to `members`; + - add a `[workspace.dependencies]` table holding the one CultLib rev + (`c2a9a6e526390808ef195759056fda0b9a55d8a3`) for `cultcache-rs`, + `cultmesh-rs` and `cultnet-rs`, plus `odin-core` at Odin `3e96c6c`. +- `crates/muninn-daemon/Cargo.toml:18-20, 24`: the four git pins become + `{ workspace = true }`. From here, "pins move in lockstep" is one line, not + a discipline. +- `crates/sleipnir-daemon/Cargo.toml`: + - the CultLib pins become `{ workspace = true }`. They were `a8aedda` in + Odin: the pin moves from Odin `main`'s to Muninn's; + - `odin-core = { path = "../odin-core" }` becomes `{ workspace = true }`; + - `edition`, `license` and `publish` already read `.workspace`, and + Muninn's workspace defines all three. +- `crates/sleipnir-daemon/src/main.rs`: **no edit**. The pin move from + `a8aedda` to `c2a9a6e` is the only behavioural exposure. Odin made the + same move for this crate in `3e96c6c`. +- `Cargo.lock`: regenerated. It gains `vigem-client` for Windows only, and + Muninn's recipe keeps building `-p muninn-daemon --bin muninn` (`:14-22`), + so Raven's Muninn build is unchanged. + +**Deletes:** none in Muninn. Odin `main`'s copy becomes a forbidden writer, +and its removal is the post-ship Odin commit. + +**Verification:** +- `cargo test -p sleipnir-daemon` on Yggdrasil (Linux, `LoggingBackend`). The + existing 22 tests (`S :2959-3660`) pass unchanged at the new pin. +- `cargo test -p muninn-daemon` passes unchanged. The workspace-dependency + hoist is proved by an unchanged `cargo tree -d -p muninn-daemon` for + `cultcache-rs`: exactly one. +- Starfire: one Windows `cargo check -p sleipnir-daemon`, because + `vigem-client` is `cfg(windows)`. +- `SleipnirInputMappingRecord` keeps coming from odin-core (`S :13`). Moving + it into Sleipnir is a later subtraction, not this cut. + +**Build budget:** one binary target, `sleipnir`, joins the workspace. It +leaves Odin's workspace at the post-ship commit, so the estate's target count +is unchanged. + +**Ledger:** 0 (a move) plus about −10 manifest lines (the pins hoisted). + +### H4: Sleipnir requests input and applies edges (Muninn repo) + +Developed with H2 on one Hands branch, and merged with it. + +**Authority map.** +- **Owner:** `commit_pad(state)` is the only caller of + `VirtualPadBackend::update`. Today there are five direct calls: `S :387`, + `:400`, `:472`, `:525`, and the `LoggingBackend` path. +- **Inputs:** + - typed input advertisements; + - the mapping record; + - the answered request; + - frames on its own session. +- **Outputs:** the request, acks, the pad timeline, and the Eve surface. +- **Derived state:** + - "available devices" is derived from advertisements; + - the selected endpoint is derived from the chosen advertisement; + - neither is discovered from JSON. +- **Forbidden writers:** + - any `backend.update` outside `commit_pad`; + - a snapshot writing `buttons` inside an epoch; + - JSON; + - `discover_provider_endpoints`. +- **Shared paths:** frames, epoch baselines, staleness neutralisation, mapping + change and reconnect all reach the pad through `commit_pad`. + +**Deletes first** (`S`, identical lines after H3): +1. **The losing path per Q10: Sleipnir's listening mode.** + - `Options.rudp_bind` (`:42`); + - the `--rudp-bind` | `--udp-bind` arm (`:2823-2829`); + - the server branch of `create_rudp_stream` (`:2244-2281`); + - `[--rudp-bind ADDR]` in `usage` (`:2906`). +2. **The JSON subscription.** + - `HidControllerRudpSubscription` (`:68-72`); + - `ActiveRudpStream.last_subscription*` (`:64-65`); + - `send_hid_subscription_if_due` (`:2283-2321`) and its call (`:426-431`). +3. **The JSON decode and the button coalescing.** + - `receive_rudp_records` (`:2480-2541`) is rewritten to decode + `MuninnHidWireRecord`; + - `coalesce_latest_timed_hid_records_by_device` (`:2543-2565`) and + `coalesce_latest_hid_records_by_device` (`:2567-2588`) are deleted, + with their tests (`:2959-2996`). Axes stay latest-wins, because the + frame carries only current axes. +4. **JSON and Odin-generic discovery** (B21). + - The second, provider-key pull in `pull_odin_catalog_snapshot` + (`:950-975`). The first pull's schema list becomes + `[muninn.input_stream_advertisement.v1, sleipnir.input_mapping.v1]`, + plus the request schema for the answer. + - `muninn_provider_keys_for_discovered_hid_hosts` (`:978-1003`) and + `hid_state_host_id_from_value` (`:1005-1019`). + - `effective_muninn_hid_endpoint` (`:1826-1833`). + - `discover_available_hid_devices` through `endpoint_looks_like_socket` + (`:1845-2131`). + - `resolve_socket_addr` stays. `discover_muninn_hid_endpoint` through + `stream_host_hint` (`:2370-2478`) goes. + - The eight discovery tests (`:3164-3513`) are replaced by three tests over + typed advertisements. + - Imports go: `EVE_PROVIDER_ADVERTISEMENT_SCHEMA` (used only at `:957`, + `:1890` and `:2420`), `MUNINN_HID_CONTROLLER_STATE_SCHEMA`, + `MuninnHidControllerStateRecord`, `OdinEndpointQuery` and + `discover_provider_endpoints` (`:10-14`). Sleipnir's odin-core symbols + fall from 10 to 4: the Eve advertisement and surface records, + `OdinDocuments`, and `SleipnirInputMappingRecord`. Pass 1 of H5 takes + `IdunnDaemonHealthRecord` too. +5. **Direct pad writes:** the five `backend.update` sites listed above. +6. **Removed-flag stubs that only reject old spellings:** + `--command-rudp-bind`, `--command-rudp-advertise` and + `--odin-cultmesh-rudp` (`:2830-2849`), with their tests (`:3605-3647`). + They are older than a Muninn-workspace body, and nothing passes them now + (`Ops idunn-deployment-targets.ps1:131`: `sleipnir --host raven`). **Adds:** -- `EdgeCursor` per subscribed device. -- An actuation queue drained by **one** `commit_pad(state)`, which is the - only caller of `VirtualPadBackend::update`. Frame axes, cursor edges, - epoch baselines and staleness neutralisation (`INPUT_STALE_NEUTRAL_AFTER`, - `S :28`) all go through it (invariant 10). -- The visibility hold of 24 ms, with the budget override at 100 ms: an edge - older than the budget is committed without the hold (invariant 13). +- `SleipnirDocuments`: `OdinDocuments` plus the two input records, on the + model of `MuninnDocuments` (`M :10503-10542`). It replaces `OdinDocuments` + at `S :269, 281`. +- `select_input_device(advertisements, mapping) -> Option<(advertisement, device_id)>`. + This is **one** function. It matches `mapping.stream_id` against the + advertisement's `stream_id`, and `mapping.device_filter` against + `device_ids` and `device_kinds`. The rules of `record_matches_filter` + (`S :2602-2612`) are kept. + - Persisted mapping records hold the old stream-id format + (`host:move_id:hid-controller-state`). They fall through to + `device_filter` and are rewritten on the next Eve mapping command. No + migration shim. +- **The request lifecycle,** the Ratatoskr pattern (`R catalog.rs:95-179`): + - publish `start` on selection, with `receiver_id = sleipnir.` and + `input_budget_ms` from the advertisement's default; + - publish `stop` on deselection, on mapping disable, and on clean exit; + - publish a **new** `start` (a fresh `request_id`) when the session is lost + or silent for `INPUT_STREAM_RECONNECT_AFTER` (`S :29`). A restarted + producer re-admits by demand anyway (B23); this covers the Odin document + being lost. +- **Dial:** the client branch of `create_rudp_stream` (`S :2196-2243`), with + `connect(receiver_id bytes)` in place of `connect(Vec::new())` + (`S :2232`, `:2365`), because the hub binds the session to the request by + its connect payload. +- `EdgeCursor` per selected device. +- An actuation queue drained by `commit_pad`. Frame axes, cursor edges, epoch + baselines, staleness neutralisation (`INPUT_STALE_NEUTRAL_AFTER`, `S :28`) + and a mapping change all go through it (invariant 10). +- The 24 ms visibility hold, overridden at the **request's** + `input_budget_ms`: an edge older than the budget is committed without the + hold (invariant 13). - `hid_edge_ack` for `applied_through` after each commit, and every tick while nonzero, on `latest`. -- `hid_subscription` as a typed record every 1 s. +- `map_record_to_virtual_pad` (`S :2677-2696`), `apply_pending_learn` + (`S :1714-1754`) and `input_latency_snapshot` (`S :2614-2651`) take the + cursor's pad input (axes plus held buttons plus the frame's timestamps) + instead of `MuninnHidControllerStateRecord`. The mapping logic is unchanged. +- The loop's sleep uses a 2 ms default for `--interval-ms` (`S :2791` + today: 8). -**Rules (on a recording backend, asserting the pad timeline, which is the -layer the game samples):** +**Rules** (on a recording backend, asserting the pad timeline, which is the +layer the game samples): - A quick tap under `loss-5pct` and `burst-8`: the timeline shows press, then release; the press is held ≥ 24 ms; nothing is doubled. - Reordered and duplicated frames produce the same timeline as clean. - A burst of 20 taps: every one appears. The last is committed no later than - 100 ms plus one tick after capture. Kill a mutant that removes the budget - override. Probe at `budget ± ε`. + `input_budget_ms` plus one tick after capture. Kill a mutant that removes the + budget override. Probe at `budget ± ε`, with the budget taken from a request + of 60 ms and one of 100 ms. The hold follows the request, not a constant. - A frame from epoch `current − 1` after a rotation is ignored, and the pad shows the new baseline. - Silence for 1.5 s neutralises through `commit_pad`. Assert that the backend - was called by the same function (a dev-only call-site counter). -- End to end on Yggdrasil: Muninn's H2 sender with a scripted source, through - a seeded drop relay, to Sleipnir with a recording backend. The relay and - profiles are the Cut 3b tool's. The test lives in Sleipnir, with Muninn's - scripted-source sender reached through `muninn-contracts` plus a thin test - driver. + was called only from that function (a dev-only call-site counter). +- Selection: + - a mapping naming a device kind picks the right advertisement among two + hosts; + - a mapping naming an absent device publishes no request; + - a `failed` answer surfaces its `detail` on the Eve surface. +- **End to end on Yggdrasil**, now inside one workspace: + - H2's `run_input_hub` with a scripted source, through a seeded drop relay + (the Cut 3b tool's relay and profiles), to Sleipnir's session loop with a + recording backend; + - an in-process CultMesh node stands in for Odin, holding the advertisement + and request. + - The test lives in `crates/sleipnir-daemon/tests/`, with `muninn-daemon`'s + organ reached as a dev-dependency only if Hands can make it a lib target + cheaply. Otherwise the test drives the hub from `muninn-contracts`'s state + machines plus a thin test driver, as in pass 2. -**Verification:** `cargo test` and `cargo mutants --in-diff` on Yggdrasil. +**Verification:** `cargo test -p sleipnir-daemon` and `cargo mutants --in-diff` +on Yggdrasil, one job batched with H2's. One Starfire Windows check covers both +crates. -**Ledger:** about −120 (JSON, coalescing) and +180. **Net about +60.** +**Build budget:** `sleipnir-daemon` only. It gains the `muninn-contracts` path +dependency and drops `serde_json` if nothing else in `main.rs` still needs it. +The Eve surface builds JSON (`S :1021-1455`), so it probably stays. + +**Ledger:** about −1,050 (listening mode ~45, JSON subscription ~50, +JSON decode and coalesce ~110, discovery ~420, removed-flag stubs ~20, their +tests ~450) and about +350 (selection and request ~120, cursor, queue and +commit ~130, tests ~250 minus the retired). **Net about −600.** ### H5: deploy, and the viewer's side -- **Sleipnir recipe** `deployment/idunn/raven-sleipnir.toml`, in the Sleipnir - repo: - - a `rust-host` build step, `cargo build --locked --release`, which builds - `vigem-client` on Windows; +**Preflight (Q13):** establish whether `raven-sleipnir` runs today (B16 says +unverified). On Raven, read: +- the scheduled task the legacy target keeps alive + (`Ops idunn-deployment-targets.ps1:126-138`); +- Sleipnir's published health `sleipnir.cultnet-rudp-input-mirror-health` on + Odin. + +If it runs, Raven's local pad mirror is live. It dials Raven's Muninn at +`10.77.0.4:17887` with JSON, and it breaks the moment Idunn deploys a +`main` that contains H2 (`raven-muninn` admits `refs/heads/main` by +`ref-head`, binding `raven-muninn.toml.in:7-9`). + +**Steps:** +- **Sleipnir recipe** `deployment/idunn/raven-sleipnir.toml` in **Muninn's** + repo, beside `raven-muninn.toml`: + - a `rust-host` build step, `cargo build --locked --release -p sleipnir-daemon + --bin sleipnir`, which builds `vigem-client` on Windows; - `[[dependencies]] odin.verse-rendezvous`, per Idunn's B3 ruling ("the recipe declares readiness"), because Sleipnir publishes its Eve surface - to Odin; - - its presence contract, modelled on `idunn_presence.rs` in Muninn; - - the binding goes in gamecult-ops. + and its requests to Odin; + - its presence contract. +- **Presence:** `M src/idunn_presence.rs` (229 lines; Muninn-specific only in + one doc line and one error string, `:14`, `:146`) moves **verbatim** into + `muninn-contracts` as `idunn_presence`. Both daemons call it. + - Delete Sleipnir's legacy `publish_idunn_health_if_configured` and + `publish_idunn_rudp_health` (`S :792-905`), their three flags + (`S :2853-2867`), and the `IdunnDaemonHealthRecord` import. That leaves + three odin-core symbols. + - Presence's rightful owner is CultLib, because every Idunn-launched daemon + needs it. Recorded under "Substrate missing"; not moved here. +- **Binding** `idunn/yggdrasil/bindings/raven-sleipnir.toml.in` in + gamecult-ops, modelled on `raven-muninn.toml.in`, with the same repository + (`GameCult/Muninn`) and a different `recipe_path`. + - In the same change, `raven-muninn.toml.in`'s argument binding + `hid_controller_rudp_advertise` (`:38`) becomes `input_rudp_advertise`. - **Retire** the legacy `raven-sleipnir` script target - (`idunn-deployment-targets.ps1:126-138`) in the same gamecult-ops change. - gamecult-ops owns it. -- **The viewer's Muninn**, per Q10. The viewer's host needs a Muninn that - captures the pad. For Starfire, that is the `starfire-muninn` target - rebound to an Idunn recipe; it is legacy today (teardown-map L74). A viewer - outside GameCult's hosts runs Muninn by hand. That limit is recorded, not - solved here. -- **Firewall:** the host that listens, per Q10, opens one UDP port. Under the - recommended direction that is the game host, Raven, which already opens - 5220 and 17887. + (`Ops idunn-deployment-targets.ps1:126-138`, `Repo = "Odin"`) and + `scripts/deploy-raven-sleipnir.ps1` / `restart-raven-sleipnir.ps1`, in the + same gamecult-ops change. gamecult-ops owns them. +- **The viewer's Muninn.** + - Starfire's is the legacy `starfire-muninn` script target + (`Ops :74-86`). `restart-starfire-muninn.ps1:14-15, 74-79` already passes + an optional HID bind and advertise; these become `--input-rudp-bind` and + `--input-rudp-advertise`, with Starfire's mesh address advertised. + - Rebinding `starfire-muninn` to an Idunn recipe is its own ops item, not + this cut. + - A viewer outside GameCult's hosts runs Muninn by hand. That limit is + recorded, not solved here. +- **Firewall, per the Q10 consequence:** each **viewer** host admits inbound + UDP on its input port (17887) from the game host. Starfire needs one + Windows Firewall rule. It is scoped to the mesh interface where possible, + and recorded in gamecult-ops inventory beside Raven's 5220/17887. Raven + keeps 17887 open only while it also produces input for its own local + mirror. - **What only live proves.** Raven with a game, the operator present, and the - ported `xinput_edge_observer` example reading the ViGEm pad as the game - does: - - taps from Starfire's pad reach the game over LAN and over the mesh hairpin; + ported `xinput_edge_observer` example (`80adfd3`, 127 lines, into + `crates/sleipnir-daemon/examples/`) reading the ViGEm pad as the game does: + - Sleipnir on Raven finds Starfire's advertisement, requests, dials, and the + request is answered `running`; + - taps from Starfire's pad reach the game over LAN and over the mesh + hairpin; - the observer shows every tap at ≥ 24 ms visibility; - - end-to-end input latency. + - end-to-end input latency, from `edge_captured_ns` to the observer; + - a `serve` restart on Starfire resumes input with no operator action (B23). + +**Ledger (repo code only):** about −115 (legacy health) and +40 (presence +wiring). The recipe and binding are declarations. --- ## Sequencing -Two tracks, media and input. They share Muninn's `main.rs`, so their Hands -run **serially in Muninn**, and in parallel only across repositories and -worktrees. +Two tracks, media and input. From H3 on they share one repository, Muninn, +and `muninn-daemon/src/main.rs`, so their Hands run **serially in Muninn**, +and in parallel only across repositories and worktrees. **Now:** -1. **Cuts 0-1** (in Hands, `hands/rr-cut0-1`). +1. **Cuts 0-1** (merged to `main` at `c3520d1`). 2. **Retag `3e96c6c` as `pins/odin-core-cultlib-c2a9a6e`** (Q2 note). This is a tag only; Odin `main` is untouched. 3. **Muninn named cut 3** (retire `--idunn-rudp-health`). It removes one of @@ -1465,21 +1951,27 @@ worktrees. 6. **In parallel, other repos:** Cut 3 (CultLib worktree; Soul passes before the tag). -**Input track** (after step 5): -7. **H1** (`muninn-contracts`). It can run parallel to Cut 3, in a different - repo. -8. **H2** (Muninn), after Q10. -9. **H3, then H4** (Sleipnir's new repo), after Q9. There is no CultLib bump - and no new `pins/` commit: both sit on `c2a9a6e`. -10. **H5**, after Idunn B3 (the recipe declares its Odin dependency). This is - operator deployment. +**Input track:** +7. **H3** (Sleipnir into Muninn's workspace). Behaviour-neutral and + independent of named cut 1. It touches only manifests, the lock and the + imported crate, so it may run beside Cut 2 without touching `main.rs`. +8. **H1** (`muninn-contracts`), after step 5 and Q11. If Q11 rules CultLib, H1 + joins Cut 3's CultLib work and the input track waits for the pin gate + (step 12). +9. **H2 and H4** on one Hands branch, after Q12. Soul verifies each cut + separately. They **merge to `main` together, and only when H5 is ready to + deploy in the same window**, or with `raven-muninn`'s deployment brake + engaged, because `raven-muninn` deploys `main`'s head and a new-wire + Muninn breaks the legacy Sleipnir (Q13). +10. **H5**, after Idunn B3 (the recipe declares its Odin dependency), and the + Q13 preflight. This is operator deployment. **Media track:** 11. **Pin gate:** a single-purpose Odin commit bumps odin-core to Cut 3's CultLib tag, parented on `3e96c6c`, tagged - `pins/odin-core-cultlib-`. Muninn, Sleipnir and Ratatoskr then move - their pins in lockstep. **Sleipnir moves too**, because it shares - `muninn-contracts`. + `pins/odin-core-cultlib-`. Muninn's `[workspace.dependencies]` (H3) + moves once, which moves Muninn and Sleipnir together by construction. + Ratatoskr moves in lockstep. 12. **Cut 4** (Ratatoskr), then **Cut 5** (Muninn video parity). 13. **Cut 6a** (after Cut 2; independent of Cut 5), then **6b** (after Cut 5, for the ceiling), then **6c** (after `route/b3-declare` merges, Idunn B3, @@ -1498,60 +1990,96 @@ worktrees. After the ship: the Odin commit that deletes `crates/sleipnir-daemon`, and optionally Odin's own CultLib bump, which is the Odin Stability session's call. -**Recipe contention.** Only 6c edits `raven-muninn.toml`, and only on top of -`2260853` after it merges. H5 creates `raven-sleipnir.toml` in a different -repository. +**Recipe contention.** 6c and H2 both edit `raven-muninn.toml`, in different +blocks (H2: the input arguments `:62-65` and a `[[provides]]`; 6c: the encoder), +and both sit on top of `2260853` after it merges. Whichever lands second +rebases. H5 creates `raven-sleipnir.toml` beside it. **Yggdrasil load.** One job at a time for this campaign while StreamPixels' verification runs. 6a's apt install makes its jobs longer, so batch its unit -and integration runs into one job. +and integration runs into one job. H2 and H4 run as one job. --- ## Operator questions -Q1-Q8 are ruled; see the Rulings block. Two forks are open. Neither blocks the +Q1-Q10 are ruled; see the Rulings block. Three forks are open. None blocks the media track. -**Q9. Where does Sleipnir live once it changes?** +**Q11. Who owns the input-stream capability records?** - Context: - - Sleipnir is in Odin's workspace at Odin `main`'s CultLib pin (`a8aedda`). - That pin carries StreamPixels and must not move now. - - Consuming Muninn's HID records at Muninn's pin reopens the two-`cultcache-rs` - diamond inside Odin, and only moving that pin closes it (B16). + - The video capability's pair is CultLib's producer-agnostic + `gamecult.media_stream_*` (`C media_stream_contracts.rs:71-183`). Muninn, + Ratatoskr and StreamPixels' vendored copy share it across three repos. + - Input has one producer (Muninn) and one consumer (Sleipnir), and after Q9 + they share one workspace. + - Any CultLib change moves Muninn off `c2a9a6e`, and only the pin gate + closes the odin-core diamond that reopens (B11). - Options: - - (a) **Own repo `GameCult/Sleipnir`**, with history from Odin. Its pins match - Muninn's, and odin-core comes from the `pins/` tag. Odin `main` deletes its - copy after the ship. This is the Muninn and Ratatoskr pattern: one organ, - one repo, one deploy target. - - (b) **A crate in Muninn's workspace.** Cheapest: one pin set, and the - contracts crate is internal. But the capture broker's repo then also owns - the actuator on another host with different privileges (ViGEm). - - (c) **Stay in Odin, on a branch**, until the ship, then bump Odin's pin. - This puts an off-`main` body on Raven for the whole interval, which is the - drift the doctrine forbids, and it blocks H3-H5 on the ship. -- Recommendation: **(a)**. Choose (b) if a new repository's overhead (CI, - pins, a recipe) outweighs the separation for now. Both avoid Odin `main`. + - (a) **`muninn-contracts`, as `muninn.input_stream_*`.** H1 needs no CultLib + change and runs before Cut 3's tag. When a second producer or consumer + appears, the records move to CultLib under `gamecult.*`. They are live + documents republished every tick, not stored truth, so that move is a + schema rename with no migration. + - (b) **CultLib, as `gamecult.input_stream_*`,** beside the media pair. This + is the general-library shape a reasonable CultLib consumer would expect, + and it is the exact mirror. H1 joins Cut 3's CultLib tag, and the whole + input track waits for the pin gate (step 12), behind Cuts 3 and 4. +- Recommendation: **(a)**. The mechanism is mirrored exactly; only the + schema's owner differs, and it differs because the capability has one + implementation today. +- What depends on it: H1's location and ids; whether the input track waits + for the pin gate; `MuninnDocuments` and `SleipnirDocuments` registrations. -**Q10. Which end dials, for remote-play input?** +**Q12. Move evidence rides the HID listener. What happens to it?** (B20) - Context: - - Today Sleipnir dials Muninn's HID listener (Raven:17887). Muninn also has - an outbound path (B15). - - In remote play, Muninn runs on the **viewer's** host. If Sleipnir dials, - every viewer opens an inbound UDP port. - - That is what the 2026-09-10 media inversion ruled out for viewers - (teardown-map L486-495): "not something a user can be asked for". + - Muninn sends Move-evidence frames (MessagePack + `mimir.muninn_move_evidence_stream_frame.v1`) on channel `move-evidence` + of the HID connection, only to a session that sent the JSON + `hid.subscribe`. + - Mimir's runtime does that (`Mi MimirOdinMoveProofEvidenceRingProvider.cs:223`), + after finding the endpoint in the JSON `inputStreams` H2 deletes. + - Mimir's provider was last changed on 2026-07-14 (`345c46b`). Raven's + recipe sets no `--move-evidence-stream`. Nightwing and Starfire configure + it. - Options: - - (a) **The viewer's Muninn dials the game host's Sleipnir.** Sleipnir - listens and advertises its endpoint through Odin, as Muninn does for media. - Delete Muninn's ingress server. - - (b) **Keep Sleipnir dialling Muninn.** Delete Muninn's outbound client. - Every viewer admits inbound UDP. -- Recommendation: **(a)**, consistent with the media ruling. The game host - already admits UDP. Consequence: Sleipnir gains a listening - `CultNetRudpServerHub`, and **subscription** becomes Sleipnir telling each - attached Muninn which device it wants, over the same session. The records - are unchanged. + - (a) **Fold Move evidence into the input-stream capability.** Muninn + advertises a second `muninn.input_stream_advertisement.v1` per host, with + a `payload_schema` field distinguishing HID frames from Move-evidence + frames. Mimir requests it by document and dials with its `receiver_id`. + This needs a Mimir (C#) cut, "H2m", landing with H2. + - (b) **Keep a Move-evidence-only JSON `hid.subscribe` arm** on the new hub + until Mimir moves. This keeps JSON on a live wire (invariant 14) and a + second admission path (Q10), so it needs a named deletion line. + - (c) **Drop the remote Move-evidence transport**, if Mimir's move proof is + dormant. Delete the RUDP hand-off (`M :4267-4275`), `rudp_sender`, and the + bind coupling of `local_ring_enabled` (`:4238`). Mimir re-enters through + (a) when it next needs the stream. +- Recommendation: **(a) if anyone runs Mimir's move proof today, else (c).** + (b) only as a bounded bridge under (a). +- What depends on it: H2's deletion list items 2 and 7; whether a Mimir cut + joins the input track. + +**Q13. Is Raven's legacy Sleipnir live, and may its local mirror go dark +between the H2/H4 merge and H5?** +- Context: + - B16 left "whether it runs on Raven today" unverified. + - `raven-muninn` deploys `main`'s head. The moment `main` holds H2, Raven's + Muninn speaks the new wire, and a legacy JSON Sleipnir on Raven stops + receiving input. +- Options: + - (a) **Hold the H2/H4 merge until H5 deploys in the same window.** No dark + interval; the merge waits on Idunn B3. + - (b) **Merge when Soul passes, with `raven-muninn`'s deployment brake + engaged** until H5. Raven's Muninn stays on the previous release, and + media Cuts behind it wait too. + - (c) **Accept a dark interval** for Raven's local mirror, if the preflight + shows it is not in use. +- Recommendation: run H5's preflight first. If the mirror is live, choose + **(a)**. If not, choose **(c)**. (b) blocks the media track and is the + worst trade. +- What depends on it: when H2 and H4 may merge; whether H5 waits on B3 before + any of the input track lands on `main`. --- From 83b3947a8f7923d876e1a75eb7bd1f72f82131a7 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 19:58:10 +0200 Subject: [PATCH 20/44] Record Q11 (muninn-contracts) and Q12 (fold Move evidence in) Co-Authored-By: Claude Opus 5.5 --- docs/realtime-robustness-cut.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/realtime-robustness-cut.md b/docs/realtime-robustness-cut.md index f52f1ef..478562d 100644 --- a/docs/realtime-robustness-cut.md +++ b/docs/realtime-robustness-cut.md @@ -68,6 +68,13 @@ the ruled design. The earlier options survive only in git (`e70db69`). and Sleipnir requests it the way Ratatoskr requests video. The HID cuts H0-H5 need re-mapping to this shape before Hands. +**Rulings, 2026-09-30 (operator), pass 3 forks:** +- **Q11 (a): the input-stream records live in `muninn-contracts` as `muninn.input_stream_*`.** The input track + needs no CultLib change. Promote them to CultLib if a second producer appears. +- **Q12 (a): Mimir's Move proof is in use.** Move evidence becomes a channel on the input-stream session, and a + small Mimir cut switches over. H2 waits for that Mimir cut. +- **Q13 is open.** Run H5's preflight first, to find out whether Raven's legacy Sleipnir is live. + ## Target: ends and invariants **End.** A Muninn stream that loses packets degrades by what each signal class From 8d869ca8dfbd9e9f7deec0c5be8b1bbec5cda83b Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 20:01:33 +0200 Subject: [PATCH 21/44] Record Q13: no live Sleipnir on Raven, H2 and H4 merge independently Co-Authored-By: Claude Opus 5.5 --- docs/realtime-robustness-cut.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/realtime-robustness-cut.md b/docs/realtime-robustness-cut.md index 478562d..cd5b568 100644 --- a/docs/realtime-robustness-cut.md +++ b/docs/realtime-robustness-cut.md @@ -73,7 +73,11 @@ the ruled design. The earlier options survive only in git (`e70db69`). needs no CultLib change. Promote them to CultLib if a second producer appears. - **Q12 (a): Mimir's Move proof is in use.** Move evidence becomes a channel on the input-stream session, and a small Mimir cut switches over. H2 waits for that Mimir cut. -- **Q13 is open.** Run H5's preflight first, to find out whether Raven's legacy Sleipnir is live. +- **Q13 (c): no live Sleipnir, so accept the gap.** H2 and H4 may merge independently. The operator said + (2026-09-30): "If Sleipnir is running, feel free to take it down; we're certainly not using it". + - Checked read-only on Raven the same day: no Sleipnir process is running. + - Only an on-demand scheduled task, `\Codex-Sleipnir-LAN-Proof`, remains. It last ran on 2026-07-17. + - Raven runs `muninn.exe` alone. ## Target: ends and invariants From e66c2565fbb0f16b06b87f8c0ea038ca9d326589 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 20:04:17 +0200 Subject: [PATCH 22/44] Bound the media sender: one deadline owner, whole-group drops, a drivable seam The sender's queues were unbounded (mpsc::channel plus two VecDeques), expired payloads one at a time so half a frame could leave after the other half died, gave repairs a fresh deadline from the clock, spun on a 1 ms sleep, and could not be driven without PowerShell, ffmpeg and WASAPI. The latency budget also had two owners: a 2 s producer default that the receiver's 250 ms age never matched. MediaSendCore (new media_send.rs) owns the queues, hub, feedback intake, repair cache and budget, and progress counters. run_rudp_mux_once now spawns encoders, feeds readers into the core and publishes; it decides no deadline. - The unit is a group: one access unit with its parity, or one audio packet, stamped produced_at + the request's latency budget when it leaves the packetizer. Expiry is per group; a group is sent whole or not at all. - Queues are capped per kind (audio 256, video 512 groups), drop the oldest group and count it (groups_dropped_audio, groups_dropped_video). The reader channel is a bounded sync_channel. - The Annex B packetizer returns one group per access unit and no longer errors on pending overflow: an unfinished access unit larger than the ceiling is dropped and counted. - Repairs inherit the deadline of their frame and are not sent after it. A blocked send polls resends and stops at the group deadline; the sleep is gone. - MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS is deleted. The default budget is 250 ms (Q7), used only when a request names none and offered as the advertisement's default_latency_budget_ms. The profile loses its three copies of the budget; the telemetry JSON carries one latency_budget_ms. - A test harness drives the real readers and core over loopback through a seeded drop relay to a CultNet RUDP client, from a committed H.264 clip (testdata/clip.h264, ffmpeg command recorded beside it) and a PCM ramp. Co-Authored-By: Claude Opus 5.5 --- crates/muninn-daemon/src/main.rs | 1239 ++--------------- crates/muninn-daemon/src/media_packetizer.rs | 143 +- crates/muninn-daemon/src/media_send.rs | 960 +++++++++++++ crates/muninn-daemon/src/media_send/tests.rs | 845 +++++++++++ crates/muninn-daemon/testdata/clip.h264 | Bin 0 -> 8855 bytes .../testdata/clip.h264.provenance.txt | 7 + 6 files changed, 2065 insertions(+), 1129 deletions(-) create mode 100644 crates/muninn-daemon/src/media_send.rs create mode 100644 crates/muninn-daemon/src/media_send/tests.rs create mode 100644 crates/muninn-daemon/testdata/clip.h264 create mode 100644 crates/muninn-daemon/testdata/clip.h264.provenance.txt diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index 7857ad3..0b69938 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -1,10 +1,11 @@ mod idunn_presence; mod media_packetizer; +mod media_send; -use crate::media_packetizer::{ - AudioPcmStreamSendConfig, AudioPcmStreamSendState, GameCultMediaWireRecord, - MuninnMediaSendPayload, VideoAnnexBStreamSendConfig, VideoAnnexBStreamSendState, - decode_media_wire_record, +use crate::media_packetizer::{AudioPcmStreamSendConfig, VideoAnnexBStreamSendConfig}; +use crate::media_send::{ + MediaSendCore, MediaSendPolicy, media_intake_channel, spawn_audio_group_reader, + spawn_video_group_reader, }; use anyhow::{Context, Result, anyhow}; use cultmesh_rs::{ @@ -12,12 +13,11 @@ use cultmesh_rs::{ CultMeshSharedMemoryFrameRing, CultMeshStreamBodyTransport, CultMeshStreamCatalog, CultMeshStreamClock, CultMeshStreamDescriptor, CultMeshStreamKind, }; -use cultnet_rs::GameCultMediaReceiverFeedbackRecord; use cultnet_rs::{ - CultNetMessage, CultNetRawDocumentRecord, CultNetRawPayloadEncoding, CultNetRudpServerEvent, - CultNetRudpServerHub, CultNetRudpServerHubOptions, CultNetRudpServerSessionContext, - CultNetRudpSocketTransportConnection, CultNetRudpSocketTransportOptions, CultNetTransportFrame, - CultNetWireContract, GAMECULT_MEDIA_STREAM_ADVERTISEMENT_SCHEMA, + CultNetMessage, CultNetRawDocumentRecord, CultNetRawPayloadEncoding, CultNetRudpServerHub, + CultNetRudpServerHubOptions, CultNetRudpSocketTransportConnection, + CultNetRudpSocketTransportOptions, CultNetWireContract, + GAMECULT_MEDIA_STREAM_ADVERTISEMENT_SCHEMA, GAMECULT_MEDIA_STREAM_REQUEST_SCHEMA, GAMECULT_RUNTIME_PRESENCE_HEALTH_SCHEMA, GameCultMediaStreamAdvertisementRecord, GameCultMediaStreamRequestRecord, GameCultRuntimePresenceHealthRecord, decode_cultnet_message_from_slice, @@ -37,7 +37,7 @@ use odin_core::{ }; use serde::{Deserialize, Serialize}; use serde_json::json; -use std::collections::{HashMap, HashSet, VecDeque}; +use std::collections::{HashMap, HashSet}; use std::env; use std::fs; #[cfg(feature = "psmoveapi-tracker")] @@ -52,8 +52,9 @@ use std::process::{Child, Command, Stdio}; use std::sync::{ Arc, Mutex, atomic::{AtomicU64, Ordering}, - mpsc, }; +#[cfg(any(windows, feature = "psmoveapi-tracker"))] +use std::sync::mpsc; use std::thread; use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; @@ -90,25 +91,14 @@ const MUNINN_RUDP_MEDIA_MAX_FRAGMENT_BYTES: usize = MUNINN_RUDP_IPV4_UDP_PAYLOAD /// nearly every audio fragment was resent before its ack arrived and the /// producer's send loop drowned in retransmits, starving video (measured /// 2026-09-10: 7 frames in 9 s with audio on, 266 without). Audio expires at -/// the assembly deadline anyway; 30 ms costs nothing it can feel. +/// the latency budget anyway; 30 ms costs nothing it can feel. const MUNINN_RUDP_MEDIA_RESEND_DELAY_MS: u64 = 30; -const MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS: u64 = 2_000; +/// What a request that names no latency budget gets, and what the +/// advertisement offers as `default_latency_budget_ms`. It is the request, +/// not this constant, that owns the deadline once one is named. +const MUNINN_RUDP_MEDIA_DEFAULT_LATENCY_BUDGET_MS: u64 = 250; const MUNINN_RUDP_MEDIA_RECEIVER_GAP_WAIT_MS: u64 = 16; -const MUNINN_RUDP_MEDIA_REPAIR_CACHE_CHUNKS: usize = 16_384; -const MUNINN_RUDP_MEDIA_REPAIR_BURST_CHUNKS: usize = 2_048; -const MUNINN_RUDP_MEDIA_REPAIR_INITIAL_CHUNKS_PER_SECOND: usize = 4_096; -const MUNINN_RUDP_MEDIA_REPAIR_MIN_CHUNKS_PER_SECOND: usize = 8; -const MUNINN_RUDP_MEDIA_REPAIR_MAX_CHUNKS_PER_SECOND: usize = 16_384; -const MUNINN_RUDP_MEDIA_REPAIR_ADD_CHUNKS_PER_SECOND: usize = 2_048; -const MUNINN_RUDP_MEDIA_REPAIR_RECOVERY_INTERVAL_MS: u64 = 2_000; -const MUNINN_RUDP_MEDIA_REPAIR_MAX_FEEDBACK_PER_POLL: usize = 32; -const MUNINN_RUDP_MEDIA_REPAIR_MAX_CHUNKS_PER_POLL: usize = 256; const MUNINN_RUDP_MEDIA_SOCKET_BUFFER_BYTES: usize = 16 * 1024 * 1024; -/// A receiver that has said nothing for this long (Ratatoskr pings every -/// second or so) is dropped so its payloads stop being sent into the void. -const MUNINN_RUDP_MEDIA_RECEIVER_TIMEOUT_MS: u64 = 6_000; -const MUNINN_RUDP_MEDIA_SEND_PACE_EVERY_PAYLOADS: usize = 4; -const MUNINN_RUDP_MEDIA_SEND_PACE_SLEEP_US: u64 = 250; const MUNINN_RUDP_ACTIVE_CATALOG_REPUBLISH_MS: u64 = 2_000; const MUNINN_ODIN_PROVIDER_LEASE_REFRESH_SECONDS: u64 = 30; const PS_MOVE_LED_REPORT_LEN: usize = 49; @@ -275,12 +265,7 @@ struct MuninnRudpMediaProfile { max_fragment_bytes: usize, video_b_frames: u8, video_rc_lookahead: u8, - sender_queue_deadline_ms: u64, sender_resend_delay_ms: u64, - sender_reliable_expire_after_ms: u64, - sender_pace_every_payloads: usize, - sender_pace_sleep_us: u64, - receiver_assembly_deadline_ms: u64, receiver_gap_wait_ms: u64, } @@ -1488,7 +1473,7 @@ fn command_rudp_video_bitrate_kbps(command: &MuninnCaptureStreamCommandRecord) - fn command_rudp_latency_budget_ms(command: &MuninnCaptureStreamCommandRecord) -> u32 { if command.rudp_latency_budget_ms == 0 { - MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS as u32 + MUNINN_RUDP_MEDIA_DEFAULT_LATENCY_BUDGET_MS as u32 } else { command.rudp_latency_budget_ms } @@ -2415,7 +2400,8 @@ fn run_rudp_mux_once( let mut audio_sender = None; let result = (|| -> Result { let media_profile = muninn_rudp_media_profile_for_options(options); - let mut hub = open_media_rudp_hub(options, &media_profile)?; + let policy = MediaSendPolicy::from_request(options.rudp_latency_budget_ms); + let hub = open_media_rudp_hub(options, &media_profile, &policy)?; publish_stream( node, options, @@ -2431,10 +2417,10 @@ fn run_rudp_mux_once( )?; let mut last_stream_publish_at = Instant::now(); - let (payload_tx, payload_rx) = mpsc::channel::>(); + let (intake_tx, intake_rx) = media_intake_channel(); video_sender = if let Some(stdout) = video_ffmpeg_stdout { - Some(video_rudp_payload_reader( - payload_tx.clone(), + Some(spawn_video_group_reader( + intake_tx.clone(), stdout, VideoAnnexBStreamSendConfig { stream_id: options.stream_id.clone(), @@ -2445,19 +2431,20 @@ fn run_rudp_mux_once( frame_duration_ticks: video_frame_duration_ticks(options)?, timebase_num: 1, timebase_den: 90_000, - deadline_delay_ticks: rudp_media_deadline_delay_ticks(&media_profile), + deadline_delay_ticks: policy.video_deadline_delay_ticks(), max_payload_bytes: options.media_packet_bytes.max(256), max_pending_bytes: options.media_packet_bytes.max(256) * 4096, source_runtime_id: options.host_id.clone(), source_role: "muninn.rudp.video".to_string(), }, + policy.clone(), )) } else { None }; audio_sender = if let Some(stdout) = audio_ffmpeg_stdout { - Some(audio_rudp_payload_reader( - payload_tx.clone(), + Some(spawn_audio_group_reader( + intake_tx.clone(), stdout, AudioPcmStreamSendConfig { stream_id: options.stream_id.clone(), @@ -2468,7 +2455,7 @@ fn run_rudp_mux_once( packet_duration_ticks: 480, timebase_num: 1, timebase_den: options.audio_sample_rate, - deadline_delay_ticks: rudp_audio_deadline_delay_ticks(options, &media_profile), + deadline_delay_ticks: policy.audio_deadline_delay_ticks(options.audio_sample_rate), channels: options.audio_channels, bytes_per_sample: 4, max_pending_bytes: 480usize @@ -2478,193 +2465,39 @@ fn run_rudp_mux_once( source_runtime_id: options.host_id.clone(), source_role: "muninn.rudp.audio".to_string(), }, + policy.clone(), )) } else { None }; - drop(payload_tx); + drop(intake_tx); - let mut payloads_sent = 0_u64; - let mut payloads_queue_expired = 0_u64; - let mut payloads_send_expired = 0_u64; - let mut receiver_feedback = MuninnRudpReceiverFeedbackStats::default(); - let mut handled_keyframe_requests = 0_u64; - let mut repair_cache = - RecentVideoChunkRepairCache::new(MUNINN_RUDP_MEDIA_REPAIR_CACHE_CHUNKS); - let mut repair_budget = MuninnRudpRepairBudget::new( - MUNINN_RUDP_MEDIA_REPAIR_INITIAL_CHUNKS_PER_SECOND, - MUNINN_RUDP_MEDIA_REPAIR_BURST_CHUNKS, - ); - let mut video_send_pacer = MuninnRudpMediaSendPacer::new( - media_profile.sender_pace_every_payloads, - Duration::from_micros(media_profile.sender_pace_sleep_us), - ); - let mut audio_send_pacer = MuninnRudpMediaSendPacer::new(0, Duration::ZERO); - let mut pending_payloads = PendingMuninnMediaSendQueues::default(); - let mut payload_channel_disconnected = false; + let mut core = MediaSendCore::new(hub, &policy); loop { - if pending_payloads.is_empty() && !payload_channel_disconnected { - payload_channel_disconnected = receive_pending_media_payloads( - &payload_rx, - &mut pending_payloads, - Duration::from_millis(5), - )?; - } else if !payload_channel_disconnected { - payload_channel_disconnected = - drain_available_media_payloads(&payload_rx, &mut pending_payloads)?; - } - - if let Some(queued) = pending_payloads.pop_next() { - if media_payload_queue_age_exceeded( - queued.queued_at, - Instant::now(), - Duration::from_millis(media_profile.sender_queue_deadline_ms), - ) { - payloads_queue_expired += 1; - let payloads_dropped = payloads_queue_expired + payloads_send_expired; - // A stale payload is already unsendable. Do not make - // queue recovery slower by polling feedback, sending - // repairs, and polling retransmits once for every stale - // item. Normal live-send and idle paths service those - // controls as soon as the expired backlog is drained. - if payloads_dropped == 1 || payloads_dropped % 300 == 0 { - let expired = reliable_packets_expired(&hub); - eprintln!( - "{}", - rudp_media_progress_detail( - payloads_sent, - payloads_dropped, - payloads_queue_expired, - payloads_send_expired, - expired, - hub.sessions().len(), - &receiver_feedback - ) - ); - } - continue; - } - - let payload_len = queued.payload.payload.len(); - let send_pacer = match queued.kind { - QueuedMuninnMediaKind::Video => &mut video_send_pacer, - QueuedMuninnMediaKind::Audio => &mut audio_send_pacer, - }; - let sent = send_rudp_media_payload_with_backpressure( - &mut hub, - None, - queued.payload.clone(), - queued.queued_at, - Duration::from_millis(media_profile.sender_queue_deadline_ms), - send_pacer, - )?; - if !sent { - payloads_send_expired += 1; - continue; - } - let payloads_dropped = payloads_queue_expired + payloads_send_expired; - if queued.kind == QueuedMuninnMediaKind::Video { - repair_cache.remember(&queued.payload)?; - } - poll_rudp_media_receiver_feedback( - &mut hub, - &mut receiver_feedback, - &repair_cache, - &mut repair_budget, - &media_profile, - &mut video_send_pacer, - payloads_dropped, - )?; - record_receiver_keyframe_pressure( - &receiver_feedback, - &mut handled_keyframe_requests, - ); - poll_rudp_resends_with_backpressure(&mut hub)?; - republish_running_stream_if_due( - node, - options, - plan, - supervisor_pid, - video_ffmpeg - .as_ref() - .map(Child::id) - .or_else(|| audio_ffmpeg.as_ref().map(Child::id)) - .unwrap_or(supervisor_pid), - restart_count, - &mut last_stream_publish_at, - )?; - payloads_sent += 1; - if payloads_sent == 1 || payloads_sent % 900 == 0 { - let expired = reliable_packets_expired(&hub); - eprintln!( - "{}; pending_audio={} pending_video={}; latest {:?} payload was {payload_len} bytes.", - rudp_media_progress_detail( - payloads_sent, - payloads_dropped, - payloads_queue_expired, - payloads_send_expired, - expired, - hub.sessions().len(), - &receiver_feedback - ), - pending_payloads.audio_len(), - pending_payloads.video_len(), - queued.kind - ); - } - continue; - } - - if payload_channel_disconnected { - let expired = reliable_packets_expired(&hub); - let payloads_dropped = payloads_queue_expired + payloads_send_expired; + core.intake(&intake_rx, Duration::from_millis(5))?; + if core.send_next(Instant::now())? { + core.service_control(Instant::now())?; + } else if core.finished() { break Ok(RudpMuxRestart { - detail: format!( - "encoder stdout ended; {}", - rudp_media_progress_detail( - payloads_sent, - payloads_dropped, - payloads_queue_expired, - payloads_send_expired, - expired, - hub.sessions().len(), - &receiver_feedback - ) - ), + detail: format!("encoder stdout ended; {}", core.progress_detail()), delay: default_rudp_mux_restart_delay(restart_count), }); + } else { + core.service_control(Instant::now())?; } - - { - let payloads_dropped = payloads_queue_expired + payloads_send_expired; - poll_rudp_media_receiver_feedback( - &mut hub, - &mut receiver_feedback, - &repair_cache, - &mut repair_budget, - &media_profile, - &mut video_send_pacer, - payloads_dropped, - )?; - record_receiver_keyframe_pressure( - &receiver_feedback, - &mut handled_keyframe_requests, - ); - poll_rudp_resends_with_backpressure(&mut hub)?; - republish_running_stream_if_due( - node, - options, - plan, - supervisor_pid, - video_ffmpeg - .as_ref() - .map(Child::id) - .or_else(|| audio_ffmpeg.as_ref().map(Child::id)) - .unwrap_or(supervisor_pid), - restart_count, - &mut last_stream_publish_at, - )?; - } + republish_running_stream_if_due( + node, + options, + plan, + supervisor_pid, + video_ffmpeg + .as_ref() + .map(Child::id) + .or_else(|| audio_ffmpeg.as_ref().map(Child::id)) + .unwrap_or(supervisor_pid), + restart_count, + &mut last_stream_publish_at, + )?; } })(); @@ -2692,506 +2525,17 @@ fn run_rudp_mux_once( result } -struct QueuedMuninnMediaSendPayload { - payload: MuninnMediaSendPayload, - queued_at: Instant, - kind: QueuedMuninnMediaKind, -} - -#[derive(Clone, Copy, Debug, PartialEq, Eq)] -enum QueuedMuninnMediaKind { - Video, - Audio, -} - -#[derive(Default)] -struct PendingMuninnMediaSendQueues { - audio: VecDeque, - video: VecDeque, -} - -impl PendingMuninnMediaSendQueues { - fn push(&mut self, payload: QueuedMuninnMediaSendPayload) { - match payload.kind { - QueuedMuninnMediaKind::Audio => self.audio.push_back(payload), - QueuedMuninnMediaKind::Video => self.video.push_back(payload), - } - } - - fn pop_next(&mut self) -> Option { - self.audio.pop_front().or_else(|| self.video.pop_front()) - } - - fn is_empty(&self) -> bool { - self.audio.is_empty() && self.video.is_empty() - } - - fn audio_len(&self) -> usize { - self.audio.len() - } - - fn video_len(&self) -> usize { - self.video.len() - } -} - -#[derive(Clone, Debug, Default, PartialEq, Eq)] -struct MuninnRudpReceiverFeedbackStats { - feedback_records: u64, - requested_keyframes: u64, - late_frames: u64, - missing_video_chunks: u64, - repaired_video_chunks: u64, - deferred_repair_chunks: u64, - repair_chunks_per_second: usize, - highest_decodable_frame_id: Option, -} - -#[derive(Debug)] -struct MuninnRudpRepairBudget { - chunks_per_second: usize, - min_chunks_per_second: usize, - max_chunks_per_second: usize, - add_chunks_per_second: usize, - recovery_interval: Duration, - max_available_chunks: usize, - available_chunks: usize, - last_refill_at: Instant, - last_rate_adjust_at: Instant, - last_queue_dropped: u64, -} - -impl MuninnRudpRepairBudget { - fn new(chunks_per_second: usize, max_available_chunks: usize) -> Self { - let now = Instant::now(); - let max_available_chunks = max_available_chunks.max(1); - Self { - chunks_per_second: chunks_per_second.max(1), - min_chunks_per_second: MUNINN_RUDP_MEDIA_REPAIR_MIN_CHUNKS_PER_SECOND, - max_chunks_per_second: MUNINN_RUDP_MEDIA_REPAIR_MAX_CHUNKS_PER_SECOND, - add_chunks_per_second: MUNINN_RUDP_MEDIA_REPAIR_ADD_CHUNKS_PER_SECOND, - recovery_interval: Duration::from_millis(MUNINN_RUDP_MEDIA_REPAIR_RECOVERY_INTERVAL_MS), - max_available_chunks, - available_chunks: max_available_chunks, - last_refill_at: now, - last_rate_adjust_at: now, - last_queue_dropped: 0, - } - } - - fn chunks_per_second(&self) -> usize { - self.chunks_per_second - } - - fn take(&mut self, requested_chunks: usize, now: Instant, queue_dropped: u64) -> usize { - self.adjust_rate(now, queue_dropped, requested_chunks); - self.refill(now); - let allowed = requested_chunks.min(self.available_chunks); - self.available_chunks -= allowed; - allowed - } - - fn adjust_rate(&mut self, now: Instant, queue_dropped: u64, requested_chunks: usize) { - if queue_dropped > self.last_queue_dropped { - self.chunks_per_second = (self.chunks_per_second / 2).max(self.min_chunks_per_second); - self.available_chunks = self.available_chunks.min(self.chunks_per_second); - self.last_queue_dropped = queue_dropped; - self.last_rate_adjust_at = now; - return; - } - self.last_queue_dropped = queue_dropped; - if requested_chunks == 0 - || now.saturating_duration_since(self.last_rate_adjust_at) < self.recovery_interval - { - return; - } - if self.chunks_per_second < self.max_chunks_per_second { - self.chunks_per_second = self - .chunks_per_second - .saturating_add(self.add_chunks_per_second) - .min(self.max_chunks_per_second); - self.last_rate_adjust_at = now; - } - } - - fn refill(&mut self, now: Instant) { - let elapsed_ms = now - .saturating_duration_since(self.last_refill_at) - .as_millis() as usize; - if elapsed_ms == 0 { - return; - } - let refill_chunks = elapsed_ms.saturating_mul(self.chunks_per_second) / 1_000; - if refill_chunks == 0 { - return; - } - self.available_chunks = self - .available_chunks - .saturating_add(refill_chunks) - .min(self.max_available_chunks); - self.last_refill_at = now; - } -} - -#[derive(Debug)] -struct RecentVideoChunkRepairCache { - max_entries: usize, - order: VecDeque, - entries: HashMap, -} - -impl RecentVideoChunkRepairCache { - fn new(max_entries: usize) -> Self { - Self { - max_entries, - order: VecDeque::new(), - entries: HashMap::new(), - } - } - - fn remember(&mut self, payload: &MuninnMediaSendPayload) -> Result<()> { - let Some(key) = video_repair_cache_key_from_payload(payload)? else { - return Ok(()); - }; - if self.entries.contains_key(&key) { - self.entries.insert(key, payload.clone()); - return Ok(()); - } - self.order.push_back(key.clone()); - self.entries.insert(key, payload.clone()); - while self.entries.len() > self.max_entries { - let Some(expired) = self.order.pop_front() else { - break; - }; - self.entries.remove(&expired); - } - Ok(()) - } - - fn repair_payloads_for_feedback( - &self, - feedback: &GameCultMediaReceiverFeedbackRecord, - ) -> Vec { - feedback - .missing_video_chunk_keys - .iter() - .filter_map(|chunk_key| { - self.entries - .get(&video_repair_cache_key( - &feedback.stream_id, - &feedback.session_id, - chunk_key, - )) - .cloned() - }) - .collect() - } -} - -fn video_repair_cache_key(stream_id: &str, session_id: &str, chunk_key: &str) -> String { - format!("{stream_id}:{session_id}:video:{chunk_key}") -} - -fn video_repair_cache_key_from_payload(payload: &MuninnMediaSendPayload) -> Result> { - if payload.channel_id != crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL { - return Ok(None); - } - let GameCultMediaWireRecord::Video(video) = decode_media_wire_record(&payload.payload)? else { - return Ok(None); - }; - Ok(Some(video_repair_cache_key( - &video.stream_id, - &video.session_id, - &crate::media_packetizer::video_chunk_feedback_key(video.frame_id, video.chunk_index), - ))) -} - -fn queue_muninn_media_payload( - tx: &mpsc::Sender>, - payload: MuninnMediaSendPayload, - kind: QueuedMuninnMediaKind, -) -> Result<()> { - tx.send(Ok(QueuedMuninnMediaSendPayload { - payload, - queued_at: Instant::now(), - kind, - })) - .context("queueing typed Muninn media payload") -} - -fn receive_pending_media_payloads( - rx: &mpsc::Receiver>, - pending: &mut PendingMuninnMediaSendQueues, - timeout: Duration, -) -> Result { - match rx.recv_timeout(timeout) { - Ok(Ok(payload)) => { - pending.push(payload); - drain_available_media_payloads(rx, pending) - } - Ok(Err(error)) => Err(error), - Err(mpsc::RecvTimeoutError::Timeout) => Ok(false), - Err(mpsc::RecvTimeoutError::Disconnected) => Ok(true), - } -} - -fn drain_available_media_payloads( - rx: &mpsc::Receiver>, - pending: &mut PendingMuninnMediaSendQueues, -) -> Result { - loop { - match rx.try_recv() { - Ok(Ok(payload)) => pending.push(payload), - Ok(Err(error)) => return Err(error), - Err(mpsc::TryRecvError::Empty) => return Ok(false), - Err(mpsc::TryRecvError::Disconnected) => return Ok(true), - } - } -} - -fn media_payload_queue_age_exceeded(queued_at: Instant, now: Instant, max_age: Duration) -> bool { - now.saturating_duration_since(queued_at) > max_age -} - -fn poll_rudp_resends_with_backpressure(hub: &mut CultNetRudpServerHub) -> Result<()> { - match hub.poll_resends() { - Ok(()) => Ok(()), - Err(error) if is_would_block_error(&error) => Ok(()), - Err(error) => Err(error).context("polling Muninn RUDP media resends"), - } -} - -/// To one receiver, or with `None` to every receiver attached right now. A -/// payload with nobody to send it to is not a failure; the progress line -/// says how many receivers there are. -fn send_rudp_media_payload_with_backpressure( - hub: &mut CultNetRudpServerHub, - receiver: Option<&CultNetRudpServerSessionContext>, - payload: MuninnMediaSendPayload, - queued_at: Instant, - max_age: Duration, - send_pacer: &mut MuninnRudpMediaSendPacer, -) -> Result { - let receivers = match receiver { - Some(receiver) => vec![receiver.clone()], - None => hub.sessions(), - }; - for receiver in &receivers { - loop { - match hub.send(receiver, payload.channel_id, payload.payload.clone()) { - Ok(()) => break, - Err(error) if is_would_block_error(&error) => { - if media_payload_queue_age_exceeded(queued_at, Instant::now(), max_age) { - return Ok(false); - } - poll_rudp_resends_with_backpressure(hub)?; - thread::sleep(Duration::from_millis(1)); - } - Err(error) => { - return Err(error) - .context("sending typed Muninn media payload over RUDP media"); - } - } - } - } - send_pacer.observe_sent_payload(); - Ok(true) -} - -#[derive(Debug)] -struct MuninnRudpMediaSendPacer { - payloads_since_pause: usize, - every_payloads: usize, - sleep_for: Duration, -} - -impl MuninnRudpMediaSendPacer { - fn new(every_payloads: usize, sleep_for: Duration) -> Self { - Self { - payloads_since_pause: 0, - every_payloads: every_payloads.max(1), - sleep_for, - } - } - - fn observe_sent_payload(&mut self) { - if self.sleep_for.is_zero() { - return; - } - self.payloads_since_pause = self.payloads_since_pause.saturating_add(1); - if self.payloads_since_pause < self.every_payloads { - return; - } - self.payloads_since_pause = 0; - thread::sleep(self.sleep_for); - } -} - -fn is_would_block_error(error: &anyhow::Error) -> bool { - error.chain().any(|cause| { - cause - .downcast_ref::() - .is_some_and(|io| io.kind() == ErrorKind::WouldBlock) - || cause.to_string().contains("os error 10035") - }) -} - fn default_rudp_mux_restart_delay(restart_count: u32) -> Duration { Duration::from_secs((2 + restart_count).min(30) as u64) } -fn record_receiver_keyframe_pressure( - receiver_feedback: &MuninnRudpReceiverFeedbackStats, - handled_keyframe_requests: &mut u64, -) { - if receiver_feedback.requested_keyframes <= *handled_keyframe_requests { - return; - } - *handled_keyframe_requests = receiver_feedback.requested_keyframes; - eprintln!( - "Muninn RUDP receiver requested a fresh keyframe; continuing current low-latency encoder session until explicit encoder control exists." - ); -} - -fn rudp_media_progress_detail( - sent: u64, - queue_dropped: u64, - queue_expired: u64, - send_expired: u64, - reliable_expired: u64, - receivers: usize, - receiver_feedback: &MuninnRudpReceiverFeedbackStats, -) -> String { - format!( - "Muninn RUDP media progress: receivers={receivers} sent={sent} queue_dropped={queue_dropped} queue_expired={queue_expired} send_expired={send_expired} reliable_expired={reliable_expired} receiver_feedback={} receiver_keyframes={} receiver_late_frames={} receiver_missing_chunks={} receiver_repaired_chunks={} receiver_deferred_repairs={} repair_rate={} receiver_highest_decodable={}", - receiver_feedback.feedback_records, - receiver_feedback.requested_keyframes, - receiver_feedback.late_frames, - receiver_feedback.missing_video_chunks, - receiver_feedback.repaired_video_chunks, - receiver_feedback.deferred_repair_chunks, - receiver_feedback.repair_chunks_per_second, - receiver_feedback - .highest_decodable_frame_id - .map(|frame_id| frame_id.to_string()) - .unwrap_or_else(|| "none".to_string()) - ) -} - -fn poll_rudp_media_receiver_feedback( - hub: &mut CultNetRudpServerHub, - stats: &mut MuninnRudpReceiverFeedbackStats, - repair_cache: &RecentVideoChunkRepairCache, - repair_budget: &mut MuninnRudpRepairBudget, - media_profile: &MuninnRudpMediaProfile, - send_pacer: &mut MuninnRudpMediaSendPacer, - queue_dropped: u64, -) -> Result<()> { - for gone in hub.remove_timed_out_sessions(MUNINN_RUDP_MEDIA_RECEIVER_TIMEOUT_MS) { - eprintln!( - "Muninn media receiver {} at {} went silent and was dropped.", - String::from_utf8_lossy(&gone.connect_payload), - gone.remote_addr - ); - } - let mut feedback_processed = 0_usize; - loop { - match hub.receive_event_once() { - Ok(Some(CultNetRudpServerEvent::Connected { session })) => { - eprintln!( - "Muninn media receiver {} attached from {}.", - String::from_utf8_lossy(&session.connect_payload), - session.remote_addr - ); - } - Ok(Some(CultNetRudpServerEvent::Disconnected { session, reason })) => { - eprintln!( - "Muninn media receiver {} at {} disconnected: {}.", - String::from_utf8_lossy(&session.connect_payload), - session.remote_addr, - String::from_utf8_lossy(&reason) - ); - } - Ok(Some(CultNetRudpServerEvent::Frame { session, frame })) => { - if feedback_processed >= MUNINN_RUDP_MEDIA_REPAIR_MAX_FEEDBACK_PER_POLL { - return Ok(()); - } - feedback_processed += 1; - let repair_payloads = - record_rudp_media_receiver_feedback(&frame, stats, repair_cache)?; - let requested_repairs = repair_payloads.len(); - let poll_limited_repairs = - requested_repairs.min(MUNINN_RUDP_MEDIA_REPAIR_MAX_CHUNKS_PER_POLL); - let allowed_repairs = - repair_budget.take(poll_limited_repairs, Instant::now(), queue_dropped); - stats.repair_chunks_per_second = repair_budget.chunks_per_second(); - stats.deferred_repair_chunks = stats - .deferred_repair_chunks - .saturating_add(requested_repairs.saturating_sub(allowed_repairs) as u64); - // Repairs go back to the receiver that asked, not to everyone. - for payload in repair_payloads.into_iter().take(allowed_repairs) { - if send_rudp_media_payload_with_backpressure( - hub, - Some(&session), - payload, - Instant::now(), - Duration::from_millis(media_profile.sender_queue_deadline_ms), - send_pacer, - )? { - stats.repaired_video_chunks = stats.repaired_video_chunks.saturating_add(1); - } - } - } - Ok(Some(CultNetRudpServerEvent::Pong { .. })) => {} - Ok(None) => return Ok(()), - Err(error) if is_would_block_error(&error) => return Ok(()), - Err(error) => return Err(error).context("polling Muninn RUDP media feedback"), - } - } -} - -fn record_rudp_media_receiver_feedback( - frame: &CultNetTransportFrame, - stats: &mut MuninnRudpReceiverFeedbackStats, - repair_cache: &RecentVideoChunkRepairCache, -) -> Result> { - if frame.channel_id != crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL { - return Ok(Vec::new()); - } - - let GameCultMediaWireRecord::Feedback(feedback) = decode_media_wire_record(&frame.payload)? - else { - return Ok(Vec::new()); - }; - - let repair_payloads = repair_cache.repair_payloads_for_feedback(&feedback); - stats.feedback_records = stats.feedback_records.saturating_add(1); - if feedback.requested_keyframe { - stats.requested_keyframes = stats.requested_keyframes.saturating_add(1); - } - stats.late_frames = stats - .late_frames - .saturating_add(feedback.late_frame_ids.len() as u64); - stats.missing_video_chunks = stats - .missing_video_chunks - .saturating_add(feedback.missing_video_chunk_keys.len() as u64); - if let Some(frame_id) = feedback.highest_decodable_frame_id { - stats.highest_decodable_frame_id = Some( - stats - .highest_decodable_frame_id - .map(|current| current.max(frame_id)) - .unwrap_or(frame_id), - ); - } - Ok(repair_payloads) -} - /// Muninn listens for receivers here. It used to dial a receiver that had /// to open a port for it; that put a firewall rule on every viewer's /// machine. The producer is the host that serves, so the producer listens. fn open_media_rudp_hub( options: &Options, media_profile: &MuninnRudpMediaProfile, + policy: &MediaSendPolicy, ) -> Result { let socket = UdpSocket::bind(options.media_rudp_bind).with_context(|| { format!( @@ -3204,7 +2548,11 @@ fn open_media_rudp_hub( socket .set_nonblocking(true) .context("setting Muninn media RUDP listener nonblocking")?; - let hub = CultNetRudpServerHub::new(muninn_media_rudp_hub_options(socket, media_profile))?; + let hub = CultNetRudpServerHub::new(muninn_media_rudp_hub_options( + socket, + media_profile, + policy, + ))?; eprintln!( "Muninn media RUDP listening at {} for receivers dialling connection {:#x}.", hub.local_addr()?, @@ -3226,110 +2574,21 @@ fn configure_media_rudp_socket_buffers(socket: &UdpSocket) -> Result<()> { /// One session per receiver carries both legs: video lossy under parity on /// the media channel, audio reliable on its own channel and given up on -/// past the receiver's assembly deadline. +/// past the request's latency budget. fn muninn_media_rudp_hub_options( socket: UdpSocket, media_profile: &MuninnRudpMediaProfile, + policy: &MediaSendPolicy, ) -> CultNetRudpServerHubOptions { let mut options = CultNetRudpServerHubOptions::new("muninn-media", socket, MUNINN_MEDIA_RUDP_CONNECTION_ID); options.resend_delay_ms = media_profile.sender_resend_delay_ms; options.max_fragment_bytes = Some(media_profile.max_fragment_bytes as u32); options.media_delivery = Some(cultnet_rs::CultNetTransportDelivery::Unreliable); - options.media_reliable_expire_after_ms = Some(media_profile.receiver_assembly_deadline_ms); + options.media_reliable_expire_after_ms = Some(policy.latency_budget_ms()); options } -fn reliable_packets_expired(hub: &CultNetRudpServerHub) -> u64 { - hub.stats().reliable_packets_expired -} - -fn video_rudp_payload_reader( - tx: mpsc::Sender>, - mut reader: R, - config: VideoAnnexBStreamSendConfig, -) -> thread::JoinHandle<()> -where - R: Read + Send + 'static, -{ - thread::spawn(move || { - if let Err(error) = read_video_rudp_payloads(&tx, &mut reader, config) { - let _ = tx.send(Err(error)); - } - }) -} - -fn audio_rudp_payload_reader( - tx: mpsc::Sender>, - mut reader: R, - config: AudioPcmStreamSendConfig, -) -> thread::JoinHandle<()> -where - R: Read + Send + 'static, -{ - thread::spawn(move || { - if let Err(error) = read_audio_rudp_payloads(&tx, &mut reader, config) { - let _ = tx.send(Err(error)); - } - }) -} - -fn read_video_rudp_payloads( - tx: &mpsc::Sender>, - reader: &mut R, - config: VideoAnnexBStreamSendConfig, -) -> Result<()> -where - R: Read, -{ - let mut sender = VideoAnnexBStreamSendState::new(config)?; - let mut buffer = vec![0_u8; 64 * 1024]; - loop { - let read = reader - .read(&mut buffer) - .context("reading encoded Annex B video from ffmpeg stdout")?; - if read == 0 { - for payload in sender.finish(×tamp()?)? { - queue_muninn_media_payload(tx, payload, QueuedMuninnMediaKind::Video) - .context("queueing final typed video media payload")?; - } - return Ok(()); - } - for payload in sender.push(×tamp()?, &buffer[..read])? { - queue_muninn_media_payload(tx, payload, QueuedMuninnMediaKind::Video) - .context("queueing typed video media payload")?; - } - } -} - -fn read_audio_rudp_payloads( - tx: &mpsc::Sender>, - reader: &mut R, - config: AudioPcmStreamSendConfig, -) -> Result<()> -where - R: Read, -{ - let mut sender = AudioPcmStreamSendState::new(config)?; - let mut buffer = vec![0_u8; 16 * 1024]; - loop { - let read = reader - .read(&mut buffer) - .context("reading PCM audio from ffmpeg stdout")?; - if read == 0 { - for payload in sender.finish(×tamp()?)? { - queue_muninn_media_payload(tx, payload, QueuedMuninnMediaKind::Audio) - .context("queueing final typed audio media payload")?; - } - return Ok(()); - } - for payload in sender.push(×tamp()?, &buffer[..read])? { - queue_muninn_media_payload(tx, payload, QueuedMuninnMediaKind::Audio) - .context("queueing typed audio media payload")?; - } - } -} - fn video_frame_duration_ticks(options: &Options) -> Result { if options.framerate == 0 { return Err(anyhow!("framerate must be greater than zero")); @@ -3337,32 +2596,6 @@ fn video_frame_duration_ticks(options: &Options) -> Result { Ok((90_000_u32 / options.framerate).max(1)) } -fn rudp_media_deadline_delay_ticks(media_profile: &MuninnRudpMediaProfile) -> i64 { - i64::try_from( - media_profile - .receiver_assembly_deadline_ms - .saturating_mul(90), - ) - .unwrap_or(i64::MAX) -} - -fn rudp_audio_deadline_delay_ticks( - options: &Options, - media_profile: &MuninnRudpMediaProfile, -) -> i64 { - if options.audio_sample_rate == 0 { - return i64::from(1_024); - } - i64::try_from( - media_profile - .receiver_assembly_deadline_ms - .saturating_mul(u64::from(options.audio_sample_rate)) - / 1_000, - ) - .unwrap_or(i64::MAX) - .max(i64::from(1_024)) -} - fn publish_surface( node: &mut cultmesh_rs::CultMeshNode, options: &Options, @@ -3845,10 +3078,8 @@ fn publish_runtime_boundary_records( "video_gop_frames": muninn_rudp_video_gop_frames(options), "video_rate_control": "cbr", "video_rc_lookahead": media_profile.video_rc_lookahead, - "sender_queue_deadline_ms": media_profile.sender_queue_deadline_ms, "sender_resend_delay_ms": media_profile.sender_resend_delay_ms, - "sender_reliable_expire_after_ms": media_profile.sender_reliable_expire_after_ms, - "receiver_assembly_deadline_ms": media_profile.receiver_assembly_deadline_ms, + "latency_budget_ms": options.rudp_latency_budget_ms, "receiver_gap_wait_ms": media_profile.receiver_gap_wait_ms, "late_media_policy": "drop expired queued media; do not repair frames outside the latency budget", "recovery": "fixed quarter-second IDR budget with receiver feedback pressure telemetry" @@ -10261,24 +9492,12 @@ fn muninn_rudp_media_profile() -> MuninnRudpMediaProfile { } fn muninn_rudp_media_profile_for_options(options: &Options) -> MuninnRudpMediaProfile { - muninn_rudp_media_profile_for_bitrate_and_latency( - options.rudp_video_bitrate_kbps, - options.rudp_latency_budget_ms, - ) + muninn_rudp_media_profile_for_bitrate(options.rudp_video_bitrate_kbps) } +/// Encoder and wire shape. It carries no deadline: the request's latency +/// budget reaches the sender only through `MediaSendPolicy`. fn muninn_rudp_media_profile_for_bitrate(video_bitrate_kbps: u32) -> MuninnRudpMediaProfile { - muninn_rudp_media_profile_for_bitrate_and_latency( - video_bitrate_kbps, - MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS as u32, - ) -} - -fn muninn_rudp_media_profile_for_bitrate_and_latency( - video_bitrate_kbps: u32, - latency_budget_ms: u32, -) -> MuninnRudpMediaProfile { - let latency_budget_ms = u64::from(latency_budget_ms.max(1)); MuninnRudpMediaProfile { profile_id: MUNINN_RUDP_MEDIA_PROFILE_ID, video_codec: "h264", @@ -10290,12 +9509,7 @@ fn muninn_rudp_media_profile_for_bitrate_and_latency( max_fragment_bytes: MUNINN_RUDP_MEDIA_MAX_FRAGMENT_BYTES, video_b_frames: 0, video_rc_lookahead: 0, - sender_queue_deadline_ms: latency_budget_ms, sender_resend_delay_ms: MUNINN_RUDP_MEDIA_RESEND_DELAY_MS, - sender_reliable_expire_after_ms: latency_budget_ms, - sender_pace_every_payloads: MUNINN_RUDP_MEDIA_SEND_PACE_EVERY_PAYLOADS, - sender_pace_sleep_us: MUNINN_RUDP_MEDIA_SEND_PACE_SLEEP_US, - receiver_assembly_deadline_ms: latency_budget_ms, receiver_gap_wait_ms: MUNINN_RUDP_MEDIA_RECEIVER_GAP_WAIT_MS, } } @@ -10571,7 +9785,7 @@ impl Options { media_transport: MediaTransport::Rudp, media_packet_bytes: MUNINN_RUDP_MEDIA_PACKET_BYTES, rudp_video_bitrate_kbps: MUNINN_RUDP_MEDIA_VIDEO_BITRATE_KBPS, - rudp_latency_budget_ms: MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS as u32, + rudp_latency_budget_ms: MUNINN_RUDP_MEDIA_DEFAULT_LATENCY_BUDGET_MS as u32, width: 1920, height: 1080, framerate: 30, @@ -11215,6 +10429,7 @@ fn parse_move_state_source(value: &str) -> Result { #[cfg(test)] mod tests { use super::*; + use crate::media_send::{MediaKind, QueuedMediaGroup}; fn media_stream_request() -> GameCultMediaStreamRequestRecord { GameCultMediaStreamRequestRecord { @@ -12356,9 +11571,9 @@ mod tests { access_unit: &[u8], ) -> Vec { let mut sender = crate::media_packetizer::VideoAnnexBStreamSendState::new(config).unwrap(); - let mut payloads = sender.push("2026-06-18T00:00:00Z", access_unit).unwrap(); - payloads.extend(sender.finish("2026-06-18T00:00:00Z").unwrap()); - payloads + let mut groups = sender.push("2026-06-18T00:00:00Z", access_unit).unwrap(); + groups.extend(sender.finish("2026-06-18T00:00:00Z").unwrap()); + groups.into_iter().flatten().collect() } #[test] @@ -12441,7 +11656,8 @@ mod tests { fn rudp_media_hub_serves_lossy_video_and_reliable_audio_on_one_session() { let socket = UdpSocket::bind("127.0.0.1:0").unwrap(); let profile = muninn_rudp_media_profile(); - let options = muninn_media_rudp_hub_options(socket, &profile); + let policy = MediaSendPolicy::from_request(137); + let options = muninn_media_rudp_hub_options(socket, &profile, &policy); assert_eq!(options.runtime_id, "muninn-media"); assert_eq!(options.connection_id, MUNINN_MEDIA_RUDP_CONNECTION_ID); assert_eq!(options.resend_delay_ms, MUNINN_RUDP_MEDIA_RESEND_DELAY_MS); @@ -12468,7 +11684,7 @@ mod tests { ); assert_eq!( channel("audio").reliable_expire_after_ms, - Some(profile.receiver_assembly_deadline_ms), + Some(policy.latency_budget_ms()), "audio older than the receiver's deadline is not worth a retransmit" ); } @@ -12503,59 +11719,8 @@ mod tests { assert_eq!(args.last().map(String::as_str), Some("pipe:1")); } - #[test] - fn media_payload_queue_deadline_is_strictly_bounded() { - let queued_at = Instant::now(); - let deadline = Duration::from_millis(muninn_rudp_media_profile().sender_queue_deadline_ms); - - assert!(!media_payload_queue_age_exceeded( - queued_at, - queued_at + deadline, - deadline - )); - assert!(media_payload_queue_age_exceeded( - queued_at, - queued_at + deadline + Duration::from_millis(1), - deadline - )); - } - - #[test] - fn rudp_media_sender_prioritizes_pending_audio_over_video() { - let queued_at = Instant::now(); - let mut pending = PendingMuninnMediaSendQueues::default(); - pending.push(QueuedMuninnMediaSendPayload { - payload: MuninnMediaSendPayload { - channel_id: crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL, - payload: vec![0x76], - }, - queued_at, - kind: QueuedMuninnMediaKind::Video, - }); - pending.push(QueuedMuninnMediaSendPayload { - payload: MuninnMediaSendPayload { - channel_id: crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL, - payload: vec![0x61], - }, - queued_at, - kind: QueuedMuninnMediaKind::Audio, - }); - - let first = pending.pop_next().expect("audio payload should be queued"); - let second = pending - .pop_next() - .expect("video payload should remain queued"); - - assert_eq!(first.kind, QueuedMuninnMediaKind::Audio); - assert_eq!(first.payload.payload, vec![0x61]); - assert_eq!(second.kind, QueuedMuninnMediaKind::Video); - assert_eq!(second.payload.payload, vec![0x76]); - assert!(pending.is_empty()); - } - - #[test] - fn rudp_latency_budget_owns_sender_and_record_deadlines() { - let options = Options::parse( + fn options_with_latency_budget(budget_ms: &str) -> Options { + Options::parse( [ "activate", "--media-transport", @@ -12567,210 +11732,72 @@ mod tests { "--audio-sample-rate", "48000", "--rudp-latency-budget-ms", - "2000", + budget_ms, ] .into_iter() .map(String::from), ) - .unwrap(); - let profile = muninn_rudp_media_profile_for_options(&options); + .unwrap() + } - assert_eq!(profile.sender_queue_deadline_ms, 2000); - assert_eq!(profile.sender_reliable_expire_after_ms, 2000); + #[test] + fn the_requests_latency_budget_owns_queue_hub_expiry_and_record_deadlines() { + // Two budgets, both different from the default and from each other, so + // a clamp, an offset or a fallback to the default is visible at one of + // them. + for (budget_ms, video_ticks, audio_ticks) in [(137_u32, 12_330_i64, 6_576_i64), (613, 55_170, 29_424)] + { + let options = options_with_latency_budget(&budget_ms.to_string()); + let policy = MediaSendPolicy::from_request(options.rudp_latency_budget_ms); + let produced_at = Instant::now(); + let group = QueuedMediaGroup::new(MediaKind::Video, produced_at, &policy, Vec::new()); + + assert_eq!( + group.deadline - produced_at, + Duration::from_millis(u64::from(budget_ms)) + ); + assert_eq!(policy.video_deadline_delay_ticks(), video_ticks); + assert_eq!( + policy.audio_deadline_delay_ticks(options.audio_sample_rate), + audio_ticks + ); + let hub_options = muninn_media_rudp_hub_options( + UdpSocket::bind("127.0.0.1:0").unwrap(), + &muninn_rudp_media_profile_for_options(&options), + &policy, + ); + assert_eq!( + hub_options.media_reliable_expire_after_ms, + Some(u64::from(budget_ms)) + ); + } assert_eq!( - profile.sender_pace_every_payloads, - MUNINN_RUDP_MEDIA_SEND_PACE_EVERY_PAYLOADS - ); - assert_eq!( - profile.sender_pace_sleep_us, - MUNINN_RUDP_MEDIA_SEND_PACE_SLEEP_US - ); - assert_eq!(profile.receiver_assembly_deadline_ms, 2000); - assert_eq!(rudp_media_deadline_delay_ticks(&profile), 180_000); - assert_eq!(rudp_audio_deadline_delay_ticks(&options, &profile), 96_000); - assert_eq!( - rudp_endpoint_for_options(&options), + rudp_endpoint_for_options(&options_with_latency_budget("137")), "cultmesh://odin/media/muninn-raven-av#muninn.raven.av.rudp" ); } #[test] - fn rudp_media_progress_detail_reports_queue_and_transport_pressure() { - let receiver_feedback = MuninnRudpReceiverFeedbackStats { - feedback_records: 2, - requested_keyframes: 1, - late_frames: 3, - missing_video_chunks: 4, - repaired_video_chunks: 0, - deferred_repair_chunks: 5, - repair_chunks_per_second: 64, - highest_decodable_frame_id: Some(88), - }; - - assert_eq!( - rudp_media_progress_detail(120, 3, 2, 1, 9, 2, &receiver_feedback), - "Muninn RUDP media progress: receivers=2 sent=120 queue_dropped=3 queue_expired=2 send_expired=1 reliable_expired=9 receiver_feedback=2 receiver_keyframes=1 receiver_late_frames=3 receiver_missing_chunks=4 receiver_repaired_chunks=0 receiver_deferred_repairs=5 repair_rate=64 receiver_highest_decodable=88" - ); - } - - #[test] - fn rudp_repair_budget_backs_off_on_media_drops_and_recovers_when_stable() { - let start = Instant::now(); - let mut budget = MuninnRudpRepairBudget { - chunks_per_second: 64, - min_chunks_per_second: 8, - max_chunks_per_second: 128, - add_chunks_per_second: 8, - recovery_interval: Duration::from_secs(2), - max_available_chunks: 4, - available_chunks: 4, - last_refill_at: start, - last_rate_adjust_at: start, - last_queue_dropped: 0, - }; - - assert_eq!(budget.take(4, start, 0), 4); - assert_eq!(budget.chunks_per_second(), 64); - assert_eq!(budget.take(3, start + Duration::from_millis(10), 1), 0); - assert_eq!(budget.chunks_per_second(), 32); - assert_eq!(budget.take(3, start + Duration::from_secs(1), 1), 3); - assert_eq!(budget.chunks_per_second(), 32); - assert_eq!(budget.take(3, start + Duration::from_secs(3), 1), 3); - assert_eq!(budget.chunks_per_second(), 40); - } - - #[test] - fn default_rudp_repair_budget_has_lan_stream_headroom() { - let mut budget = MuninnRudpRepairBudget::new( - MUNINN_RUDP_MEDIA_REPAIR_INITIAL_CHUNKS_PER_SECOND, - MUNINN_RUDP_MEDIA_REPAIR_BURST_CHUNKS, - ); - let start = budget.last_refill_at; - - assert_eq!(budget.chunks_per_second(), 4_096); - assert_eq!(budget.take(2_048, start, 0), 2_048); - assert_eq!(budget.take(8_192, start + Duration::from_secs(1), 0), 2_048); - assert_eq!(budget.take(8_192, start + Duration::from_secs(3), 0), 2_048); - assert_eq!(budget.chunks_per_second(), 6_144); - assert_eq!(budget.take(512, start + Duration::from_secs(4), 1), 512); - assert_eq!(budget.chunks_per_second(), 3_072); - } - - #[test] - fn receiver_feedback_keyframe_requests_are_recorded_without_encoder_restart() { - let mut handled = 0; - let mut receiver_feedback = MuninnRudpReceiverFeedbackStats::default(); - - record_receiver_keyframe_pressure(&receiver_feedback, &mut handled); - assert_eq!(handled, 0); - - receiver_feedback.requested_keyframes = 1; - record_receiver_keyframe_pressure(&receiver_feedback, &mut handled); - assert_eq!(handled, 1); - record_receiver_keyframe_pressure(&receiver_feedback, &mut handled); - assert_eq!(handled, 1); - - receiver_feedback.requested_keyframes = 2; - record_receiver_keyframe_pressure(&receiver_feedback, &mut handled); - assert_eq!(handled, 2); - } - - #[test] - fn rudp_media_receiver_feedback_updates_sender_pressure_stats() { - let feedback = cultnet_rs::build_receiver_feedback(cultnet_rs::ReceiverFeedbackOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "raven:session:video", - receiver_id: "starfire.obs", - highest_decodable_frame_id: Some(41), - missing_frame_ids: Vec::new(), - missing_video_chunk_keys: vec!["42:1".to_string(), "42:3".to_string()], - late_frame_ids: vec![42, 43], - requested_keyframe: true, - jitter_us: 500, - decode_queue_us: 2_000, - observed_at: "unix:1000", - }) - .unwrap(); - let payload = crate::media_packetizer::encode_media_wire_record( - &crate::media_packetizer::GameCultMediaWireRecord::Feedback(feedback), - crate::media_packetizer::MediaWireProvenance { - stored_at: "unix:1000", - runtime_id: "starfire", - role: "mimir.obs", - producer: "mimir", - }, + fn a_request_naming_no_latency_budget_gets_250_ms_and_the_advertisement_says_so() { + assert_eq!(MUNINN_RUDP_MEDIA_DEFAULT_LATENCY_BUDGET_MS, 250); + let options = Options::parse([].into_iter()).unwrap(); + assert_eq!(options.rudp_latency_budget_ms, 250); + let advertised = Options::parse( + ["serve", "--media-rudp-advertise", "127.0.0.1:5220"] + .into_iter() + .map(String::from), ) .unwrap(); - let frame = CultNetTransportFrame { - channel_id: crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL.to_string(), - payload, - }; - let mut stats = MuninnRudpReceiverFeedbackStats::default(); - let repair_cache = RecentVideoChunkRepairCache::new(16); + let advertisement = media_stream_advertisement(&advertised, false).unwrap(); + assert_eq!(advertisement.default_latency_budget_ms, 250); - let repairs = - record_rudp_media_receiver_feedback(&frame, &mut stats, &repair_cache).unwrap(); - - assert_eq!(stats.feedback_records, 1); - assert_eq!(stats.requested_keyframes, 1); - assert_eq!(stats.late_frames, 2); - assert_eq!(stats.missing_video_chunks, 2); - assert_eq!(stats.repaired_video_chunks, 0); - assert_eq!(stats.highest_decodable_frame_id, Some(41)); - assert!(repairs.is_empty()); - } - - #[test] - fn repair_cache_returns_recent_missing_video_chunks_from_feedback() { - let video = cultnet_rs::GameCultMediaVideoAccessUnitRecord { - stream_id: "muninn.raven.av.rudp".to_string(), - session_id: "raven:session:video".to_string(), - frame_id: 42, - codec: "h264".to_string(), - pts_ticks: 126_000, - duration_ticks: 3_000, - timebase_num: 1, - timebase_den: 90_000, - keyframe: false, - dependency_frame_id: Some(41), - deadline_ticks: 127_800, - chunk_index: 3, - chunk_count: 5, - payload: vec![1, 2, 3, 4], - }; - let payload = MuninnMediaSendPayload { - channel_id: crate::media_packetizer::MUNINN_MEDIA_RUDP_CHANNEL, - payload: crate::media_packetizer::encode_media_wire_record( - &crate::media_packetizer::GameCultMediaWireRecord::Video(video), - crate::media_packetizer::MediaWireProvenance { - stored_at: "unix:1000", - runtime_id: "muninn-test", - role: "repair-cache-test", - producer: "mimir", - }, - ) - .unwrap(), - }; - let feedback = cultnet_rs::build_receiver_feedback(cultnet_rs::ReceiverFeedbackOptions { - stream_id: "muninn.raven.av.rudp", - session_id: "raven:session:video", - receiver_id: "starfire.obs", - highest_decodable_frame_id: Some(41), - missing_frame_ids: Vec::new(), - missing_video_chunk_keys: vec!["42:3".to_string(), "42:4".to_string()], - late_frame_ids: vec![42], - requested_keyframe: true, - jitter_us: 500, - decode_queue_us: 2_000, - observed_at: "unix:1000", - }) - .unwrap(); - - let mut cache = RecentVideoChunkRepairCache::new(16); - cache.remember(&payload).unwrap(); - let repairs = cache.repair_payloads_for_feedback(&feedback); - - assert_eq!(repairs, vec![payload]); + let mut request = media_stream_request(); + request.latency_budget_ms = 0; + let command = command_from_media_stream_request(&options, &request).unwrap(); + assert_eq!(command_rudp_latency_budget_ms(&command), 250); + request.latency_budget_ms = 40; + let command = command_from_media_stream_request(&options, &request).unwrap(); + assert_eq!(command_rudp_latency_budget_ms(&command), 40); } #[test] @@ -14037,10 +13064,20 @@ Device 00:07:04:A8:00:D0 (public) ); assert_eq!( media_profile - .get("sender_reliable_expire_after_ms") + .get("latency_budget_ms") .and_then(|value| value.as_u64()), - Some(MUNINN_RUDP_MEDIA_RECEIVER_ASSEMBLY_DEADLINE_MS) + Some(MUNINN_RUDP_MEDIA_DEFAULT_LATENCY_BUDGET_MS) ); + for retired in [ + "sender_queue_deadline_ms", + "sender_reliable_expire_after_ms", + "receiver_assembly_deadline_ms", + ] { + assert!( + media_profile.get(retired).is_none(), + "{retired} was a second name for the request budget" + ); + } assert_eq!( media_profile .get("sender_resend_delay_ms") diff --git a/crates/muninn-daemon/src/media_packetizer.rs b/crates/muninn-daemon/src/media_packetizer.rs index d814944..bcf2423 100644 --- a/crates/muninn-daemon/src/media_packetizer.rs +++ b/crates/muninn-daemon/src/media_packetizer.rs @@ -213,11 +213,17 @@ pub struct MuninnMediaSendPayload { pub payload: Vec, } +/// Everything one video access unit puts on the wire: its chunks and, until +/// the FEC cut replaces it, their parity. A group is sent whole or not at +/// all, because parity for a frame that never completes is wasted bandwidth. +pub type MuninnMediaPayloadGroup = Vec; + pub struct VideoAnnexBStreamSendState { config: VideoAnnexBStreamSendConfig, pending: Vec, next_frame_id: u64, next_pts_ticks: i64, + dropped_access_units: u64, } impl VideoAnnexBStreamSendState { @@ -260,26 +266,35 @@ impl VideoAnnexBStreamSendState { next_pts_ticks: config.first_pts_ticks, config, pending: Vec::new(), + dropped_access_units: 0, }) } - pub fn push(&mut self, stored_at: &str, bytes: &[u8]) -> Result> { + /// One group per completed access unit. Whatever is still pending after + /// that is a single unfinished access unit; when it outgrows + /// `max_pending_bytes` it is dropped and counted, never an error that + /// would restart the stream. + pub fn push(&mut self, stored_at: &str, bytes: &[u8]) -> Result> { if !bytes.is_empty() { self.pending.extend_from_slice(bytes); } + let groups = self.emit_available(stored_at, false)?; if self.pending.len() > self.config.max_pending_bytes { - return Err(anyhow!( - "Annex B stream sender pending buffer exceeded {} bytes without a complete frame", - self.config.max_pending_bytes - )); + self.pending.clear(); + self.dropped_access_units += 1; } - self.emit_available(stored_at, false) + Ok(groups) } - pub fn finish(&mut self, stored_at: &str) -> Result> { + pub fn finish(&mut self, stored_at: &str) -> Result> { self.emit_available(stored_at, true) } + /// Access units dropped for outgrowing `max_pending_bytes`, cumulative. + pub fn dropped_access_units(&self) -> u64 { + self.dropped_access_units + } + pub fn pending_bytes(&self) -> usize { self.pending.len() } @@ -292,10 +307,17 @@ impl VideoAnnexBStreamSendState { &mut self, stored_at: &str, flush_last: bool, - ) -> Result> { + ) -> Result> { if stored_at.is_empty() { return Err(anyhow!("stored_at must be non-empty")); } + // After a drop the tail of the dropped access unit arrives with no + // start code in front of it; skip to the next one. + if let Some((start, _)) = find_annex_b_start_code(&self.pending, 0) + && start > 0 + { + self.pending.drain(..start); + } if self.pending.is_empty() { return Ok(Vec::new()); } @@ -319,7 +341,7 @@ impl VideoAnnexBStreamSendState { return Ok(Vec::new()); } - let mut send_payloads = Vec::new(); + let mut groups = Vec::with_capacity(emit_count); let mut emitted_bytes = 0_usize; for access_unit in access_units.iter().take(emit_count) { emitted_bytes = emitted_bytes @@ -345,7 +367,7 @@ impl VideoAnnexBStreamSendState { access_unit, )?; let wire_records = video_wire_records_with_parity(&records)?; - send_payloads.extend(wire_payloads_to_media_send(encode_media_wire_records( + groups.push(wire_payloads_to_media_send(encode_media_wire_records( &wire_records, stored_at, &self.config.source_runtime_id, @@ -355,7 +377,7 @@ impl VideoAnnexBStreamSendState { } self.pending.drain(..emitted_bytes); - Ok(send_payloads) + Ok(groups) } fn advance_frame_clock(&mut self) -> Result<()> { @@ -1525,8 +1547,8 @@ mod tests { stream.extend_from_slice(&start_code()); stream.extend_from_slice(&[second_slice_header, 0x80]); let mut sender = VideoAnnexBStreamSendState::new(config)?; - let mut payloads = sender.push("2026-06-18T00:00:00Z", &stream)?; - payloads.extend(sender.finish("2026-06-18T00:00:00Z")?); + let mut payloads = flat(sender.push("2026-06-18T00:00:00Z", &stream)?); + payloads.extend(flat(sender.finish("2026-06-18T00:00:00Z")?)); let mut records = Vec::new(); for payload in &payloads { if let GameCultMediaWireRecord::Video(record) = @@ -1595,8 +1617,8 @@ mod tests { stream.extend_from_slice(&start_code()); stream.extend_from_slice(&[0x41, 0x80]); let mut sender = VideoAnnexBStreamSendState::new(stream_send_config())?; - let mut payloads = sender.push("2026-06-18T00:00:00Z", &stream)?; - payloads.extend(sender.finish("2026-06-18T00:00:00Z")?); + let mut payloads = flat(sender.push("2026-06-18T00:00:00Z", &stream)?); + payloads.extend(flat(sender.finish("2026-06-18T00:00:00Z")?)); assert!(payloads.len() >= 2); let wire_records = payloads .iter() @@ -1636,9 +1658,10 @@ mod tests { let second_push = sender.push("2026-06-18T00:00:00Z", &second_frame)?; assert_eq!(second_push.len(), 1); - assert_eq!(second_push[0].channel_id, MUNINN_MEDIA_RUDP_CHANNEL); + assert_eq!(second_push[0].len(), 1); + assert_eq!(second_push[0][0].channel_id, MUNINN_MEDIA_RUDP_CHANNEL); let GameCultMediaWireRecord::Video(first) = - decode_media_wire_record(&second_push[0].payload)? + decode_media_wire_record(&second_push[0][0].payload)? else { panic!("expected video media record"); }; @@ -1651,7 +1674,8 @@ mod tests { let tail = sender.finish("2026-06-18T00:00:00Z")?; assert_eq!(tail.len(), 1); - let GameCultMediaWireRecord::Video(second) = decode_media_wire_record(&tail[0].payload)? + assert_eq!(tail[0].len(), 1); + let GameCultMediaWireRecord::Video(second) = decode_media_wire_record(&tail[0][0].payload)? else { panic!("expected video media record"); }; @@ -1680,21 +1704,84 @@ mod tests { ); } + fn flat(groups: Vec) -> Vec { + groups.into_iter().flatten().collect() + } + #[test] - fn annex_b_stream_send_state_rejects_unbounded_pending_bytes() -> Result<()> { + fn annex_b_stream_send_state_drops_and_counts_an_oversize_access_unit_instead_of_erroring() + -> Result<()> { let mut config = stream_send_config(); - config.max_pending_bytes = 4; + config.max_pending_bytes = 8; let mut sender = VideoAnnexBStreamSendState::new(config)?; - let error = sender - .push("2026-06-18T00:00:00Z", &[0x47, 0x40, 0x00, 0x10, 0x00]) - .unwrap_err(); + // One access unit that never completes and is larger than the ceiling. + let mut oversize = start_code().to_vec(); + oversize.extend_from_slice(&[0x65, 0x80, 1, 2, 3, 4, 5, 6, 7, 8]); + let groups = sender.push("2026-06-18T00:00:00Z", &oversize)?; - assert!( - error - .to_string() - .contains("pending buffer exceeded 4 bytes") - ); + assert!(groups.is_empty()); + assert_eq!(sender.dropped_access_units(), 1); + assert_eq!(sender.pending_bytes(), 0); + + // The tail of the dropped unit has no start code and is skipped; the + // stream then carries on with the next access units. + let mut next = vec![9, 9, 9]; + next.extend_from_slice(&start_code()); + next.extend_from_slice(&[0x65, 0x80]); + next.extend_from_slice(&start_code()); + next.extend_from_slice(&[0x41, 0x80]); + let groups = sender.push("2026-06-18T00:00:00Z", &next)?; + + assert_eq!(groups.len(), 1); + assert_eq!(sender.dropped_access_units(), 1); + let GameCultMediaWireRecord::Video(record) = + decode_media_wire_record(&groups[0][0].payload)? + else { + panic!("expected video media record"); + }; + assert!(record.keyframe); + Ok(()) + } + + #[test] + fn annex_b_stream_send_state_returns_one_group_per_access_unit_with_all_its_chunks_and_parity() + -> Result<()> { + // Three chunks of 16 bytes plus a short fourth: one access unit. + let mut stream = start_code().to_vec(); + stream.extend_from_slice(&[0x65, 0x80]); + stream.resize(52, 0xAB); + stream.extend_from_slice(&start_code()); + stream.extend_from_slice(&[0x41, 0x80]); + let mut sender = VideoAnnexBStreamSendState::new(stream_send_config())?; + + let mut groups = sender.push("2026-06-18T00:00:00Z", &stream)?; + groups.extend(sender.finish("2026-06-18T00:00:00Z")?); + + assert_eq!(groups.len(), 2); + let mut frame_ids_per_group = Vec::new(); + for group in &groups { + let mut ids = std::collections::BTreeSet::new(); + let mut data = 0; + let mut parity = 0; + for payload in group { + match decode_media_wire_record(&payload.payload)? { + GameCultMediaWireRecord::Video(record) => { + ids.insert(record.frame_id); + data += 1; + } + GameCultMediaWireRecord::VideoParity(record) => { + ids.insert(record.frame_id); + parity += 1; + } + other => panic!("unexpected record {other:?}"), + } + } + assert_eq!(ids.len(), 1, "a group carries exactly one frame"); + frame_ids_per_group.push((ids.into_iter().next().unwrap(), data, parity)); + } + assert_eq!(frame_ids_per_group[0], (9, 4, 4)); + assert_eq!(frame_ids_per_group[1], (10, 1, 0)); Ok(()) } diff --git a/crates/muninn-daemon/src/media_send.rs b/crates/muninn-daemon/src/media_send.rs new file mode 100644 index 0000000..e84855f --- /dev/null +++ b/crates/muninn-daemon/src/media_send.rs @@ -0,0 +1,960 @@ +//! The media send path: the one place that decides when a frame is too old. +//! +//! **Owner.** `MediaSendCore` owns the bounded group queues, the hub, the +//! receiver-feedback intake, the repair cache and its budget, and the progress +//! counters. `run_rudp_mux_once` spawns the encoders and publishes; it feeds +//! this module bytes and never decides a deadline. +//! +//! **One deadline owner.** `MediaSendPolicy::latency_budget` comes from the +//! request's `latency_budget_ms` and is the only source of a deadline. A group +//! is stamped `produced_at + latency_budget` when it leaves the packetizer; a +//! repair inherits the deadline of the frame it repairs; the hub's reliable +//! expiry and the record deadline ticks derive from the same budget. +//! +//! **Bounds.** Between the encoder and the socket every queue has a count +//! bound (`MEDIA_GROUP_CHANNEL_BOUND`, the per-kind group caps) and a time +//! bound (the group deadline). Crossing either drops whole groups, oldest +//! first, and counts them. The video cap is 512 groups of at most one access +//! unit each, and an access unit is at most `max_pending_bytes` (848 * 4096 +//! bytes at the default packet size), so the count cap alone implies a worst +//! case of about 1.7 GiB; in practice the deadline empties the queue long +//! before that. + +use crate::media_packetizer::{ + AudioPcmStreamSendConfig, AudioPcmStreamSendState, GameCultMediaWireRecord, + MUNINN_MEDIA_RUDP_CHANNEL, MuninnMediaPayloadGroup, MuninnMediaSendPayload, + VideoAnnexBStreamSendConfig, VideoAnnexBStreamSendState, decode_media_wire_record, + video_chunk_feedback_key, +}; +use anyhow::{Context, Result}; +use cultnet_rs::{ + CultNetRudpServerEvent, CultNetRudpServerHub, CultNetRudpServerSessionContext, + CultNetTransportFrame, GameCultMediaReceiverFeedbackRecord, +}; +use std::collections::{HashMap, VecDeque}; +use std::io::{ErrorKind, Read}; +use std::sync::mpsc; +use std::thread; +use std::time::{Duration, Instant}; + +pub const MEDIA_SEND_AUDIO_GROUP_CAP: usize = 256; +pub const MEDIA_SEND_VIDEO_GROUP_CAP: usize = 512; +/// Groups the reader threads may have handed over and the send loop not yet +/// taken. Small on purpose: the caps above are where a backlog lives. +pub const MEDIA_GROUP_CHANNEL_BOUND: usize = 8; + +const REPAIR_CACHE_CHUNKS: usize = 16_384; +pub const REPAIR_BURST_CHUNKS: usize = 2_048; +pub const REPAIR_INITIAL_CHUNKS_PER_SECOND: usize = 4_096; +const REPAIR_MIN_CHUNKS_PER_SECOND: usize = 8; +const REPAIR_MAX_CHUNKS_PER_SECOND: usize = 16_384; +const REPAIR_ADD_CHUNKS_PER_SECOND: usize = 2_048; +const REPAIR_RECOVERY_INTERVAL_MS: u64 = 2_000; +const REPAIR_MAX_FEEDBACK_PER_POLL: usize = 32; +const REPAIR_MAX_CHUNKS_PER_POLL: usize = 256; +/// A receiver that has said nothing for this long (Ratatoskr pings every +/// second or so) is dropped so its payloads stop being sent into the void. +const RECEIVER_TIMEOUT_MS: u64 = 6_000; +pub const SEND_PACE_EVERY_PAYLOADS: usize = 4; +pub const SEND_PACE_SLEEP_US: u64 = 250; + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum MediaKind { + Video, + Audio, +} + +/// What the request decided about sending. Nothing else mints a deadline. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct MediaSendPolicy { + pub latency_budget: Duration, + pub video_pace_every_payloads: usize, + pub video_pace_sleep: Duration, +} + +impl MediaSendPolicy { + pub fn from_request(latency_budget_ms: u32) -> Self { + Self { + latency_budget: Duration::from_millis(u64::from(latency_budget_ms.max(1))), + video_pace_every_payloads: SEND_PACE_EVERY_PAYLOADS, + video_pace_sleep: Duration::from_micros(SEND_PACE_SLEEP_US), + } + } + + pub fn latency_budget_ms(&self) -> u64 { + self.latency_budget.as_millis() as u64 + } + + /// The video record deadline, in the 90 kHz video timebase. + pub fn video_deadline_delay_ticks(&self) -> i64 { + i64::try_from(self.latency_budget_ms().saturating_mul(90)).unwrap_or(i64::MAX) + } + + /// The audio record deadline, in samples at `sample_rate`. + pub fn audio_deadline_delay_ticks(&self, sample_rate: u32) -> i64 { + if sample_rate == 0 { + return 1_024; + } + i64::try_from( + self.latency_budget_ms() + .saturating_mul(u64::from(sample_rate)) + / 1_000, + ) + .unwrap_or(i64::MAX) + .max(1_024) + } +} + +/// One access unit with its parity, or one audio packet. It is sent whole or +/// not at all, and it dies at `deadline`. +pub struct QueuedMediaGroup { + pub kind: MediaKind, + pub deadline: Instant, + pub payloads: MuninnMediaPayloadGroup, +} + +impl QueuedMediaGroup { + pub fn new( + kind: MediaKind, + produced_at: Instant, + policy: &MediaSendPolicy, + payloads: MuninnMediaPayloadGroup, + ) -> Self { + Self { + kind, + deadline: produced_at + policy.latency_budget, + payloads, + } + } + + /// Sendable at the deadline itself, expired one instant after. + pub fn expired(&self, now: Instant) -> bool { + now > self.deadline + } +} + +/// What a reader thread hands the send loop. +pub enum MediaIntake { + Group(QueuedMediaGroup), + /// Video access units the packetizer dropped for outgrowing its ceiling. + VideoDropped(u64), +} + +pub type MediaIntakeSender = mpsc::SyncSender>; +pub type MediaIntakeReceiver = mpsc::Receiver>; + +pub fn media_intake_channel() -> (MediaIntakeSender, MediaIntakeReceiver) { + mpsc::sync_channel(MEDIA_GROUP_CHANNEL_BOUND) +} + +#[derive(Default)] +struct PendingMediaGroups { + audio: VecDeque, + video: VecDeque, +} + +impl PendingMediaGroups { + /// `true` when the queue was at its cap and its oldest group was dropped + /// to make room. + fn push(&mut self, group: QueuedMediaGroup) -> bool { + let (queue, cap) = match group.kind { + MediaKind::Audio => (&mut self.audio, MEDIA_SEND_AUDIO_GROUP_CAP), + MediaKind::Video => (&mut self.video, MEDIA_SEND_VIDEO_GROUP_CAP), + }; + let dropped = queue.len() >= cap; + if dropped { + queue.pop_front(); + } + queue.push_back(group); + dropped + } + + /// Audio leaves before video: a late audio packet is a click, a late + /// frame is one dropped frame. + fn pop_next(&mut self) -> Option { + self.audio.pop_front().or_else(|| self.video.pop_front()) + } + + fn is_empty(&self) -> bool { + self.audio.is_empty() && self.video.is_empty() + } +} + +/// Counted where it happens. `groups_dropped_*` is a cap crossing; +/// `groups_expired` is a group whose deadline passed with none of it sent; +/// `groups_cut_short` is one whose deadline passed with part of it already on +/// the wire, which is the only way a partial frame can leave. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct MediaSendStats { + pub groups_sent: u64, + pub payloads_sent: u64, + pub groups_dropped_audio: u64, + pub groups_dropped_video: u64, + pub groups_expired: u64, + pub groups_cut_short: u64, +} + +impl MediaSendStats { + pub fn groups_lost(&self) -> u64 { + self.groups_dropped_audio + + self.groups_dropped_video + + self.groups_expired + + self.groups_cut_short + } + + /// Accounts for one group the send loop has finished with. + fn record_group(&mut self, outcome: &GroupSend, group_payloads: usize) { + match outcome { + GroupSend::Complete => { + self.groups_sent += 1; + self.payloads_sent += group_payloads as u64; + } + GroupSend::DeadlinePassed { payloads_out: 0 } => self.groups_expired += 1, + GroupSend::DeadlinePassed { payloads_out } => { + self.payloads_sent += *payloads_out as u64; + self.groups_cut_short += 1; + } + } + } +} + +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct MuninnRudpReceiverFeedbackStats { + pub feedback_records: u64, + pub requested_keyframes: u64, + pub late_frames: u64, + pub missing_video_chunks: u64, + pub repaired_video_chunks: u64, + pub deferred_repair_chunks: u64, + pub repair_chunks_per_second: usize, + pub highest_decodable_frame_id: Option, +} + +#[derive(Debug)] +pub struct MuninnRudpRepairBudget { + chunks_per_second: usize, + min_chunks_per_second: usize, + max_chunks_per_second: usize, + add_chunks_per_second: usize, + recovery_interval: Duration, + max_available_chunks: usize, + available_chunks: usize, + last_refill_at: Instant, + last_rate_adjust_at: Instant, + last_queue_dropped: u64, +} + +impl MuninnRudpRepairBudget { + pub fn new(chunks_per_second: usize, max_available_chunks: usize) -> Self { + let now = Instant::now(); + let max_available_chunks = max_available_chunks.max(1); + Self { + chunks_per_second: chunks_per_second.max(1), + min_chunks_per_second: REPAIR_MIN_CHUNKS_PER_SECOND, + max_chunks_per_second: REPAIR_MAX_CHUNKS_PER_SECOND, + add_chunks_per_second: REPAIR_ADD_CHUNKS_PER_SECOND, + recovery_interval: Duration::from_millis(REPAIR_RECOVERY_INTERVAL_MS), + max_available_chunks, + available_chunks: max_available_chunks, + last_refill_at: now, + last_rate_adjust_at: now, + last_queue_dropped: 0, + } + } + + pub fn chunks_per_second(&self) -> usize { + self.chunks_per_second + } + + pub fn take(&mut self, requested_chunks: usize, now: Instant, queue_dropped: u64) -> usize { + self.adjust_rate(now, queue_dropped, requested_chunks); + self.refill(now); + let allowed = requested_chunks.min(self.available_chunks); + self.available_chunks -= allowed; + allowed + } + + fn adjust_rate(&mut self, now: Instant, queue_dropped: u64, requested_chunks: usize) { + if queue_dropped > self.last_queue_dropped { + self.chunks_per_second = (self.chunks_per_second / 2).max(self.min_chunks_per_second); + self.available_chunks = self.available_chunks.min(self.chunks_per_second); + self.last_queue_dropped = queue_dropped; + self.last_rate_adjust_at = now; + return; + } + self.last_queue_dropped = queue_dropped; + if requested_chunks == 0 + || now.saturating_duration_since(self.last_rate_adjust_at) < self.recovery_interval + { + return; + } + if self.chunks_per_second < self.max_chunks_per_second { + self.chunks_per_second = self + .chunks_per_second + .saturating_add(self.add_chunks_per_second) + .min(self.max_chunks_per_second); + self.last_rate_adjust_at = now; + } + } + + fn refill(&mut self, now: Instant) { + let elapsed_ms = now + .saturating_duration_since(self.last_refill_at) + .as_millis() as usize; + if elapsed_ms == 0 { + return; + } + let refill_chunks = elapsed_ms.saturating_mul(self.chunks_per_second) / 1_000; + if refill_chunks == 0 { + return; + } + self.available_chunks = self + .available_chunks + .saturating_add(refill_chunks) + .min(self.max_available_chunks); + self.last_refill_at = now; + } +} + +#[derive(Debug)] +struct RepairEntry { + payload: MuninnMediaSendPayload, + /// The deadline of the frame group the chunk left in. A repair never + /// gets a deadline of its own. + deadline: Instant, +} + +#[derive(Debug)] +pub struct RecentVideoChunkRepairCache { + max_entries: usize, + order: VecDeque, + entries: HashMap, +} + +impl RecentVideoChunkRepairCache { + pub fn new(max_entries: usize) -> Self { + Self { + max_entries, + order: VecDeque::new(), + entries: HashMap::new(), + } + } + + pub fn remember(&mut self, payload: &MuninnMediaSendPayload, deadline: Instant) -> Result<()> { + let Some(key) = video_repair_cache_key_from_payload(payload)? else { + return Ok(()); + }; + let entry = RepairEntry { + payload: payload.clone(), + deadline, + }; + if self.entries.contains_key(&key) { + self.entries.insert(key, entry); + return Ok(()); + } + self.order.push_back(key.clone()); + self.entries.insert(key, entry); + while self.entries.len() > self.max_entries { + let Some(expired) = self.order.pop_front() else { + break; + }; + self.entries.remove(&expired); + } + Ok(()) + } + + /// The chunks the receiver is missing that are still inside their frame's + /// deadline at `now`, each with that deadline. + pub fn repair_payloads_for_feedback( + &self, + feedback: &GameCultMediaReceiverFeedbackRecord, + now: Instant, + ) -> Vec<(MuninnMediaSendPayload, Instant)> { + feedback + .missing_video_chunk_keys + .iter() + .filter_map(|chunk_key| { + self.entries.get(&video_repair_cache_key( + &feedback.stream_id, + &feedback.session_id, + chunk_key, + )) + }) + .filter(|entry| now <= entry.deadline) + .map(|entry| (entry.payload.clone(), entry.deadline)) + .collect() + } +} + +fn video_repair_cache_key(stream_id: &str, session_id: &str, chunk_key: &str) -> String { + format!("{stream_id}:{session_id}:video:{chunk_key}") +} + +fn video_repair_cache_key_from_payload(payload: &MuninnMediaSendPayload) -> Result> { + if payload.channel_id != MUNINN_MEDIA_RUDP_CHANNEL { + return Ok(None); + } + let GameCultMediaWireRecord::Video(video) = decode_media_wire_record(&payload.payload)? else { + return Ok(None); + }; + Ok(Some(video_repair_cache_key( + &video.stream_id, + &video.session_id, + &video_chunk_feedback_key(video.frame_id, video.chunk_index), + ))) +} + +#[derive(Debug)] +pub struct MuninnRudpMediaSendPacer { + payloads_since_pause: usize, + every_payloads: usize, + sleep_for: Duration, +} + +impl MuninnRudpMediaSendPacer { + pub fn new(every_payloads: usize, sleep_for: Duration) -> Self { + Self { + payloads_since_pause: 0, + every_payloads: every_payloads.max(1), + sleep_for, + } + } + + fn observe_sent_payload(&mut self) { + if self.sleep_for.is_zero() { + return; + } + self.payloads_since_pause = self.payloads_since_pause.saturating_add(1); + if self.payloads_since_pause < self.every_payloads { + return; + } + self.payloads_since_pause = 0; + thread::sleep(self.sleep_for); + } +} + +pub fn is_would_block_error(error: &anyhow::Error) -> bool { + error.chain().any(|cause| { + cause + .downcast_ref::() + .is_some_and(|io| io.kind() == ErrorKind::WouldBlock) + || cause.to_string().contains("os error 10035") + }) +} + +/// Tries `attempt` until it goes through or `deadline` passes. While the +/// socket is full it polls resends and tries again; it never sleeps and never +/// outlives the deadline. `false` means the deadline won. +fn send_until( + host: &mut H, + deadline: Instant, + mut now: impl FnMut() -> Instant, + mut attempt: impl FnMut(&mut H) -> Result<()>, + mut poll: impl FnMut(&mut H) -> Result<()>, +) -> Result { + loop { + match attempt(host) { + Ok(()) => return Ok(true), + Err(error) if is_would_block_error(&error) => { + if now() > deadline { + return Ok(false); + } + poll(host)?; + thread::yield_now(); + } + Err(error) => return Err(error).context("sending typed Muninn media payload"), + } + } +} + +fn poll_resends(hub: &mut CultNetRudpServerHub) -> Result<()> { + match hub.poll_resends() { + Ok(()) => Ok(()), + Err(error) if is_would_block_error(&error) => Ok(()), + Err(error) => Err(error).context("polling Muninn RUDP media resends"), + } +} + +#[derive(Debug)] +enum GroupSend { + Complete, + /// The deadline passed after `payloads_out` payloads had gone out. + DeadlinePassed { payloads_out: usize }, +} + +/// Every payload to every receiver, in order, or as many as the deadline +/// allows. A payload with nobody to send it to is not a failure; the progress +/// line says how many receivers there are. +fn send_payloads( + hub: &mut CultNetRudpServerHub, + receivers: &[CultNetRudpServerSessionContext], + payloads: &[MuninnMediaSendPayload], + deadline: Instant, + pacer: &mut MuninnRudpMediaSendPacer, +) -> Result { + for (payloads_out, payload) in payloads.iter().enumerate() { + for receiver in receivers { + let sent = send_until( + hub, + deadline, + Instant::now, + |hub| hub.send(receiver, payload.channel_id, payload.payload.clone()), + poll_resends, + )?; + if !sent { + return Ok(GroupSend::DeadlinePassed { payloads_out }); + } + } + pacer.observe_sent_payload(); + } + Ok(GroupSend::Complete) +} + +pub struct MediaSendCore { + hub: CultNetRudpServerHub, + queues: PendingMediaGroups, + repair_cache: RecentVideoChunkRepairCache, + repair_budget: MuninnRudpRepairBudget, + video_pacer: MuninnRudpMediaSendPacer, + audio_pacer: MuninnRudpMediaSendPacer, + stats: MediaSendStats, + feedback: MuninnRudpReceiverFeedbackStats, + handled_keyframe_requests: u64, + disconnected: bool, +} + +impl MediaSendCore { + pub fn new(hub: CultNetRudpServerHub, policy: &MediaSendPolicy) -> Self { + Self { + hub, + queues: PendingMediaGroups::default(), + repair_cache: RecentVideoChunkRepairCache::new(REPAIR_CACHE_CHUNKS), + repair_budget: MuninnRudpRepairBudget::new( + REPAIR_INITIAL_CHUNKS_PER_SECOND, + REPAIR_BURST_CHUNKS, + ), + video_pacer: MuninnRudpMediaSendPacer::new( + policy.video_pace_every_payloads, + policy.video_pace_sleep, + ), + audio_pacer: MuninnRudpMediaSendPacer::new(0, Duration::ZERO), + stats: MediaSendStats::default(), + feedback: MuninnRudpReceiverFeedbackStats::default(), + handled_keyframe_requests: 0, + disconnected: false, + } + } + + #[cfg(test)] + pub fn stats(&self) -> &MediaSendStats { + &self.stats + } + + #[cfg(test)] + pub fn feedback(&self) -> &MuninnRudpReceiverFeedbackStats { + &self.feedback + } + + #[cfg(test)] + pub fn hub(&self) -> &CultNetRudpServerHub { + &self.hub + } + + /// Nothing queued and every reader gone: the encoders have ended. + pub fn finished(&self) -> bool { + self.disconnected && self.queues.is_empty() + } + + /// Takes what the reader threads have produced. Waits up to `wait` for the + /// first group only when nothing is queued to send. + pub fn intake(&mut self, rx: &MediaIntakeReceiver, wait: Duration) -> Result<()> { + if self.disconnected { + return Ok(()); + } + if self.queues.is_empty() { + match rx.recv_timeout(wait) { + Ok(item) => self.accept(item?), + Err(mpsc::RecvTimeoutError::Timeout) => return Ok(()), + Err(mpsc::RecvTimeoutError::Disconnected) => { + self.disconnected = true; + return Ok(()); + } + } + } + loop { + match rx.try_recv() { + Ok(item) => self.accept(item?), + Err(mpsc::TryRecvError::Empty) => return Ok(()), + Err(mpsc::TryRecvError::Disconnected) => { + self.disconnected = true; + return Ok(()); + } + } + } + } + + fn accept(&mut self, item: MediaIntake) { + match item { + MediaIntake::Group(group) => self.enqueue(group), + MediaIntake::VideoDropped(count) => { + self.stats.groups_dropped_video += count; + self.log_loss_milestone(); + } + } + } + + pub fn enqueue(&mut self, group: QueuedMediaGroup) { + let kind = group.kind; + if self.queues.push(group) { + match kind { + MediaKind::Audio => self.stats.groups_dropped_audio += 1, + MediaKind::Video => self.stats.groups_dropped_video += 1, + } + self.log_loss_milestone(); + } + } + + /// Sends the next group that is still inside its deadline at `now`, + /// discarding expired ones whole on the way. `true` when a group went out + /// (all of it, or the part the deadline allowed). + pub fn send_next(&mut self, now: Instant) -> Result { + while let Some(group) = self.queues.pop_next() { + if group.expired(now) { + self.stats.groups_expired += 1; + self.log_loss_milestone(); + continue; + } + let receivers = self.hub.sessions(); + let pacer = match group.kind { + MediaKind::Video => &mut self.video_pacer, + MediaKind::Audio => &mut self.audio_pacer, + }; + let outcome = send_payloads( + &mut self.hub, + &receivers, + &group.payloads, + group.deadline, + pacer, + )?; + self.stats.record_group(&outcome, group.payloads.len()); + match outcome { + GroupSend::Complete => { + if group.kind == MediaKind::Video { + for payload in &group.payloads { + self.repair_cache.remember(payload, group.deadline)?; + } + } + if self.stats.groups_sent == 1 || self.stats.groups_sent % 900 == 0 { + eprintln!("{}", self.progress_detail()); + } + } + GroupSend::DeadlinePassed { .. } => self.log_loss_milestone(), + } + return Ok(true); + } + Ok(false) + } + + /// Receiver feedback, repairs, keyframe pressure and resends. + pub fn service_control(&mut self, now: Instant) -> Result<()> { + self.poll_feedback(now)?; + if self.feedback.requested_keyframes > self.handled_keyframe_requests { + self.handled_keyframe_requests = self.feedback.requested_keyframes; + eprintln!( + "Muninn RUDP receiver requested a fresh keyframe; continuing current low-latency encoder session until explicit encoder control exists." + ); + } + poll_resends(&mut self.hub) + } + + fn poll_feedback(&mut self, now: Instant) -> Result<()> { + for gone in self.hub.remove_timed_out_sessions(RECEIVER_TIMEOUT_MS) { + eprintln!( + "Muninn media receiver {} at {} went silent and was dropped.", + String::from_utf8_lossy(&gone.connect_payload), + gone.remote_addr + ); + } + let mut feedback_processed = 0_usize; + loop { + match self.hub.receive_event_once() { + Ok(Some(CultNetRudpServerEvent::Connected { session })) => { + eprintln!( + "Muninn media receiver {} attached from {}.", + String::from_utf8_lossy(&session.connect_payload), + session.remote_addr + ); + } + Ok(Some(CultNetRudpServerEvent::Disconnected { session, reason })) => { + eprintln!( + "Muninn media receiver {} at {} disconnected: {}.", + String::from_utf8_lossy(&session.connect_payload), + session.remote_addr, + String::from_utf8_lossy(&reason) + ); + } + Ok(Some(CultNetRudpServerEvent::Frame { session, frame })) => { + if feedback_processed >= REPAIR_MAX_FEEDBACK_PER_POLL { + return Ok(()); + } + feedback_processed += 1; + let repairs = record_receiver_feedback( + &frame, + &mut self.feedback, + &self.repair_cache, + now, + )?; + let requested = repairs.len(); + let allowed = self.repair_budget.take( + requested.min(REPAIR_MAX_CHUNKS_PER_POLL), + now, + self.stats.groups_lost(), + ); + self.feedback.repair_chunks_per_second = self.repair_budget.chunks_per_second(); + self.feedback.deferred_repair_chunks = self + .feedback + .deferred_repair_chunks + .saturating_add(requested.saturating_sub(allowed) as u64); + // Repairs go back to the receiver that asked, not to everyone, + // and each one keeps the deadline of its own frame. + for (payload, deadline) in repairs.into_iter().take(allowed) { + let outcome = send_payloads( + &mut self.hub, + std::slice::from_ref(&session), + std::slice::from_ref(&payload), + deadline, + &mut self.video_pacer, + )?; + if matches!(outcome, GroupSend::Complete) { + self.feedback.repaired_video_chunks = + self.feedback.repaired_video_chunks.saturating_add(1); + } + } + } + Ok(Some(CultNetRudpServerEvent::Pong { .. })) => {} + Ok(None) => return Ok(()), + Err(error) if is_would_block_error(&error) => return Ok(()), + Err(error) => return Err(error).context("polling Muninn RUDP media feedback"), + } + } + } + + fn log_loss_milestone(&self) { + let lost = self.stats.groups_lost(); + // Loss can arrive in the hundreds per second; the first and every + // 300th is enough to see it without flooding the log. + if lost == 1 || lost % 300 == 0 { + eprintln!("{}", self.progress_detail()); + } + } + + pub fn progress_detail(&self) -> String { + format!( + "Muninn RUDP media progress: receivers={} groups_sent={} payloads_sent={} groups_dropped_audio={} groups_dropped_video={} groups_expired={} groups_cut_short={} reliable_expired={} receiver_feedback={} receiver_keyframes={} receiver_late_frames={} receiver_missing_chunks={} receiver_repaired_chunks={} receiver_deferred_repairs={} repair_rate={} receiver_highest_decodable={}; pending_audio={} pending_video={}", + self.hub.sessions().len(), + self.stats.groups_sent, + self.stats.payloads_sent, + self.stats.groups_dropped_audio, + self.stats.groups_dropped_video, + self.stats.groups_expired, + self.stats.groups_cut_short, + self.hub.stats().reliable_packets_expired, + self.feedback.feedback_records, + self.feedback.requested_keyframes, + self.feedback.late_frames, + self.feedback.missing_video_chunks, + self.feedback.repaired_video_chunks, + self.feedback.deferred_repair_chunks, + self.feedback.repair_chunks_per_second, + self.feedback + .highest_decodable_frame_id + .map(|frame_id| frame_id.to_string()) + .unwrap_or_else(|| "none".to_string()), + self.queues.audio.len(), + self.queues.video.len(), + ) + } + + #[cfg(test)] + pub(crate) fn queued_groups(&self, kind: MediaKind) -> usize { + match kind { + MediaKind::Audio => self.queues.audio.len(), + MediaKind::Video => self.queues.video.len(), + } + } + + #[cfg(test)] + pub(crate) fn queued_payload_bytes(&self, kind: MediaKind) -> usize { + match kind { + MediaKind::Audio => &self.queues.audio, + MediaKind::Video => &self.queues.video, + } + .iter() + .flat_map(|group| &group.payloads) + .map(|payload| payload.payload.len()) + .sum() + } + + #[cfg(test)] + pub(crate) fn oldest_deadline(&self, kind: MediaKind) -> Option { + match kind { + MediaKind::Audio => self.queues.audio.front(), + MediaKind::Video => self.queues.video.front(), + } + .map(|group| group.deadline) + } +} + +fn record_receiver_feedback( + frame: &CultNetTransportFrame, + stats: &mut MuninnRudpReceiverFeedbackStats, + repair_cache: &RecentVideoChunkRepairCache, + now: Instant, +) -> Result> { + if frame.channel_id != MUNINN_MEDIA_RUDP_CHANNEL { + return Ok(Vec::new()); + } + + let GameCultMediaWireRecord::Feedback(feedback) = decode_media_wire_record(&frame.payload)? + else { + return Ok(Vec::new()); + }; + + let repairs = repair_cache.repair_payloads_for_feedback(&feedback, now); + stats.feedback_records = stats.feedback_records.saturating_add(1); + if feedback.requested_keyframe { + stats.requested_keyframes = stats.requested_keyframes.saturating_add(1); + } + stats.late_frames = stats + .late_frames + .saturating_add(feedback.late_frame_ids.len() as u64); + stats.missing_video_chunks = stats + .missing_video_chunks + .saturating_add(feedback.missing_video_chunk_keys.len() as u64); + if let Some(frame_id) = feedback.highest_decodable_frame_id { + stats.highest_decodable_frame_id = Some( + stats + .highest_decodable_frame_id + .map(|current| current.max(frame_id)) + .unwrap_or(frame_id), + ); + } + Ok(repairs) +} + +/// Reads Annex B from `reader`, packetizes it, and hands one group per access +/// unit to the send loop, stamped with the request's deadline. +pub fn spawn_video_group_reader( + tx: MediaIntakeSender, + mut reader: R, + config: VideoAnnexBStreamSendConfig, + policy: MediaSendPolicy, +) -> thread::JoinHandle<()> +where + R: Read + Send + 'static, +{ + thread::spawn(move || { + if let Err(error) = read_video_groups(&tx, &mut reader, config, &policy) { + let _ = tx.send(Err(error)); + } + }) +} + +pub fn spawn_audio_group_reader( + tx: MediaIntakeSender, + mut reader: R, + config: AudioPcmStreamSendConfig, + policy: MediaSendPolicy, +) -> thread::JoinHandle<()> +where + R: Read + Send + 'static, +{ + thread::spawn(move || { + if let Err(error) = read_audio_groups(&tx, &mut reader, config, &policy) { + let _ = tx.send(Err(error)); + } + }) +} + +fn send_intake(tx: &MediaIntakeSender, item: MediaIntake) -> Result<()> { + tx.send(Ok(item)).context("queueing typed Muninn media") +} + +fn read_video_groups( + tx: &MediaIntakeSender, + reader: &mut R, + config: VideoAnnexBStreamSendConfig, + policy: &MediaSendPolicy, +) -> Result<()> { + let mut sender = VideoAnnexBStreamSendState::new(config)?; + let mut buffer = vec![0_u8; 64 * 1024]; + let mut dropped_reported = 0_u64; + loop { + let read = reader + .read(&mut buffer) + .context("reading encoded Annex B video from ffmpeg stdout")?; + let stored_at = crate::timestamp()?; + let (groups, done) = if read == 0 { + (sender.finish(&stored_at)?, true) + } else { + (sender.push(&stored_at, &buffer[..read])?, false) + }; + for payloads in groups { + send_intake( + tx, + MediaIntake::Group(QueuedMediaGroup::new( + MediaKind::Video, + Instant::now(), + policy, + payloads, + )), + )?; + } + let dropped = sender.dropped_access_units(); + if dropped > dropped_reported { + send_intake(tx, MediaIntake::VideoDropped(dropped - dropped_reported))?; + dropped_reported = dropped; + } + if done { + return Ok(()); + } + } +} + +fn read_audio_groups( + tx: &MediaIntakeSender, + reader: &mut R, + config: AudioPcmStreamSendConfig, + policy: &MediaSendPolicy, +) -> Result<()> { + let mut sender = AudioPcmStreamSendState::new(config)?; + let mut buffer = vec![0_u8; 16 * 1024]; + loop { + let read = reader + .read(&mut buffer) + .context("reading PCM audio from ffmpeg stdout")?; + let stored_at = crate::timestamp()?; + let (payloads, done) = if read == 0 { + (sender.finish(&stored_at)?, true) + } else { + (sender.push(&stored_at, &buffer[..read])?, false) + }; + for payload in payloads { + send_intake( + tx, + MediaIntake::Group(QueuedMediaGroup::new( + MediaKind::Audio, + Instant::now(), + policy, + vec![payload], + )), + )?; + } + if done { + return Ok(()); + } + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/muninn-daemon/src/media_send/tests.rs b/crates/muninn-daemon/src/media_send/tests.rs new file mode 100644 index 0000000..7f39e6d --- /dev/null +++ b/crates/muninn-daemon/src/media_send/tests.rs @@ -0,0 +1,845 @@ +use super::*; +use crate::media_packetizer::{MediaWireProvenance, encode_media_wire_record}; +use cultnet_rs::{ + CultNetRudpPacketType, CultNetRudpSocketTransportConnection, CultNetRudpSocketTransportOptions, + CultNetTransportDelivery, ReceiverFeedbackOptions, build_receiver_feedback, decode_rudp_packet, +}; +use std::collections::{BTreeMap, BTreeSet}; +use std::io::Cursor; +use std::net::{SocketAddr, UdpSocket}; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::{Arc, Mutex}; + +const CLIP: &[u8] = include_bytes!("../../testdata/clip.h264"); +const STREAM_ID: &str = "muninn.harness.rudp"; +const VIDEO_SESSION_ID: &str = "harness:video"; +const AUDIO_SESSION_ID: &str = "harness:audio"; +const WAIT: Duration = Duration::from_secs(5); + +fn wait_until(timeout: Duration, mut done: impl FnMut() -> bool) -> bool { + let start = Instant::now(); + while start.elapsed() < timeout { + if done() { + return true; + } + thread::sleep(Duration::from_millis(1)); + } + done() +} + +fn video_config() -> VideoAnnexBStreamSendConfig { + VideoAnnexBStreamSendConfig { + stream_id: STREAM_ID.to_string(), + session_id: VIDEO_SESSION_ID.to_string(), + codec: "h264".to_string(), + first_frame_id: 0, + first_pts_ticks: 0, + frame_duration_ticks: 3_000, + timebase_num: 1, + timebase_den: 90_000, + deadline_delay_ticks: 22_500, + max_payload_bytes: 848, + max_pending_bytes: 848 * 4096, + source_runtime_id: "harness".to_string(), + source_role: "muninn.rudp.video".to_string(), + } +} + +fn audio_config() -> AudioPcmStreamSendConfig { + AudioPcmStreamSendConfig { + stream_id: STREAM_ID.to_string(), + session_id: AUDIO_SESSION_ID.to_string(), + codec: "pcm-f32le-interleaved".to_string(), + first_packet_id: 0, + first_pts_ticks: 0, + packet_duration_ticks: 480, + timebase_num: 1, + timebase_den: 48_000, + deadline_delay_ticks: 24_000, + channels: 2, + bytes_per_sample: 4, + max_pending_bytes: 480 * 2 * 4 * 128, + source_runtime_id: "harness".to_string(), + source_role: "muninn.rudp.audio".to_string(), + } +} + +/// Ten audio packets of an ascending f32 ramp: every byte position is +/// distinct, so a reordered or dropped packet cannot pass for the ramp. +fn pcm_ramp() -> Vec { + let samples = 480 * 2 * 10; + (0..samples) + .flat_map(|index| (index as f32 / samples as f32).to_le_bytes()) + .collect() +} + +/// The clip's access units as the packetizer sends them: one group each. +fn clip_groups() -> Vec { + let mut sender = VideoAnnexBStreamSendState::new(video_config()).unwrap(); + let mut groups = sender.push("unix-0", CLIP).unwrap(); + groups.extend(sender.finish("unix-0").unwrap()); + groups +} + +fn group_at( + kind: MediaKind, + produced_at: Instant, + policy: &MediaSendPolicy, + payloads: MuninnMediaPayloadGroup, +) -> QueuedMediaGroup { + QueuedMediaGroup::new(kind, produced_at, policy, payloads) +} + +fn marker_payload(marker: u8) -> MuninnMediaSendPayload { + MuninnMediaSendPayload { + channel_id: MUNINN_MEDIA_RUDP_CHANNEL, + payload: vec![marker], + } +} + +/// `(frame_id, is_parity, chunk or parity index)` of a video wire record. +fn frame_of(payload: &[u8]) -> Option<(u64, bool, u16)> { + match decode_media_wire_record(payload).ok()? { + GameCultMediaWireRecord::Video(record) => Some((record.frame_id, false, record.chunk_index)), + GameCultMediaWireRecord::VideoParity(record) => { + Some((record.frame_id, true, record.parity_index)) + } + _ => None, + } +} + +fn test_hub(policy: &MediaSendPolicy) -> CultNetRudpServerHub { + let socket = UdpSocket::bind("127.0.0.1:0").unwrap(); + socket.set_nonblocking(true).unwrap(); + CultNetRudpServerHub::new(crate::muninn_media_rudp_hub_options( + socket, + &crate::muninn_rudp_media_profile(), + policy, + )) + .unwrap() +} + +/// The request's budget and no pacing sleeps: the harness is about what the +/// core decides, not about how fast a Windows sender is allowed to go. +fn quiet_policy(latency_budget_ms: u32) -> MediaSendPolicy { + let mut policy = MediaSendPolicy::from_request(latency_budget_ms); + policy.video_pace_sleep = Duration::ZERO; + policy +} + +/// One datagram the hub sent toward the receiver, as the relay saw it. +#[derive(Clone, Debug)] +struct Sent { + packet_type: CultNetRudpPacketType, + channel: String, + payload: Vec, + dropped: bool, +} + +/// A UDP relay between the receiver and the hub. The hub's data packets are +/// dropped by a seeded schedule. Everything is logged before the drop, so +/// tests assert on what the sender put on the wire. +struct DropRelay { + addr: SocketAddr, + log: Arc>>, + stop: Arc, + thread: Option>, +} + +impl DropRelay { + fn start(hub_addr: SocketAddr, drop_percent: u64, seed: u64) -> Self { + let socket = UdpSocket::bind("127.0.0.1:0").unwrap(); + socket + .set_read_timeout(Some(Duration::from_millis(1))) + .unwrap(); + let addr = socket.local_addr().unwrap(); + let log = Arc::new(Mutex::new(Vec::new())); + let stop = Arc::new(AtomicBool::new(false)); + let thread = { + let log = Arc::clone(&log); + let stop = Arc::clone(&stop); + thread::spawn(move || { + let mut client: Option = None; + let mut state = seed.wrapping_mul(0x9E37_79B9_7F4A_7C15) | 1; + let mut buffer = vec![0_u8; 65_535]; + while !stop.load(Ordering::Relaxed) { + let Ok((received, from)) = socket.recv_from(&mut buffer) else { + continue; + }; + if from != hub_addr { + client = Some(from); + let _ = socket.send_to(&buffer[..received], hub_addr); + continue; + } + let Some(client) = client else { continue }; + let Ok(packet) = decode_rudp_packet(&buffer[..received]) else { + continue; + }; + let is_data = packet.packet_type == CultNetRudpPacketType::Data; + state ^= state << 13; + state ^= state >> 7; + state ^= state << 17; + let dropped = is_data && state % 100 < drop_percent; + log.lock().unwrap().push(Sent { + packet_type: packet.packet_type, + channel: packet.channel_id, + payload: packet.payload, + dropped, + }); + if !dropped { + let _ = socket.send_to(&buffer[..received], client); + } + } + }) + }; + Self { + addr, + log, + stop, + thread: Some(thread), + } + } + + fn data(&self) -> Vec { + self.log + .lock() + .unwrap() + .iter() + .filter(|sent| sent.packet_type == CultNetRudpPacketType::Data) + .cloned() + .collect() + } + + fn video_frames_on_wire(&self) -> Vec<(u64, bool, u16)> { + self.data() + .iter() + .filter(|sent| sent.channel == MUNINN_MEDIA_RUDP_CHANNEL) + .filter_map(|sent| frame_of(&sent.payload)) + .collect() + } +} + +impl Drop for DropRelay { + fn drop(&mut self) { + self.stop.store(true, Ordering::Relaxed); + if let Some(thread) = self.thread.take() { + let _ = thread.join(); + } + } +} + +struct Rig { + core: MediaSendCore, + client: CultNetRudpSocketTransportConnection, + relay: DropRelay, + policy: MediaSendPolicy, +} + +fn rig(latency_budget_ms: u32, drop_percent: u64, seed: u64) -> Rig { + let policy = quiet_policy(latency_budget_ms); + let hub = test_hub(&policy); + let relay = DropRelay::start(hub.local_addr().unwrap(), drop_percent, seed); + let socket = UdpSocket::bind("127.0.0.1:0").unwrap(); + socket.set_nonblocking(true).unwrap(); + let mut options = CultNetRudpSocketTransportOptions::client( + "harness-receiver", + socket, + relay.addr, + crate::MUNINN_MEDIA_RUDP_CONNECTION_ID, + ); + options.media_delivery = Some(CultNetTransportDelivery::Unreliable); + options.max_fragment_bytes = Some(crate::MUNINN_RUDP_MEDIA_MAX_FRAGMENT_BYTES as u32); + let mut client = CultNetRudpSocketTransportConnection::new(options).unwrap(); + let mut core = MediaSendCore::new(hub, &policy); + client.connect(b"harness-receiver".to_vec()).unwrap(); + assert!( + wait_until(WAIT, || { + core.service_control(Instant::now()).unwrap(); + let _ = client.receive_once().unwrap(); + client.connected() && core.hub().sessions().len() == 1 + }), + "receiver never attached through the relay" + ); + Rig { + core, + client, + relay, + policy, + } +} + +// ---- policy, groups and queues ----------------------------------------------------- + +#[test] +fn a_group_is_expired_only_after_its_deadline_and_never_at_it() { + let policy = quiet_policy(250); + let produced_at = Instant::now(); + let group = group_at(MediaKind::Video, produced_at, &policy, Vec::new()); + + assert!(!group.expired(group.deadline)); + assert!(!group.expired(group.deadline - Duration::from_millis(1))); + assert!(group.expired(group.deadline + Duration::from_millis(1))); +} + +#[test] +fn a_zero_request_budget_still_leaves_the_stream_a_millisecond() { + assert_eq!( + MediaSendPolicy::from_request(0).latency_budget, + Duration::from_millis(1) + ); +} + +#[test] +fn the_queue_caps_groups_per_kind_and_drops_the_oldest_first() { + let policy = quiet_policy(250); + let mut core = MediaSendCore::new(test_hub(&policy), &policy); + let t0 = Instant::now(); + let over = 37; + for index in 0..(MEDIA_SEND_VIDEO_GROUP_CAP + over) { + core.enqueue(group_at( + MediaKind::Video, + t0 + Duration::from_millis(index as u64), + &policy, + vec![marker_payload(1)], + )); + } + for index in 0..(MEDIA_SEND_AUDIO_GROUP_CAP + 5) { + core.enqueue(group_at( + MediaKind::Audio, + t0 + Duration::from_millis(index as u64), + &policy, + vec![marker_payload(2)], + )); + } + + assert_eq!( + core.queued_groups(MediaKind::Video), + MEDIA_SEND_VIDEO_GROUP_CAP + ); + assert_eq!( + core.queued_groups(MediaKind::Audio), + MEDIA_SEND_AUDIO_GROUP_CAP + ); + // One byte per group: resident bytes are bounded by the cap times the group size. + assert_eq!( + core.queued_payload_bytes(MediaKind::Video), + MEDIA_SEND_VIDEO_GROUP_CAP + ); + assert_eq!( + core.queued_payload_bytes(MediaKind::Audio), + MEDIA_SEND_AUDIO_GROUP_CAP + ); + assert_eq!(core.stats().groups_dropped_video, over as u64); + assert_eq!(core.stats().groups_dropped_audio, 5); + // The survivors are the newest: the oldest deadline left is the 38th group's. + assert_eq!( + core.oldest_deadline(MediaKind::Video), + Some(t0 + Duration::from_millis(over as u64) + policy.latency_budget) + ); + assert_eq!( + core.oldest_deadline(MediaKind::Audio), + Some(t0 + Duration::from_millis(5) + policy.latency_budget) + ); +} + +#[test] +fn the_intake_channel_holds_the_reader_at_its_bound_instead_of_growing() { + let policy = quiet_policy(5_000); + let (tx, rx) = media_intake_channel(); + let frames = clip_groups().len(); + assert!(frames > MEDIA_GROUP_CHANNEL_BOUND + 1); + let reader = spawn_video_group_reader(tx, Cursor::new(CLIP.to_vec()), video_config(), policy); + + // Nothing drains, so the reader parks with the channel full. + thread::sleep(Duration::from_millis(300)); + assert!( + !reader.is_finished(), + "an unbounded channel let the reader run to the end" + ); + + let mut received = 0; + wait_until(WAIT, || { + while rx.try_recv().is_ok() { + received += 1; + } + received == frames + }); + assert_eq!(received, frames); + assert!(wait_until(WAIT, || reader.is_finished())); +} + +#[test] +fn a_blocked_send_gives_up_at_the_group_deadline_and_not_before() { + let start = Instant::now(); + let deadline = start + Duration::from_millis(3); + let ticks = std::cell::Cell::new(0_u64); + let clock = || { + ticks.set(ticks.get() + 1); + start + Duration::from_millis(ticks.get()) + }; + let mut polls = 0_u32; + + // Blocked forever: the deadline ends it, after polling resends in between. + let sent = send_until( + &mut polls, + deadline, + clock, + |_| Err(std::io::Error::from(ErrorKind::WouldBlock).into()), + |polls| { + *polls += 1; + Ok(()) + }, + ) + .unwrap(); + assert!(!sent); + assert_eq!(polls, 3, "one poll per blocked attempt inside the deadline"); + + // Blocked twice, then through: sent, without waiting for the deadline. + ticks.set(0); + let mut attempts = 0_u32; + let sent = send_until( + &mut attempts, + start + Duration::from_millis(100), + clock, + |attempts| { + *attempts += 1; + if *attempts < 3 { + Err(std::io::Error::from(ErrorKind::WouldBlock).into()) + } else { + Ok(()) + } + }, + |_| Ok(()), + ) + .unwrap(); + assert!(sent); + assert_eq!(attempts, 3); +} + +#[test] +fn a_send_error_that_is_not_backpressure_is_an_error_not_a_dropped_group() { + let error = send_until( + &mut (), + Instant::now() + Duration::from_secs(1), + Instant::now, + |_| Err(anyhow::anyhow!("socket closed")), + |_| Ok(()), + ) + .unwrap_err(); + assert!(format!("{error:#}").contains("socket closed")); +} + +// ---- moved from the mux: repair budget, feedback intake, repair cache --------------- + +#[test] +fn rudp_repair_budget_backs_off_on_media_drops_and_recovers_when_stable() { + let start = Instant::now(); + let mut budget = MuninnRudpRepairBudget { + chunks_per_second: 64, + min_chunks_per_second: 8, + max_chunks_per_second: 128, + add_chunks_per_second: 8, + recovery_interval: Duration::from_secs(2), + max_available_chunks: 4, + available_chunks: 4, + last_refill_at: start, + last_rate_adjust_at: start, + last_queue_dropped: 0, + }; + + assert_eq!(budget.take(4, start, 0), 4); + assert_eq!(budget.chunks_per_second(), 64); + assert_eq!(budget.take(3, start + Duration::from_millis(10), 1), 0); + assert_eq!(budget.chunks_per_second(), 32); + assert_eq!(budget.take(3, start + Duration::from_secs(1), 1), 3); + assert_eq!(budget.chunks_per_second(), 32); + assert_eq!(budget.take(3, start + Duration::from_secs(3), 1), 3); + assert_eq!(budget.chunks_per_second(), 40); +} + +#[test] +fn default_rudp_repair_budget_has_lan_stream_headroom() { + let mut budget = + MuninnRudpRepairBudget::new(REPAIR_INITIAL_CHUNKS_PER_SECOND, REPAIR_BURST_CHUNKS); + let start = budget.last_refill_at; + + assert_eq!(budget.chunks_per_second(), 4_096); + assert_eq!(budget.take(2_048, start, 0), 2_048); + assert_eq!(budget.take(8_192, start + Duration::from_secs(1), 0), 2_048); + assert_eq!(budget.take(8_192, start + Duration::from_secs(3), 0), 2_048); + assert_eq!(budget.chunks_per_second(), 6_144); + assert_eq!(budget.take(512, start + Duration::from_secs(4), 1), 512); + assert_eq!(budget.chunks_per_second(), 3_072); +} + +fn feedback_for( + missing_chunk_keys: Vec, + requested_keyframe: bool, +) -> GameCultMediaReceiverFeedbackRecord { + build_receiver_feedback(ReceiverFeedbackOptions { + stream_id: STREAM_ID, + session_id: VIDEO_SESSION_ID, + receiver_id: "harness-receiver", + highest_decodable_frame_id: Some(41), + missing_frame_ids: Vec::new(), + missing_video_chunk_keys: missing_chunk_keys, + late_frame_ids: vec![42, 43], + requested_keyframe, + jitter_us: 500, + decode_queue_us: 2_000, + observed_at: "unix:1000", + }) + .unwrap() +} + +fn feedback_wire(feedback: GameCultMediaReceiverFeedbackRecord) -> Vec { + encode_media_wire_record( + &GameCultMediaWireRecord::Feedback(feedback), + MediaWireProvenance { + stored_at: "unix:1000", + runtime_id: "harness", + role: "harness.receiver", + producer: "harness", + }, + ) + .unwrap() +} + +#[test] +fn rudp_media_receiver_feedback_updates_sender_pressure_stats() { + let frame = CultNetTransportFrame { + channel_id: MUNINN_MEDIA_RUDP_CHANNEL.to_string(), + payload: feedback_wire(feedback_for(vec!["42:1".into(), "42:3".into()], true)), + }; + let mut stats = MuninnRudpReceiverFeedbackStats::default(); + let repair_cache = RecentVideoChunkRepairCache::new(16); + + let repairs = + record_receiver_feedback(&frame, &mut stats, &repair_cache, Instant::now()).unwrap(); + + assert_eq!(stats.feedback_records, 1); + assert_eq!(stats.requested_keyframes, 1); + assert_eq!(stats.late_frames, 2); + assert_eq!(stats.missing_video_chunks, 2); + assert_eq!(stats.repaired_video_chunks, 0); + assert_eq!(stats.highest_decodable_frame_id, Some(41)); + assert!(repairs.is_empty()); +} + +#[test] +fn repair_cache_returns_recent_missing_video_chunks_with_their_frames_deadline() { + let groups = clip_groups(); + let payload = groups[0][0].clone(); + let (frame_id, _, chunk_index) = frame_of(&payload.payload).unwrap(); + let feedback = feedback_for( + vec![ + video_chunk_feedback_key(frame_id, chunk_index), + "999:0".to_string(), + ], + false, + ); + let deadline = Instant::now() + Duration::from_millis(250); + + let mut cache = RecentVideoChunkRepairCache::new(16); + cache.remember(&payload, deadline).unwrap(); + let repairs = cache.repair_payloads_for_feedback(&feedback, deadline); + + assert_eq!(repairs, vec![(payload, deadline)]); +} + +// ---- the wire: whole groups, repairs inside their frame's deadline ------------------ + +#[test] +fn a_group_past_its_deadline_puts_nothing_on_the_wire_and_a_live_one_puts_all_of_it() { + let mut rig = rig(250, 0, 1); + let groups = clip_groups(); + let stale = groups[0].clone(); + let live = groups + .iter() + .skip(1) + .find(|group| group.len() > 2) + .expect("the clip has a later multi-chunk frame") + .clone(); + let live_frame = frame_of(&live[0].payload).unwrap().0; + let t0 = Instant::now(); + let budget = rig.policy.latency_budget; + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, stale)); + rig.core.enqueue(group_at( + MediaKind::Video, + t0 + 5 * budget, + &rig.policy, + live.clone(), + )); + + // Two budgets after the stale group was made, inside the live group's. + assert!(rig.core.send_next(t0 + 2 * budget).unwrap()); + + assert_eq!(rig.core.stats().groups_expired, 1); + assert_eq!(rig.core.stats().groups_sent, 1); + assert!(wait_until(WAIT, || { + rig.relay.video_frames_on_wire().len() == live.len() + })); + thread::sleep(Duration::from_millis(100)); + let on_wire = rig.relay.video_frames_on_wire(); + assert_eq!( + on_wire.len(), + live.len(), + "every payload of the live group, and no other" + ); + assert!(on_wire.iter().all(|(frame, _, _)| *frame == live_frame)); + assert!(rig.core.progress_detail().contains("groups_sent=1")); + assert!(rig.core.progress_detail().contains("groups_expired=1")); +} + +#[test] +fn audio_leaves_before_video_on_the_wire() { + let mut rig = rig(250, 0, 1); + let t0 = Instant::now(); + let video = clip_groups().remove(1); + let mut audio_sender = AudioPcmStreamSendState::new(audio_config()).unwrap(); + let audio = audio_sender.push("unix-0", &pcm_ramp()).unwrap().remove(0); + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, video)); + rig.core + .enqueue(group_at(MediaKind::Audio, t0, &rig.policy, vec![audio])); + + assert!(rig.core.send_next(t0).unwrap()); + assert!(rig.core.send_next(t0).unwrap()); + + assert!(wait_until(WAIT, || !rig.relay.data().is_empty())); + assert_eq!(rig.relay.data()[0].channel, "audio"); +} + +/// Sends the clip's first multi-chunk frame at `t0` and returns its deadline, +/// its frame id and how many payloads it put on the wire. +fn send_repairable_frame(rig: &mut Rig, t0: Instant) -> (Instant, u64, usize) { + let group = clip_groups() + .into_iter() + .find(|group| group.len() > 2) + .unwrap(); + let (frame_id, _, _) = frame_of(&group[0].payload).unwrap(); + let queued = group_at(MediaKind::Video, t0, &rig.policy, group.clone()); + let deadline = queued.deadline; + rig.core.enqueue(queued); + assert!(rig.core.send_next(t0).unwrap()); + assert!(wait_until(WAIT, || rig.relay.video_frames_on_wire().len() + == group.len())); + (deadline, frame_id, group.len()) +} + +fn ask_for_chunk(rig: &mut Rig, frame_id: u64, at: Instant, records_seen: u64) { + rig.client + .send( + MUNINN_MEDIA_RUDP_CHANNEL, + feedback_wire(feedback_for( + vec![video_chunk_feedback_key(frame_id, 0)], + false, + )), + ) + .unwrap(); + assert!( + wait_until(WAIT, || { + rig.core.service_control(at).unwrap(); + rig.core.feedback().feedback_records == records_seen + }), + "the hub never received the feedback" + ); +} + +#[test] +fn a_repair_is_sent_inside_its_frames_deadline_and_not_after_it() { + // Taken before the handshake, so real time is well past it by the time + // anything is sent: a repair that took its deadline from the clock + // instead of its frame would still be alive at the probe below. + let t0 = Instant::now(); + let mut rig = rig(250, 0, 1); + let (deadline, frame_id, frame_payloads) = send_repairable_frame(&mut rig, t0); + let epsilon = Duration::from_millis(2); + + ask_for_chunk(&mut rig, frame_id, deadline - epsilon, 1); + assert!( + wait_until(WAIT, || rig.relay.video_frames_on_wire().len() + == frame_payloads + 1), + "a repair asked for just before the deadline is sent" + ); + assert_eq!(rig.core.feedback().repaired_video_chunks, 1); + + ask_for_chunk(&mut rig, frame_id, deadline + epsilon, 2); + thread::sleep(Duration::from_millis(150)); + assert_eq!( + rig.relay.video_frames_on_wire().len(), + frame_payloads + 1, + "a repair asked for just after the deadline is not sent" + ); + assert_eq!(rig.core.feedback().repaired_video_chunks, 1); + assert_eq!(rig.core.feedback().missing_video_chunks, 2); +} + +// ---- the harness end to end: the fixture clip and the PCM ramp --------------------- + +#[derive(Default)] +struct Received { + chunks: BTreeMap>, + chunk_counts: BTreeMap, + audio: BTreeMap>, +} + +impl Received { + fn take(&mut self, rig: &mut Rig) { + while let Some(frame) = rig.client.receive_once().unwrap() { + match decode_media_wire_record(&frame.payload).unwrap() { + GameCultMediaWireRecord::Video(record) => { + self.chunks + .entry(record.frame_id) + .or_default() + .insert(record.chunk_index); + self.chunk_counts + .insert(record.frame_id, record.chunk_count); + } + GameCultMediaWireRecord::Audio(record) => { + self.audio.insert(record.packet_id, record.payload); + } + _ => {} + } + } + } + + fn complete_frames(&self) -> BTreeSet { + self.chunks + .iter() + .filter(|(frame, chunks)| chunks.len() == self.chunk_counts[frame] as usize) + .map(|(frame, _)| *frame) + .collect() + } +} + +/// Feeds the fixture through the real readers and the send loop, over the +/// relay, and returns what the receiver assembled. +fn run_clip(rig: &mut Rig, with_audio: bool) -> Received { + let (tx, rx) = media_intake_channel(); + let video = spawn_video_group_reader( + tx.clone(), + Cursor::new(CLIP.to_vec()), + video_config(), + rig.policy.clone(), + ); + let audio = with_audio.then(|| { + spawn_audio_group_reader( + tx.clone(), + Cursor::new(pcm_ramp()), + audio_config(), + rig.policy.clone(), + ) + }); + drop(tx); + let mut received = Received::default(); + let start = Instant::now(); + while !rig.core.finished() && start.elapsed() < WAIT { + rig.core.intake(&rx, Duration::from_millis(2)).unwrap(); + rig.core.send_next(Instant::now()).unwrap(); + rig.core.service_control(Instant::now()).unwrap(); + received.take(rig); + } + assert!(rig.core.finished(), "the send loop never finished the clip"); + let settle = Instant::now(); + while settle.elapsed() < Duration::from_millis(300) { + rig.core.service_control(Instant::now()).unwrap(); + received.take(rig); + thread::sleep(Duration::from_millis(1)); + } + video.join().unwrap(); + if let Some(audio) = audio { + audio.join().unwrap(); + } + received +} + +#[test] +fn the_clip_and_the_pcm_ramp_arrive_whole_through_a_lossless_relay() { + // A budget far above the run time: nothing here may expire. + let mut rig = rig(5_000, 0, 1); + let frames = clip_groups().len() as u64; + + let received = run_clip(&mut rig, true); + + assert_eq!( + received.complete_frames(), + (0..frames).collect::>() + ); + assert_eq!(rig.core.stats().groups_lost(), 0); + let heard: Vec = received.audio.values().flatten().copied().collect(); + assert_eq!(received.audio.len(), 10); + assert_eq!(heard, pcm_ramp(), "the ramp arrived complete and in order"); +} + +#[test] +fn the_seeded_relay_drops_the_same_datagrams_every_run_and_the_sender_carries_on() { + let run = |seed| { + let mut rig = rig(5_000, 30, seed); + let received = run_clip(&mut rig, false); + let dropped: Vec = rig.relay.data().iter().map(|sent| sent.dropped).collect(); + (received.complete_frames(), dropped, rig.core.stats().clone()) + }; + + let (complete_a, dropped_a, stats_a) = run(7); + let (complete_b, dropped_b, _) = run(7); + let (_, dropped_other, _) = run(8); + let frames = clip_groups().len(); + + assert_eq!(dropped_a, dropped_b, "same seed, same drop schedule"); + assert_ne!( + dropped_a, dropped_other, + "a different seed drops different datagrams" + ); + assert_eq!(complete_a, complete_b); + assert!(dropped_a.iter().any(|dropped| *dropped)); + assert!( + complete_a.len() < frames, + "30% loss without parity or repair leaves incomplete frames" + ); + assert_eq!(stats_a.groups_sent, frames as u64); + assert_eq!( + stats_a.groups_lost(), + 0, + "loss on the wire is not a sender-side drop" + ); +} + +#[test] +fn a_group_is_counted_by_what_the_deadline_let_reach_the_wire() { + let mut stats = MediaSendStats::default(); + + stats.record_group(&GroupSend::Complete, 6); + assert_eq!((stats.groups_sent, stats.payloads_sent), (1, 6)); + + // Deadline passed before the first payload: nothing left, so nothing was cut. + stats.record_group(&GroupSend::DeadlinePassed { payloads_out: 0 }, 6); + assert_eq!((stats.groups_expired, stats.groups_cut_short), (1, 0)); + assert_eq!(stats.payloads_sent, 6); + + // Deadline passed with part of the group already out: a partial frame. + stats.record_group(&GroupSend::DeadlinePassed { payloads_out: 2 }, 6); + assert_eq!((stats.groups_expired, stats.groups_cut_short), (1, 1)); + assert_eq!(stats.payloads_sent, 8); + assert_eq!(stats.groups_lost(), 2); +} + +#[test] +fn an_oversize_access_unit_reaches_the_sender_as_a_dropped_video_group_not_an_error() { + let policy = quiet_policy(250); + let mut core = MediaSendCore::new(test_hub(&policy), &policy); + let (tx, rx) = media_intake_channel(); + let mut config = video_config(); + config.max_pending_bytes = 8; + let mut oversize = vec![0, 0, 0, 1, 0x65, 0x80]; + oversize.extend_from_slice(&[7; 20]); + let reader = spawn_video_group_reader(tx, Cursor::new(oversize), config, policy); + + assert!(wait_until(WAIT, || reader.is_finished())); + core.intake(&rx, Duration::from_millis(50)).unwrap(); + core.intake(&rx, Duration::from_millis(50)).unwrap(); + + assert_eq!(core.stats().groups_dropped_video, 1); + assert!(core.finished(), "the stream ended cleanly, it was not restarted by an error"); +} diff --git a/crates/muninn-daemon/testdata/clip.h264 b/crates/muninn-daemon/testdata/clip.h264 new file mode 100644 index 0000000000000000000000000000000000000000..860d9e0f7d6f7c38adce6e7042d880d82318f29f GIT binary patch literal 8855 zcmb8Uc{r4R^fx{m#y(@;XHY4LAvW3-|z4DdH#IvKhAyL=Y7t(&-FUzy5~Kw8vpB6{eyR>Ttr}-GKL2{2E*h$jigw1dZFyx6OmrXJ zeX!wvNNs&RWcX1Xouf#Ut|7|jGK#z5pviU6I&sR@{)jHp@`5$j)7Q_3yJ3yR#fA9! zM^A3rN@I#|wx$9W%quR(&KXg=R z05T%#GFQ_^A#o9LXzjle6Yh)F)Bg6edLINYuI!MD4y}s}#Bm|! zHk8`|U2fN|a@+T}7l6M5=a-o(#3b6f|yJEuos#&YnNpPPwY2&-C=UB3f@y=2C)x#w}ye=a}kluUQo?FiKJKTh*4ht8h) zc`)F~iLO&$&eLB^$jfYoT(BN};TCgJo>y_kx(DC;^%QzJ?#UYIX_!dd#TDhV`PY!% zV26>e$cINshW)p(bmqx6^k_*&$_vGj+yT<}vIcNmtc}@0p-ih_3WruJbz(&|6TnO0 zxhMMooYxm2Vy*XyaY?}^2cQ5^-V_9tt~n^c0>pV4q*Z$%!Tr5IU$rta6ud}p*G>ng zIte22YsuCrGAp6@4bjx@Njl?!YAT1*|6MuKE*U?`E@z!fb?n%<#UHPWO`kcKfJ3bC{zFZCyn5!Az{-wrE0DZ$vX(MG0kU|VTI!^LU)^%pHzHO>p z7#Qe(WC0E5e3xHlJ9i{ZtUa1wjm(e!*>Sb>M4eqpVKzJex)rP*u>hakW4;bwI9vCD z+Ok+T)t)=>VfCTEc_WN1!(6F&=f`-z#Upl(ky-En0JFOTJD08)SJt5nb&3HcDQn9R z-ZbuQw7rnU%MjqbE&eZuMCj>24v+V5-MCB2P+eXCD3RA-UTm5TP(J$Wv~Vh1$`ubF znaT0oNQ2!4&JzVe^11PGKEee~LFA;TUPx6w&*Lp@1zkA<;oZ(<&~X$Y>-M9{l$v7T zwQWz-KbP#@*z7YYX8~hLr!+THRS$MT512Xi0_7j}NSy0DbhSqYkaGWwcIW*$B~7FP z7@F+iKKfi?nx>Z5y692|CTI#Ftv=ih8E-NBj`xbox|sQl7ZbCGPsTXe=io(z3NhFB z;pULKS9ueM?-Ck%{Eze=C~W{=CZ&(5zIo4!05GFv6AF9twDbG{{K*&T^t4Hy-Lbk^ z&R%MLw!%mA&NbThy6bu2KAFR?(jnAFzV-r#v&-X~Hm&e`c*IfAqTrMWDhI*%j4}lX zF!OHFya2`^fZ;)vWzjSshrhGdoR>*^D`RRh^Gim>?~|42g}T(l*O%A~UcY^x5M!)F zu!3@O$>dmCy~5q1PSIl9FPY8!<{Hk1-1NMs#*Zu5GKoOpO6udcj%H=4JbfrMx;@wV? zV;_DGR7t702cbT_E8xi1ELUGC*r0Dc^Dp2NIp}bU>ExJxJ8+Nqjl`?J__>+%4l;Rr zdGE~`BtBg|g(N4AdQ-$4eyIGThR#5&^45bnTgejV&PB!uGiI%EtAjx3NIVk>hfUbo%b zmQ(=~`L-Lc+~s*HiU9?WN0J`NG>v#Xq=iVOpvo%llsCe<4@tWksuza_ z!7=bzjAh97@W96&ZFXb1u5H6AXMBd7qYIHMs3 zK^};|`SeA}>ylB24~*1xm=La)@v^m#bAKaV_Y~vf2w)1iN3S`3i4+q}2k z4O&^7xpbX_{mxXzd~M!eNK{t1rq&%}Sy?3t(O46{=)bp5(A_7hV~gc;zj09LdcV3- zO;WOu*6}BLA(6@MkuEL&!9|@HUj_r6ZLzryfXWPd&l*u!^N6GENT4G1;d>`u9Z{Bc zfOT2u45ybeUhdN1n|`$2!A8h};16dCeGWM=-4VHk`aa%1MN1=3Is?TudLiO3u9~Y| zHhT=Ql(BM^dtZVl11MxuC&?x9q~eC<6ZY#|C1@lx`%s4cNgYH+@8b{lU7&2|Jn4Zo zHl!#R-%Jzz3^%yac=ioLC79>!zH>yXq>=|KcLuh)CQZ>ES9bGdF=#eP2@EUyq_*$O zF%~SMJ@#mkw-6C8LRrq?5D7h)B zd440Fk#l~ApLtwTq#O}5&aBz8rY%G`PBodUEfQDj7d(ejAvp?g;Ql)^6~F$pJw9s& zDK9EzJ5P4;Qvz<4Tv>ie@Aj$nTHzSf1b>86m5p2!JCQ1;th)x~WaZ`h9L5pU=aXSj zgE>`3&P%+Z{Sggw#+D-E=1McgqlZ^fLEN+H4*v=IkDGX6DZcvYoWZ**jErAN`1OO3jh%tZE-3!RRq^+E&%HJTsNasxNB1o;mp~U?iOO=t`@l|i7Go=)w_3`|3Z`Uad4PG9}Mr@Sb>hE}* zi2uH`kz4V(5-MmV<_A)3kBfCB96zBCcyp!;(mnNvPUu_Ox*wBoC5~YwKvFhPR;M&H zAj^eyi7$XA+kBoE4`|wXSA8Lmm4tVMEtaKSE6;li9*-#Bsxy6ZG5xOTiN=_9+TkCc z(y!%+mEe~Pl|HOzPz&3WS=3oWK_Cu7 z!njW%&fO+fsjcugg4#Enk8cZjF0`2R}7E&@|QgV*CRw zFKBTuQTkfMjFM8j4NJQ6Q7>(Z?OA^Wm&EH%;fOvwbIcGI$zPmRw|V-Y7`uO`PUOxA zBt2#_SF5w{%h~9nX$If-W7nGg$vWadgX1HAD%sFdK%8zr z64E5)*H)?awheq>Kd3&-t$%p=(ie_ebvrb-u&oMC)?M>PSR#lK^*&l#!oG{xpPrBk zk_J8V^2TLSFP>ok>|0VzgkI3b0vW0&j9%wq0o3}wem{1Kdac~Ne1OzoB}RCVz@p?Y zd5Jk}v6qp8yQK{0`@1hH$WPGZ!@n!7;m^B&uyl9i9I=ax`Rk%=jv((z`6>>^Snac; z+CNvnrTtl#GmN29X`o{s7>?Q7`Lk#6AVgFWmhGIiL;cUV2c}?Vl%>DGiaw~N%yt@G zKa4DVPMsE3YZ?*EgeA*cKre+xuTk)26B9Adm0~a-mN>cTtK0EngDiQ)4@E4bkO@X~ z`&C;CABuyRyB+;xq$B%Ky};m_`LouEywXX2O0Obg0D>`KZ-16*eKkqquL-6uteF=w zGT6?-wp8Qf!_yqPq<6AJUF-$9L}x%5hz3^})uavq3NBmk)%7;WXVI5)p_PT1!5MD~ z5>+4y7xRjkA?K@D( zy{~gSdlGKus#ofo^&)3EMTH$4y6b;%i|fS9!cKR~{(PG@ZI>*M1TH2}v9ZhMqgCt{ zHzT(5eGas@sCWJA)$x z5^+X2X#@^3SyqrZbS0kqi%v+(|FB46t3rw+2kPG{y@?IlkGPL?#!fuEfxW}Y-735a zXJns?+~6?MG@S+hkzVyGvzTHW!)jrm>9J*J5^ww|ug)Q!?@m;S=Jn@W03y3SY<2*$ zXYTz;_G~8N)kZsj%IWq~hQCwIsMRd-AGt-}wtWtkV|dJ+_2Eo=y25Yx=mgWp?YC<^ zhOD4_FG{P3ZDN8UOSi|#({K`Uaw2NwgqARKfZA8}6D85@We_FVeI`ro0NbsojJ*b_ zGctisy}k{0vAh2aCHXu`OBl53VP@TgYt`%X0gA&-h?y7uJ{-F{}=wtFEfRgOGj|up}sWD$ABmd4cL3s z;ZfSm@}{tkRfp*5KO~hk-7FK)+cF_uA&nR6M12J#?5DI5yVF5r+u5-;xB4$e?RBnW z$Lqrpy9;uG69S0cIRygP@;v|osUXI1BE<`QlSIt7Np8l<&W^7Ds;@%@UZQN^`e*%zhM7_0dEuCStBJY`p> zil>dUTw474@I#S`=vAA2zTX!5(yw{P?oLw?016ud3?P z_Pn%ezN6|b8Ix*z8YgwS@Ej20o`w5nve&;c%ywby8!wo;9K!^=SI$=VM-H0I20rw4 zFs=wBKXXUBK%REyJuMg|3A)xgD1OQa8^?6{BdKYHWv1>zrMLTUX1&;$p)wh9A;fDh&(j)b*ts6 z6T*no7uBegol8kHQ!1%Dmtfp6eSQ6awT&9)Met=A>BHEl^ju0Ezj~AH;sj9XcT?iv zP5uj$0~+UToI8_I7679Gd5-yKA1WFX=F-P`p@J(fcwauR9m0wxvJtJd1w%pOVY2c& zW_h zaL;EPTT@6m=RX<3Kem=3q~)HFz$9hn=lrjnNxkk;olSY5G7_AB@>hdrYEA1e7_s#_ zTY>U$FI_Lt58C5zSJ*#sr6@d)EKy!!`bvQ8^Lo@ z8+Q{$eI@jhlfp{MoW}dp*o8JAAg2eUO2TshaG-5M5A=a{*F9>{d&eu63$g8dL@*c> zHKjRG*J$!CJ2CESvV*06V%#_YU|v*`c0y%b#5s%+xKBxVU+NFty&&_La=oFU6I;8C z#@CmiAWx_qYsR-l#yTkd?DO~q2M1uT!orWp@DTOmzqXa0Fy8qet4E9x16ig9i_NAo zDHSA9fU6fwvr;8=zotCA^H#$m303VtIgx7=9!k)vw@9lmE8b7xp|Axy4dm0?fSD(F z08EI}>Qg*HXL7$P(#o<|luoB9gwK2u1;Yzm^+!V#viZdlMYSF8JtoZE&?*HfBSwVB zXfnLOo1V*$=RDa3P6UeS>pqhjiObb;YCdLcx)$$C{}hs$u`oi>Zv~ebhH^N6p)1{3 zajoG;{m?DQ;l$AU?qI-*jD3mlE>)@sOjuB&$;O;0fH7?}nKHppMzz8&=@Eq#*1 zbLyd!1ch`u#_6tbr(dp^>lF=xKJpi^J`!Nwv)z%gGEK%tgj1f4v-n3 z3rns3EuAT*41Gw1Ol5;EROB4G)|+;J005V7a(rhiJtwOCJ_Wvn$50fIq#E18Ofgf7 zM?xo4jy>Oa2WEm%5?O?@A4qwFs*?dIl8nWLY0;a5L&7?u_$6d4%BGhA`;;!#h%F-H z;8s!q)lG2>FJkWMB+YDqzb=Ju=RJB7yrPH~P6JhK7+vL>5E5tsm)7Iy9S1bj%kB#B4@JIV1KHpnB5JwR z-lOZbp~C|!Kw+2oc-+-qa!QcW3tQYdkMnaTaCi z!cxTVY+-U$bPddz4v-P#FAK{wQxX8Z*C5CaAruD_ph=CN{AQD54+w_CGC98`iPAZK zcUQ0U?)QCjtmZM~7wxte6**CkU4m{2mCtxIb^F}cyx%mM@0|9sW2G+Ed#|dVDI;z1 zD4Mv+-@Idm=GUO?gvj2M>FxODK}y)Ute4%!US;XWyCqq#JE0k`(he${W(d9VXulfV z>&2Jw8M_|!qnU-{ct5gCbuc2^&sp#jP&|d3E+Y!i8FxT)YCtVybDodOU70_LWhep28?NtICyyEDC0rnIaO zO4cJLs?udU(rb`j=issN0lW(3aZ2n5{&zxKBNtrv5}%x`-|Csp!8uaT{7CP*L(91E z5^(A%b0DtCZjp|F{_~ZrR0fxJy>w)=(}WBo40$bi;)?^#F=nwJU-e}yA+VfQU*GuI z$mLlx|DSiY{;1Ngl;L}p_V6ZKF$y0r@soLVKh1}@%vdV)zXXdqUj#hw<_m=QicPl- zg~UWTh-LR}o|ufMockc{u#aPIuKR$?=<&Fjvg{C`V0ERcZzmLK zG3-@4`A&hf&NFW2*LQWECe`k=k(Tx`o&h+_Igh6TO3X_m5|vjF#QoT~L!y{2wvyj~)gRlCml!o#>`x9){{_@FRyIMM{ z=H+bX*elTZSnDB1uBo(#0Ul~g`p@8+@I{D64(*vftjJ&6sp0>_(ei{7y@iVyag6u2 zlPbhhiI_T~^OGueyR7wCy7GGUr4Dh%TQM*+{^$FiQR=AT7N5DF5N^cADNCbd!Gye~ zk^_EzC)rt8L((w|WM^-GYP5%uJ-$JPWxaHlh^LgU|CH=y_T!7{ayQhUKj1e+?%i=3 zoMChS(qMW$&Y>OCPp9$HMD(9VgF_v?W>5c6bLm)92!9;gW|>HjObZDfDSHK}qX||- zzUALI8TB{LRBl-)J{djH=u#OoNb^5n90Oz=N}!l(TTzMuoqKE7l6TZGWOF+TtiJYWaLj7$ z(`9<0sx$Vvc#dhrXBhYBS|4k7b@ittGi(^!8J;xT59eZ~{QgHj2QzB&n&VXe;*Hb@N3~XSo{M6Rd6QoF^ycE|{m3-&f&ci8_mEp8S?dUS6Y|6#h$|AMiFXl3tB zK%<@WNu7HbUbQEoOIlR2emf)YAw0hWNwnDR`c#LTSdv@^;F2j+oNTayyQ;woip)8eWj2z|V znWSQ*%$afVb6wB$W|T7o;m!&=$E3K_-I(X>Md%&RRMknMOFNuFu%-)=l|@{GZJchY zI@*e`EiNNGTxi?OhAs5Nr>6XEbFFyus}a{tUwu2*ytx{l{1}n-rz%Z(gO-1Bi>Py$ z-7@*)Ka&wiXx2vSvRCiH5_Vt7cU0t1De Date: Tue, 29 Sep 2026 20:04:39 +0200 Subject: [PATCH 23/44] Describe the group send queue and the 250 ms default in the media doc The streaming doc still said a request naming no latency budget got 2,000 ms and did not mention that the sender queue is bounded, per-group, and owns the deadline that repairs inherit. Re-anchor the two main.rs references it moved. Co-Authored-By: Claude Opus 5.5 --- docs/muninn-media-streaming.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/muninn-media-streaming.md b/docs/muninn-media-streaming.md index 0eefb53..c94ef67 100644 --- a/docs/muninn-media-streaming.md +++ b/docs/muninn-media-streaming.md @@ -237,7 +237,7 @@ a temporary PCM/AAC compatibility bridge. Recommended first LAN profile: - Profile id: `muninn.rudp.low_latency_h264_lan.v1`. -- Video: H.264 NVENC, `p5` (`main.rs:10279`), ultra-low-latency tune, CBR high enough that LAN +- Video: H.264 NVENC, `p5` (`main.rs:9504`), ultra-low-latency tune, CBR high enough that LAN bandwidth is not the constraint, no B-frames, no lookahead, short GOP or intra-refresh, keyframe actuation on feedback pressure (not built: keyframe requests are only counted and logged today; Cut 6 builds it). @@ -257,7 +257,8 @@ Recommended first LAN profile: in CultNet deliberately instead of falling through to accidental IP fragmentation. - Resend cadence: sender RUDP media resends are scheduled every `30` ms (`main.rs:94`) while - the packet is still inside its expiry, which is the request's latency budget (default `2,000` ms, `main.rs:95`). + the packet is still inside its expiry, which is the request's latency budget (a request that names none gets `250` ms, `main.rs:98`, and the advertisement offers the same as `default_latency_budget_ms`). +- Send queue: `media_send.rs` owns it. The unit is a group, one access unit with its parity or one audio packet, stamped `produced_at + latency budget` when the packetizer emits it. A group is sent whole or dropped whole at its deadline; queues are capped per kind (audio 256, video 512 groups) and drop the oldest group, counted as `groups_dropped_audio` and `groups_dropped_video`. A repair keeps the deadline of the frame it repairs and is not sent after it. - Control: sender may adapt bitrate, keyframe cadence, chunk size, and playout budget from receiver feedback; the receiver must not silently stretch latency to preserve visual perfection. From d564543b70a961466be770e6170c1e4c4d564283 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 20:05:34 +0200 Subject: [PATCH 24/44] State the stream rule once: consumers dial the producing Muninn The input firewall rule is what any producing Muninn needs, not an input exception or an accepted cost of Q10. Co-Authored-By: Claude Opus 5.5 --- docs/realtime-robustness-cut.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/realtime-robustness-cut.md b/docs/realtime-robustness-cut.md index cd5b568..24816fb 100644 --- a/docs/realtime-robustness-cut.md +++ b/docs/realtime-robustness-cut.md @@ -65,8 +65,8 @@ the ruled design. The earlier options survive only in git (`e70db69`). viewer-dials recommendation. Operator: "Ratatoskr is asking Muninn to open a video stream, Sleipnir asks Muninn to open an input stream. Both should be Muninn capabilities which it chooses to broadcast via CultMesh." So Muninn publishes an input-stream capability through CultMesh beside its media capability, - and Sleipnir requests it the way Ratatoskr requests video. The HID cuts H0-H5 need re-mapping to this - shape before Hands. + and Sleipnir requests it the way Ratatoskr requests video. Both consumers dial the producing Muninn. + Pass 3 re-mapped H0-H5 to this shape. **Rulings, 2026-09-30 (operator), pass 3 forks:** - **Q11 (a): the input-stream records live in `muninn-contracts` as `muninn.input_stream_*`.** The input track @@ -1279,11 +1279,12 @@ that request path, read at the SHAs above. | Producer admits and answers | Muninn pulls request documents from Odin each tick (`M :971-1034`), turns them into `MuninnCaptureStreamCommandRecord`s, and writes the answer onto the request key (`M :1038-1117`). | The **same pull** takes both request schemas in one snapshot. Input requests go to the input organ as demand (B23), with **no** detour through a command record, and are answered on the same key. | | Who dials | The consumer dials the advertised endpoint (`R receiver.rs:4-7`). Its connect payload is its `receiver_id` (`R receiver.rs:40-42`). Muninn listens on a `CultNetRudpServerHub` (`M :3192-3213`). | The consumer (Sleipnir, on the game host) dials the viewer's Muninn. Muninn listens on a `CultNetRudpServerHub` and serves a session only the device its request names. | -**Consequence the operator accepted in Q10:** the producer is on the viewer, so -**the viewer's host admits inbound UDP** for input. That is the cost the -2026-09-10 media inversion refused for video viewers (teardown-map -L486-495). For input it is ruled acceptable. H5 records the firewall rule per -viewer host. +**One rule for both streams:** the consumer dials the Muninn that produces the +stream, and that Muninn listens. For video, the producing Muninn is on the game +host. For input, it is on the viewer's machine, because the controller is +there. Every host whose Muninn produces a stream admits inbound UDP on that +stream's port. Raven already does this for video. H5 adds the same rule on each +viewer that produces input. **Two deliberate differences from the video path**, each protecting a named invariant: @@ -1922,8 +1923,8 @@ If it runs, Raven's local pad mirror is live. It dials Raven's Muninn at this cut. - A viewer outside GameCult's hosts runs Muninn by hand. That limit is recorded, not solved here. -- **Firewall, per the Q10 consequence:** each **viewer** host admits inbound - UDP on its input port (17887) from the game host. Starfire needs one +- **Firewall:** a host whose Muninn produces input admits inbound UDP on its + input port (17887) from the game host, as a video producer does on its media port. Starfire needs one Windows Firewall rule. It is scoped to the mesh interface where possible, and recorded in gamecult-ops inventory beside Raven's 5220/17887. Raven keeps 17887 open only while it also produces input for its own local From 6a628ee551f115093c64f79e4e22317f8948e10a Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 20:11:40 +0200 Subject: [PATCH 25/44] Hoist the CultLib and odin-core pins into one workspace table Sleipnir joins the workspace at Muninn's pins (CultLib c2a9a6e, odin-core Odin 3e96c6c) instead of Odin main's a8aedda and a path dependency. Muninn and Sleipnir now move together by construction. Manifests and lock only; no source change. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 23 +++++++++++++++++++++++ Cargo.toml | 9 +++++++++ crates/muninn-daemon/Cargo.toml | 8 ++++---- crates/sleipnir-daemon/Cargo.toml | 8 ++++---- 4 files changed, 40 insertions(+), 8 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 27c00d7..2419f4b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -791,6 +791,20 @@ version = "0.4.12" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" +[[package]] +name = "sleipnir-daemon" +version = "0.1.0" +dependencies = [ + "anyhow", + "cultcache-rs", + "cultmesh-rs", + "cultnet-rs", + "odin-core", + "rmp-serde", + "serde_json", + "vigem-client", +] + [[package]] name = "socket2" version = "0.5.10" @@ -878,6 +892,15 @@ version = "0.9.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" +[[package]] +name = "vigem-client" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b857e6f99efe1e1eb1e4dfb035de8ae7ec8ec56bd1928edcbd7c6e4427634d52" +dependencies = [ + "winapi", +] + [[package]] name = "wasi" version = "0.11.1+wasi-snapshot-preview1" diff --git a/Cargo.toml b/Cargo.toml index a6c8188..12add68 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,6 +3,7 @@ members = [ "crates/muninn-daemon", "crates/muninn-move-tracker", "crates/muninn-psmoveapi-tracker", + "crates/sleipnir-daemon", ] resolver = "3" @@ -10,3 +11,11 @@ resolver = "3" edition = "2024" license = "MIT" publish = false + +# One pin per shared upstream. Muninn and Sleipnir resolve the same CultLib and +# odin-core by construction; a bump is one edit here. +[workspace.dependencies] +cultcache-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c2a9a6e526390808ef195759056fda0b9a55d8a3", package = "cultcache-rs" } +cultmesh-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c2a9a6e526390808ef195759056fda0b9a55d8a3", package = "cultmesh-rs" } +cultnet-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c2a9a6e526390808ef195759056fda0b9a55d8a3", package = "cultnet-rs" } +odin-core = { git = "https://github.com/GameCult/Odin.git", rev = "3e96c6c85ca8b89b1bc7b01c1b7744f43111be99" } diff --git a/crates/muninn-daemon/Cargo.toml b/crates/muninn-daemon/Cargo.toml index ac34344..5b495ee 100644 --- a/crates/muninn-daemon/Cargo.toml +++ b/crates/muninn-daemon/Cargo.toml @@ -15,13 +15,13 @@ path = "src/main.rs" [dependencies] anyhow = "1" -cultcache-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c2a9a6e526390808ef195759056fda0b9a55d8a3", package = "cultcache-rs" } -cultmesh-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c2a9a6e526390808ef195759056fda0b9a55d8a3", package = "cultmesh-rs" } -cultnet-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "c2a9a6e526390808ef195759056fda0b9a55d8a3", package = "cultnet-rs" } +cultcache-rs = { workspace = true } +cultmesh-rs = { workspace = true } +cultnet-rs = { workspace = true } libc = "0.2" muninn-move-tracker = { path = "../muninn-move-tracker" } muninn-psmoveapi-tracker = { path = "../muninn-psmoveapi-tracker", optional = true } -odin-core = { git = "https://github.com/GameCult/Odin.git", rev = "3e96c6c85ca8b89b1bc7b01c1b7744f43111be99" } +odin-core = { workspace = true } rmp-serde = "1.3" serde = { version = "1", features = ["derive"] } serde_bytes = "0.11" diff --git a/crates/sleipnir-daemon/Cargo.toml b/crates/sleipnir-daemon/Cargo.toml index c0372a4..b10f048 100644 --- a/crates/sleipnir-daemon/Cargo.toml +++ b/crates/sleipnir-daemon/Cargo.toml @@ -11,10 +11,10 @@ path = "src/main.rs" [dependencies] anyhow = "1" -cultmesh-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "a8aeddacab7dd4b9e634b4420867ea3b402cb858", package = "cultmesh-rs" } -cultnet-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "a8aeddacab7dd4b9e634b4420867ea3b402cb858", package = "cultnet-rs" } -cultcache-rs = { git = "https://github.com/GameCult/CultLib.git", rev = "a8aeddacab7dd4b9e634b4420867ea3b402cb858", package = "cultcache-rs" } -odin-core = { path = "../odin-core" } +cultmesh-rs = { workspace = true } +cultnet-rs = { workspace = true } +cultcache-rs = { workspace = true } +odin-core = { workspace = true } rmp-serde = "1.3" serde_json = "1" From ed02890c12b50d89384ddfaf4607d1e0fbd875e2 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 20:16:07 +0200 Subject: [PATCH 26/44] Give Sleipnir the media_delivery field CultLib c2a9a6e requires Odin main's Sleipnir was written against CultLib a8aedda, and its two CultNetRudpSocketTransportOptions initialisers do not compile at Muninn's c2a9a6e pin. media_delivery: None is the field's default, so behaviour is unchanged. Co-Authored-By: Claude Opus 5.5 --- crates/sleipnir-daemon/src/main.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/crates/sleipnir-daemon/src/main.rs b/crates/sleipnir-daemon/src/main.rs index 06b056f..1be0193 100644 --- a/crates/sleipnir-daemon/src/main.rs +++ b/crates/sleipnir-daemon/src/main.rs @@ -2227,6 +2227,7 @@ fn create_rudp_stream( max_fragment_bytes: Some(HID_RUDP_MAX_FRAGMENT_BYTES), max_pending_reliable_packets: Some(256), media_reliable_expire_after_ms: Some(25), + media_delivery: None, reconnect_policy: None, })?; transport.connect(Vec::new())?; @@ -2268,6 +2269,7 @@ fn create_rudp_stream( max_fragment_bytes: Some(HID_RUDP_MAX_FRAGMENT_BYTES), max_pending_reliable_packets: Some(256), media_reliable_expire_after_ms: Some(25), + media_delivery: None, reconnect_policy: None, })?, target: None, From 95b84a81027730c9f174562f5101eb6b8f6b3c76 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 20:24:31 +0200 Subject: [PATCH 27/44] Record the Cut 2 Soul pass and the loss-signalling owner Co-Authored-By: Claude Opus 5.5 --- docs/realtime-robustness-cut.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/realtime-robustness-cut.md b/docs/realtime-robustness-cut.md index 24816fb..04ba0d6 100644 --- a/docs/realtime-robustness-cut.md +++ b/docs/realtime-robustness-cut.md @@ -79,6 +79,20 @@ the ruled design. The earlier options survive only in git (`e70db69`). - Only an on-demand scheduled task, `\Codex-Sleipnir-LAN-Proof`, remains. It last ran on 2026-07-17. - Raven runs `muninn.exe` alone. +**Cut 2 Soul pass, 2026-09-30: fix first.** The queues, caps and budget ownership hold. Findings: +- Audio waits behind a whole video group send. +- The deadline is checked only when the socket blocks. +- Whole-frame drops leave the receiver no trace. +- A packetizer overflow can emit a corrupt access unit. +- The budget has no upper clamp. + +**Ruling (Self, 2026-09-30): the receiver owns loss signalling.** A frame lost whole on the network looks the +same as one the sender dropped, so there is one owner for both: +- Ratatoskr requests a keyframe on a `frame_id` gap. This is a Cut 4 requirement. +- Cut 2 makes every sender-side drop (queue cap, expiry, packetizer overflow) consume a `frame_id`, so the gap + is visible. +- The latency budget is clamped to 2000 ms. + ## Target: ends and invariants **End.** A Muninn stream that loses packets degrades by what each signal class From 89ae74ae0f1fcc0c0262736f18580f7afc36f7ab Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 20:37:30 +0200 Subject: [PATCH 28/44] Make a packetizer overflow drop consume its frame id and its leftover slices An access unit dropped for outgrowing max_pending_bytes consumed no frame id, so a receiver could not see the gap, and the slices that followed it were emitted as a complete access unit of their own. The drop now spends the frame id (and its pts step) and the state discards the leftover slices up to the next access-unit boundary, waiting for the boundary when the leftover is not yet complete. A stream that resumes on a boundary loses nothing more. Co-Authored-By: Claude Opus 5.5 --- crates/muninn-daemon/src/media_packetizer.rs | 145 ++++++++++++++++++- 1 file changed, 143 insertions(+), 2 deletions(-) diff --git a/crates/muninn-daemon/src/media_packetizer.rs b/crates/muninn-daemon/src/media_packetizer.rs index bcf2423..cff3fb5 100644 --- a/crates/muninn-daemon/src/media_packetizer.rs +++ b/crates/muninn-daemon/src/media_packetizer.rs @@ -224,6 +224,9 @@ pub struct VideoAnnexBStreamSendState { next_frame_id: u64, next_pts_ticks: i64, dropped_access_units: u64, + /// Set by an overflow drop: the slices that follow belong to the dropped + /// access unit and are discarded up to the next access-unit boundary. + discarding_tail: bool, } impl VideoAnnexBStreamSendState { @@ -267,13 +270,17 @@ impl VideoAnnexBStreamSendState { config, pending: Vec::new(), dropped_access_units: 0, + discarding_tail: false, }) } /// One group per completed access unit. Whatever is still pending after /// that is a single unfinished access unit; when it outgrows /// `max_pending_bytes` it is dropped and counted, never an error that - /// would restart the stream. + /// would restart the stream. The dropped unit consumes its frame id, so a + /// receiver sees the gap, and its remaining slices are discarded up to the + /// next access-unit boundary instead of being emitted as a frame of their + /// own. pub fn push(&mut self, stored_at: &str, bytes: &[u8]) -> Result> { if !bytes.is_empty() { self.pending.extend_from_slice(bytes); @@ -281,7 +288,11 @@ impl VideoAnnexBStreamSendState { let groups = self.emit_available(stored_at, false)?; if self.pending.len() > self.config.max_pending_bytes { self.pending.clear(); - self.dropped_access_units += 1; + if !self.discarding_tail { + self.dropped_access_units += 1; + self.advance_frame_clock()?; + self.discarding_tail = true; + } } Ok(groups) } @@ -321,6 +332,12 @@ impl VideoAnnexBStreamSendState { if self.pending.is_empty() { return Ok(Vec::new()); } + if self.discarding_tail && !self.discard_leftover_slices(flush_last)? { + return Ok(Vec::new()); + } + if self.pending.is_empty() { + return Ok(Vec::new()); + } let access_units = match video_annex_b_access_units(&self.config.codec, &self.pending) { Ok(access_units) => access_units, @@ -380,6 +397,48 @@ impl VideoAnnexBStreamSendState { Ok(groups) } + /// While the tail of a dropped access unit is being discarded: if the + /// pending bytes open with a continuation slice, drops that leftover access + /// unit (up to the next boundary) and stops discarding; if they open on a + /// boundary, stops discarding and leaves them alone. `false` means it + /// cannot tell yet (the leftover is not complete) and the caller must wait + /// for more bytes. + fn discard_leftover_slices(&mut self, flush_last: bool) -> Result { + let codec = self.config.codec.as_str(); + let nal_units = match normalized_video_codec(codec) { + Some("h265") => annex_b_nal_units(&self.pending, "H.265", h265_nal_type), + _ => annex_b_nal_units(&self.pending, "H.264", h264_nal_type), + }; + let Ok(nal_units) = nal_units else { + return Ok(false); + }; + let first = &nal_units[0]; + let continuation = match normalized_video_codec(codec) { + Some("h265") => { + is_h265_vcl_nal(first.nal_type) + && !h265_first_slice_segment_in_pic(first.payload).unwrap_or(false) + } + _ => { + is_h264_vcl_nal(first.nal_type) + && h264_first_mb_in_slice(first.payload).unwrap_or(1) != 0 + } + }; + if !continuation { + self.discarding_tail = false; + return Ok(true); + } + let access_units = video_annex_b_access_units(codec, &self.pending)?; + if access_units.len() >= 2 { + self.pending.drain(..access_units[0].bytes.len()); + } else if flush_last { + self.pending.clear(); + } else { + return Ok(false); + } + self.discarding_tail = false; + Ok(true) + } + fn advance_frame_clock(&mut self) -> Result<()> { self.next_frame_id = self .next_frame_id @@ -1704,6 +1763,88 @@ mod tests { ); } + /// `(frame_id, whole access unit bytes)` for each group, chunks rejoined. + fn frames_of(groups: &[MuninnMediaPayloadGroup]) -> Result)>> { + groups + .iter() + .map(|group| { + let mut frame_id = None; + let mut bytes = Vec::new(); + for payload in group { + if let GameCultMediaWireRecord::Video(record) = + decode_media_wire_record(&payload.payload)? + { + frame_id = Some(record.frame_id); + bytes.extend_from_slice(&record.payload); + } + } + Ok((frame_id.expect("a group carries video chunks"), bytes)) + }) + .collect() + } + + #[test] + fn an_overflow_drop_consumes_its_frame_id_and_discards_the_leftover_slices() -> Result<()> { + let mut config = stream_send_config(); + config.max_pending_bytes = 16; + config.max_payload_bytes = 64; + let mut sender = VideoAnnexBStreamSendState::new(config)?; + let stored_at = "2026-06-18T00:00:00Z"; + let nal = |header: [u8; 2], filler: &[u8]| { + [&start_code()[..], &header[..], filler].concat() + }; + + // Frame 9 whole, then the head of a frame that outgrows the ceiling. + let mut first = nal([0x65, 0x80], &[0xA1]); + first.extend(nal([0x41, 0x80], &[0xB2; 30])); + let groups = frames_of(&sender.push(stored_at, &first)?)?; + assert_eq!(groups, vec![(9, nal([0x65, 0x80], &[0xA1]))]); + assert_eq!(sender.dropped_access_units(), 1); + assert_eq!(sender.next_frame_id(), 11, "the dropped frame 10 is spent"); + + // Its second slice (first_mb_in_slice != 0) arrives alone: nothing can + // be decided yet, and nothing is emitted. + assert!(sender.push(stored_at, &nal([0x41, 0x40], &[0xC3]))?.is_empty()); + assert_eq!(sender.dropped_access_units(), 1); + + // Then two whole frames follow: the leftover slice goes with frame 10. + let mut next = nal([0x41, 0x80], &[0xD4]); + next.extend(nal([0x41, 0x80], &[0xE5])); + let mut groups = frames_of(&sender.push(stored_at, &next)?)?; + groups.extend(frames_of(&sender.finish(stored_at)?)?); + assert_eq!( + groups, + vec![ + (11, nal([0x41, 0x80], &[0xD4])), + (12, nal([0x41, 0x80], &[0xE5])), + ] + ); + assert_eq!(sender.dropped_access_units(), 1); + Ok(()) + } + + #[test] + fn a_stream_that_resumes_on_a_frame_boundary_after_an_overflow_loses_nothing_more() -> Result<()> { + let mut config = stream_send_config(); + config.max_pending_bytes = 16; + let mut sender = VideoAnnexBStreamSendState::new(config)?; + let stored_at = "2026-06-18T00:00:00Z"; + let nal = |header: [u8; 2], filler: &[u8]| { + [&start_code()[..], &header[..], filler].concat() + }; + + assert!(sender.push(stored_at, &nal([0x65, 0x80], &[0xB2; 30]))?.is_empty()); + assert_eq!(sender.next_frame_id(), 10); + + // The next bytes open on a new frame, not on a leftover slice. + let mut next = nal([0x41, 0x80], &[0xD4]); + next.extend(nal([0x41, 0x80], &[0xE5])); + let groups = frames_of(&sender.push(stored_at, &next)?)?; + assert_eq!(groups.len(), 1); + assert_eq!(groups[0].0, 10); + Ok(()) + } + fn flat(groups: Vec) -> Vec { groups.into_iter().flatten().collect() } From 96b64cba973104a24a447a9636279b0c95099b30 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 20:37:31 +0200 Subject: [PATCH 29/44] Send media one payload per step: audio first, per-payload deadlines, clamped budget The send loop now moves one payload per step and chooses it afresh: audio, then repairs, then video. A video group in progress or a full socket no longer holds audio back for more than the payload in progress; a full socket hands control back instead of spinning to the group deadline. Repairs are queued by feedback intake and sent by the same step, each checked against its own frame's deadline at send time and only to the receiver that asked. The group deadline is checked before every payload; a group that outlives it mid-send is abandoned and counted groups_cut_short. A request's latency budget is clamped to 1..=2000 ms. Tests pin the cap values, the clamp, per-payload audio priority (mid-frame, full socket, between repairs), the send-time deadline for groups and repairs, repairs going only to the asker, and the frame-id gap left by a queue-cap, expiry or overflow drop. Co-Authored-By: Claude Opus 5.5 --- crates/muninn-daemon/src/media_send.rs | 291 ++++++---- crates/muninn-daemon/src/media_send/tests.rs | 546 ++++++++++++++++--- docs/muninn-media-streaming.md | 2 +- 3 files changed, 659 insertions(+), 180 deletions(-) diff --git a/crates/muninn-daemon/src/media_send.rs b/crates/muninn-daemon/src/media_send.rs index e84855f..b6b58f1 100644 --- a/crates/muninn-daemon/src/media_send.rs +++ b/crates/muninn-daemon/src/media_send.rs @@ -11,6 +11,14 @@ //! repair inherits the deadline of the frame it repairs; the hub's reliable //! expiry and the record deadline ticks derive from the same budget. //! +//! **Priority.** The send loop moves one payload per step and chooses the +//! payload afresh each time: audio first, then repairs, then video. Audio that +//! arrives while a video group is half sent, or while the socket is full, +//! goes out before the video group's next payload; nothing holds audio behind +//! video for longer than one payload. The group deadline is checked before +//! every payload; a group that outlives it mid-send is abandoned and counted +//! `groups_cut_short`. +//! //! **Bounds.** Between the encoder and the socket every queue has a count //! bound (`MEDIA_GROUP_CHANNEL_BOUND`, the per-kind group caps) and a time //! bound (the group deadline). Crossing either drops whole groups, oldest @@ -39,6 +47,9 @@ use std::time::{Duration, Instant}; pub const MEDIA_SEND_AUDIO_GROUP_CAP: usize = 256; pub const MEDIA_SEND_VIDEO_GROUP_CAP: usize = 512; +/// The longest latency budget a request may claim (the old default). Above +/// this the queues stop being bounded in time. +pub const MEDIA_SEND_MAX_LATENCY_BUDGET_MS: u32 = 2_000; /// Groups the reader threads may have handed over and the send loop not yet /// taken. Small on purpose: the caps above are where a backlog lives. pub const MEDIA_GROUP_CHANNEL_BOUND: usize = 8; @@ -75,7 +86,9 @@ pub struct MediaSendPolicy { impl MediaSendPolicy { pub fn from_request(latency_budget_ms: u32) -> Self { Self { - latency_budget: Duration::from_millis(u64::from(latency_budget_ms.max(1))), + latency_budget: Duration::from_millis(u64::from( + latency_budget_ms.clamp(1, MEDIA_SEND_MAX_LATENCY_BUDGET_MS), + )), video_pace_every_payloads: SEND_PACE_EVERY_PAYLOADS, video_pace_sleep: Duration::from_micros(SEND_PACE_SLEEP_US), } @@ -169,12 +182,6 @@ impl PendingMediaGroups { dropped } - /// Audio leaves before video: a late audio packet is a click, a late - /// frame is one dropped frame. - fn pop_next(&mut self) -> Option { - self.audio.pop_front().or_else(|| self.video.pop_front()) - } - fn is_empty(&self) -> bool { self.audio.is_empty() && self.video.is_empty() } @@ -442,28 +449,29 @@ pub fn is_would_block_error(error: &anyhow::Error) -> bool { }) } -/// Tries `attempt` until it goes through or `deadline` passes. While the -/// socket is full it polls resends and tries again; it never sleeps and never -/// outlives the deadline. `false` means the deadline won. -fn send_until( - host: &mut H, - deadline: Instant, - mut now: impl FnMut() -> Instant, - mut attempt: impl FnMut(&mut H) -> Result<()>, - mut poll: impl FnMut(&mut H) -> Result<()>, +/// One payload to one receiver, once. `false` means the socket is full: resends +/// are polled and the caller tries again on its next step, choosing again what +/// is most urgent. It never waits, so a full socket cannot hold a queued audio +/// packet behind video. +fn try_send( + hub: &mut CultNetRudpServerHub, + receiver: &CultNetRudpServerSessionContext, + payload: &MuninnMediaSendPayload, + socket_full: bool, ) -> Result { - loop { - match attempt(host) { - Ok(()) => return Ok(true), - Err(error) if is_would_block_error(&error) => { - if now() > deadline { - return Ok(false); - } - poll(host)?; - thread::yield_now(); - } - Err(error) => return Err(error).context("sending typed Muninn media payload"), + let sent = if socket_full { + Err(std::io::Error::from(ErrorKind::WouldBlock).into()) + } else { + hub.send(receiver, payload.channel_id, payload.payload.clone()) + }; + match sent { + Ok(()) => Ok(true), + Err(error) if is_would_block_error(&error) => { + poll_resends(hub)?; + thread::yield_now(); + Ok(false) } + Err(error) => Err(error).context("sending typed Muninn media payload"), } } @@ -482,32 +490,29 @@ enum GroupSend { DeadlinePassed { payloads_out: usize }, } -/// Every payload to every receiver, in order, or as many as the deadline -/// allows. A payload with nobody to send it to is not a failure; the progress -/// line says how many receivers there are. -fn send_payloads( - hub: &mut CultNetRudpServerHub, - receivers: &[CultNetRudpServerSessionContext], - payloads: &[MuninnMediaSendPayload], - deadline: Instant, - pacer: &mut MuninnRudpMediaSendPacer, -) -> Result { - for (payloads_out, payload) in payloads.iter().enumerate() { - for receiver in receivers { - let sent = send_until( - hub, - deadline, - Instant::now, - |hub| hub.send(receiver, payload.channel_id, payload.payload.clone()), - poll_resends, - )?; - if !sent { - return Ok(GroupSend::DeadlinePassed { payloads_out }); - } - } - pacer.observe_sent_payload(); +/// A group being sent, one payload at a time, to the receivers there were when +/// it started. A payload with nobody to send it to is not a failure; the +/// progress line says how many receivers there are. +struct InFlight { + group: QueuedMediaGroup, + receivers: Vec, + payload: usize, + receiver: usize, +} + +impl InFlight { + /// Payloads that have reached at least one receiver. + fn payloads_out(&self) -> usize { + self.payload + usize::from(self.receiver > 0) } - Ok(GroupSend::Complete) +} + +/// A repair chunk waiting for the socket: one payload to the receiver that +/// asked, dead at the deadline of the frame it repairs. +struct PendingRepair { + receiver: CultNetRudpServerSessionContext, + payload: MuninnMediaSendPayload, + deadline: Instant, } pub struct MediaSendCore { @@ -517,6 +522,12 @@ pub struct MediaSendCore { repair_budget: MuninnRudpRepairBudget, video_pacer: MuninnRudpMediaSendPacer, audio_pacer: MuninnRudpMediaSendPacer, + audio_in_flight: Option, + video_in_flight: Option, + repairs: VecDeque, + /// Test seam: while set, the socket reports itself full. + #[cfg(test)] + pub(crate) socket_full: std::sync::Arc, stats: MediaSendStats, feedback: MuninnRudpReceiverFeedbackStats, handled_keyframe_requests: u64, @@ -538,6 +549,11 @@ impl MediaSendCore { policy.video_pace_sleep, ), audio_pacer: MuninnRudpMediaSendPacer::new(0, Duration::ZERO), + audio_in_flight: None, + video_in_flight: None, + repairs: VecDeque::new(), + #[cfg(test)] + socket_full: Default::default(), stats: MediaSendStats::default(), feedback: MuninnRudpReceiverFeedbackStats::default(), handled_keyframe_requests: 0, @@ -562,7 +578,14 @@ impl MediaSendCore { /// Nothing queued and every reader gone: the encoders have ended. pub fn finished(&self) -> bool { - self.disconnected && self.queues.is_empty() + self.disconnected && !self.has_work() + } + + fn has_work(&self) -> bool { + !self.queues.is_empty() + || self.audio_in_flight.is_some() + || self.video_in_flight.is_some() + || !self.repairs.is_empty() } /// Takes what the reader threads have produced. Waits up to `wait` for the @@ -571,7 +594,7 @@ impl MediaSendCore { if self.disconnected { return Ok(()); } - if self.queues.is_empty() { + if !self.has_work() { match rx.recv_timeout(wait) { Ok(item) => self.accept(item?), Err(mpsc::RecvTimeoutError::Timeout) => return Ok(()), @@ -614,41 +637,106 @@ impl MediaSendCore { } } - /// Sends the next group that is still inside its deadline at `now`, - /// discarding expired ones whole on the way. `true` when a group went out - /// (all of it, or the part the deadline allowed). + /// One step of the send loop: moves at most one payload toward the wire and + /// says whether there was anything to do. The next payload is chosen afresh + /// every step, audio first, then repairs, then video, so a video group in + /// progress or a full socket never holds audio back. A group whose + /// deadline has passed at `now`, before or after part of it went out, is + /// abandoned whole. pub fn send_next(&mut self, now: Instant) -> Result { - while let Some(group) = self.queues.pop_next() { - if group.expired(now) { - self.stats.groups_expired += 1; - self.log_loss_milestone(); + #[cfg(test)] + let socket_full = self.socket_full.load(std::sync::atomic::Ordering::Relaxed); + #[cfg(not(test))] + let socket_full = false; + if self.step_group(MediaKind::Audio, now, socket_full)? + || self.step_repair(now, socket_full)? + { + return Ok(true); + } + self.step_group(MediaKind::Video, now, socket_full) + } + + fn step_group(&mut self, kind: MediaKind, now: Instant, socket_full: bool) -> Result { + let in_flight = match kind { + MediaKind::Audio => &mut self.audio_in_flight, + MediaKind::Video => &mut self.video_in_flight, + }; + if in_flight.is_none() { + let queue = match kind { + MediaKind::Audio => &mut self.queues.audio, + MediaKind::Video => &mut self.queues.video, + }; + let Some(group) = queue.pop_front() else { + return Ok(false); + }; + *in_flight = Some(InFlight { + group, + receivers: self.hub.sessions(), + payload: 0, + receiver: 0, + }); + } + let flight = in_flight.as_mut().expect("in flight was just filled"); + + if flight.group.expired(now) { + let outcome = GroupSend::DeadlinePassed { + payloads_out: flight.payloads_out(), + }; + let group_payloads = flight.group.payloads.len(); + *in_flight = None; + self.stats.record_group(&outcome, group_payloads); + self.log_loss_milestone(); + return Ok(true); + } + + if let Some(payload) = flight.group.payloads.get(flight.payload) { + if let Some(receiver) = flight.receivers.get(flight.receiver) { + if !try_send(&mut self.hub, receiver, payload, socket_full)? { + return Ok(true); + } + flight.receiver += 1; + if flight.receiver < flight.receivers.len() { + return Ok(true); + } + } + flight.receiver = 0; + flight.payload += 1; + match kind { + MediaKind::Video => self.video_pacer.observe_sent_payload(), + MediaKind::Audio => self.audio_pacer.observe_sent_payload(), + } + if flight.payload < flight.group.payloads.len() { + return Ok(true); + } + } + + let flight = in_flight.take().expect("in flight is set"); + self.stats + .record_group(&GroupSend::Complete, flight.group.payloads.len()); + if kind == MediaKind::Video { + for payload in &flight.group.payloads { + self.repair_cache.remember(payload, flight.group.deadline)?; + } + } + if self.stats.groups_sent == 1 || self.stats.groups_sent % 900 == 0 { + eprintln!("{}", self.progress_detail()); + } + Ok(true) + } + + /// Sends the oldest queued repair chunk that is still inside its frame's + /// deadline at `now`; the ones already past it are discarded. + fn step_repair(&mut self, now: Instant, socket_full: bool) -> Result { + while let Some(repair) = self.repairs.front() { + if now > repair.deadline { + self.repairs.pop_front(); continue; } - let receivers = self.hub.sessions(); - let pacer = match group.kind { - MediaKind::Video => &mut self.video_pacer, - MediaKind::Audio => &mut self.audio_pacer, - }; - let outcome = send_payloads( - &mut self.hub, - &receivers, - &group.payloads, - group.deadline, - pacer, - )?; - self.stats.record_group(&outcome, group.payloads.len()); - match outcome { - GroupSend::Complete => { - if group.kind == MediaKind::Video { - for payload in &group.payloads { - self.repair_cache.remember(payload, group.deadline)?; - } - } - if self.stats.groups_sent == 1 || self.stats.groups_sent % 900 == 0 { - eprintln!("{}", self.progress_detail()); - } - } - GroupSend::DeadlinePassed { .. } => self.log_loss_milestone(), + if try_send(&mut self.hub, &repair.receiver, &repair.payload, socket_full)? { + self.repairs.pop_front(); + self.feedback.repaired_video_chunks = + self.feedback.repaired_video_chunks.saturating_add(1); + self.video_pacer.observe_sent_payload(); } return Ok(true); } @@ -705,8 +793,9 @@ impl MediaSendCore { now, )?; let requested = repairs.len(); + let room = REPAIR_CACHE_CHUNKS.saturating_sub(self.repairs.len()); let allowed = self.repair_budget.take( - requested.min(REPAIR_MAX_CHUNKS_PER_POLL), + requested.min(REPAIR_MAX_CHUNKS_PER_POLL).min(room), now, self.stats.groups_lost(), ); @@ -715,21 +804,19 @@ impl MediaSendCore { .feedback .deferred_repair_chunks .saturating_add(requested.saturating_sub(allowed) as u64); - // Repairs go back to the receiver that asked, not to everyone, - // and each one keeps the deadline of its own frame. - for (payload, deadline) in repairs.into_iter().take(allowed) { - let outcome = send_payloads( - &mut self.hub, - std::slice::from_ref(&session), - std::slice::from_ref(&payload), - deadline, - &mut self.video_pacer, - )?; - if matches!(outcome, GroupSend::Complete) { - self.feedback.repaired_video_chunks = - self.feedback.repaired_video_chunks.saturating_add(1); - } - } + // Repairs are queued for the receiver that asked, not for + // everyone; the send step sends each one inside the + // deadline of its own frame, after any waiting audio. + self.repairs.extend( + repairs + .into_iter() + .take(allowed) + .map(|(payload, deadline)| PendingRepair { + receiver: session.clone(), + payload, + deadline, + }), + ); } Ok(Some(CultNetRudpServerEvent::Pong { .. })) => {} Ok(None) => return Ok(()), diff --git a/crates/muninn-daemon/src/media_send/tests.rs b/crates/muninn-daemon/src/media_send/tests.rs index 7f39e6d..a9083b0 100644 --- a/crates/muninn-daemon/src/media_send/tests.rs +++ b/crates/muninn-daemon/src/media_send/tests.rs @@ -108,6 +108,47 @@ fn frame_of(payload: &[u8]) -> Option<(u64, bool, u16)> { } } +/// Sends until the core has nothing left to do at `now`. Only for runs where +/// the socket is never full. +fn drain(core: &mut MediaSendCore, now: Instant) { + while core.send_next(now).unwrap() {} +} + +/// `count` one-slice access units with distinct frame ids 0..count, each a +/// single small group. +fn synthetic_groups(count: usize) -> Vec { + let mut sender = VideoAnnexBStreamSendState::new(video_config()).unwrap(); + let mut stream = Vec::new(); + for index in 0..count { + let nal = if index == 0 { 0x65 } else { 0x41 }; + stream.extend_from_slice(&[0, 0, 0, 1, nal, 0x80, index as u8]); + } + let mut groups = sender.push("unix-0", &stream).unwrap(); + groups.extend(sender.finish("unix-0").unwrap()); + assert_eq!(groups.len(), count); + groups +} + +fn one_audio_group() -> MuninnMediaPayloadGroup { + let mut sender = AudioPcmStreamSendState::new(audio_config()).unwrap(); + vec![sender.push("unix-0", &pcm_ramp()).unwrap().remove(0)] +} + +/// Hands the reader one chunk per `read`, so a test decides where a push ends. +struct ChunkedReader(std::collections::VecDeque>); + +impl Read for ChunkedReader { + fn read(&mut self, buffer: &mut [u8]) -> std::io::Result { + match self.0.pop_front() { + Some(chunk) => { + buffer[..chunk.len()].copy_from_slice(&chunk); + Ok(chunk.len()) + } + None => Ok(0), + } + } +} + fn test_hub(policy: &MediaSendPolicy) -> CultNetRudpServerHub { let socket = UdpSocket::bind("127.0.0.1:0").unwrap(); socket.set_nonblocking(true).unwrap(); @@ -210,6 +251,17 @@ impl DropRelay { .collect() } + fn channels_on_wire(&self) -> Vec { + self.data().into_iter().map(|sent| sent.channel).collect() + } + + fn frame_ids_on_wire(&self) -> BTreeSet { + self.video_frames_on_wire() + .into_iter() + .map(|(frame_id, _, _)| frame_id) + .collect() + } + fn video_frames_on_wire(&self) -> Vec<(u64, bool, u16)> { self.data() .iter() @@ -289,13 +341,43 @@ fn a_zero_request_budget_still_leaves_the_stream_a_millisecond() { ); } +#[test] +fn a_request_cannot_claim_more_than_the_maximum_latency_budget() { + assert_eq!(MEDIA_SEND_MAX_LATENCY_BUDGET_MS, 2_000); + let millis = |request| MediaSendPolicy::from_request(request).latency_budget; + assert_eq!(millis(u32::MAX), Duration::from_millis(2_000)); + assert_eq!(millis(2_001), Duration::from_millis(2_000)); + assert_eq!(millis(2_000), Duration::from_millis(2_000)); + assert_eq!(millis(1_999), Duration::from_millis(1_999)); + assert_eq!(millis(250), Duration::from_millis(250)); + + // Everything derived from the request follows the clamped budget. + let policy = MediaSendPolicy::from_request(u32::MAX); + let produced_at = Instant::now(); + let group = group_at(MediaKind::Video, produced_at, &policy, Vec::new()); + assert_eq!(group.deadline - produced_at, Duration::from_millis(2_000)); + assert_eq!(policy.latency_budget_ms(), 2_000); + assert_eq!(policy.video_deadline_delay_ticks(), 180_000); + assert_eq!(policy.audio_deadline_delay_ticks(48_000), 96_000); + let hub_options = crate::muninn_media_rudp_hub_options( + UdpSocket::bind("127.0.0.1:0").unwrap(), + &crate::muninn_rudp_media_profile(), + &policy, + ); + assert_eq!(hub_options.media_reliable_expire_after_ms, Some(2_000)); +} + #[test] fn the_queue_caps_groups_per_kind_and_drops_the_oldest_first() { + const VIDEO_CAP: usize = 512; + const AUDIO_CAP: usize = 256; + assert_eq!(MEDIA_SEND_VIDEO_GROUP_CAP, VIDEO_CAP); + assert_eq!(MEDIA_SEND_AUDIO_GROUP_CAP, AUDIO_CAP); let policy = quiet_policy(250); let mut core = MediaSendCore::new(test_hub(&policy), &policy); let t0 = Instant::now(); let over = 37; - for index in 0..(MEDIA_SEND_VIDEO_GROUP_CAP + over) { + for index in 0..(VIDEO_CAP + over) { core.enqueue(group_at( MediaKind::Video, t0 + Duration::from_millis(index as u64), @@ -303,7 +385,7 @@ fn the_queue_caps_groups_per_kind_and_drops_the_oldest_first() { vec![marker_payload(1)], )); } - for index in 0..(MEDIA_SEND_AUDIO_GROUP_CAP + 5) { + for index in 0..(AUDIO_CAP + 5) { core.enqueue(group_at( MediaKind::Audio, t0 + Duration::from_millis(index as u64), @@ -312,23 +394,11 @@ fn the_queue_caps_groups_per_kind_and_drops_the_oldest_first() { )); } - assert_eq!( - core.queued_groups(MediaKind::Video), - MEDIA_SEND_VIDEO_GROUP_CAP - ); - assert_eq!( - core.queued_groups(MediaKind::Audio), - MEDIA_SEND_AUDIO_GROUP_CAP - ); + assert_eq!(core.queued_groups(MediaKind::Video), VIDEO_CAP); + assert_eq!(core.queued_groups(MediaKind::Audio), AUDIO_CAP); // One byte per group: resident bytes are bounded by the cap times the group size. - assert_eq!( - core.queued_payload_bytes(MediaKind::Video), - MEDIA_SEND_VIDEO_GROUP_CAP - ); - assert_eq!( - core.queued_payload_bytes(MediaKind::Audio), - MEDIA_SEND_AUDIO_GROUP_CAP - ); + assert_eq!(core.queued_payload_bytes(MediaKind::Video), VIDEO_CAP); + assert_eq!(core.queued_payload_bytes(MediaKind::Audio), AUDIO_CAP); assert_eq!(core.stats().groups_dropped_video, over as u64); assert_eq!(core.stats().groups_dropped_audio, 5); // The survivors are the newest: the oldest deadline left is the 38th group's. @@ -369,64 +439,294 @@ fn the_intake_channel_holds_the_reader_at_its_bound_instead_of_growing() { } #[test] -fn a_blocked_send_gives_up_at_the_group_deadline_and_not_before() { - let start = Instant::now(); - let deadline = start + Duration::from_millis(3); - let ticks = std::cell::Cell::new(0_u64); - let clock = || { - ticks.set(ticks.get() + 1); - start + Duration::from_millis(ticks.get()) - }; - let mut polls = 0_u32; +fn a_full_socket_is_recognised_and_any_other_send_error_is_an_error() { + assert!(is_would_block_error(&std::io::Error::from(ErrorKind::WouldBlock).into())); + assert!(is_would_block_error(&anyhow::anyhow!("send failed: os error 10035"))); + assert!(!is_would_block_error(&anyhow::anyhow!("socket closed"))); - // Blocked forever: the deadline ends it, after polling resends in between. - let sent = send_until( - &mut polls, - deadline, - clock, - |_| Err(std::io::Error::from(ErrorKind::WouldBlock).into()), - |polls| { - *polls += 1; - Ok(()) - }, - ) - .unwrap(); - assert!(!sent); - assert_eq!(polls, 3, "one poll per blocked attempt inside the deadline"); + let mut rig = rig(250, 0, 1); + let mut stranger = rig.core.hub().sessions()[0].clone(); + stranger.remote_addr = "127.0.0.1:9".parse().unwrap(); + let error = try_send(&mut rig.core.hub, &stranger, &marker_payload(1), false).unwrap_err(); + assert!(!is_would_block_error(&error)); + assert!(format!("{error:#}").contains("sending typed Muninn media payload")); - // Blocked twice, then through: sent, without waiting for the deadline. - ticks.set(0); - let mut attempts = 0_u32; - let sent = send_until( - &mut attempts, - start + Duration::from_millis(100), - clock, - |attempts| { - *attempts += 1; - if *attempts < 3 { - Err(std::io::Error::from(ErrorKind::WouldBlock).into()) - } else { - Ok(()) - } - }, - |_| Ok(()), - ) - .unwrap(); - assert!(sent); - assert_eq!(attempts, 3); + // A full socket is not an error: nothing is sent and the caller tries again. + let receiver = rig.core.hub().sessions()[0].clone(); + assert!(!try_send(&mut rig.core.hub, &receiver, &marker_payload(1), true).unwrap()); + thread::sleep(Duration::from_millis(50)); + assert!(rig.relay.data().is_empty()); + assert!(try_send(&mut rig.core.hub, &receiver, &marker_payload(1), false).unwrap()); } #[test] -fn a_send_error_that_is_not_backpressure_is_an_error_not_a_dropped_group() { - let error = send_until( - &mut (), - Instant::now() + Duration::from_secs(1), - Instant::now, - |_| Err(anyhow::anyhow!("socket closed")), - |_| Ok(()), - ) - .unwrap_err(); - assert!(format!("{error:#}").contains("socket closed")); +fn a_blocked_group_is_abandoned_at_its_own_deadline_not_a_budget_after_it_was_dequeued() { + // A 2 s budget, but this group's deadline is 80 ms out: a deadline taken + // from the moment the group left the queue would hold it for two seconds. + let mut rig = rig(MEDIA_SEND_MAX_LATENCY_BUDGET_MS, 0, 1); + let started = Instant::now(); + let mut group = group_at( + MediaKind::Video, + started, + &rig.policy, + (1..=6).map(marker_payload).collect(), + ); + group.deadline = started + Duration::from_millis(80); + rig.core.enqueue(group); + assert!(rig.core.send_next(started).unwrap()); + + rig.core.socket_full.store(true, Ordering::Relaxed); + while rig.core.stats().groups_cut_short == 0 && started.elapsed() < Duration::from_secs(1) { + assert!(rig.core.send_next(Instant::now()).unwrap()); + } + + let elapsed = started.elapsed(); + assert_eq!(rig.core.stats().groups_cut_short, 1); + assert_eq!(rig.core.stats().groups_expired, 0); + assert_eq!(rig.core.stats().groups_sent, 0); + assert_eq!(rig.core.stats().payloads_sent, 1); + assert!( + elapsed >= Duration::from_millis(80), + "abandoned before its deadline, after {elapsed:?}" + ); + assert!( + elapsed < Duration::from_millis(500), + "held past its deadline, until {elapsed:?}" + ); + assert!(!rig.core.has_work()); +} + +#[test] +fn a_group_whose_deadline_passes_mid_send_is_cut_short_and_counted() { + let mut rig = rig(50, 0, 1); + rig.core.video_pacer = MuninnRudpMediaSendPacer::new(1, Duration::from_millis(20)); + let payloads: MuninnMediaPayloadGroup = (1..=6).map(marker_payload).collect(); + rig.core.enqueue(group_at( + MediaKind::Video, + Instant::now(), + &rig.policy, + payloads, + )); + + while rig.core.send_next(Instant::now()).unwrap() {} + + let stats = rig.core.stats().clone(); + assert_eq!(stats.groups_cut_short, 1); + assert_eq!((stats.groups_sent, stats.groups_expired), (0, 0)); + assert!( + (1..6).contains(&stats.payloads_sent), + "some but not all of the group went out: {}", + stats.payloads_sent + ); + assert!(wait_until(WAIT, || rig.relay.data().len() as u64 + == stats.payloads_sent)); + thread::sleep(Duration::from_millis(100)); + assert_eq!(rig.relay.data().len() as u64, stats.payloads_sent); + assert!(rig.core.progress_detail().contains("groups_cut_short=1")); +} + +// ---- priority: audio goes first, one payload at a time ------------------------------- + +#[test] +fn audio_that_arrives_mid_frame_goes_out_before_the_frames_next_payload() { + let mut rig = rig(2_000, 0, 1); + let t0 = Instant::now(); + let video = clip_groups() + .into_iter() + .max_by_key(|group| group.len()) + .unwrap(); + assert!(video.len() >= 6, "the clip has a large frame"); + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, video.clone())); + for _ in 0..3 { + assert!(rig.core.send_next(t0).unwrap()); + } + + // The audio comes in through the reader channel while the frame is half sent. + let (tx, rx) = media_intake_channel(); + tx.send(Ok(MediaIntake::Group(group_at( + MediaKind::Audio, + t0, + &rig.policy, + one_audio_group(), + )))) + .unwrap(); + rig.core.intake(&rx, Duration::ZERO).unwrap(); + drain(&mut rig.core, t0); + + // An audio packet is more than one datagram; it is all sent before the + // frame's next payload. + assert!(wait_until(WAIT, || { + rig.relay.video_frames_on_wire().len() == video.len() + && rig.relay.channels_on_wire().iter().any(|channel| channel == "audio") + })); + let channels = rig.relay.channels_on_wire(); + assert_eq!( + channels.iter().position(|channel| channel == "audio"), + Some(3), + "audio waited for exactly the payload already in progress: {channels:?}" + ); + let last_audio = channels.iter().rposition(|channel| channel == "audio").unwrap(); + assert!( + channels[3..=last_audio].iter().all(|channel| channel == "audio"), + "the audio packet went out whole before video resumed: {channels:?}" + ); + assert_eq!(rig.core.stats().groups_sent, 2); +} + +#[test] +fn a_full_socket_never_holds_audio_behind_video() { + let mut rig = rig(2_000, 0, 1); + let t0 = Instant::now(); + let video = clip_groups() + .into_iter() + .max_by_key(|group| group.len()) + .unwrap(); + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, video.clone())); + for _ in 0..2 { + assert!(rig.core.send_next(t0).unwrap()); + } + + rig.core.socket_full.store(true, Ordering::Relaxed); + rig.core.enqueue(group_at( + MediaKind::Audio, + t0, + &rig.policy, + one_audio_group(), + )); + for _ in 0..50 { + let step = Instant::now(); + assert!(rig.core.send_next(t0).unwrap()); + assert!( + step.elapsed() < Duration::from_millis(50), + "a blocked step must hand control back, not wait for the socket" + ); + } + thread::sleep(Duration::from_millis(100)); + assert_eq!(rig.relay.data().len(), 2, "nothing went out while it was full"); + + rig.core.socket_full.store(false, Ordering::Relaxed); + assert!(rig.core.send_next(t0).unwrap()); + assert!(wait_until(WAIT, || rig.relay.data().len() >= 3)); + assert_eq!(rig.relay.data()[2].channel, "audio"); + drain(&mut rig.core, t0); + assert_eq!(rig.core.stats().groups_sent, 2); +} + +#[test] +fn audio_goes_out_between_repair_payloads() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let (_, frame_id, frame_payloads) = send_repairable_frame(&mut rig, t0); + ask_for_chunks(&mut rig, frame_id, &[0, 1], t0, 1); + assert_eq!(rig.core.repairs.len(), 2); + + assert!(rig.core.send_next(t0).unwrap()); + rig.core.enqueue(group_at( + MediaKind::Audio, + t0, + &rig.policy, + one_audio_group(), + )); + drain(&mut rig.core, t0); + + assert!(wait_until(WAIT, || rig.relay.video_frames_on_wire().len() + == frame_payloads + 2)); + let channels = rig.relay.channels_on_wire(); + let tail = &channels[frame_payloads..]; + assert_eq!(tail.first().map(String::as_str), Some(MUNINN_MEDIA_RUDP_CHANNEL)); + assert_eq!(tail.last().map(String::as_str), Some(MUNINN_MEDIA_RUDP_CHANNEL)); + let audio = &tail[1..tail.len() - 1]; + assert!( + !audio.is_empty() && audio.iter().all(|channel| channel == "audio"), + "the audio packet went out between the two repairs: {tail:?}" + ); + assert_eq!(rig.core.feedback().repaired_video_chunks, 2); +} + +// ---- loss leaves a gap the receiver can see -------------------------------------------- + +#[test] +fn a_group_dropped_by_the_queue_cap_leaves_its_frame_id_missing_on_the_wire() { + let mut rig = rig(2_000, 0, 1); + let t0 = Instant::now(); + let over = 3; + let mut groups = synthetic_groups(1 + MEDIA_SEND_VIDEO_GROUP_CAP + over).into_iter(); + rig.core.enqueue(group_at( + MediaKind::Video, + t0, + &rig.policy, + groups.next().unwrap(), + )); + drain(&mut rig.core, t0); + for group in groups { + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, group)); + } + drain(&mut rig.core, t0); + + let expected: BTreeSet = std::iter::once(0) + .chain((1 + over as u64)..=(MEDIA_SEND_VIDEO_GROUP_CAP + over) as u64) + .collect(); + assert!(wait_until(WAIT, || rig.relay.frame_ids_on_wire() == expected)); + assert_eq!(rig.core.stats().groups_dropped_video, over as u64); + assert!(!rig.relay.frame_ids_on_wire().contains(&1), "frame 1 is the gap"); +} + +#[test] +fn an_expired_group_leaves_its_frame_id_missing_on_the_wire() { + let mut rig = rig(250, 0, 1); + let t0 = Instant::now(); + let budget = rig.policy.latency_budget; + let groups = synthetic_groups(3); + for (group, produced_at) in groups.into_iter().zip([t0 + 5 * budget, t0, t0 + 5 * budget]) { + rig.core + .enqueue(group_at(MediaKind::Video, produced_at, &rig.policy, group)); + } + + drain(&mut rig.core, t0 + 2 * budget); + + assert!(wait_until(WAIT, || rig.relay.frame_ids_on_wire() + == BTreeSet::from([0, 2]))); + assert_eq!(rig.core.stats().groups_expired, 1); +} + +#[test] +fn an_overflow_drop_leaves_its_frame_id_missing_and_no_partial_frame_on_the_wire() { + let mut rig = rig(2_000, 0, 1); + let mut config = video_config(); + config.max_pending_bytes = 16; + let start = [0, 0, 0, 1]; + let mut first = Vec::new(); + // Frame 0, whole; then the head of a frame that outgrows the ceiling. + first.extend_from_slice(&[&start[..], &[0x65, 0x80, 0xA1]].concat()); + first.extend_from_slice(&[&start[..], &[0x41, 0x80], &[0xB2; 30]].concat()); + let mut second = Vec::new(); + // Its second slice, then two whole frames. + second.extend_from_slice(&[&start[..], &[0x41, 0x40, 0xC3, 0xC3]].concat()); + second.extend_from_slice(&[&start[..], &[0x41, 0x80, 0xD4]].concat()); + second.extend_from_slice(&[&start[..], &[0x41, 0x80, 0xE5]].concat()); + let (tx, rx) = media_intake_channel(); + let reader = spawn_video_group_reader( + tx, + ChunkedReader([first, second].into()), + config, + rig.policy.clone(), + ); + + let started = Instant::now(); + while !rig.core.finished() && started.elapsed() < WAIT { + rig.core.intake(&rx, Duration::from_millis(2)).unwrap(); + drain(&mut rig.core, Instant::now()); + } + assert!(rig.core.finished()); + reader.join().unwrap(); + + assert!(wait_until(WAIT, || rig.relay.frame_ids_on_wire() + == BTreeSet::from([0, 2, 3]))); + assert_eq!(rig.core.stats().groups_dropped_video, 1); + assert_eq!(rig.core.stats().groups_sent, 3); } // ---- moved from the mux: repair budget, feedback intake, repair cache --------------- @@ -544,7 +844,13 @@ fn repair_cache_returns_recent_missing_video_chunks_with_their_frames_deadline() cache.remember(&payload, deadline).unwrap(); let repairs = cache.repair_payloads_for_feedback(&feedback, deadline); - assert_eq!(repairs, vec![(payload, deadline)]); + assert_eq!(repairs, vec![(payload.clone(), deadline)]); + assert!( + cache + .repair_payloads_for_feedback(&feedback, deadline + Duration::from_millis(1)) + .is_empty(), + "a chunk past its frame's deadline is not offered for repair" + ); } // ---- the wire: whole groups, repairs inside their frame's deadline ------------------ @@ -573,7 +879,7 @@ fn a_group_past_its_deadline_puts_nothing_on_the_wire_and_a_live_one_puts_all_of )); // Two budgets after the stale group was made, inside the live group's. - assert!(rig.core.send_next(t0 + 2 * budget).unwrap()); + drain(&mut rig.core, t0 + 2 * budget); assert_eq!(rig.core.stats().groups_expired, 1); assert_eq!(rig.core.stats().groups_sent, 1); @@ -604,8 +910,7 @@ fn audio_leaves_before_video_on_the_wire() { rig.core .enqueue(group_at(MediaKind::Audio, t0, &rig.policy, vec![audio])); - assert!(rig.core.send_next(t0).unwrap()); - assert!(rig.core.send_next(t0).unwrap()); + drain(&mut rig.core, t0); assert!(wait_until(WAIT, || !rig.relay.data().is_empty())); assert_eq!(rig.relay.data()[0].channel, "audio"); @@ -622,18 +927,27 @@ fn send_repairable_frame(rig: &mut Rig, t0: Instant) -> (Instant, u64, usize) { let queued = group_at(MediaKind::Video, t0, &rig.policy, group.clone()); let deadline = queued.deadline; rig.core.enqueue(queued); - assert!(rig.core.send_next(t0).unwrap()); + drain(&mut rig.core, t0); assert!(wait_until(WAIT, || rig.relay.video_frames_on_wire().len() == group.len())); (deadline, frame_id, group.len()) } +/// The receiver asks for chunks and the sender takes the request in at `at`. +/// Nothing is sent: that is the send step's job, at its own `now`. fn ask_for_chunk(rig: &mut Rig, frame_id: u64, at: Instant, records_seen: u64) { + ask_for_chunks(rig, frame_id, &[0], at, records_seen); +} + +fn ask_for_chunks(rig: &mut Rig, frame_id: u64, chunks: &[u16], at: Instant, records_seen: u64) { rig.client .send( MUNINN_MEDIA_RUDP_CHANNEL, feedback_wire(feedback_for( - vec![video_chunk_feedback_key(frame_id, 0)], + chunks + .iter() + .map(|chunk| video_chunk_feedback_key(frame_id, *chunk)) + .collect(), false, )), ) @@ -658,6 +972,7 @@ fn a_repair_is_sent_inside_its_frames_deadline_and_not_after_it() { let epsilon = Duration::from_millis(2); ask_for_chunk(&mut rig, frame_id, deadline - epsilon, 1); + drain(&mut rig.core, deadline - epsilon); assert!( wait_until(WAIT, || rig.relay.video_frames_on_wire().len() == frame_payloads + 1), @@ -666,6 +981,11 @@ fn a_repair_is_sent_inside_its_frames_deadline_and_not_after_it() { assert_eq!(rig.core.feedback().repaired_video_chunks, 1); ask_for_chunk(&mut rig, frame_id, deadline + epsilon, 2); + assert!( + rig.core.repairs.is_empty(), + "a chunk already past its frame's deadline is not queued" + ); + drain(&mut rig.core, deadline + epsilon); thread::sleep(Duration::from_millis(150)); assert_eq!( rig.relay.video_frames_on_wire().len(), @@ -676,6 +996,78 @@ fn a_repair_is_sent_inside_its_frames_deadline_and_not_after_it() { assert_eq!(rig.core.feedback().missing_video_chunks, 2); } +#[test] +fn a_queued_repair_is_dropped_if_its_frames_deadline_passes_before_it_is_sent() { + let t0 = Instant::now(); + let mut rig = rig(250, 0, 1); + let (deadline, frame_id, frame_payloads) = send_repairable_frame(&mut rig, t0); + let epsilon = Duration::from_millis(2); + + // Alive when the feedback is taken in, dead by the time it is sent. + ask_for_chunk(&mut rig, frame_id, deadline - epsilon, 1); + assert_eq!(rig.core.repairs.len(), 1); + drain(&mut rig.core, deadline + epsilon); + + thread::sleep(Duration::from_millis(150)); + assert_eq!(rig.relay.video_frames_on_wire().len(), frame_payloads); + assert_eq!(rig.core.feedback().repaired_video_chunks, 0); + assert!(rig.core.repairs.is_empty()); +} + +#[test] +fn a_repair_goes_only_to_the_receiver_that_asked_for_it() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let mut other = attach_direct_receiver(&mut rig); + let (_, frame_id, frame_payloads) = send_repairable_frame(&mut rig, t0); + let heard_by_other = |other: &mut CultNetRudpSocketTransportConnection| { + let mut heard = 0; + while let Some(frame) = other.receive_once().unwrap() { + heard += usize::from(frame_of(&frame.payload).is_some()); + } + heard + }; + let mut other_heard = 0; + assert!(wait_until(WAIT, || { + other_heard += heard_by_other(&mut other); + other_heard == frame_payloads + })); + + ask_for_chunk(&mut rig, frame_id, t0, 1); + drain(&mut rig.core, t0); + + assert!(wait_until(WAIT, || rig.relay.video_frames_on_wire().len() + == frame_payloads + 1)); + thread::sleep(Duration::from_millis(150)); + other_heard += heard_by_other(&mut other); + assert_eq!(other_heard, frame_payloads, "the repair was not for this receiver"); +} + +fn attach_direct_receiver(rig: &mut Rig) -> CultNetRudpSocketTransportConnection { + let socket = UdpSocket::bind("127.0.0.1:0").unwrap(); + socket.set_nonblocking(true).unwrap(); + let mut options = CultNetRudpSocketTransportOptions::client( + "harness-receiver-b", + socket, + rig.core.hub().local_addr().unwrap(), + crate::MUNINN_MEDIA_RUDP_CONNECTION_ID, + ); + options.media_delivery = Some(CultNetTransportDelivery::Unreliable); + options.max_fragment_bytes = Some(crate::MUNINN_RUDP_MEDIA_MAX_FRAGMENT_BYTES as u32); + let mut client = CultNetRudpSocketTransportConnection::new(options).unwrap(); + client.connect(b"harness-receiver-b".to_vec()).unwrap(); + assert!( + wait_until(WAIT, || { + rig.core.service_control(Instant::now()).unwrap(); + let _ = client.receive_once().unwrap(); + rig.client.receive_once().unwrap(); + client.connected() && rig.core.hub().sessions().len() == 2 + }), + "the second receiver never attached" + ); + client +} + // ---- the harness end to end: the fixture clip and the PCM ramp --------------------- #[derive(Default)] diff --git a/docs/muninn-media-streaming.md b/docs/muninn-media-streaming.md index c94ef67..e5689c6 100644 --- a/docs/muninn-media-streaming.md +++ b/docs/muninn-media-streaming.md @@ -258,7 +258,7 @@ Recommended first LAN profile: fragmentation. - Resend cadence: sender RUDP media resends are scheduled every `30` ms (`main.rs:94`) while the packet is still inside its expiry, which is the request's latency budget (a request that names none gets `250` ms, `main.rs:98`, and the advertisement offers the same as `default_latency_budget_ms`). -- Send queue: `media_send.rs` owns it. The unit is a group, one access unit with its parity or one audio packet, stamped `produced_at + latency budget` when the packetizer emits it. A group is sent whole or dropped whole at its deadline; queues are capped per kind (audio 256, video 512 groups) and drop the oldest group, counted as `groups_dropped_audio` and `groups_dropped_video`. A repair keeps the deadline of the frame it repairs and is not sent after it. +- Send queue: `media_send.rs` owns it. The unit is a group, one access unit with its parity or one audio packet, stamped `produced_at + latency budget` when the packetizer emits it. A request's latency budget is clamped to 1..=2000 ms. The send loop moves one payload per step and picks it afresh each time: audio, then repairs, then video, so audio never waits behind more than the payload in progress, full socket or not. The group deadline is checked before every payload; a group that outlives it mid-send is abandoned and counted `groups_cut_short`. Queues are capped per kind (audio 256, video 512 groups) and drop the oldest group, counted as `groups_dropped_audio` and `groups_dropped_video`. Every access unit the sender drops (queue cap, expiry, packetizer overflow) has already consumed its frame id, so the receiver sees a gap; an overflow also discards the dropped frame's remaining slices instead of emitting them as a frame. A repair keeps the deadline of the frame it repairs, goes only to the receiver that asked, and is not sent after that deadline. - Control: sender may adapt bitrate, keyframe cadence, chunk size, and playout budget from receiver feedback; the receiver must not silently stretch latency to preserve visual perfection. From ffc723c49fab24b748400d98c759b655125dfc3c Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 20:39:01 +0200 Subject: [PATCH 30/44] Leave the repair queue bounded by the repair budget alone The extra room cap on queued repairs had no test and no owner beyond the budget and the frame deadline, which already bound the queue. Co-Authored-By: Claude Opus 5.5 --- crates/muninn-daemon/src/media_send.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/muninn-daemon/src/media_send.rs b/crates/muninn-daemon/src/media_send.rs index b6b58f1..08ce12f 100644 --- a/crates/muninn-daemon/src/media_send.rs +++ b/crates/muninn-daemon/src/media_send.rs @@ -793,9 +793,8 @@ impl MediaSendCore { now, )?; let requested = repairs.len(); - let room = REPAIR_CACHE_CHUNKS.saturating_sub(self.repairs.len()); let allowed = self.repair_budget.take( - requested.min(REPAIR_MAX_CHUNKS_PER_POLL).min(room), + requested.min(REPAIR_MAX_CHUNKS_PER_POLL), now, self.stats.groups_lost(), ); @@ -806,7 +805,8 @@ impl MediaSendCore { .saturating_add(requested.saturating_sub(allowed) as u64); // Repairs are queued for the receiver that asked, not for // everyone; the send step sends each one inside the - // deadline of its own frame, after any waiting audio. + // deadline of its own frame, after any waiting audio. The + // queue is bounded by the repair budget times the deadline. self.repairs.extend( repairs .into_iter() From 772b2d00d3e3406a7011f7f47deced7bf55bb39c Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 20:50:10 +0200 Subject: [PATCH 31/44] Pin that the send loop is not finished while a frame or repair is in flight Co-Authored-By: Claude Opus 5.5 --- crates/muninn-daemon/src/media_send/tests.rs | 28 ++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/crates/muninn-daemon/src/media_send/tests.rs b/crates/muninn-daemon/src/media_send/tests.rs index a9083b0..491ed80 100644 --- a/crates/muninn-daemon/src/media_send/tests.rs +++ b/crates/muninn-daemon/src/media_send/tests.rs @@ -645,6 +645,34 @@ fn audio_goes_out_between_repair_payloads() { assert_eq!(rig.core.feedback().repaired_video_chunks, 2); } +#[test] +fn the_send_loop_is_not_finished_while_a_group_or_a_repair_is_still_going_out() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let (_, frame_id, _) = send_repairable_frame(&mut rig, t0); + rig.core.disconnected = true; + assert!(rig.core.finished(), "nothing left to send"); + + ask_for_chunk(&mut rig, frame_id, t0, 1); + assert!(!rig.core.finished(), "a repair is waiting"); + drain(&mut rig.core, t0); + assert!(rig.core.finished()); + + let group = clip_groups() + .into_iter() + .find(|group| group.len() > 2) + .unwrap(); + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, group)); + assert!(rig.core.send_next(t0).unwrap()); + assert!( + !rig.core.finished(), + "the queue is empty but the frame is half sent" + ); + drain(&mut rig.core, t0); + assert!(rig.core.finished()); +} + // ---- loss leaves a gap the receiver can see -------------------------------------------- #[test] From cbea798a270b322172bb5564d269a110e97732bb Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 21:17:25 +0200 Subject: [PATCH 32/44] Drop a departed receiver from the send loop, pin the untested rules, clamp the budget once A receiver that timed out or disconnected between payloads left a stale session in the in-flight group snapshot and in queued repairs; the next hub.send returned "Unknown RUDP server peer" and the mux restarted for every receiver. try_send now says whether the session still exists (address and generation) and reports ReceiverGone; the group drops that receiver, the repair queue drops that receiver's repairs, and every other hub error still propagates. Tests that fail under their mutation: the three departure shapes, audio expiry, a repair kept on a full socket, resends polled on a full socket, the loss-to-repair-budget wiring, and a leftover spanning two pushes. The latency budget is clamped by one function where a request or a command line is read, so the advertisement, telemetry and stream-equivalence check all see the clamped value. Co-Authored-By: Claude Opus 5.5 --- crates/muninn-daemon/src/main.rs | 58 +++- crates/muninn-daemon/src/media_packetizer.rs | 39 +++ crates/muninn-daemon/src/media_send.rs | 74 +++-- crates/muninn-daemon/src/media_send/tests.rs | 270 ++++++++++++++++++- 4 files changed, 413 insertions(+), 28 deletions(-) diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index 0b69938..78ee035 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -4,8 +4,8 @@ mod media_send; use crate::media_packetizer::{AudioPcmStreamSendConfig, VideoAnnexBStreamSendConfig}; use crate::media_send::{ - MediaSendCore, MediaSendPolicy, media_intake_channel, spawn_audio_group_reader, - spawn_video_group_reader, + MediaSendCore, MediaSendPolicy, clamp_latency_budget_ms, media_intake_channel, + spawn_audio_group_reader, spawn_video_group_reader, }; use anyhow::{Context, Result, anyhow}; use cultmesh_rs::{ @@ -935,7 +935,7 @@ fn command_from_media_stream_request( // below every `unix-` stamp and would lose to any command ever stored. updated_at: timestamp()?, rudp_video_bitrate_kbps: request.video_bitrate_kbps, - rudp_latency_budget_ms: request.latency_budget_ms, + rudp_latency_budget_ms: clamp_latency_budget_ms(request.latency_budget_ms), video_source_id: if request.video_source_id.is_empty() { MUNINN_DISABLED_VIDEO_SOURCE_ID.to_string() } else { @@ -9928,7 +9928,7 @@ impl Options { "--rudp-latency-budget-ms must be greater than zero" )); } - options.rudp_latency_budget_ms = latency_budget; + options.rudp_latency_budget_ms = clamp_latency_budget_ms(latency_budget); } "--width" => options.width = take_value(&mut args, "--width")?.parse()?, "--height" => options.height = take_value(&mut args, "--height")?.parse()?, @@ -11800,6 +11800,56 @@ mod tests { assert_eq!(command_rudp_latency_budget_ms(&command), 40); } + #[test] + fn a_latency_budget_above_the_maximum_is_2000_ms_wherever_it_is_read() { + // The request: the command it becomes carries the clamped budget, and + // it is the same stream as a request that asked for 2000. + let options = Options::parse(["serve"].into_iter().map(String::from)).unwrap(); + let mut request = media_stream_request(); + request.latency_budget_ms = 5_000; + let command = command_from_media_stream_request(&options, &request).unwrap(); + assert_eq!(command.rudp_latency_budget_ms, 2_000); + assert_eq!(command_rudp_latency_budget_ms(&command), 2_000); + request.latency_budget_ms = 2_000; + let at_maximum = command_from_media_stream_request(&options, &request).unwrap(); + assert!(capture_stream_commands_start_equivalent(&command, &at_maximum)); + + // The command line an activation is spawned with parses to the same + // clamped value, and so does a raw 5000 typed by an operator. + let store_path = + std::env::temp_dir().join(format!("muninn-clamp-{}.cc", timestamp_ns().unwrap())); + let options = Options::parse( + [ + "serve", + "--store", + store_path.to_str().unwrap(), + "--media-rudp-advertise", + "127.0.0.1:5220", + "--rudp-latency-budget-ms", + "5000", + ] + .into_iter() + .map(String::from), + ) + .unwrap(); + assert_eq!(options.rudp_latency_budget_ms, 2_000); + + // Advertised. + let advertisement = media_stream_advertisement(&options, false).unwrap(); + assert_eq!(advertisement.default_latency_budget_ms, 2_000); + + // Reported. + let mut node = open_node(&options, "muninn-clamp-test").unwrap(); + publish_runtime_boundary_records(&mut node, &options, "idle", &[], &[]).unwrap(); + let transport = node + .get_required::("transport-profile:muninn") + .unwrap(); + assert_eq!( + transport.value["media_profile"]["latency_budget_ms"].as_u64(), + Some(2_000) + ); + } + #[test] fn idle_surface_advertises_affordances_without_active_streams() { let options = Options::parse([].into_iter()).unwrap(); diff --git a/crates/muninn-daemon/src/media_packetizer.rs b/crates/muninn-daemon/src/media_packetizer.rs index cff3fb5..3462d05 100644 --- a/crates/muninn-daemon/src/media_packetizer.rs +++ b/crates/muninn-daemon/src/media_packetizer.rs @@ -1823,6 +1823,45 @@ mod tests { Ok(()) } + #[test] + fn a_leftover_spanning_two_pushes_is_discarded_whole() -> Result<()> { + let mut config = stream_send_config(); + config.max_pending_bytes = 16; + config.max_payload_bytes = 64; + let mut sender = VideoAnnexBStreamSendState::new(config)?; + let stored_at = "2026-06-18T00:00:00Z"; + let nal = |header: [u8; 2], filler: &[u8]| { + [&start_code()[..], &header[..], filler].concat() + }; + + let mut first = nal([0x65, 0x80], &[0xA1]); + first.extend(nal([0x41, 0x80], &[0xB2; 30])); + assert_eq!(sender.push(stored_at, &first)?.len(), 1); + assert_eq!(sender.dropped_access_units(), 1); + + // The dropped frame's second and third slices (first_mb_in_slice 1 + // and 3) arrive in separate pushes. Neither is a frame, and neither + // may come out as one. + assert!(sender.push(stored_at, &nal([0x41, 0x40], &[0xC3]))?.is_empty()); + assert!(sender.push(stored_at, &nal([0x41, 0x20], &[0xC4]))?.is_empty()); + assert_eq!(sender.next_frame_id(), 11); + + let mut next = nal([0x41, 0x80], &[0xD4]); + next.extend(nal([0x41, 0x80], &[0xE5])); + let mut groups = frames_of(&sender.push(stored_at, &next)?)?; + groups.extend(frames_of(&sender.finish(stored_at)?)?); + assert_eq!( + groups, + vec![ + (11, nal([0x41, 0x80], &[0xD4])), + (12, nal([0x41, 0x80], &[0xE5])), + ], + "both leftover slices went with the dropped frame" + ); + assert_eq!(sender.dropped_access_units(), 1); + Ok(()) + } + #[test] fn a_stream_that_resumes_on_a_frame_boundary_after_an_overflow_loses_nothing_more() -> Result<()> { let mut config = stream_send_config(); diff --git a/crates/muninn-daemon/src/media_send.rs b/crates/muninn-daemon/src/media_send.rs index 08ce12f..08ff860 100644 --- a/crates/muninn-daemon/src/media_send.rs +++ b/crates/muninn-daemon/src/media_send.rs @@ -50,6 +50,13 @@ pub const MEDIA_SEND_VIDEO_GROUP_CAP: usize = 512; /// The longest latency budget a request may claim (the old default). Above /// this the queues stop being bounded in time. pub const MEDIA_SEND_MAX_LATENCY_BUDGET_MS: u32 = 2_000; + +/// The one clamp on a requested latency budget. Everything that reads a budget +/// from a request or a command line passes it through here; nothing else +/// clamps. +pub fn clamp_latency_budget_ms(requested_ms: u32) -> u32 { + requested_ms.clamp(1, MEDIA_SEND_MAX_LATENCY_BUDGET_MS) +} /// Groups the reader threads may have handed over and the send loop not yet /// taken. Small on purpose: the caps above are where a backlog lives. pub const MEDIA_GROUP_CHANNEL_BOUND: usize = 8; @@ -86,9 +93,9 @@ pub struct MediaSendPolicy { impl MediaSendPolicy { pub fn from_request(latency_budget_ms: u32) -> Self { Self { - latency_budget: Duration::from_millis(u64::from( - latency_budget_ms.clamp(1, MEDIA_SEND_MAX_LATENCY_BUDGET_MS), - )), + latency_budget: Duration::from_millis(u64::from(clamp_latency_budget_ms( + latency_budget_ms, + ))), video_pace_every_payloads: SEND_PACE_EVERY_PAYLOADS, video_pace_sleep: Duration::from_micros(SEND_PACE_SLEEP_US), } @@ -449,27 +456,47 @@ pub fn is_would_block_error(error: &anyhow::Error) -> bool { }) } -/// One payload to one receiver, once. `false` means the socket is full: resends -/// are polled and the caller tries again on its next step, choosing again what -/// is most urgent. It never waits, so a full socket cannot hold a queued audio -/// packet behind video. +#[derive(Debug, PartialEq, Eq)] +enum SendOutcome { + Sent, + /// The socket is full: resends were polled, and the caller tries again on + /// its next step, choosing again what is most urgent. + SocketFull, + /// The session this send was addressed to no longer exists, or was + /// replaced by a newer generation. The receiver left; that is not an error. + ReceiverGone, +} + +/// Whether the hub still holds exactly the session `receiver` names. +fn receiver_is_live(hub: &CultNetRudpServerHub, receiver: &CultNetRudpServerSessionContext) -> bool { + hub.session(receiver.remote_addr) + .is_some_and(|live| live.session_generation == receiver.session_generation) +} + +/// One payload to one receiver, once. It never waits, so a full socket cannot +/// hold a queued audio packet behind video. A receiver that has left is +/// reported as gone, not as a failure: the send loop serves every receiver and +/// one leaving must not stop it. Every other hub error propagates. fn try_send( hub: &mut CultNetRudpServerHub, receiver: &CultNetRudpServerSessionContext, payload: &MuninnMediaSendPayload, socket_full: bool, -) -> Result { +) -> Result { + if !receiver_is_live(hub, receiver) { + return Ok(SendOutcome::ReceiverGone); + } let sent = if socket_full { Err(std::io::Error::from(ErrorKind::WouldBlock).into()) } else { hub.send(receiver, payload.channel_id, payload.payload.clone()) }; match sent { - Ok(()) => Ok(true), + Ok(()) => Ok(SendOutcome::Sent), Err(error) if is_would_block_error(&error) => { poll_resends(hub)?; thread::yield_now(); - Ok(false) + Ok(SendOutcome::SocketFull) } Err(error) => Err(error).context("sending typed Muninn media payload"), } @@ -691,10 +718,14 @@ impl MediaSendCore { if let Some(payload) = flight.group.payloads.get(flight.payload) { if let Some(receiver) = flight.receivers.get(flight.receiver) { - if !try_send(&mut self.hub, receiver, payload, socket_full)? { - return Ok(true); + match try_send(&mut self.hub, receiver, payload, socket_full)? { + SendOutcome::SocketFull => return Ok(true), + SendOutcome::Sent => flight.receiver += 1, + // Leaves the group; the next receiver slides into this slot. + SendOutcome::ReceiverGone => { + flight.receivers.remove(flight.receiver); + } } - flight.receiver += 1; if flight.receiver < flight.receivers.len() { return Ok(true); } @@ -732,11 +763,18 @@ impl MediaSendCore { self.repairs.pop_front(); continue; } - if try_send(&mut self.hub, &repair.receiver, &repair.payload, socket_full)? { - self.repairs.pop_front(); - self.feedback.repaired_video_chunks = - self.feedback.repaired_video_chunks.saturating_add(1); - self.video_pacer.observe_sent_payload(); + match try_send(&mut self.hub, &repair.receiver, &repair.payload, socket_full)? { + SendOutcome::Sent => { + self.repairs.pop_front(); + self.feedback.repaired_video_chunks = + self.feedback.repaired_video_chunks.saturating_add(1); + self.video_pacer.observe_sent_payload(); + } + SendOutcome::SocketFull => {} + SendOutcome::ReceiverGone => { + let gone = repair.receiver.clone(); + self.repairs.retain(|queued| queued.receiver != gone); + } } return Ok(true); } diff --git a/crates/muninn-daemon/src/media_send/tests.rs b/crates/muninn-daemon/src/media_send/tests.rs index 491ed80..873afd2 100644 --- a/crates/muninn-daemon/src/media_send/tests.rs +++ b/crates/muninn-daemon/src/media_send/tests.rs @@ -445,18 +445,172 @@ fn a_full_socket_is_recognised_and_any_other_send_error_is_an_error() { assert!(!is_would_block_error(&anyhow::anyhow!("socket closed"))); let mut rig = rig(250, 0, 1); - let mut stranger = rig.core.hub().sessions()[0].clone(); - stranger.remote_addr = "127.0.0.1:9".parse().unwrap(); - let error = try_send(&mut rig.core.hub, &stranger, &marker_payload(1), false).unwrap_err(); + + // A live receiver and a payload the hub refuses is an error. + let receiver = rig.core.hub().sessions()[0].clone(); + let oversize = MuninnMediaSendPayload { + channel_id: MUNINN_MEDIA_RUDP_CHANNEL, + payload: vec![0; 17 * 1024 * 1024], + }; + let error = try_send(&mut rig.core.hub, &receiver, &oversize, false).unwrap_err(); assert!(!is_would_block_error(&error)); assert!(format!("{error:#}").contains("sending typed Muninn media payload")); // A full socket is not an error: nothing is sent and the caller tries again. - let receiver = rig.core.hub().sessions()[0].clone(); - assert!(!try_send(&mut rig.core.hub, &receiver, &marker_payload(1), true).unwrap()); + assert_eq!( + try_send(&mut rig.core.hub, &receiver, &marker_payload(1), true).unwrap(), + SendOutcome::SocketFull + ); thread::sleep(Duration::from_millis(50)); assert!(rig.relay.data().is_empty()); - assert!(try_send(&mut rig.core.hub, &receiver, &marker_payload(1), false).unwrap()); + assert_eq!( + try_send(&mut rig.core.hub, &receiver, &marker_payload(1), false).unwrap(), + SendOutcome::Sent + ); +} + +#[test] +fn a_receiver_that_is_gone_is_not_an_error_whether_it_left_or_was_replaced() { + let mut rig = rig(250, 0, 1); + let receiver = rig.core.hub().sessions()[0].clone(); + + // Never a session at that endpoint. + let mut stranger = receiver.clone(); + stranger.remote_addr = "127.0.0.1:9".parse().unwrap(); + assert_eq!( + try_send(&mut rig.core.hub, &stranger, &marker_payload(1), false).unwrap(), + SendOutcome::ReceiverGone + ); + + // A session at the endpoint, but not the generation this send was made for. + let mut older = receiver.clone(); + older.session_generation -= 1; + assert_eq!( + try_send(&mut rig.core.hub, &older, &marker_payload(1), false).unwrap(), + SendOutcome::ReceiverGone + ); + + // A session that was live and has left, even with the socket reporting full. + assert!(rig.core.hub.disconnect(&receiver, b"left".to_vec()).unwrap()); + for socket_full in [false, true] { + assert_eq!( + try_send(&mut rig.core.hub, &receiver, &marker_payload(1), socket_full).unwrap(), + SendOutcome::ReceiverGone + ); + } +} + +fn session_named(core: &MediaSendCore, name: &str) -> CultNetRudpServerSessionContext { + core.hub() + .sessions() + .into_iter() + .find(|session| session.connect_payload == name.as_bytes()) + .unwrap_or_else(|| panic!("no session named {name}")) +} + +/// How many video payloads `receiver` has been sent so far. +fn video_heard_by(receiver: &mut CultNetRudpSocketTransportConnection) -> usize { + let mut heard = 0; + while let Some(frame) = receiver.receive_once().unwrap() { + heard += usize::from(frame_of(&frame.payload).is_some()); + } + heard +} + +#[test] +fn the_only_receiver_leaving_mid_frame_ends_the_frame_without_an_error() { + let mut rig = rig(2_000, 0, 1); + let t0 = Instant::now(); + let group = clip_groups() + .into_iter() + .find(|group| group.len() > 3) + .unwrap(); + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, group)); + for _ in 0..2 { + assert!(rig.core.send_next(t0).unwrap()); + } + + let receiver = session_named(&rig.core, "harness-receiver"); + assert!(rig.core.hub.disconnect(&receiver, b"left".to_vec()).unwrap()); + drain(&mut rig.core, t0); + + assert!(!rig.core.has_work()); + assert_eq!(rig.core.stats().groups_sent, 1); + assert_eq!(rig.core.stats().groups_lost(), 0); +} + +#[test] +fn a_receiver_that_asked_for_repairs_and_left_takes_its_queued_repairs_with_it() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let mut other = attach_direct_receiver(&mut rig); + let (_, frame_id, frame_payloads) = send_repairable_frame(&mut rig, t0); + ask_for_chunks(&mut rig, frame_id, &[0, 1], t0, 1); + other + .send( + MUNINN_MEDIA_RUDP_CHANNEL, + feedback_wire(feedback_for( + vec![video_chunk_feedback_key(frame_id, 0)], + false, + )), + ) + .unwrap(); + assert!(wait_until(WAIT, || { + rig.core.service_control(t0).unwrap(); + rig.core.feedback().feedback_records == 2 + })); + assert_eq!(rig.core.repairs.len(), 3); + let asker = session_named(&rig.core, "harness-receiver"); + assert!(rig.core.hub.disconnect(&asker, b"left".to_vec()).unwrap()); + + drain(&mut rig.core, t0); + + assert!(rig.core.repairs.is_empty()); + assert_eq!( + rig.core.feedback().repaired_video_chunks, + 1, + "only the receiver still attached was repaired" + ); + let mut heard = 0; + assert!(wait_until(WAIT, || { + heard += video_heard_by(&mut other); + heard == frame_payloads + 1 + })); +} + +#[test] +fn a_receiver_leaving_mid_frame_does_not_stop_the_other_receivers_stream() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let mut other = attach_direct_receiver(&mut rig); + let group = clip_groups() + .into_iter() + .find(|group| group.len() > 3) + .unwrap(); + let expected = group.len() * 2; + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, group.clone())); + for _ in 0..3 { + assert!(rig.core.send_next(t0).unwrap()); + } + + let leaver = session_named(&rig.core, "harness-receiver"); + assert!(rig.core.hub.disconnect(&leaver, b"left".to_vec()).unwrap()); + rig.core + .enqueue(group_at(MediaKind::Video, t0, &rig.policy, group)); + drain(&mut rig.core, t0); + + assert_eq!(rig.core.stats().groups_sent, 2); + assert_eq!(rig.core.stats().groups_lost(), 0); + let mut heard = 0; + assert!( + wait_until(WAIT, || { + heard += video_heard_by(&mut other); + heard == expected + }), + "the receiver that stayed heard {heard} of {expected} payloads" + ); } #[test] @@ -1263,3 +1417,107 @@ fn an_oversize_access_unit_reaches_the_sender_as_a_dropped_video_group_not_an_er assert_eq!(core.stats().groups_dropped_video, 1); assert!(core.finished(), "the stream ended cleanly, it was not restarted by an error"); } + +// ---- the rules each get a test that fails without them -------------------------------- + +#[test] +fn an_audio_group_past_its_deadline_is_dropped_and_counted_like_a_video_group() { + let mut rig = rig(250, 0, 1); + let t0 = Instant::now(); + let budget = rig.policy.latency_budget; + rig.core.enqueue(group_at( + MediaKind::Audio, + t0, + &rig.policy, + one_audio_group(), + )); + + drain(&mut rig.core, t0 + 2 * budget); + + assert_eq!(rig.core.stats().groups_expired, 1); + assert_eq!(rig.core.stats().groups_sent, 0); + thread::sleep(Duration::from_millis(100)); + assert!(rig.relay.data().is_empty(), "stale audio reached the wire"); +} + +#[test] +fn a_repair_waiting_on_a_full_socket_stays_queued_and_goes_out_when_it_clears() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let (_, frame_id, frame_payloads) = send_repairable_frame(&mut rig, t0); + ask_for_chunk(&mut rig, frame_id, t0, 1); + assert_eq!(rig.core.repairs.len(), 1); + + rig.core.socket_full.store(true, Ordering::Relaxed); + for _ in 0..5 { + assert!(rig.core.send_next(t0).unwrap()); + } + assert_eq!(rig.core.repairs.len(), 1, "the repair was popped unsent"); + assert_eq!(rig.core.feedback().repaired_video_chunks, 0); + + rig.core.socket_full.store(false, Ordering::Relaxed); + drain(&mut rig.core, t0); + assert!(rig.core.repairs.is_empty()); + assert_eq!(rig.core.feedback().repaired_video_chunks, 1); + assert!(wait_until(WAIT, || rig.relay.video_frames_on_wire().len() + == frame_payloads + 1)); +} + +#[test] +fn a_full_socket_still_polls_resends() { + // Every datagram is dropped, so the audio packets stay unacknowledged and + // the hub owes them a resend. + let mut rig = rig(2_000, 100, 1); + let t0 = Instant::now(); + rig.core.enqueue(group_at( + MediaKind::Audio, + t0, + &rig.policy, + one_audio_group(), + )); + drain(&mut rig.core, t0); + assert!(wait_until(WAIT, || !rig.relay.data().is_empty())); + thread::sleep(Duration::from_millis(50)); + let first_pass = rig.relay.data().len(); + + // Only the full-socket path runs here: no service_control, no other poll. + rig.core.enqueue(group_at( + MediaKind::Video, + t0, + &rig.policy, + vec![marker_payload(1)], + )); + rig.core.socket_full.store(true, Ordering::Relaxed); + let started = Instant::now(); + while started.elapsed() < Duration::from_millis(300) { + assert!(rig.core.send_next(t0).unwrap()); + thread::sleep(Duration::from_millis(5)); + } + + assert!( + wait_until(WAIT, || rig.relay.data().len() > first_pass), + "no resend went out while the socket was full" + ); +} + +#[test] +fn losing_groups_slows_the_repair_budget() { + let t0 = Instant::now(); + let mut rig = rig(2_000, 0, 1); + let (_, frame_id, _) = send_repairable_frame(&mut rig, t0); + + // One group is lost at the sender: it dies before it is sent. + let mut doomed = group_at(MediaKind::Audio, t0, &rig.policy, one_audio_group()); + doomed.deadline = t0; + rig.core.enqueue(doomed); + drain(&mut rig.core, t0 + Duration::from_millis(1)); + assert_eq!(rig.core.stats().groups_lost(), 1); + + ask_for_chunk(&mut rig, frame_id, t0, 1); + + assert_eq!( + rig.core.feedback().repair_chunks_per_second, + REPAIR_INITIAL_CHUNKS_PER_SECOND / 2, + "the budget did not see the loss" + ); +} From 45e2904943487d4b6319d4432c4d3a7f3d8eb02b Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 21:18:29 +0200 Subject: [PATCH 33/44] Clamp the command's budget where the command is read, not where the request is copied A request naming no budget stores 0 and means the 250 ms default; clamping at the copy turned 0 into 1 ms. The command accessor already owns 0-means-default, so it owns the clamp too: compare, spawn arguments and logs read through it. Co-Authored-By: Claude Opus 5.5 --- crates/muninn-daemon/src/main.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index 78ee035..48d02fd 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -935,7 +935,7 @@ fn command_from_media_stream_request( // below every `unix-` stamp and would lose to any command ever stored. updated_at: timestamp()?, rudp_video_bitrate_kbps: request.video_bitrate_kbps, - rudp_latency_budget_ms: clamp_latency_budget_ms(request.latency_budget_ms), + rudp_latency_budget_ms: request.latency_budget_ms, video_source_id: if request.video_source_id.is_empty() { MUNINN_DISABLED_VIDEO_SOURCE_ID.to_string() } else { @@ -1475,7 +1475,7 @@ fn command_rudp_latency_budget_ms(command: &MuninnCaptureStreamCommandRecord) -> if command.rudp_latency_budget_ms == 0 { MUNINN_RUDP_MEDIA_DEFAULT_LATENCY_BUDGET_MS as u32 } else { - command.rudp_latency_budget_ms + clamp_latency_budget_ms(command.rudp_latency_budget_ms) } } @@ -11802,13 +11802,12 @@ mod tests { #[test] fn a_latency_budget_above_the_maximum_is_2000_ms_wherever_it_is_read() { - // The request: the command it becomes carries the clamped budget, and + // The request: the command reads back the clamped budget, and // it is the same stream as a request that asked for 2000. let options = Options::parse(["serve"].into_iter().map(String::from)).unwrap(); let mut request = media_stream_request(); request.latency_budget_ms = 5_000; let command = command_from_media_stream_request(&options, &request).unwrap(); - assert_eq!(command.rudp_latency_budget_ms, 2_000); assert_eq!(command_rudp_latency_budget_ms(&command), 2_000); request.latency_budget_ms = 2_000; let at_maximum = command_from_media_stream_request(&options, &request).unwrap(); From e9580009ea30623772b56925f0921247a5641edc Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 23:17:13 +0200 Subject: [PATCH 34/44] Retire --idunn-rudp-health and the daemon-health publisher The flag family (--idunn-rudp-health, --idunn-daemon, --idunn-health-contract), IdunnRudpHealthOptions, the health worker thread, idunn_health_payload, the RUDP health connection and the idunn.daemon_health document had no consumer since the previous Idunn generation. The raven-muninn recipe never passed them; liveness is the runtime-presence publisher. Removes the IdunnDaemonHealthRecord odin-core symbol (three remain). The daemon id is now derived from the host alone. The transport profile and command-boundary records no longer carry health_publication, and health_contract is null. The starfire, nightwing and raven health and restart scripts stop passing and checking the flags; muninn.md follows. Tests: the retired flags are unknown arguments; the boundary record carries the host-derived daemon id and no health_publication. Co-Authored-By: Claude Opus 5.5 --- crates/muninn-daemon/src/main.rs | 354 +++------------------------ docs/muninn.md | 22 +- docs/teardown-map.md | 9 +- scripts/health-muninn.ps1 | 10 +- scripts/health-nightwing-muninn.ps1 | 17 +- scripts/health-starfire-muninn.ps1 | 16 +- scripts/restart-nightwing-muninn.ps1 | 17 +- scripts/restart-starfire-muninn.ps1 | 23 +- 8 files changed, 42 insertions(+), 426 deletions(-) diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index 48d02fd..b28e042 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -21,12 +21,12 @@ use cultnet_rs::{ GAMECULT_MEDIA_STREAM_REQUEST_SCHEMA, GAMECULT_RUNTIME_PRESENCE_HEALTH_SCHEMA, GameCultMediaStreamAdvertisementRecord, GameCultMediaStreamRequestRecord, GameCultRuntimePresenceHealthRecord, decode_cultnet_message_from_slice, - encode_cultnet_message_to_vec, media_stream_request_key, validate_media_stream_request, + media_stream_request_key, validate_media_stream_request, }; #[cfg(feature = "psmoveapi-tracker")] use odin_core::MuninnMoveTrackerHealthRecord; use odin_core::{ - EveProviderAdvertisementRecord, EveSurfaceStateRecord, IdunnDaemonHealthRecord, + EveProviderAdvertisementRecord, EveSurfaceStateRecord, MUNINN_MOVE_HUE_PROGRAM_SCHEMA, MUNINN_OBS_STREAM_CATALOG_SCHEMA, MuninnCaptureStreamCommandRecord, MuninnCaptureStreamRecord, MuninnCommandBoundaryCompatRecord, MuninnHidControllerStateRecord, MuninnMoveControllerStateRecord, @@ -70,7 +70,6 @@ use std::os::windows::ffi::OsStrExt; use windows_sys::Win32::UI::Input::XboxController::{XINPUT_GAMEPAD, XINPUT_STATE, XInputGetState}; const CULTNET_RUDP_PROTOCOL_ID: &str = "cultnet.transport.rudp.v0"; -const IDUNN_HEALTH_RUDP_CONNECTION_ID: u32 = 0x1d0d_0001; const MUNINN_MEDIA_RUDP_CONNECTION_ID: u32 = 0x6d75_0001; const MUNINN_HID_CONTROLLER_RUDP_CONNECTION_ID: u32 = 0x6d75_0005; const MUNINN_COMMAND_RUDP_CONNECTION_ID: u32 = 0x61e0_0001; @@ -214,7 +213,6 @@ struct Options { quest_input_stream_id: Option, quest_pose_stream_id: Option, quest_video_input_stream_id: Option, - idunn_rudp_health: Option, odin_cultmesh_uri: Option, hid_controller_rudp_target: Option, hid_controller_rudp_bind: Option, @@ -275,13 +273,6 @@ struct MoveStateSource { hidraw_path: String, } -#[derive(Clone, Debug, PartialEq, Eq)] -struct IdunnRudpHealthOptions { - endpoint: SocketAddr, - daemon_id: String, - health_contract: String, -} - #[derive(Clone, Debug, PartialEq, Eq)] struct MuxPlan { command_line: String, @@ -406,7 +397,6 @@ fn serve(options: Options) -> Result<()> { let move_runtime_enabled = serve_should_manage_move_runtime(&options); let mut active_move_states = active_move_state_sources(serve_move_state_sources(&options, move_runtime_enabled)); - start_daemon_health_worker(&options); start_idunn_presence_worker(&options); let mut active_move_marker_cameras = active_move_marker_camera_sources(&options, Arc::clone(&move_hue_program)); @@ -613,21 +603,6 @@ fn start_idunn_presence_worker(options: &Options) { }); } -fn start_daemon_health_worker(options: &Options) { - if options.idunn_rudp_health.is_none() { - return; - } - let options = options.clone(); - thread::spawn(move || { - loop { - if let Err(error) = run_daemon_health_publisher(&options) { - eprintln!("Muninn Idunn health publish failed: {error:#}"); - } - thread::sleep(Duration::from_secs(5)); - } - }); -} - fn move_hue_program_key(host_id: &str) -> String { format!("muninn:{host_id}:move-hue-program") } @@ -2846,16 +2821,8 @@ fn publish_runtime_boundary_records( .as_ref() .map(|command| json!([command])) .unwrap_or_else(|| json!([])); - let current_transport = if options.idunn_rudp_health.is_some() { - "daemon-published-rudp-health + daemon-owned-cultcache-telemetry-store" - } else { - "daemon-owned-cultcache-telemetry-store + missing-rudp-health-publication" - }; - let transport_state = if options.idunn_rudp_health.is_some() { - "rudp-health-and-provider-store-live" - } else { - "cultcache-provider-store-only" - }; + let current_transport = "daemon-owned-cultcache-telemetry-store"; + let transport_state = "cultcache-provider-store-only"; let hid_controller_endpoint = options.hid_controller_rudp_bind.map(|bind| { options .hid_controller_rudp_advertise @@ -2994,18 +2961,6 @@ fn publish_runtime_boundary_records( "state_store": store_path, "log_root": log_root, "lifecycle_authority": "idunn-supervisor-command", - "health_publication": options.idunn_rudp_health.as_ref().map(|idunn| json!({ - "contract": idunn.health_contract, - "transport": CULTNET_RUDP_PROTOCOL_ID, - "publication_source": "daemon-published", - "endpoint": idunn.endpoint.to_string(), - "state_owner": "Muninn serve process" - })).unwrap_or_else(|| json!({ - "contract": serde_json::Value::Null, - "transport": "unconfigured", - "publication_source": "missing-daemon-publication", - "state_owner": "Muninn local store" - })), "commands": [ { "command": "muninn.capture_stream_command", @@ -3053,7 +3008,7 @@ fn publish_runtime_boundary_records( "target_transport": CULTNET_RUDP_PROTOCOL_ID, "current_transport": current_transport, "state": transport_state, - "health_contract": options.idunn_rudp_health.as_ref().map(|idunn| idunn.health_contract.clone()), + "health_contract": serde_json::Value::Null, "provider_advertisement_schema": "gamecult.eve.provider_advertisement.v1", "command_boundary_schema": "muninn.command_boundary.v1", "telemetry_surface_schema": "muninn.telemetry_surface.v1", @@ -3191,9 +3146,6 @@ fn muninn_provider_id(options: &Options) -> String { } fn muninn_daemon_id(options: &Options) -> String { - if let Some(idunn) = options.idunn_rudp_health.as_ref() { - return idunn.daemon_id.clone(); - } match options.host_id.as_str() { "raven" => "muninn".to_string(), "starfire" => "starfire-muninn".to_string(), @@ -8604,18 +8556,6 @@ fn health_check(options: &Options) -> Result<()> { Ok(detail) => ("active", detail.clone()), Err(error) => ("failed", error.to_string()), }; - if let Some(idunn) = options.idunn_rudp_health.as_ref() { - let publish_result = publish_idunn_rudp_health(idunn, state, &detail, &observed_at); - if let Err(publish_error) = publish_result { - return match result { - Ok(_) => Err(publish_error).context("publishing Muninn health to Idunn RUDP"), - Err(health_error) => Err(anyhow!( - "{health_error}; also failed to publish Muninn health to Idunn RUDP: {publish_error}" - )), - }; - } - } - match result { Ok(detail) => { println!("{detail}"); @@ -8674,22 +8614,6 @@ fn evaluate_health_from_node( )) } -fn publish_idunn_rudp_health( - options: &IdunnRudpHealthOptions, - state: &str, - detail: &str, - observed_at: &str, -) -> Result<()> { - let mut transport = connect_idunn_rudp_health(options)?; - transport - .send( - "schema", - idunn_health_payload(options, state, detail, observed_at)?, - ) - .with_context(|| format!("sending Idunn health to {}", options.endpoint))?; - Ok(()) -} - fn smootherstep(value: f64) -> f64 { let t = value.clamp(0.0, 1.0); t * t * t * (t * (t * 6.0 - 15.0) + 10.0) @@ -8700,104 +8624,6 @@ fn wrapped_hue_lerp(source: f64, target: f64, amount: f64) -> f64 { (source + delta * amount).rem_euclid(1.0) } -fn run_daemon_health_publisher(options: &Options) -> Result<()> { - let idunn = options - .idunn_rudp_health - .as_ref() - .context("Muninn daemon health publisher requires Idunn RUDP options")?; - let mut transport = connect_idunn_rudp_health(idunn)?; - let cadence = Duration::from_secs(options.interval_seconds.unwrap_or(15).max(1)); - let mut next_publish_at = Instant::now(); - loop { - if Instant::now() >= next_publish_at { - let observed_at = idunn_timestamp()?; - let (state, detail) = match evaluate_health(options) { - Ok(detail) => ("active", detail), - Err(error) => ("failed", error.to_string()), - }; - transport - .send( - "schema", - idunn_health_payload(idunn, state, &detail, &observed_at)?, - ) - .with_context(|| format!("sending Idunn health to {}", idunn.endpoint))?; - next_publish_at = Instant::now() + cadence; - } - let _ = transport.receive_once()?; - transport.poll_resends()?; - } -} - -fn idunn_health_payload( - options: &IdunnRudpHealthOptions, - state: &str, - detail: &str, - observed_at: &str, -) -> Result> { - let health = IdunnDaemonHealthRecord { - daemon_id: options.daemon_id.clone(), - state: state.to_string(), - detail: detail.to_string(), - observed_at: observed_at.to_string(), - health_contract: options.health_contract.clone(), - publication_source: "daemon-published".to_string(), - transport: CULTNET_RUDP_PROTOCOL_ID.to_string(), - }; - let message = CultNetMessage::DocumentPutRaw { - message_id: format!( - "muninn-health:{}:{}", - options.daemon_id, - observed_at.replace(':', "-") - ), - document: CultNetRawDocumentRecord { - schema_id: "idunn.daemon_health".to_string(), - record_key: options.daemon_id.clone(), - stored_at: observed_at.to_string(), - payload_encoding: CultNetRawPayloadEncoding::Messagepack, - payload: rmp_serde::to_vec(&health).context("encoding Idunn daemon health")?, - source_runtime_id: Some("muninn-daemon".to_string()), - source_agent_id: None, - source_role: Some("daemon-health-publisher".to_string()), - tags: Some(vec![CULTNET_RUDP_PROTOCOL_ID.to_string()]), - }, - }; - encode_cultnet_message_to_vec(&message, CultNetWireContract::CultNetSchemaV0) - .context("encoding Idunn health CultNet message") -} - -fn connect_idunn_rudp_health( - options: &IdunnRudpHealthOptions, -) -> Result { - let bind_address = if options.endpoint.is_ipv4() { - "0.0.0.0:0" - } else { - "[::]:0" - }; - let socket = UdpSocket::bind(bind_address) - .with_context(|| format!("binding Muninn RUDP sender at {bind_address}"))?; - socket.set_read_timeout(Some(Duration::from_secs(1)))?; - let mut transport = - CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions::client( - "muninn-daemon", - socket, - options.endpoint, - IDUNN_HEALTH_RUDP_CONNECTION_ID, - ))?; - transport.connect(Vec::new())?; - let deadline = Instant::now() + Duration::from_secs(2); - while !transport.connected() { - let _ = transport.receive_once()?; - transport.poll_resends()?; - if Instant::now() >= deadline { - return Err(anyhow!( - "timed out connecting Muninn RUDP sender to {}", - options.endpoint - )); - } - } - Ok(transport) -} - fn verify_move_sources_fresh(options: &Options, node: &cultmesh_rs::CultMeshNode) -> Result<()> { let move_state_sources = serve_move_state_sources(options, serve_should_manage_move_runtime(options)); @@ -9837,7 +9663,6 @@ impl Options { quest_input_stream_id: None, quest_pose_stream_id: None, quest_video_input_stream_id: None, - idunn_rudp_health: None, odin_cultmesh_uri: Some("cultmesh://odin/rendezvous/provider-catalog".to_string()), hid_controller_rudp_target: None, hid_controller_rudp_bind: None, @@ -9848,9 +9673,6 @@ impl Options { }; let mut args = args.peekable(); - let mut idunn_rudp_health_endpoint = None; - let mut idunn_daemon_id = None; - let mut idunn_health_contract = None; while let Some(arg) = args.next() { match arg.as_str() { "serve" => options.mode = Mode::Serve, @@ -10087,19 +9909,6 @@ impl Options { options.quest_video_input_stream_id = Some(take_value(&mut args, "--quest-video-input-stream")?) } - "--idunn-rudp-health" => { - idunn_rudp_health_endpoint = Some( - take_value(&mut args, "--idunn-rudp-health")? - .parse() - .context("--idunn-rudp-health must be a socket address")?, - ) - } - "--idunn-daemon" => { - idunn_daemon_id = Some(take_value(&mut args, "--idunn-daemon")?) - } - "--idunn-health-contract" => { - idunn_health_contract = Some(take_value(&mut args, "--idunn-health-contract")?) - } "--odin-cultmesh-rudp" => { let _ = take_value(&mut args, "--odin-cultmesh-rudp")?; return Err(anyhow!( @@ -10287,32 +10096,11 @@ impl Options { options.quest_video_input_stream_id.as_ref(), ), ("--move-host", options.move_host_address.as_ref()), - ("--idunn-daemon", idunn_daemon_id.as_ref()), - ("--idunn-health-contract", idunn_health_contract.as_ref()), ] { if value.is_some_and(|value| value.trim().is_empty()) { return Err(anyhow!("{name} must be non-empty")); } } - options.idunn_rudp_health = match ( - idunn_rudp_health_endpoint, - idunn_daemon_id, - idunn_health_contract, - ) { - (None, None, None) => None, - (Some(endpoint), Some(daemon_id), Some(health_contract)) => { - Some(IdunnRudpHealthOptions { - endpoint, - daemon_id, - health_contract, - }) - } - _ => { - return Err(anyhow!( - "--idunn-rudp-health, --idunn-daemon, and --idunn-health-contract must be provided together" - )); - } - }; Ok(options) } } @@ -10330,14 +10118,6 @@ fn timestamp() -> Result { Ok(format!("unix-{seconds}")) } -fn idunn_timestamp() -> Result { - let seconds = SystemTime::now() - .duration_since(UNIX_EPOCH) - .context("system clock is before Unix epoch")? - .as_secs(); - Ok(format!("unix:{seconds}")) -} - fn timestamp_ns() -> Result { let nanos = SystemTime::now() .duration_since(UNIX_EPOCH) @@ -10406,7 +10186,7 @@ fn parse_move_marker_camera_source(value: &str) -> Result &'static str { - "Usage: muninn [serve|activate|request-stream|capture-stream-status|obs-catalog-status|request-move-light|move-light-status|move-identity-status|move-source-status|move-state-status|claim-move-host|quest-access-status] [--store ] [--activate-store ] [--stream-action ] [--target-host ] [--media-transport ] [--media-rudp-bind ] [--media-rudp-advertise ] [--media-packet-bytes ] [--rudp-video-bitrate-kbps ] [--rudp-latency-budget-ms ] [--video-source ] [--audio-source ] [--audio-source-id ] [--no-video] [--no-audio] [--loopback-script ] [--ffmpeg ] [--odin-cultmesh-uri ] [--move-state =] [--move-marker-camera =] [--move-psmoveapi-tracker] [--move-tracker-exposure-milli <0..1000>] [--move-marker-width ] [--move-marker-height ] [--move-marker-fps ] [--move-host ] [--move-evidence-stream ] [--move-evidence-verse ] [--move-evidence-ring-slots ] [--move-evidence-slot-bytes ] [--move-evidence-snapshot ] [--quest-adb] [--quest-serial ] [--quest-input-stream ] [--quest-pose-stream ] [--quest-video-input-stream ] [--idunn-rudp-health ] [--idunn-daemon ] [--idunn-health-contract ] [--dry-run] [--health]\n\nMuninn is Odin's portable telemetry Verse assembler. serve publishes cheap typed telemetry affordances, optional Quest USB access surfaces, and the explicitly configured Move runtime; when serve receives --move-state, --move-marker-camera, --move-host, or --move-evidence-stream it may publish source-local Move controller state, source-local optical marker candidates, typed Move identity records, a CultMesh Move evidence stream, optionally write a latest one-copy Move proof evidence snapshot for Mimir field capture/replay, and keep USB-attached PS Moves claimed to that explicit Bluetooth host; --move-psmoveapi-tracker delegates camera exposure and optical extraction to the reference PSMoveAPI backend while Muninn retains stable-ID light actuation; serve consumes typed capture stream commands from its provider-owned activation store and owns the local ffmpeg/loopback activation child lifecycle, listens for media receivers on --media-rudp-bind and advertises that endpoint (--media-rudp-advertise when the bind address is not reachable as-is), and publishes its discovery advertisement through --odin-cultmesh-uri; activate starts an explicitly requested local CultNet RUDP stream as a daemon child that serves every receiver dialling --media-rudp-bind; request-stream discovers the provider through Odin and sends its typed command to that provider; obs-catalog-status pulls Odin-owned muninn.obs_stream_catalog discovery into the local compatibility store for OBS; capture-stream-status reads typed capture stream command receipts; use --no-video or --no-audio to request one leg over the CultNet RUDP media lane; request-move-light publishes a typed Move light command for Muninn serve to execute; move-light-status reads typed command receipts; move-identity-status reads typed Move identity records; move-source-status prints live Move source discovery; move-state-status reads typed controller-state records; claim-move-host assigns USB-attached PS Moves to a Bluetooth host; quest-access-status reads typed Quest access state. In --health mode, the Idunn RUDP flags publish the same typed daemon health document to Idunn for explicit diagnostics." + "Usage: muninn [serve|activate|request-stream|capture-stream-status|obs-catalog-status|request-move-light|move-light-status|move-identity-status|move-source-status|move-state-status|claim-move-host|quest-access-status] [--store ] [--activate-store ] [--stream-action ] [--target-host ] [--media-transport ] [--media-rudp-bind ] [--media-rudp-advertise ] [--media-packet-bytes ] [--rudp-video-bitrate-kbps ] [--rudp-latency-budget-ms ] [--video-source ] [--audio-source ] [--audio-source-id ] [--no-video] [--no-audio] [--loopback-script ] [--ffmpeg ] [--odin-cultmesh-uri ] [--move-state =] [--move-marker-camera =] [--move-psmoveapi-tracker] [--move-tracker-exposure-milli <0..1000>] [--move-marker-width ] [--move-marker-height ] [--move-marker-fps ] [--move-host ] [--move-evidence-stream ] [--move-evidence-verse ] [--move-evidence-ring-slots ] [--move-evidence-slot-bytes ] [--move-evidence-snapshot ] [--quest-adb] [--quest-serial ] [--quest-input-stream ] [--quest-pose-stream ] [--quest-video-input-stream ] [--dry-run] [--health]\n\nMuninn is Odin's portable telemetry Verse assembler. serve publishes cheap typed telemetry affordances, optional Quest USB access surfaces, and the explicitly configured Move runtime; when serve receives --move-state, --move-marker-camera, --move-host, or --move-evidence-stream it may publish source-local Move controller state, source-local optical marker candidates, typed Move identity records, a CultMesh Move evidence stream, optionally write a latest one-copy Move proof evidence snapshot for Mimir field capture/replay, and keep USB-attached PS Moves claimed to that explicit Bluetooth host; --move-psmoveapi-tracker delegates camera exposure and optical extraction to the reference PSMoveAPI backend while Muninn retains stable-ID light actuation; serve consumes typed capture stream commands from its provider-owned activation store and owns the local ffmpeg/loopback activation child lifecycle, listens for media receivers on --media-rudp-bind and advertises that endpoint (--media-rudp-advertise when the bind address is not reachable as-is), and publishes its discovery advertisement through --odin-cultmesh-uri; activate starts an explicitly requested local CultNet RUDP stream as a daemon child that serves every receiver dialling --media-rudp-bind; request-stream discovers the provider through Odin and sends its typed command to that provider; obs-catalog-status pulls Odin-owned muninn.obs_stream_catalog discovery into the local compatibility store for OBS; capture-stream-status reads typed capture stream command receipts; use --no-video or --no-audio to request one leg over the CultNet RUDP media lane; request-move-light publishes a typed Move light command for Muninn serve to execute; move-light-status reads typed command receipts; move-identity-status reads typed Move identity records; move-source-status prints live Move source discovery; move-state-status reads typed controller-state records; claim-move-host assigns USB-attached PS Moves to a Bluetooth host; quest-access-status reads typed Quest access state. In --health mode, the Idunn RUDP flags publish the same typed daemon health document to Idunn for explicit diagnostics." } fn parse_move_state_source(value: &str) -> Result { @@ -10430,6 +10210,7 @@ fn parse_move_state_source(value: &str) -> Result { mod tests { use super::*; use crate::media_send::{MediaKind, QueuedMediaGroup}; + use cultnet_rs::encode_cultnet_message_to_vec; fn media_stream_request() -> GameCultMediaStreamRequestRecord { GameCultMediaStreamRequestRecord { @@ -10875,39 +10656,20 @@ mod tests { } #[test] - fn health_idunn_rudp_options_are_explicit_bundle() { - let options = Options::parse( - [ - "--health", - "--idunn-rudp-health", - "127.0.0.1:17870", - "--idunn-daemon", - "starfire-muninn", - "--idunn-health-contract", - "muninn.cultnet-rudp-local-telemetry-and-quest-access", - ] - .into_iter() - .map(String::from), - ) - .unwrap(); - - let idunn = options.idunn_rudp_health.unwrap(); - assert_eq!(options.mode, Mode::Health); - assert_eq!(idunn.endpoint, "127.0.0.1:17870".parse().unwrap()); - assert_eq!(idunn.daemon_id, "starfire-muninn"); - assert_eq!( - idunn.health_contract, - "muninn.cultnet-rudp-local-telemetry-and-quest-access" - ); - - let error = Options::parse( - ["--health", "--idunn-rudp-health", "127.0.0.1:17870"] - .into_iter() - .map(String::from), - ) - .unwrap_err() - .to_string(); - assert!(error.contains("must be provided together")); + fn retired_idunn_rudp_health_flags_are_unknown_arguments() { + for flag in [ + "--idunn-rudp-health", + "--idunn-daemon", + "--idunn-health-contract", + ] { + let error = Options::parse(["--health", flag, "127.0.0.1:17870"].into_iter().map(String::from)) + .unwrap_err() + .to_string(); + assert!( + error.contains(&format!("unknown Muninn argument: {flag}")), + "{flag} must be rejected, got: {error}" + ); + } } #[test] @@ -10995,67 +10757,6 @@ mod tests { assert!(error.contains("request-stream requires --odin-cultmesh-uri")); } - #[test] - fn idunn_rudp_health_publisher_sends_raw_daemon_health_document() { - let receiver = UdpSocket::bind("127.0.0.1:0").unwrap(); - receiver - .set_read_timeout(Some(Duration::from_secs(1))) - .unwrap(); - let receiver_addr = receiver.local_addr().unwrap(); - let handle = thread::spawn(move || { - let mut transport = CultNetRudpSocketTransportConnection::new( - CultNetRudpSocketTransportOptions::server( - "idunn-test", - receiver, - IDUNN_HEALTH_RUDP_CONNECTION_ID, - ), - ) - .unwrap(); - let deadline = Instant::now() + Duration::from_secs(2); - loop { - if let Some(frame) = transport.receive_once().unwrap() { - return cultnet_rs::decode_cultnet_message_from_slice( - &frame.payload, - CultNetWireContract::CultNetSchemaV0, - ) - .unwrap(); - } - transport.poll_resends().unwrap(); - if Instant::now() >= deadline { - panic!("timed out waiting for Muninn RUDP health frame"); - } - } - }); - let options = IdunnRudpHealthOptions { - endpoint: receiver_addr, - daemon_id: "starfire-muninn".to_string(), - health_contract: "muninn.cultnet-rudp-local-telemetry-and-quest-access".to_string(), - }; - - publish_idunn_rudp_health(&options, "active", "Muninn healthy", "unix:100").unwrap(); - - let message = handle.join().unwrap(); - let CultNetMessage::DocumentPutRaw { document, .. } = message else { - panic!("expected raw document put"); - }; - assert_eq!(document.schema_id, "idunn.daemon_health"); - assert_eq!(document.record_key, "starfire-muninn"); - assert_eq!( - document.payload_encoding, - CultNetRawPayloadEncoding::Messagepack - ); - let health: IdunnDaemonHealthRecord = rmp_serde::from_slice(&document.payload).unwrap(); - assert_eq!(health.daemon_id, "starfire-muninn"); - assert_eq!(health.state, "active"); - assert_eq!( - health.health_contract, - "muninn.cultnet-rudp-local-telemetry-and-quest-access" - ); - assert_eq!(health.publication_source, "daemon-published"); - assert_eq!(health.transport, CULTNET_RUDP_PROTOCOL_ID); - assert_eq!(health.observed_at, "unix:100"); - } - #[test] fn repeated_capture_stream_start_is_equivalent_when_media_shape_matches() { let options = Options::parse( @@ -12985,12 +12686,6 @@ Device 00:07:04:A8:00:D0 (public) "C:/Meta/Odin/state/muninn.activate.cc", "--target-host", "cultmesh://odin/media/muninn-raven-av", - "--idunn-rudp-health", - "198.51.100.10:17870", - "--idunn-daemon", - "muninn", - "--idunn-health-contract", - "muninn.cultnet-rudp-remote-telemetry-health", ] .into_iter() .map(String::from), @@ -13023,6 +12718,13 @@ Device 00:07:04:A8:00:D0 (public) assert!(invocation.contains("request-stream")); assert!(invocation.contains("--target-host cultmesh://odin/media/muninn-raven-av")); + assert_eq!( + boundary.value.get("daemon_id").and_then(|value| value.as_str()), + Some("muninn") + ); + assert!(boundary.value.get("health_publication").is_none()); + assert!(transport.value.get("health_contract").is_some_and(|value| value.is_null())); + let command_lowerings = transport .value .get("command_lowerings") diff --git a/docs/muninn.md b/docs/muninn.md index 6b7df20..bd9f5b5 100644 --- a/docs/muninn.md +++ b/docs/muninn.md @@ -22,7 +22,7 @@ microphones, cameras, and future sensors. ```powershell cargo build -p muninn-daemon -muninn serve --store C:\Meta\Odin\state\muninn.telemetry.cc --interval-seconds 15 --idunn-rudp-health $env:IDUNN_RUDP_HEALTH --idunn-daemon starfire-muninn --idunn-health-contract muninn.cultnet-rudp-local-telemetry-and-quest-access +muninn serve --store C:\Meta\Odin\state\muninn.telemetry.cc --interval-seconds 15 muninn --health --store C:\Meta\Odin\state\muninn.telemetry.cc ``` @@ -97,10 +97,7 @@ E:\Projects\Odin\scripts\restart-starfire-muninn.cmd E:\Projects\Odin\scripts\health-starfire-muninn.cmd ``` -The restart script launches Muninn hidden with `--host starfire --quest-adb`, -`--idunn-rudp-health` from explicit `-IdunnRudpHealth` or -`IDUNN_RUDP_HEALTH`, `--idunn-daemon starfire-muninn`, and -`--idunn-health-contract muninn.cultnet-rudp-local-telemetry-and-quest-access`. +The restart script launches Muninn hidden with `--host starfire --quest-adb`. If the CultCache store at `C:\Meta\Odin\state\starfire.muninn.telemetry.cc` fails MessagePack decode on boot, the restart path archives the corrupt file, clears the stale `.lock`, and relaunches the daemon instead of leaving the lane @@ -192,11 +189,7 @@ muninn move-light-status \ Idunn keeps the Muninn daemon alive. Idunn does not learn a Move-specific watcher, and Mimir does not write HID directly except through temporary smoke scripts used to prove hardware behavior before a Muninn daemon is available. -When `serve` is launched with `--idunn-rudp-health`, `--idunn-daemon`, and -`--idunn-health-contract`, the long-running Muninn body publishes -`idunn.daemon_health` directly to Idunn over `cultnet.transport.rudp.v0` on its -normal cadence. `--health` keeps the same publication path for manual proof and -compatibility probes, but the live owner is the daemon's `serve` process. +`--health` reads the telemetry store and reports; it publishes nothing. Quest ADB probing is a telemetry input, not daemon liveness. If `adb` is missing or the Quest is unavailable, Muninn publishes `muninn.quest_access` as `unavailable` and keeps serving the local telemetry surface. @@ -235,10 +228,6 @@ actuators only, not lifecycle owners. The binary is installed at `/home/metacrat/.local/state/gamecult/muninn/muninn.telemetry.cc`, and the restart actuator launches `serve --host nightwing --interval-seconds 15` with `--move-state move-usb=/dev/input/by-id/usb-Sony_Computer_Entertainment_Motion_Controller-joystick`, -`--idunn-rudp-health` supplied by explicit `-IdunnRudpHealth` or -`IDUNN_RUDP_HEALTH`, -`--idunn-daemon nightwing-muninn`, -`--idunn-health-contract muninn.cultnet-rudp-remote-telemetry-and-move-hid`, PID, and logs under `/home/metacrat/.local/state/gamecult/muninn`. With that Move state source attached, `serve` also publishes the @@ -248,10 +237,7 @@ Nightwing source discovery must emit one Move source per controller id. The USB pairing collection and Bluetooth joystick can expose the same controller as separate `/dev/input/js*` paths; `nightwing-move-state-sources.sh` prefers the Bluetooth `HID_ID=0005:0000054C:000003D5` path so Idunn health does not demand -fresh records from two faces of the same controller. The Nightwing health -actuator requires the same configured Idunn RUDP endpoint, but that command is -fallback proof only; the live keepalive contract is now published by the -long-running Nightwing `serve` process. +fresh records from two faces of the same controller. Each private PSMoveAPI Eye worker owns optical observation admission before the parent aggregates evidence. Positions older than 50 ms, blobs below 2 px, diff --git a/docs/teardown-map.md b/docs/teardown-map.md index 69356c3..d89ec71 100644 --- a/docs/teardown-map.md +++ b/docs/teardown-map.md @@ -701,8 +701,7 @@ by continuity in under 10 s. The catalog on Odin named the new endpoint the first time the restarted `serve` advertised. Still Raven-specific and unmanaged: the two activation scripts and -`health-muninn.ps1`, which still passes the retired `--idunn-rudp-health` -flags. That flag family (`IdunnRudpHealthOptions`, `run_daemon_health_publisher`, -`idunn.daemon_health` documents) has no consumer since the previous Idunn -generation was retired and is the next cut; nightwing and starfire's restart -scripts still require it, so it goes with them. +`health-muninn.ps1`. The retired `--idunn-rudp-health` flag family +(`IdunnRudpHealthOptions`, `run_daemon_health_publisher`, `idunn.daemon_health` +documents) had no consumer since the previous Idunn generation was retired; it +was deleted from `muninn`, its five host scripts and `muninn.md` in named cut 3. diff --git a/scripts/health-muninn.ps1 b/scripts/health-muninn.ps1 index f783148..407b89e 100644 --- a/scripts/health-muninn.ps1 +++ b/scripts/health-muninn.ps1 @@ -5,7 +5,6 @@ param( [string] $ActivateStorePath = "C:\Meta\Odin\state\muninn.activate.cc", [string] $LogRoot = "C:\Meta\Odin\logs\muninn", [int] $MaxStoreAgeSeconds = 180, - [string] $IdunnRudpHealth = $env:IDUNN_RUDP_HEALTH, [int] $ConnectTimeoutSeconds = 10, [string] $SshUser = "madman's lullaby", [string] $IdentityFile = "" @@ -13,10 +12,6 @@ param( $ErrorActionPreference = "Stop" -if ([string]::IsNullOrWhiteSpace($IdunnRudpHealth)) { - throw "Idunn RUDP health endpoint must be supplied by -IdunnRudpHealth or IDUNN_RUDP_HEALTH; no Starfire LAN default is allowed." -} - function Set-AsciiFile { param( [Parameter(Mandatory = $true)] [string] $Path, @@ -177,10 +172,7 @@ if (`$null -eq `$process) { } foreach (`$pattern in @( "--host raven", - "--activate-store $ActivateStorePath", - "--idunn-rudp-health $IdunnRudpHealth", - "--idunn-daemon muninn", - "--idunn-health-contract muninn.cultnet-rudp-remote-telemetry-health" + "--activate-store $ActivateStorePath" )) { if (`$process.CommandLine -notlike "*`$pattern*") { throw "Muninn serve process is missing expected command-line segment `${pattern}: `$(`$process.CommandLine)" diff --git a/scripts/health-nightwing-muninn.ps1 b/scripts/health-nightwing-muninn.ps1 index ce2ce79..d6319cd 100644 --- a/scripts/health-nightwing-muninn.ps1 +++ b/scripts/health-nightwing-muninn.ps1 @@ -5,16 +5,11 @@ param( [string] $PidPath = "/home/metacrat/.local/state/gamecult/muninn/muninn.pid", [string[]] $MoveState = @(), [int] $IntervalSeconds = 15, - [int] $MaxStoreAgeSeconds = 180, - [string] $IdunnRudpHealth = $env:IDUNN_RUDP_HEALTH + [int] $MaxStoreAgeSeconds = 180 ) $ErrorActionPreference = "Stop" -if ([string]::IsNullOrWhiteSpace($IdunnRudpHealth)) { - throw "Idunn RUDP health endpoint must be supplied by -IdunnRudpHealth or IDUNN_RUDP_HEALTH; no WireGuard endpoint default is allowed." -} - function Set-AsciiFile { param( [Parameter(Mandatory = $true)] [string] $Path, @@ -76,16 +71,6 @@ if [ -z "`$process_line" ]; then echo 'Nightwing Muninn serve command line is unavailable' >&2 exit 1 fi -for pattern in \ - '--idunn-rudp-health $IdunnRudpHealth' \ - '--idunn-daemon nightwing-muninn' \ - '--idunn-health-contract muninn.cultnet-rudp-remote-telemetry-and-move-hid' -do - if ! printf '%s\n' "`$process_line" | grep -F -- "`$pattern" >/dev/null 2>&1; then - echo "Nightwing Muninn serve command line is missing `$pattern" >&2 - exit 1 - fi -done if [ ! -f '$StorePath' ]; then echo 'Muninn telemetry store is missing on Nightwing' >&2 exit 1 diff --git a/scripts/health-starfire-muninn.ps1 b/scripts/health-starfire-muninn.ps1 index c331145..d5be3ec 100644 --- a/scripts/health-starfire-muninn.ps1 +++ b/scripts/health-starfire-muninn.ps1 @@ -3,16 +3,11 @@ param( [string] $StorePath = "C:\Meta\Odin\state\starfire.muninn.telemetry.cc", [string] $LogRoot = "C:\Meta\Odin\logs\starfire-muninn", [string[]] $MoveState = @(), - [int] $MaxStoreAgeSeconds = 180, - [string] $IdunnRudpHealth = $env:IDUNN_RUDP_HEALTH + [int] $MaxStoreAgeSeconds = 180 ) $ErrorActionPreference = "Stop" -if ([string]::IsNullOrWhiteSpace($IdunnRudpHealth)) { - throw "Idunn RUDP health endpoint must be supplied by -IdunnRudpHealth or IDUNN_RUDP_HEALTH; no Starfire LAN default is allowed." -} - if (-not (Test-Path -LiteralPath $MuninnExe)) { throw "Muninn executable not found at $MuninnExe" } @@ -28,15 +23,6 @@ $process = Get-CimInstance Win32_Process | if ($null -eq $process) { throw "Starfire Muninn serve process is not running with Quest access enabled" } -foreach ($pattern in @( - "--idunn-rudp-health $IdunnRudpHealth", - "--idunn-daemon starfire-muninn", - "--idunn-health-contract muninn.cultnet-rudp-local-telemetry-and-quest-access" -)) { - if ($process.CommandLine -notlike "*$pattern*") { - throw "Starfire Muninn serve process is missing expected command-line segment ${pattern}: $($process.CommandLine)" - } -} if (-not (Test-Path -LiteralPath $StorePath)) { throw "Starfire Muninn telemetry store is missing at $StorePath" } diff --git a/scripts/restart-nightwing-muninn.ps1 b/scripts/restart-nightwing-muninn.ps1 index 9f92fa4..5c7392c 100644 --- a/scripts/restart-nightwing-muninn.ps1 +++ b/scripts/restart-nightwing-muninn.ps1 @@ -17,9 +17,6 @@ param( "nightwing-eye-1" = 100 }, [int] $IntervalSeconds = 15, - [string] $IdunnRudpHealth = $env:IDUNN_RUDP_HEALTH, - [string] $IdunnDaemon = "nightwing-muninn", - [string] $IdunnHealthContract = "muninn.cultnet-rudp-remote-telemetry-and-move-hid", [string] $OdinCultMeshUri = $(if ($env:ODIN_CULTMESH_URI) { $env:ODIN_CULTMESH_URI } else { "cultmesh://odin/rendezvous/provider-catalog" }), [string] $OdinCultMeshRudpEndpoint = $(if ($env:CULTMESH_URI_ODIN_RUDP) { $env:CULTMESH_URI_ODIN_RUDP } else { "10.77.0.2:17871" }), [string] $HidControllerRudpBind = "0.0.0.0:17888", @@ -34,12 +31,6 @@ if ($env:IDUNN_ACTUATOR -ne "1" -or $env:IDUNN_COMMAND_AUTHORITY -ne "idunn-daem throw "restart-nightwing-muninn.ps1 is an Idunn actuator body. Redeploy by poking Idunn; direct service restart is not an owned path." } -if ([string]::IsNullOrWhiteSpace($IdunnRudpHealth)) { - throw "Idunn RUDP health endpoint must be supplied by -IdunnRudpHealth or IDUNN_RUDP_HEALTH; no Starfire LAN default is allowed." -} -if ($IdunnRudpHealth -match '^(127\.0\.0\.1|localhost):(\d+)$') { - $IdunnRudpHealth = "10.77.0.2:$($Matches[2])" -} if (-not [string]::IsNullOrWhiteSpace($HidControllerRudpBind) -and [string]::IsNullOrWhiteSpace($HidControllerRudpAdvertise)) { throw "HID controller RUDP advertise endpoint must be supplied by -HidControllerRudpAdvertise or MUNINN_HID_CONTROLLER_RUDP_ADVERTISE when HID RUDP bind is enabled; no Nightwing LAN default is allowed." } @@ -162,10 +153,7 @@ set -- serve \ --host nightwing $moveRuntimeSetBlock set -- "`$@" \ - --interval-seconds '$IntervalSeconds' \ - --idunn-rudp-health '$IdunnRudpHealth' \ - --idunn-daemon '$IdunnDaemon' \ - --idunn-health-contract '$IdunnHealthContract' + --interval-seconds '$IntervalSeconds' $odinCultMeshUriSetBlock $hidControllerRudpSetBlock $commandRudpSetBlock @@ -179,10 +167,9 @@ muninn_pid="`$(cat '$LogRoot/muninn.pid')" kill -0 "`$muninn_pid" 2>/dev/null muninn_cmdline="`$(tr '\0' ' ' < "/proc/`$muninn_pid/cmdline")" if ! printf '%s\n' "`$muninn_cmdline" | grep -F -- '--host nightwing' >/dev/null 2>&1 || - ! printf '%s\n' "`$muninn_cmdline" | grep -F -- '--idunn-rudp-health $IdunnRudpHealth' >/dev/null 2>&1 || ! printf '%s\n' "`$muninn_cmdline" | grep -F -- '--move-marker-camera nightwing-eye-0=/dev/video2' >/dev/null 2>&1 || ! printf '%s\n' "`$muninn_cmdline" | grep -F -- '--move-marker-camera nightwing-eye-1=/dev/video3' >/dev/null 2>&1; then - echo 'Nightwing Muninn serve command line is missing Idunn health or dual-camera arguments' >&2 + echo 'Nightwing Muninn serve command line is missing dual-camera arguments' >&2 exit 1 fi "@ diff --git a/scripts/restart-starfire-muninn.ps1 b/scripts/restart-starfire-muninn.ps1 index 70b79f6..69af854 100644 --- a/scripts/restart-starfire-muninn.ps1 +++ b/scripts/restart-starfire-muninn.ps1 @@ -6,9 +6,6 @@ param( [string] $MoveBluetoothHost = "", [string[]] $MoveState = @(), [switch] $EnableUsbMoveState, - [string] $IdunnRudpHealth = $env:IDUNN_RUDP_HEALTH, - [string] $IdunnDaemon = "starfire-muninn", - [string] $IdunnHealthContract = "muninn.cultnet-rudp-local-telemetry-and-quest-access", [string] $OdinCultMeshUri = $(if ($env:ODIN_CULTMESH_URI) { $env:ODIN_CULTMESH_URI } else { "cultmesh://odin/rendezvous/provider-catalog" }), [string] $OdinCultMeshRudpEndpoint = $(if ($env:CULTMESH_URI_ODIN_RUDP) { $env:CULTMESH_URI_ODIN_RUDP } else { "127.0.0.1:17871" }), [string] $HidControllerRudpBind = "", @@ -29,9 +26,6 @@ if ($env:IDUNN_ACTUATOR -ne "1" -or $env:IDUNN_COMMAND_AUTHORITY -ne "idunn-daem if (-not (Test-Path -LiteralPath $MuninnExe)) { throw "Muninn executable not found at $MuninnExe" } -if ([string]::IsNullOrWhiteSpace($IdunnRudpHealth)) { - throw "Idunn RUDP health endpoint must be supplied by -IdunnRudpHealth or IDUNN_RUDP_HEALTH; no Starfire LAN default is allowed." -} if (-not [string]::IsNullOrWhiteSpace($HidControllerRudpBind) -and [string]::IsNullOrWhiteSpace($HidControllerRudpAdvertise)) { throw "HID controller RUDP advertise endpoint must be supplied by -HidControllerRudpAdvertise or MUNINN_HID_CONTROLLER_RUDP_ADVERTISE when HID RUDP bind is enabled; no Starfire LAN default is allowed." } @@ -63,10 +57,7 @@ $arguments = @( "--host", "starfire", "--interval-seconds", "15", "--quest-adb", - "--quest-serial", $QuestSerial, - "--idunn-rudp-health", $IdunnRudpHealth, - "--idunn-daemon", $IdunnDaemon, - "--idunn-health-contract", $IdunnHealthContract + "--quest-serial", $QuestSerial ) if (-not [string]::IsNullOrWhiteSpace($OdinCultMeshUri)) { $arguments += @("--odin-cultmesh-uri", $OdinCultMeshUri) @@ -160,15 +151,3 @@ if ($null -eq $processCheck) { if ($null -eq $processCheck) { throw "Starfire Muninn serve process is not running after restart" } -foreach ($pattern in @( - "--idunn-rudp-health", - $IdunnRudpHealth, - "--idunn-daemon", - $IdunnDaemon, - "--idunn-health-contract", - $IdunnHealthContract -)) { - if ($processCheck.CommandLine -notlike "*$pattern*") { - throw "Starfire Muninn serve command line is missing ${pattern}: $($processCheck.CommandLine)" - } -} From 7b8b37a2fd58b819ad7cd7d34390b482f116690c Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 23:18:57 +0200 Subject: [PATCH 35/44] health_check no longer reads a timestamp it does not publish The previous commit left health_check computing an observed_at and a state/detail pair whose only consumer was the deleted publisher; the timestamp helper itself was deleted, so the workspace did not build. Co-Authored-By: Claude Opus 5.5 --- crates/muninn-daemon/src/main.rs | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index b28e042..c3b310c 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -8550,19 +8550,9 @@ fn quest_access_status(options: Options) -> Result<()> { } fn health_check(options: &Options) -> Result<()> { - let observed_at = idunn_timestamp()?; - let result = evaluate_health(options); - let (state, detail) = match &result { - Ok(detail) => ("active", detail.clone()), - Err(error) => ("failed", error.to_string()), - }; - match result { - Ok(detail) => { - println!("{detail}"); - Ok(()) - } - Err(error) => Err(error), - } + let detail = evaluate_health(options)?; + println!("{detail}"); + Ok(()) } fn evaluate_health(options: &Options) -> Result { From e27de13efd0f94194ff0bbf17bd41c0e6a46bc75 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 23:31:46 +0200 Subject: [PATCH 36/44] muninn-contracts: Muninn's 15 state records leave odin-core New library crate crates/muninn-contracts holds the records Muninn owns (telemetry surface, capture stream and command, OBS catalog, Move marker candidate, controller state, identity, light command, hue program, tracker health and evidence transport health, HID controller state, Quest access, command boundary, transport profile), their schema constants, and the MuninnRecords document set. The definitions are the odin-core ones moved verbatim; the wire is unchanged. muninn and sleipnir import the records from here, so both link one definition. muninn registers MuninnRecords after OdinDocuments, which stays because it still carries Odin's own records and stale copies of the same schema ids. Muninn's odin-core imports are now EveProviderAdvertisementRecord, EveSurfaceStateRecord and OdinDocuments. Tests pin every type name and schema id, the document-set bindings, and the positional wire layout of two records. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 15 + Cargo.toml | 1 + crates/muninn-contracts/Cargo.toml | 21 + crates/muninn-contracts/src/lib.rs | 176 +++++++++ crates/muninn-contracts/src/records.rs | 508 +++++++++++++++++++++++++ crates/muninn-daemon/Cargo.toml | 1 + crates/muninn-daemon/src/main.rs | 22 +- crates/sleipnir-daemon/Cargo.toml | 1 + crates/sleipnir-daemon/src/main.rs | 5 +- 9 files changed, 739 insertions(+), 11 deletions(-) create mode 100644 crates/muninn-contracts/Cargo.toml create mode 100644 crates/muninn-contracts/src/lib.rs create mode 100644 crates/muninn-contracts/src/records.rs diff --git a/Cargo.lock b/Cargo.lock index 2419f4b..70a0f01 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -479,6 +479,19 @@ version = "2.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" +[[package]] +name = "muninn-contracts" +version = "0.1.0" +dependencies = [ + "anyhow", + "cultcache-rs", + "cultmesh-rs", + "cultnet-rs", + "rmp-serde", + "serde", + "serde_json", +] + [[package]] name = "muninn-daemon" version = "0.1.0" @@ -488,6 +501,7 @@ dependencies = [ "cultmesh-rs", "cultnet-rs", "libc", + "muninn-contracts", "muninn-move-tracker", "muninn-psmoveapi-tracker", "odin-core", @@ -799,6 +813,7 @@ dependencies = [ "cultcache-rs", "cultmesh-rs", "cultnet-rs", + "muninn-contracts", "odin-core", "rmp-serde", "serde_json", diff --git a/Cargo.toml b/Cargo.toml index 12add68..b9d770a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,6 @@ [workspace] members = [ + "crates/muninn-contracts", "crates/muninn-daemon", "crates/muninn-move-tracker", "crates/muninn-psmoveapi-tracker", diff --git a/crates/muninn-contracts/Cargo.toml b/crates/muninn-contracts/Cargo.toml new file mode 100644 index 0000000..8b674b5 --- /dev/null +++ b/crates/muninn-contracts/Cargo.toml @@ -0,0 +1,21 @@ +[package] +name = "muninn-contracts" +version = "0.1.0" +edition.workspace = true +license.workspace = true +publish.workspace = true + +[lib] +name = "muninn_contracts" +path = "src/lib.rs" + +[dependencies] +anyhow = "1" +cultcache-rs = { workspace = true } +cultmesh-rs = { workspace = true } +cultnet-rs = { workspace = true } +serde = { version = "1", features = ["derive"] } +serde_json = "1" + +[dev-dependencies] +rmp-serde = "1.3" diff --git a/crates/muninn-contracts/src/lib.rs b/crates/muninn-contracts/src/lib.rs new file mode 100644 index 0000000..0ec0605 --- /dev/null +++ b/crates/muninn-contracts/src/lib.rs @@ -0,0 +1,176 @@ +//! Muninn's typed state records: the wire and store contract that `muninn` and +//! `sleipnir` share. Library only: no sockets, threads, devices or Odin. + +mod records; + +pub use records::*; + +cultmesh_rs::cultmesh_documents!(MuninnRecords { + MuninnTelemetrySurfaceRecord => MUNINN_TELEMETRY_SURFACE_SCHEMA, + MuninnCaptureStreamRecord => MUNINN_CAPTURE_STREAM_SCHEMA, + MuninnCaptureStreamCommandRecord => MUNINN_CAPTURE_STREAM_COMMAND_SCHEMA, + MuninnObsStreamCatalogRecord => MUNINN_OBS_STREAM_CATALOG_SCHEMA, + MuninnMoveMarkerCandidateRecord => MUNINN_MOVE_MARKER_CANDIDATE_SCHEMA, + MuninnMoveControllerStateRecord => MUNINN_MOVE_CONTROLLER_STATE_SCHEMA, + MuninnHidControllerStateRecord => MUNINN_HID_CONTROLLER_STATE_SCHEMA, + MuninnMoveIdentityRecord => MUNINN_MOVE_IDENTITY_SCHEMA, + MuninnMoveLightCommandRecord => MUNINN_MOVE_LIGHT_COMMAND_SCHEMA, + MuninnMoveHueProgramRecord => MUNINN_MOVE_HUE_PROGRAM_SCHEMA, + MuninnMoveTrackerHealthRecord => MUNINN_MOVE_TRACKER_HEALTH_SCHEMA, + MuninnMoveEvidenceTransportHealthRecord => MUNINN_MOVE_EVIDENCE_TRANSPORT_HEALTH_SCHEMA, + MuninnQuestAccessRecord => MUNINN_QUEST_ACCESS_SCHEMA, + MuninnCommandBoundaryCompatRecord => MUNINN_COMMAND_BOUNDARY_SCHEMA, + MuninnTransportProfileCompatRecord => MUNINN_TRANSPORT_PROFILE_SCHEMA, +}); + +#[cfg(test)] +mod tests { + use super::*; + use cultcache_rs::{CultCache, DatabaseEntry}; + use cultmesh_rs::CultMeshDocumentSet; + use cultnet_rs::CultNetDocumentRegistry; + + /// Every Muninn record: its type name, its schema id, the schema constant + /// the document set binds it under, and its Rust name. + fn contract() -> Vec<(&'static str, &'static str, &'static str, &'static str)> { + macro_rules! row { + ($record:ty, $constant:expr) => { + ( + <$record as DatabaseEntry>::TYPE, + <$record as DatabaseEntry>::SCHEMA_NAME, + $constant, + stringify!($record), + ) + }; + } + vec![ + row!(MuninnTelemetrySurfaceRecord, MUNINN_TELEMETRY_SURFACE_SCHEMA), + row!(MuninnCaptureStreamRecord, MUNINN_CAPTURE_STREAM_SCHEMA), + row!(MuninnCaptureStreamCommandRecord, MUNINN_CAPTURE_STREAM_COMMAND_SCHEMA), + row!(MuninnObsStreamCatalogRecord, MUNINN_OBS_STREAM_CATALOG_SCHEMA), + row!(MuninnMoveMarkerCandidateRecord, MUNINN_MOVE_MARKER_CANDIDATE_SCHEMA), + row!(MuninnMoveControllerStateRecord, MUNINN_MOVE_CONTROLLER_STATE_SCHEMA), + row!(MuninnHidControllerStateRecord, MUNINN_HID_CONTROLLER_STATE_SCHEMA), + row!(MuninnMoveIdentityRecord, MUNINN_MOVE_IDENTITY_SCHEMA), + row!(MuninnMoveLightCommandRecord, MUNINN_MOVE_LIGHT_COMMAND_SCHEMA), + row!(MuninnMoveHueProgramRecord, MUNINN_MOVE_HUE_PROGRAM_SCHEMA), + row!(MuninnMoveTrackerHealthRecord, MUNINN_MOVE_TRACKER_HEALTH_SCHEMA), + row!( + MuninnMoveEvidenceTransportHealthRecord, + MUNINN_MOVE_EVIDENCE_TRANSPORT_HEALTH_SCHEMA + ), + row!(MuninnQuestAccessRecord, MUNINN_QUEST_ACCESS_SCHEMA), + row!(MuninnCommandBoundaryCompatRecord, MUNINN_COMMAND_BOUNDARY_SCHEMA), + row!(MuninnTransportProfileCompatRecord, MUNINN_TRANSPORT_PROFILE_SCHEMA), + ] + } + + #[test] + fn record_names_are_the_published_schema_ids() { + let expected = [ + ("muninn.telemetry_surface", "muninn.telemetry_surface.v1"), + ("muninn.capture_stream", "muninn.capture_stream.v1"), + ("muninn.capture_stream_command", "muninn.capture_stream_command.v1"), + ("muninn.obs_stream_catalog", "muninn.obs_stream_catalog.v1"), + ("muninn.move_marker_candidate", "muninn.move_marker_candidate.v1"), + ("muninn.move_controller_state", "muninn.move_controller_state.v1"), + ("muninn.hid_controller_state", "muninn.hid_controller_state.v1"), + ("muninn.move_identity", "muninn.move_identity.v1"), + ("muninn.move_light_command", "muninn.move_light_command.v1"), + ("muninn.move_hue_program", "muninn.move_hue_program.v1"), + ("muninn.move_tracker_health", "muninn.move_tracker_health.v1"), + ( + "muninn.move_evidence_transport_health", + "muninn.move_evidence_transport_health.v1", + ), + ("muninn.quest_access", "muninn.quest_access.v1"), + ("muninn.command_boundary", "muninn.command_boundary.v1"), + ("muninn.transport_profile", "muninn.transport_profile.v1"), + ]; + let actual: Vec<_> = contract() + .into_iter() + .map(|(record_type, schema, constant, _)| { + assert_eq!(schema, constant, "schema constant and derive disagree"); + (record_type, schema) + }) + .collect(); + assert_eq!(actual, expected); + } + + #[test] + fn document_set_binds_every_record_under_its_schema() { + let mut cache = CultCache::new(); + MuninnRecords.register_cache(&mut cache).unwrap(); + let mut registry = CultNetDocumentRegistry::new(); + MuninnRecords.register_documents(&mut registry).unwrap(); + + let rows = contract(); + let mut registered = cache.registered_entry_types(); + registered.sort(); + let mut expected: Vec = rows.iter().map(|row| row.0.to_string()).collect(); + expected.sort(); + assert_eq!(registered, expected); + for (record_type, schema, _, record) in rows { + let binding = registry + .binding_by_schema_id(schema) + .unwrap_or_else(|| panic!("{record} is not bound under {schema}")); + assert_eq!(binding.document_type, record_type, "{record}"); + } + } + + #[test] + fn hid_controller_state_wire_layout_is_positional_by_key() { + let record = MuninnHidControllerStateRecord { + stream_id: "muninn.raven.hid".into(), + host_id: "raven".into(), + device_id: "xbox-0".into(), + device_kind: "xinput".into(), + sequence: 7, + source_timestamp_ns: -3, + axes: vec![0.5, -1.0], + buttons: vec!["a".into(), "b".into()], + battery01: 1.0, + observed_at: "unix:100".into(), + source_path: "xinput://0".into(), + }; + let bytes = rmp_serde::to_vec(&record).unwrap(); + assert_eq!( + hex(&bytes), + "9bb06d756e696e6e2e726176656e2e686964a5726176656ea678626f782d30a678696e70757407fd92ca3f000000cabf80000092a161a162ca3f800000a8756e69783a313030aa78696e7075743a2f2f30" + ); + assert_eq!( + rmp_serde::from_slice::(&bytes).unwrap(), + record + ); + } + + #[test] + fn hue_program_wire_layout_carries_its_defaulted_tail() { + let record = MuninnMoveHueProgramRecord { + program_id: "prog".into(), + host_id: "raven".into(), + mode: "cycle".into(), + cycle_ms: 20, + epoch_ns: -1, + hold_at_ns: 0, + requested_by: "mimir".into(), + updated_at: "unix:1".into(), + order_mode: "ring".into(), + transition_percent: 50, + transition_percent_explicit: true, + }; + let bytes = rmp_serde::to_vec(&record).unwrap(); + assert_eq!( + hex(&bytes), + "9ba470726f67a5726176656ea56379636c6514ff00a56d696d6972a6756e69783a31a472696e6732c3" + ); + assert_eq!( + rmp_serde::from_slice::(&bytes).unwrap(), + record + ); + } + + fn hex(bytes: &[u8]) -> String { + bytes.iter().map(|byte| format!("{byte:02x}")).collect() + } +} diff --git a/crates/muninn-contracts/src/records.rs b/crates/muninn-contracts/src/records.rs new file mode 100644 index 0000000..7742843 --- /dev/null +++ b/crates/muninn-contracts/src/records.rs @@ -0,0 +1,508 @@ +use cultcache_rs::DatabaseEntry; +use serde_json::Value; + +pub const MUNINN_TELEMETRY_SURFACE_SCHEMA: &str = "muninn.telemetry_surface.v1"; +pub const MUNINN_CAPTURE_STREAM_SCHEMA: &str = "muninn.capture_stream.v1"; +pub const MUNINN_CAPTURE_STREAM_COMMAND_SCHEMA: &str = "muninn.capture_stream_command.v1"; +pub const MUNINN_OBS_STREAM_CATALOG_SCHEMA: &str = "muninn.obs_stream_catalog.v1"; +pub const MUNINN_MOVE_MARKER_CANDIDATE_SCHEMA: &str = "muninn.move_marker_candidate.v1"; +pub const MUNINN_MOVE_CONTROLLER_STATE_SCHEMA: &str = "muninn.move_controller_state.v1"; +pub const MUNINN_HID_CONTROLLER_STATE_SCHEMA: &str = "muninn.hid_controller_state.v1"; +pub const MUNINN_MOVE_IDENTITY_SCHEMA: &str = "muninn.move_identity.v1"; +pub const MUNINN_MOVE_LIGHT_COMMAND_SCHEMA: &str = "muninn.move_light_command.v1"; +pub const MUNINN_MOVE_HUE_PROGRAM_SCHEMA: &str = "muninn.move_hue_program.v1"; +pub const MUNINN_MOVE_TRACKER_HEALTH_SCHEMA: &str = "muninn.move_tracker_health.v1"; +pub const MUNINN_MOVE_EVIDENCE_TRANSPORT_HEALTH_SCHEMA: &str = + "muninn.move_evidence_transport_health.v1"; +pub const MUNINN_QUEST_ACCESS_SCHEMA: &str = "muninn.quest_access.v1"; +pub const MUNINN_COMMAND_BOUNDARY_SCHEMA: &str = "muninn.command_boundary.v1"; +pub const MUNINN_TRANSPORT_PROFILE_SCHEMA: &str = "muninn.transport_profile.v1"; + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache(type = "muninn.capture_stream", schema = "muninn.capture_stream.v1")] +pub struct MuninnCaptureStreamRecord { + #[cultcache(key = 0)] + pub stream_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub state: String, + #[cultcache(key = 3)] + pub video_source: String, + #[cultcache(key = 4)] + pub audio_source: String, + #[cultcache(key = 5)] + pub transport: String, + #[cultcache(key = 6)] + pub targets: Vec, + #[cultcache(key = 7)] + pub command_witness: String, + #[cultcache(key = 8)] + pub supervisor_pid: Option, + #[cultcache(key = 9)] + pub mux_pid: Option, + #[cultcache(key = 10)] + pub restart_count: u32, + #[cultcache(key = 11)] + pub detail: String, + #[cultcache(key = 12)] + pub updated_at: String, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache( + type = "muninn.capture_stream_command", + schema = "muninn.capture_stream_command.v1" +)] +pub struct MuninnCaptureStreamCommandRecord { + #[cultcache(key = 0)] + pub command_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub stream_id: String, + #[cultcache(key = 3)] + pub state: String, + #[cultcache(key = 4)] + pub action: String, + #[cultcache(key = 5)] + pub target_host: String, + #[cultcache(key = 6)] + pub port: u16, + #[cultcache(key = 7)] + pub obs_target_host: Option, + #[cultcache(key = 8)] + pub obs_port: u16, + #[cultcache(key = 9)] + pub media_transport: String, + #[cultcache(key = 10)] + pub media_packet_bytes: u32, + #[cultcache(key = 11)] + pub requested_by: String, + #[cultcache(key = 12)] + pub detail: String, + #[cultcache(key = 13)] + pub updated_at: String, + #[cultcache(key = 14, default)] + pub rudp_video_bitrate_kbps: u32, + #[cultcache(key = 15, default)] + pub rudp_latency_budget_ms: u32, + #[cultcache(key = 16, default)] + pub video_source_id: String, + #[cultcache(key = 17, default)] + pub audio_source_id: String, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache( + type = "muninn.telemetry_surface", + schema = "muninn.telemetry_surface.v1" +)] +pub struct MuninnTelemetrySurfaceRecord { + #[cultcache(key = 0)] + pub surface_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub state: String, + #[cultcache(key = 3)] + pub available_sources: Vec, + #[cultcache(key = 4)] + pub stream_affordances: Vec, + #[cultcache(key = 5)] + pub active_streams: Vec, + #[cultcache(key = 6)] + pub activation_authority: String, + #[cultcache(key = 7)] + pub detail: String, + #[cultcache(key = 8)] + pub updated_at: String, + #[cultcache(key = 9, default)] + pub primary_stream_id: String, + #[cultcache(key = 10, default)] + pub primary_stream_label: String, + #[cultcache(key = 11, default)] + pub command_rudp_target: String, + #[cultcache(key = 12, default)] + pub media_target_host: String, + #[cultcache(key = 13, default)] + pub media_port: u16, + #[cultcache(key = 14, default)] + pub media_packet_bytes: u32, + #[cultcache(key = 15, default)] + pub rudp_video_bitrate_kbps: u32, + #[cultcache(key = 16, default)] + pub rudp_latency_budget_ms: u32, + #[cultcache(key = 17, default)] + pub video_source_ids: Vec, + #[cultcache(key = 18, default)] + pub video_source_labels: Vec, + #[cultcache(key = 19, default)] + pub audio_source_ids: Vec, + #[cultcache(key = 20, default)] + pub audio_source_labels: Vec, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache( + type = "muninn.obs_stream_catalog", + schema = "muninn.obs_stream_catalog.v1" +)] +pub struct MuninnObsStreamCatalogRecord { + #[cultcache(key = 0)] + pub catalog_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub stream_ids: Vec, + #[cultcache(key = 3)] + pub labels: Vec, + #[cultcache(key = 4)] + pub urls: Vec, + #[cultcache(key = 5)] + pub states: Vec, + #[cultcache(key = 6)] + pub updated_at: String, + #[cultcache(key = 7, default)] + pub command_rudp_target: String, + #[cultcache(key = 8, default)] + pub media_target_host: String, + #[cultcache(key = 9, default)] + pub media_port: u16, + #[cultcache(key = 10, default)] + pub media_packet_bytes: u32, + #[cultcache(key = 11, default)] + pub rudp_video_bitrate_kbps: u32, + #[cultcache(key = 12, default)] + pub rudp_latency_budget_ms: u32, + #[cultcache(key = 13, default)] + pub video_source_ids: Vec, + #[cultcache(key = 14, default)] + pub video_source_labels: Vec, + #[cultcache(key = 15, default)] + pub audio_source_ids: Vec, + #[cultcache(key = 16, default)] + pub audio_source_labels: Vec, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "muninn.move_marker_candidate", + schema = "muninn.move_marker_candidate.v1" +)] +pub struct MuninnMoveMarkerCandidateRecord { + #[cultcache(key = 0)] + pub stream_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub camera_id: String, + #[cultcache(key = 3)] + pub frame_sequence: u64, + #[cultcache(key = 4)] + pub source_id_hash: u64, + #[cultcache(key = 5)] + pub tile_x: u32, + #[cultcache(key = 6)] + pub tile_y: u32, + #[cultcache(key = 7)] + pub center_x_px: f32, + #[cultcache(key = 8)] + pub center_y_px: f32, + #[cultcache(key = 9)] + pub radius_px: f32, + #[cultcache(key = 10)] + pub area_px: u32, + #[cultcache(key = 11)] + pub mean_luma: f32, + #[cultcache(key = 12)] + pub peak_luma: u32, + #[cultcache(key = 13)] + pub score: f32, + #[cultcache(key = 14)] + pub observed_at: String, + #[cultcache(key = 15, default)] + pub move_id: String, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "muninn.move_controller_state", + schema = "muninn.move_controller_state.v1" +)] +pub struct MuninnMoveControllerStateRecord { + #[cultcache(key = 0)] + pub stream_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub move_id: String, + #[cultcache(key = 3)] + pub sequence: u64, + #[cultcache(key = 4)] + pub source_timestamp_ns: i64, + #[cultcache(key = 5)] + pub accelerometer_xyz: Vec, + #[cultcache(key = 6)] + pub gyroscope_xyz: Vec, + #[cultcache(key = 7)] + pub magnetometer_xyz: Vec, + #[cultcache(key = 8)] + pub trigger_value: f32, + #[cultcache(key = 9)] + pub buttons: Vec, + #[cultcache(key = 10)] + pub battery01: f32, + #[cultcache(key = 11)] + pub observed_at: String, + #[cultcache(key = 12, default)] + pub source_path: String, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "muninn.hid_controller_state", + schema = "muninn.hid_controller_state.v1" +)] +pub struct MuninnHidControllerStateRecord { + #[cultcache(key = 0)] + pub stream_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub device_id: String, + #[cultcache(key = 3)] + pub device_kind: String, + #[cultcache(key = 4)] + pub sequence: u64, + #[cultcache(key = 5)] + pub source_timestamp_ns: i64, + #[cultcache(key = 6)] + pub axes: Vec, + #[cultcache(key = 7)] + pub buttons: Vec, + #[cultcache(key = 8)] + pub battery01: f32, + #[cultcache(key = 9)] + pub observed_at: String, + #[cultcache(key = 10)] + pub source_path: String, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache(type = "muninn.move_identity", schema = "muninn.move_identity.v1")] +pub struct MuninnMoveIdentityRecord { + #[cultcache(key = 0)] + pub identity_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub move_id: String, + #[cultcache(key = 3)] + pub source_path: String, + #[cultcache(key = 4)] + pub bluetooth_host_address: String, + #[cultcache(key = 5)] + pub state: String, + #[cultcache(key = 6)] + pub detail: String, + #[cultcache(key = 7)] + pub observed_at: String, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache( + type = "muninn.move_light_command", + schema = "muninn.move_light_command.v1" +)] +pub struct MuninnMoveLightCommandRecord { + #[cultcache(key = 0)] + pub command_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub move_id: String, + #[cultcache(key = 3)] + pub hidraw_path: String, + #[cultcache(key = 4)] + pub colors: Vec, + #[cultcache(key = 5)] + pub durations_ms: Vec, + #[cultcache(key = 6)] + pub repeat_count: u32, + #[cultcache(key = 7)] + pub authority: String, + #[cultcache(key = 8)] + pub state: String, + #[cultcache(key = 9)] + pub detail: String, + #[cultcache(key = 10)] + pub updated_at: String, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache( + type = "muninn.move_hue_program", + schema = "muninn.move_hue_program.v1" +)] +pub struct MuninnMoveHueProgramRecord { + #[cultcache(key = 0)] + pub program_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub mode: String, + #[cultcache(key = 3)] + pub cycle_ms: u64, + #[cultcache(key = 4)] + pub epoch_ns: i64, + #[cultcache(key = 5)] + pub hold_at_ns: i64, + #[cultcache(key = 6)] + pub requested_by: String, + #[cultcache(key = 7)] + pub updated_at: String, + #[cultcache(key = 8, default)] + pub order_mode: String, + #[cultcache(key = 9, default)] + pub transition_percent: u8, + #[cultcache(key = 10, default)] + pub transition_percent_explicit: bool, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "muninn.move_tracker_health", + schema = "muninn.move_tracker_health.v1" +)] +pub struct MuninnMoveTrackerHealthRecord { + #[cultcache(key = 0)] + pub health_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub camera_id: String, + #[cultcache(key = 3)] + pub camera_index: i32, + #[cultcache(key = 4)] + pub state: String, + #[cultcache(key = 5)] + pub camera_name: String, + #[cultcache(key = 6)] + pub camera_api: String, + #[cultcache(key = 7)] + pub width: u32, + #[cultcache(key = 8)] + pub height: u32, + #[cultcache(key = 9)] + pub exposure: f32, + #[cultcache(key = 10)] + pub calibrated_controller_count: u32, + #[cultcache(key = 11)] + pub update_count: u64, + #[cultcache(key = 12)] + pub observation_count: u64, + #[cultcache(key = 13)] + pub latest_observation_count: u32, + #[cultcache(key = 14)] + pub last_observation_at: String, + #[cultcache(key = 15)] + pub detail: String, + #[cultcache(key = 16)] + pub updated_at: String, + #[cultcache(key = 17, default)] + pub image_mean_rgb: Vec, + #[cultcache(key = 18, default)] + pub image_peak_rgb: Vec, + #[cultcache(key = 19, default)] + pub color_evidence_move_ids: Vec, + #[cultcache(key = 20, default)] + pub color_evidence_pixel_counts: Vec, + #[cultcache(key = 21, default)] + pub rejected_stale_count: u64, + #[cultcache(key = 22, default)] + pub rejected_radius_count: u64, + #[cultcache(key = 23, default)] + pub rejected_bounds_count: u64, + #[cultcache(key = 24, default)] + pub rejected_continuity_count: u64, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache( + type = "muninn.move_evidence_transport_health", + schema = "muninn.move_evidence_transport_health.v1" +)] +pub struct MuninnMoveEvidenceTransportHealthRecord { + #[cultcache(key = 0)] + pub health_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub stream_id: String, + #[cultcache(key = 3)] + pub produced_frames: u64, + #[cultcache(key = 4)] + pub local_ring_admissions: u64, + #[cultcache(key = 5)] + pub remote_handoffs: u64, + #[cultcache(key = 6)] + pub remote_sends: u64, + #[cultcache(key = 7)] + pub updated_at: String, +} + +#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)] +#[cultcache(type = "muninn.quest_access", schema = "muninn.quest_access.v1")] +pub struct MuninnQuestAccessRecord { + #[cultcache(key = 0)] + pub access_id: String, + #[cultcache(key = 1)] + pub host_id: String, + #[cultcache(key = 2)] + pub serial: String, + #[cultcache(key = 3)] + pub connection_state: String, + #[cultcache(key = 4)] + pub product: String, + #[cultcache(key = 5)] + pub model: String, + #[cultcache(key = 6)] + pub device: String, + #[cultcache(key = 7)] + pub transport_id: String, + #[cultcache(key = 8)] + pub input_stream_id: String, + #[cultcache(key = 9)] + pub pose_stream_id: String, + #[cultcache(key = 10)] + pub video_input_stream_id: String, + #[cultcache(key = 11)] + pub video_input_transport: String, + #[cultcache(key = 12)] + pub state: String, + #[cultcache(key = 13)] + pub detail: String, + #[cultcache(key = 14)] + pub observed_at: String, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "muninn.command_boundary", + schema = "muninn.command_boundary.v1" +)] +pub struct MuninnCommandBoundaryCompatRecord { + #[cultcache(key = 0)] + pub value: Value, +} + +#[derive(Clone, Debug, PartialEq, DatabaseEntry)] +#[cultcache( + type = "muninn.transport_profile", + schema = "muninn.transport_profile.v1" +)] +pub struct MuninnTransportProfileCompatRecord { + #[cultcache(key = 0)] + pub value: Value, +} diff --git a/crates/muninn-daemon/Cargo.toml b/crates/muninn-daemon/Cargo.toml index 5b495ee..c77d6c5 100644 --- a/crates/muninn-daemon/Cargo.toml +++ b/crates/muninn-daemon/Cargo.toml @@ -19,6 +19,7 @@ cultcache-rs = { workspace = true } cultmesh-rs = { workspace = true } cultnet-rs = { workspace = true } libc = "0.2" +muninn-contracts = { path = "../muninn-contracts" } muninn-move-tracker = { path = "../muninn-move-tracker" } muninn-psmoveapi-tracker = { path = "../muninn-psmoveapi-tracker", optional = true } odin-core = { workspace = true } diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index c3b310c..cf8e119 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -23,18 +23,18 @@ use cultnet_rs::{ GameCultRuntimePresenceHealthRecord, decode_cultnet_message_from_slice, media_stream_request_key, validate_media_stream_request, }; -#[cfg(feature = "psmoveapi-tracker")] -use odin_core::MuninnMoveTrackerHealthRecord; -use odin_core::{ - EveProviderAdvertisementRecord, EveSurfaceStateRecord, +use muninn_contracts::{ MUNINN_MOVE_HUE_PROGRAM_SCHEMA, MUNINN_OBS_STREAM_CATALOG_SCHEMA, MuninnCaptureStreamCommandRecord, MuninnCaptureStreamRecord, MuninnCommandBoundaryCompatRecord, MuninnHidControllerStateRecord, MuninnMoveControllerStateRecord, MuninnMoveEvidenceTransportHealthRecord, MuninnMoveHueProgramRecord, MuninnMoveIdentityRecord, MuninnMoveLightCommandRecord, MuninnMoveMarkerCandidateRecord, MuninnObsStreamCatalogRecord, - MuninnQuestAccessRecord, MuninnTelemetrySurfaceRecord, MuninnTransportProfileCompatRecord, - OdinDocuments, + MuninnQuestAccessRecord, MuninnRecords, MuninnTelemetrySurfaceRecord, + MuninnTransportProfileCompatRecord, }; +#[cfg(feature = "psmoveapi-tracker")] +use muninn_contracts::MuninnMoveTrackerHealthRecord; +use odin_core::{EveProviderAdvertisementRecord, EveSurfaceStateRecord, OdinDocuments}; use serde::{Deserialize, Serialize}; use serde_json::json; use std::collections::{HashMap, HashSet}; @@ -9526,15 +9526,18 @@ fn ensure_state_dirs(options: &Options) -> Result<()> { Ok(()) } -/// Odin's document set plus the producer-agnostic media stream contract. -/// Muninn advertises through the latter and takes requests through it; the -/// former is what the rest of its state still speaks. +/// Odin's document set, Muninn's own records, and the producer-agnostic media +/// stream contract. Muninn's records are registered after Odin's, so +/// `muninn-contracts` decides every `muninn.*` binding; Odin's document set +/// still carries stale copies of the same schema ids (and the store may hold +/// legacy Odin records), which is why it stays registered. #[derive(Clone, Copy, Debug, Default)] struct MuninnDocuments; impl cultmesh_rs::CultMeshDocumentSet for MuninnDocuments { fn register_cache(&self, cache: &mut cultcache_rs::CultCache) -> Result<()> { OdinDocuments.register_cache(cache)?; + MuninnRecords.register_cache(cache)?; cache.register_entry_type::()?; cache.register_entry_type::()?; cache.register_entry_type::()?; @@ -9543,6 +9546,7 @@ impl cultmesh_rs::CultMeshDocumentSet for MuninnDocuments { fn register_documents(&self, registry: &mut cultnet_rs::CultNetDocumentRegistry) -> Result<()> { OdinDocuments.register_documents(registry)?; + MuninnRecords.register_documents(registry)?; registry.register( cultnet_rs::CultNetDocumentBinding::for_entry_with_schema_id::< GameCultMediaStreamAdvertisementRecord, diff --git a/crates/sleipnir-daemon/Cargo.toml b/crates/sleipnir-daemon/Cargo.toml index b10f048..09e4533 100644 --- a/crates/sleipnir-daemon/Cargo.toml +++ b/crates/sleipnir-daemon/Cargo.toml @@ -14,6 +14,7 @@ anyhow = "1" cultmesh-rs = { workspace = true } cultnet-rs = { workspace = true } cultcache-rs = { workspace = true } +muninn-contracts = { path = "../muninn-contracts" } odin-core = { workspace = true } rmp-serde = "1.3" serde_json = "1" diff --git a/crates/sleipnir-daemon/src/main.rs b/crates/sleipnir-daemon/src/main.rs index 1be0193..cccedfd 100644 --- a/crates/sleipnir-daemon/src/main.rs +++ b/crates/sleipnir-daemon/src/main.rs @@ -7,10 +7,11 @@ use cultnet_rs::{ CultNetRudpSocketTransportConnection, CultNetRudpSocketTransportOptions, CultNetWireContract, encode_cultnet_message_to_vec, }; +use muninn_contracts::{MUNINN_HID_CONTROLLER_STATE_SCHEMA, MuninnHidControllerStateRecord}; use odin_core::{ EVE_PROVIDER_ADVERTISEMENT_SCHEMA, EveProviderAdvertisementRecord, EveSurfaceStateRecord, - IdunnDaemonHealthRecord, MUNINN_HID_CONTROLLER_STATE_SCHEMA, MuninnHidControllerStateRecord, - OdinDocuments, OdinEndpointQuery, SleipnirInputMappingRecord, discover_provider_endpoints, + IdunnDaemonHealthRecord, OdinDocuments, OdinEndpointQuery, SleipnirInputMappingRecord, + discover_provider_endpoints, }; use std::collections::HashMap; use std::env; From b2014284d1731c27abe8f8185b3e17f6127cb26a Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 29 Sep 2026 23:34:35 +0200 Subject: [PATCH 37/44] muninn-contracts: pin that a defaulted tail decodes from an older payload The wire-layout goldens set every field, so dropping `default` from a record's tail survived them. Adds a test that decodes an eight-element hue program payload and expects the defaulted tail. Co-Authored-By: Claude Opus 5.5 --- crates/muninn-contracts/src/lib.rs | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/crates/muninn-contracts/src/lib.rs b/crates/muninn-contracts/src/lib.rs index 0ec0605..fb312ef 100644 --- a/crates/muninn-contracts/src/lib.rs +++ b/crates/muninn-contracts/src/lib.rs @@ -170,6 +170,25 @@ mod tests { ); } + #[test] + fn hue_program_from_an_older_payload_defaults_its_tail() { + let older = decode_hex( + "98a470726f67a5726176656ea56379636c6514ff00a56d696d6972a6756e69783a31", + ); + let record: MuninnMoveHueProgramRecord = rmp_serde::from_slice(&older).unwrap(); + assert_eq!(record.updated_at, "unix:1"); + assert_eq!(record.order_mode, ""); + assert_eq!(record.transition_percent, 0); + assert!(!record.transition_percent_explicit); + } + + fn decode_hex(text: &str) -> Vec { + (0..text.len()) + .step_by(2) + .map(|index| u8::from_str_radix(&text[index..index + 2], 16).unwrap()) + .collect() + } + fn hex(bytes: &[u8]) -> String { bytes.iter().map(|byte| format!("{byte:02x}")).collect() } From 139ca7397fffe5502aea2e1300e7c8a5ccf76328 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Wed, 30 Sep 2026 00:17:50 +0200 Subject: [PATCH 38/44] muninn-contracts: pin every record's wire bytes and every defaulted key One table, 15 records: each encodes to its pinned positional MessagePack array (dropped, swapped, retyped keys change the bytes), and every record with a defaulted tail decodes from a payload that ends before each defaulted key, one truncation per key, reading the rest as zero values. Replaces the two hand-written hid and hue tests and the single hue truncation. Co-Authored-By: Claude Sonnet 5.5 --- crates/muninn-contracts/src/lib.rs | 465 ++++++++++++++++++++++++----- 1 file changed, 398 insertions(+), 67 deletions(-) diff --git a/crates/muninn-contracts/src/lib.rs b/crates/muninn-contracts/src/lib.rs index fb312ef..e111ae5 100644 --- a/crates/muninn-contracts/src/lib.rs +++ b/crates/muninn-contracts/src/lib.rs @@ -118,75 +118,406 @@ mod tests { } } + /// One wire pin per record. `bytes` is the record's positional MessagePack + /// array, encoded from a sample whose every field holds a distinct, + /// non-default value (Options: one `None`, one `Some`). `first_default` is + /// the key of the first defaulted tail field; records without one carry + /// `None`. + struct Pin { + record: &'static str, + bytes: Vec, + first_default: Option, + golden: &'static str, + /// Decode a payload as this record and encode it again. + reencode: fn(&[u8]) -> Result, String>, + } + + fn pin( + record: &'static str, + sample: T, + first_default: Option, + golden: &'static str, + ) -> Pin + where + T: serde::Serialize + serde::de::DeserializeOwned, + { + Pin { + record, + bytes: rmp_serde::to_vec(&sample).unwrap(), + first_default, + golden, + reencode: |bytes| { + let decoded: T = rmp_serde::from_slice(bytes).map_err(|error| error.to_string())?; + rmp_serde::to_vec(&decoded).map_err(|error| error.to_string()) + }, + } + } + + fn text(value: &str) -> String { + value.to_string() + } + + fn texts(values: &[&str]) -> Vec { + values.iter().map(|value| value.to_string()).collect() + } + + fn pins() -> Vec { + vec![ + pin( + "MuninnTelemetrySurfaceRecord", + MuninnTelemetrySurfaceRecord { + surface_id: text("surface"), + host_id: text("host"), + state: text("live"), + available_sources: texts(&["src"]), + stream_affordances: texts(&["aff"]), + active_streams: texts(&["act"]), + activation_authority: text("auth"), + detail: text("detail"), + updated_at: text("t"), + primary_stream_id: text("psid"), + primary_stream_label: text("plabel"), + command_rudp_target: text("cmd"), + media_target_host: text("mth"), + media_port: 4001, + media_packet_bytes: 1200, + rudp_video_bitrate_kbps: 8000, + rudp_latency_budget_ms: 40, + video_source_ids: texts(&["vid"]), + video_source_labels: texts(&["vlab"]), + audio_source_ids: texts(&["aid"]), + audio_source_labels: texts(&["alab"]), + }, + Some(9), + "dc0015a773757266616365a4686f7374a46c69766591a373726391a361666691a3616374a461757468a664657461696ca174a470736964a6706c6162656ca3636d64a36d7468cd0fa1cd04b0cd1f402891a376696491a4766c616291a361696491a4616c6162", + ), + pin( + "MuninnCaptureStreamRecord", + MuninnCaptureStreamRecord { + stream_id: text("stream"), + host_id: text("host"), + state: text("live"), + video_source: text("vsrc"), + audio_source: text("asrc"), + transport: text("rudp"), + targets: texts(&["tgt"]), + command_witness: text("wit"), + supervisor_pid: None, + mux_pid: Some(77), + restart_count: 3, + detail: text("detail"), + updated_at: text("t"), + }, + None, + "9da673747265616da4686f7374a46c697665a476737263a461737263a47275647091a3746774a3776974c04d03a664657461696ca174", + ), + pin( + "MuninnCaptureStreamCommandRecord", + MuninnCaptureStreamCommandRecord { + command_id: text("cmd"), + host_id: text("host"), + stream_id: text("stream"), + state: text("live"), + action: text("start"), + target_host: text("tgt"), + port: 4001, + obs_target_host: Some(text("obs")), + obs_port: 4002, + media_transport: text("rudp"), + media_packet_bytes: 1200, + requested_by: text("who"), + detail: text("detail"), + updated_at: text("t"), + rudp_video_bitrate_kbps: 8000, + rudp_latency_budget_ms: 40, + video_source_id: text("vid"), + audio_source_id: text("aid"), + }, + Some(14), + "dc0012a3636d64a4686f7374a673747265616da46c697665a57374617274a3746774cd0fa1a36f6273cd0fa2a472756470cd04b0a377686fa664657461696ca174cd1f4028a3766964a3616964", + ), + pin( + "MuninnObsStreamCatalogRecord", + MuninnObsStreamCatalogRecord { + catalog_id: text("catalog"), + host_id: text("host"), + stream_ids: texts(&["sid"]), + labels: texts(&["lab"]), + urls: texts(&["url"]), + states: texts(&["st"]), + updated_at: text("t"), + command_rudp_target: text("cmd"), + media_target_host: text("mth"), + media_port: 4001, + media_packet_bytes: 1200, + rudp_video_bitrate_kbps: 8000, + rudp_latency_budget_ms: 40, + video_source_ids: texts(&["vid"]), + video_source_labels: texts(&["vlab"]), + audio_source_ids: texts(&["aid"]), + audio_source_labels: texts(&["alab"]), + }, + Some(7), + "dc0011a7636174616c6f67a4686f737491a373696491a36c616291a375726c91a27374a174a3636d64a36d7468cd0fa1cd04b0cd1f402891a376696491a4766c616291a361696491a4616c6162", + ), + pin( + "MuninnMoveMarkerCandidateRecord", + MuninnMoveMarkerCandidateRecord { + stream_id: text("stream"), + host_id: text("host"), + camera_id: text("cam"), + frame_sequence: 11, + source_id_hash: 12, + tile_x: 13, + tile_y: 14, + center_x_px: 1.5, + center_y_px: 2.5, + radius_px: 3.5, + area_px: 15, + mean_luma: 4.5, + peak_luma: 16, + score: 0.5, + observed_at: text("t"), + move_id: text("move"), + }, + Some(15), + "dc0010a673747265616da4686f7374a363616d0b0c0d0eca3fc00000ca40200000ca406000000fca4090000010ca3f000000a174a46d6f7665", + ), + pin( + "MuninnMoveControllerStateRecord", + MuninnMoveControllerStateRecord { + stream_id: text("stream"), + host_id: text("host"), + move_id: text("move"), + sequence: 21, + source_timestamp_ns: -22, + accelerometer_xyz: vec![1.0, 2.0, 3.0], + gyroscope_xyz: vec![4.0, 5.0, 6.0], + magnetometer_xyz: vec![7.0, 8.0, 9.0], + trigger_value: 0.25, + buttons: texts(&["cross"]), + battery01: 0.75, + observed_at: text("t"), + source_path: text("/dev/js0"), + }, + Some(12), + "9da673747265616da4686f7374a46d6f766515ea93ca3f800000ca40000000ca4040000093ca40800000ca40a00000ca40c0000093ca40e00000ca41000000ca41100000ca3e80000091a563726f7373ca3f400000a174a82f6465762f6a7330", + ), + pin( + "MuninnHidControllerStateRecord", + MuninnHidControllerStateRecord { + stream_id: text("muninn.raven.hid"), + host_id: text("raven"), + device_id: text("xbox-0"), + device_kind: text("xinput"), + sequence: 7, + source_timestamp_ns: -3, + axes: vec![0.5, -1.0], + buttons: texts(&["a", "b"]), + battery01: 1.0, + observed_at: text("unix:100"), + source_path: text("xinput://0"), + }, + None, + "9bb06d756e696e6e2e726176656e2e686964a5726176656ea678626f782d30a678696e70757407fd92ca3f000000cabf80000092a161a162ca3f800000a8756e69783a313030aa78696e7075743a2f2f30", + ), + pin( + "MuninnMoveIdentityRecord", + MuninnMoveIdentityRecord { + identity_id: text("identity"), + host_id: text("host"), + move_id: text("move"), + source_path: text("path"), + bluetooth_host_address: text("bt"), + state: text("live"), + detail: text("detail"), + observed_at: text("t"), + }, + None, + "98a86964656e74697479a4686f7374a46d6f7665a470617468a26274a46c697665a664657461696ca174", + ), + pin( + "MuninnMoveLightCommandRecord", + MuninnMoveLightCommandRecord { + command_id: text("cmd"), + host_id: text("host"), + move_id: text("move"), + hidraw_path: text("hidraw"), + colors: texts(&["red"]), + durations_ms: vec![100, 200], + repeat_count: 5, + authority: text("auth"), + state: text("live"), + detail: text("detail"), + updated_at: text("t"), + }, + None, + "9ba3636d64a4686f7374a46d6f7665a668696472617791a37265649264ccc805a461757468a46c697665a664657461696ca174", + ), + pin( + "MuninnMoveHueProgramRecord", + MuninnMoveHueProgramRecord { + program_id: text("prog"), + host_id: text("raven"), + mode: text("cycle"), + cycle_ms: 20, + epoch_ns: -1, + hold_at_ns: 0, + requested_by: text("mimir"), + updated_at: text("unix:1"), + order_mode: text("ring"), + transition_percent: 50, + transition_percent_explicit: true, + }, + Some(8), + "9ba470726f67a5726176656ea56379636c6514ff00a56d696d6972a6756e69783a31a472696e6732c3", + ), + pin( + "MuninnMoveTrackerHealthRecord", + MuninnMoveTrackerHealthRecord { + health_id: text("health"), + host_id: text("host"), + camera_id: text("cam"), + camera_index: -2, + state: text("live"), + camera_name: text("name"), + camera_api: text("api"), + width: 640, + height: 480, + exposure: 0.5, + calibrated_controller_count: 2, + update_count: 30, + observation_count: 31, + latest_observation_count: 32, + last_observation_at: text("last"), + detail: text("detail"), + updated_at: text("t"), + image_mean_rgb: vec![1, 2, 3], + image_peak_rgb: vec![4, 5, 6], + color_evidence_move_ids: texts(&["move"]), + color_evidence_pixel_counts: vec![40], + rejected_stale_count: 41, + rejected_radius_count: 42, + rejected_bounds_count: 43, + rejected_continuity_count: 44, + }, + Some(17), + "dc0019a66865616c7468a4686f7374a363616dfea46c697665a46e616d65a3617069cd0280cd01e0ca3f000000021e1f20a46c617374a664657461696ca174930102039304050691a46d6f76659128292a2b2c", + ), + pin( + "MuninnMoveEvidenceTransportHealthRecord", + MuninnMoveEvidenceTransportHealthRecord { + health_id: text("health"), + host_id: text("host"), + stream_id: text("stream"), + produced_frames: 50, + local_ring_admissions: 51, + remote_handoffs: 52, + remote_sends: 53, + updated_at: text("t"), + }, + None, + "98a66865616c7468a4686f7374a673747265616d32333435a174", + ), + pin( + "MuninnQuestAccessRecord", + MuninnQuestAccessRecord { + access_id: text("access"), + host_id: text("host"), + serial: text("serial"), + connection_state: text("conn"), + product: text("product"), + model: text("model"), + device: text("device"), + transport_id: text("tid"), + input_stream_id: text("input"), + pose_stream_id: text("pose"), + video_input_stream_id: text("video"), + video_input_transport: text("vtransport"), + state: text("live"), + detail: text("detail"), + observed_at: text("t"), + }, + None, + "9fa6616363657373a4686f7374a673657269616ca4636f6e6ea770726f64756374a56d6f64656ca6646576696365a3746964a5696e707574a4706f7365a5766964656faa767472616e73706f7274a46c697665a664657461696ca174", + ), + pin( + "MuninnCommandBoundaryCompatRecord", + MuninnCommandBoundaryCompatRecord { + value: serde_json::json!({ "daemon_id": "muninn" }), + }, + None, + "9181a96461656d6f6e5f6964a66d756e696e6e", + ), + pin( + "MuninnTransportProfileCompatRecord", + MuninnTransportProfileCompatRecord { + value: serde_json::json!({ "state": "live" }), + }, + None, + "9181a57374617465a46c697665", + ), + ] + } + + /// Every record's bytes are exactly the pinned positional array: a swapped + /// key, a changed type or a moved field changes them. #[test] - fn hid_controller_state_wire_layout_is_positional_by_key() { - let record = MuninnHidControllerStateRecord { - stream_id: "muninn.raven.hid".into(), - host_id: "raven".into(), - device_id: "xbox-0".into(), - device_kind: "xinput".into(), - sequence: 7, - source_timestamp_ns: -3, - axes: vec![0.5, -1.0], - buttons: vec!["a".into(), "b".into()], - battery01: 1.0, - observed_at: "unix:100".into(), - source_path: "xinput://0".into(), + fn every_record_encodes_to_its_pinned_positional_bytes() { + let mut wrong = Vec::new(); + for pin in pins() { + let actual = hex(&pin.bytes); + if actual != pin.golden { + wrong.push(format!("{}: {actual}", pin.record)); + } + let reencoded = (pin.reencode)(&pin.bytes) + .unwrap_or_else(|error| panic!("{} does not decode its own bytes: {error}", pin.record)); + assert_eq!(reencoded, pin.bytes, "{} round trip", pin.record); + } + assert!( + wrong.is_empty(), + "unpinned or moved wire layouts:\n{}", + wrong.join("\n") + ); + } + + /// A payload written before a defaulted key existed still decodes, once + /// per defaulted key, and every key from there on reads as its zero value. + #[test] + fn every_defaulted_tail_key_decodes_from_a_payload_that_ends_before_it() { + use serde_json::Value; + let is_zero = |value: &Value| match value { + Value::Null => true, + Value::Bool(flag) => !flag, + Value::Number(number) => number.as_f64() == Some(0.0), + Value::String(text) => text.is_empty(), + Value::Array(items) => items.is_empty(), + Value::Object(_) => false, }; - let bytes = rmp_serde::to_vec(&record).unwrap(); - assert_eq!( - hex(&bytes), - "9bb06d756e696e6e2e726176656e2e686964a5726176656ea678626f782d30a678696e70757407fd92ca3f000000cabf80000092a161a162ca3f800000a8756e69783a313030aa78696e7075743a2f2f30" - ); - assert_eq!( - rmp_serde::from_slice::(&bytes).unwrap(), - record - ); - } - - #[test] - fn hue_program_wire_layout_carries_its_defaulted_tail() { - let record = MuninnMoveHueProgramRecord { - program_id: "prog".into(), - host_id: "raven".into(), - mode: "cycle".into(), - cycle_ms: 20, - epoch_ns: -1, - hold_at_ns: 0, - requested_by: "mimir".into(), - updated_at: "unix:1".into(), - order_mode: "ring".into(), - transition_percent: 50, - transition_percent_explicit: true, - }; - let bytes = rmp_serde::to_vec(&record).unwrap(); - assert_eq!( - hex(&bytes), - "9ba470726f67a5726176656ea56379636c6514ff00a56d696d6972a6756e69783a31a472696e6732c3" - ); - assert_eq!( - rmp_serde::from_slice::(&bytes).unwrap(), - record - ); - } - - #[test] - fn hue_program_from_an_older_payload_defaults_its_tail() { - let older = decode_hex( - "98a470726f67a5726176656ea56379636c6514ff00a56d696d6972a6756e69783a31", - ); - let record: MuninnMoveHueProgramRecord = rmp_serde::from_slice(&older).unwrap(); - assert_eq!(record.updated_at, "unix:1"); - assert_eq!(record.order_mode, ""); - assert_eq!(record.transition_percent, 0); - assert!(!record.transition_percent_explicit); - } - - fn decode_hex(text: &str) -> Vec { - (0..text.len()) - .step_by(2) - .map(|index| u8::from_str_radix(&text[index..index + 2], 16).unwrap()) - .collect() + for pin in pins() { + let Some(first_default) = pin.first_default else { + continue; + }; + let full: Vec = rmp_serde::from_slice(&pin.bytes).unwrap(); + for end in first_default..full.len() { + let truncated = rmp_serde::to_vec(&full[..end]).unwrap(); + let decoded = (pin.reencode)(&truncated).unwrap_or_else(|error| { + panic!( + "{} does not decode a payload ending before key {end}: {error}", + pin.record + ) + }); + let decoded: Vec = rmp_serde::from_slice(&decoded).unwrap(); + assert_eq!(decoded.len(), full.len(), "{} ending before key {end}", pin.record); + assert_eq!(&decoded[..end], &full[..end], "{} ending before key {end}", pin.record); + assert!( + decoded[end..].iter().all(is_zero), + "{} ending before key {end} defaulted to {:?}", + pin.record, + &decoded[end..] + ); + } + } } fn hex(bytes: &[u8]) -> String { From 2742b4ddcf880f67856e5857bf690dc179464a5e Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Wed, 30 Sep 2026 00:17:51 +0200 Subject: [PATCH 39/44] Correct stale health text, pin per-host boundary identity, note deploy order The MuninnRecords comment claimed muninn-contracts decides every muninn.* binding; today odin-core registers identical strings first and the registration is inert until Odin deletes its copies. The help text no longer describes the retired --idunn flags, the health-*.cmd stubs no longer claim daemon-published health, and docs/muninn.md says to install the binary and the scripts together. A test now pins daemon_id, state and current_transport for raven, starfire and nightwing. Co-Authored-By: Claude Sonnet 5.5 --- crates/muninn-daemon/src/main.rs | 71 +++++++++++++++++++++++++++-- docs/muninn.md | 5 ++ scripts/health-muninn.cmd | 2 +- scripts/health-nightwing-muninn.cmd | 2 +- scripts/health-starfire-muninn.cmd | 2 +- 5 files changed, 74 insertions(+), 8 deletions(-) diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index cf8e119..b2d21ca 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -9527,10 +9527,13 @@ fn ensure_state_dirs(options: &Options) -> Result<()> { } /// Odin's document set, Muninn's own records, and the producer-agnostic media -/// stream contract. Muninn's records are registered after Odin's, so -/// `muninn-contracts` decides every `muninn.*` binding; Odin's document set -/// still carries stale copies of the same schema ids (and the store may hold -/// legacy Odin records), which is why it stays registered. +/// stream contract. Today Odin's document set (odin-core) is registered first +/// and carries identical `muninn.*` type names and schema ids, so +/// `MuninnRecords` registers the same strings again and binds nothing new; +/// cultcache errors at startup if the two ever diverge. Odin's copies are to be +/// deleted, at which point `muninn-contracts` becomes the sole owner of every +/// `muninn.*` binding. The registration stays so that deletion changes nothing +/// here. #[derive(Clone, Copy, Debug, Default)] struct MuninnDocuments; @@ -10180,7 +10183,7 @@ fn parse_move_marker_camera_source(value: &str) -> Result &'static str { - "Usage: muninn [serve|activate|request-stream|capture-stream-status|obs-catalog-status|request-move-light|move-light-status|move-identity-status|move-source-status|move-state-status|claim-move-host|quest-access-status] [--store ] [--activate-store ] [--stream-action ] [--target-host ] [--media-transport ] [--media-rudp-bind ] [--media-rudp-advertise ] [--media-packet-bytes ] [--rudp-video-bitrate-kbps ] [--rudp-latency-budget-ms ] [--video-source ] [--audio-source ] [--audio-source-id ] [--no-video] [--no-audio] [--loopback-script ] [--ffmpeg ] [--odin-cultmesh-uri ] [--move-state =] [--move-marker-camera =] [--move-psmoveapi-tracker] [--move-tracker-exposure-milli <0..1000>] [--move-marker-width ] [--move-marker-height ] [--move-marker-fps ] [--move-host ] [--move-evidence-stream ] [--move-evidence-verse ] [--move-evidence-ring-slots ] [--move-evidence-slot-bytes ] [--move-evidence-snapshot ] [--quest-adb] [--quest-serial ] [--quest-input-stream ] [--quest-pose-stream ] [--quest-video-input-stream ] [--dry-run] [--health]\n\nMuninn is Odin's portable telemetry Verse assembler. serve publishes cheap typed telemetry affordances, optional Quest USB access surfaces, and the explicitly configured Move runtime; when serve receives --move-state, --move-marker-camera, --move-host, or --move-evidence-stream it may publish source-local Move controller state, source-local optical marker candidates, typed Move identity records, a CultMesh Move evidence stream, optionally write a latest one-copy Move proof evidence snapshot for Mimir field capture/replay, and keep USB-attached PS Moves claimed to that explicit Bluetooth host; --move-psmoveapi-tracker delegates camera exposure and optical extraction to the reference PSMoveAPI backend while Muninn retains stable-ID light actuation; serve consumes typed capture stream commands from its provider-owned activation store and owns the local ffmpeg/loopback activation child lifecycle, listens for media receivers on --media-rudp-bind and advertises that endpoint (--media-rudp-advertise when the bind address is not reachable as-is), and publishes its discovery advertisement through --odin-cultmesh-uri; activate starts an explicitly requested local CultNet RUDP stream as a daemon child that serves every receiver dialling --media-rudp-bind; request-stream discovers the provider through Odin and sends its typed command to that provider; obs-catalog-status pulls Odin-owned muninn.obs_stream_catalog discovery into the local compatibility store for OBS; capture-stream-status reads typed capture stream command receipts; use --no-video or --no-audio to request one leg over the CultNet RUDP media lane; request-move-light publishes a typed Move light command for Muninn serve to execute; move-light-status reads typed command receipts; move-identity-status reads typed Move identity records; move-source-status prints live Move source discovery; move-state-status reads typed controller-state records; claim-move-host assigns USB-attached PS Moves to a Bluetooth host; quest-access-status reads typed Quest access state. In --health mode, the Idunn RUDP flags publish the same typed daemon health document to Idunn for explicit diagnostics." + "Usage: muninn [serve|activate|request-stream|capture-stream-status|obs-catalog-status|request-move-light|move-light-status|move-identity-status|move-source-status|move-state-status|claim-move-host|quest-access-status] [--store ] [--activate-store ] [--stream-action ] [--target-host ] [--media-transport ] [--media-rudp-bind ] [--media-rudp-advertise ] [--media-packet-bytes ] [--rudp-video-bitrate-kbps ] [--rudp-latency-budget-ms ] [--video-source ] [--audio-source ] [--audio-source-id ] [--no-video] [--no-audio] [--loopback-script ] [--ffmpeg ] [--odin-cultmesh-uri ] [--move-state =] [--move-marker-camera =] [--move-psmoveapi-tracker] [--move-tracker-exposure-milli <0..1000>] [--move-marker-width ] [--move-marker-height ] [--move-marker-fps ] [--move-host ] [--move-evidence-stream ] [--move-evidence-verse ] [--move-evidence-ring-slots ] [--move-evidence-slot-bytes ] [--move-evidence-snapshot ] [--quest-adb] [--quest-serial ] [--quest-input-stream ] [--quest-pose-stream ] [--quest-video-input-stream ] [--dry-run] [--health]\n\nMuninn is Odin's portable telemetry Verse assembler. serve publishes cheap typed telemetry affordances, optional Quest USB access surfaces, and the explicitly configured Move runtime; when serve receives --move-state, --move-marker-camera, --move-host, or --move-evidence-stream it may publish source-local Move controller state, source-local optical marker candidates, typed Move identity records, a CultMesh Move evidence stream, optionally write a latest one-copy Move proof evidence snapshot for Mimir field capture/replay, and keep USB-attached PS Moves claimed to that explicit Bluetooth host; --move-psmoveapi-tracker delegates camera exposure and optical extraction to the reference PSMoveAPI backend while Muninn retains stable-ID light actuation; serve consumes typed capture stream commands from its provider-owned activation store and owns the local ffmpeg/loopback activation child lifecycle, listens for media receivers on --media-rudp-bind and advertises that endpoint (--media-rudp-advertise when the bind address is not reachable as-is), and publishes its discovery advertisement through --odin-cultmesh-uri; activate starts an explicitly requested local CultNet RUDP stream as a daemon child that serves every receiver dialling --media-rudp-bind; request-stream discovers the provider through Odin and sends its typed command to that provider; obs-catalog-status pulls Odin-owned muninn.obs_stream_catalog discovery into the local compatibility store for OBS; capture-stream-status reads typed capture stream command receipts; use --no-video or --no-audio to request one leg over the CultNet RUDP media lane; request-move-light publishes a typed Move light command for Muninn serve to execute; move-light-status reads typed command receipts; move-identity-status reads typed Move identity records; move-source-status prints live Move source discovery; move-state-status reads typed controller-state records; claim-move-host assigns USB-attached PS Moves to a Bluetooth host; quest-access-status reads typed Quest access state." } fn parse_move_state_source(value: &str) -> Result { @@ -12665,6 +12668,64 @@ Device 00:07:04:A8:00:D0 (public) let _ = fs::remove_file(store_path); } + #[test] + fn help_names_no_retired_health_flag() { + assert!(!help_text().contains("--idunn")); + assert!(!help_text().contains("daemon health")); + } + + #[test] + fn runtime_boundary_names_each_host_daemon_and_its_transport() { + for (host, daemon_id) in [ + ("raven", "muninn"), + ("starfire", "starfire-muninn"), + ("nightwing", "nightwing-muninn"), + ] { + let store_path = std::env::temp_dir().join(format!( + "muninn-boundary-{host}-{}.cc", + timestamp_ns().unwrap() + )); + let options = Options::parse( + ["serve", "--host", host, "--store", store_path.to_str().unwrap()] + .into_iter() + .map(String::from), + ) + .unwrap(); + let mut node = open_node(&options, "muninn-boundary-host-test").unwrap(); + + publish_runtime_boundary_records(&mut node, &options, "idle", &[], &[]).unwrap(); + + let boundary = node + .get_required::(&format!( + "command-boundary:{daemon_id}" + )) + .unwrap(); + let transport = node + .get_required::(&format!( + "transport-profile:{daemon_id}" + )) + .unwrap(); + for record in [&boundary.value, &transport.value] { + assert_eq!( + record.get("daemon_id").and_then(|value| value.as_str()), + Some(daemon_id), + "{host}" + ); + } + assert_eq!( + transport.value.get("current_transport").and_then(|value| value.as_str()), + Some("daemon-owned-cultcache-telemetry-store"), + "{host}" + ); + assert_eq!( + transport.value.get("state").and_then(|value| value.as_str()), + Some("cultcache-provider-store-only"), + "{host}" + ); + let _ = fs::remove_file(store_path); + } + } + #[test] fn runtime_boundary_records_use_explicit_activation_store_path() { let store_path = diff --git a/docs/muninn.md b/docs/muninn.md index bd9f5b5..b262640 100644 --- a/docs/muninn.md +++ b/docs/muninn.md @@ -239,6 +239,11 @@ separate `/dev/input/js*` paths; `nightwing-move-state-sources.sh` prefers the Bluetooth `HID_ID=0005:0000054C:000003D5` path so Idunn health does not demand fresh records from two faces of the same controller. +Starfire and Nightwing binaries and their `scripts/*-muninn.ps1` actuators +must be installed together: a binary that rejects the retired +`--idunn-rudp-health`, `--idunn-daemon` and `--idunn-health-contract` flags +fails to start under an old restart script, and a new script never passes them. + Each private PSMoveAPI Eye worker owns optical observation admission before the parent aggregates evidence. Positions older than 50 ms, blobs below 2 px, out-of-frame coordinates, implausible radius jumps, and frame-to-frame diff --git a/scripts/health-muninn.cmd b/scripts/health-muninn.cmd index 7811b7d..e2ddbe7 100644 --- a/scripts/health-muninn.cmd +++ b/scripts/health-muninn.cmd @@ -1,3 +1,3 @@ @echo off -echo health-muninn.cmd archived: Raven Muninn health is daemon-published over CultNet/RUDP as muninn.cultnet-rudp-remote-telemetry-health. Use health-muninn.ps1 only as an explicit witness inspection, not Idunn health truth. +echo health-muninn.cmd archived: Raven Muninn has no daemon-published health. Run health-muninn.ps1 as an explicit witness inspection (scheduled-task actions, serve process, store freshness); it is not Idunn health truth. exit /b 2 diff --git a/scripts/health-nightwing-muninn.cmd b/scripts/health-nightwing-muninn.cmd index 6b6554b..eede45d 100644 --- a/scripts/health-nightwing-muninn.cmd +++ b/scripts/health-nightwing-muninn.cmd @@ -1,3 +1,3 @@ @echo off -echo health-nightwing-muninn.cmd archived: Nightwing Muninn health is daemon-published over CultNet/RUDP as muninn.cultnet-rudp-remote-telemetry-and-move-hid. Use health-nightwing-muninn.ps1 only as an explicit witness inspection, not Idunn health truth. +echo health-nightwing-muninn.cmd archived: Nightwing Muninn has no daemon-published health. Run health-nightwing-muninn.ps1 as an explicit witness inspection (serve process, store freshness, PID file); it is not Idunn health truth. exit /b 2 diff --git a/scripts/health-starfire-muninn.cmd b/scripts/health-starfire-muninn.cmd index 36d421c..db26de6 100644 --- a/scripts/health-starfire-muninn.cmd +++ b/scripts/health-starfire-muninn.cmd @@ -1,3 +1,3 @@ @echo off -echo health-starfire-muninn.cmd archived: Starfire Muninn health is daemon-published over CultNet/RUDP as muninn.cultnet-rudp-local-telemetry-and-quest-access. Use health-starfire-muninn.ps1 only as an explicit witness inspection, not Idunn health truth. +echo health-starfire-muninn.cmd archived: Starfire Muninn has no daemon-published health. Run health-starfire-muninn.ps1 as an explicit witness inspection (serve process, store freshness, PID file); it is not Idunn health truth. exit /b 2 From 344de9f9a1ca21b33cb3af1ca463819378d2a955 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Thu, 22 Oct 2026 20:17:52 +0200 Subject: [PATCH 40/44] Quarantine Muninn's Eve operator surfaces: move-hue and input-mirror dashboards, Eve command ingress Parked at tag parked/Muninn-eve-surface per thing2:ruling:eve-dashboards-quarantined. Provider advertisements and the Odin provider lease stay; their surfaces entries go. --command-rudp-bind is rejected as removed. Co-Authored-By: Claude Sonnet 5.5 --- crates/muninn-daemon/src/main.rs | 484 +----------------------- crates/sleipnir-daemon/src/main.rs | 538 +-------------------------- scripts/restart-nightwing-muninn.ps1 | 3 +- 3 files changed, 12 insertions(+), 1013 deletions(-) diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index b2d21ca..5e7f8f2 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -34,7 +34,7 @@ use muninn_contracts::{ }; #[cfg(feature = "psmoveapi-tracker")] use muninn_contracts::MuninnMoveTrackerHealthRecord; -use odin_core::{EveProviderAdvertisementRecord, EveSurfaceStateRecord, OdinDocuments}; +use odin_core::{EveProviderAdvertisementRecord, OdinDocuments}; use serde::{Deserialize, Serialize}; use serde_json::json; use std::collections::{HashMap, HashSet}; @@ -72,7 +72,6 @@ use windows_sys::Win32::UI::Input::XboxController::{XINPUT_GAMEPAD, XINPUT_STATE const CULTNET_RUDP_PROTOCOL_ID: &str = "cultnet.transport.rudp.v0"; const MUNINN_MEDIA_RUDP_CONNECTION_ID: u32 = 0x6d75_0001; const MUNINN_HID_CONTROLLER_RUDP_CONNECTION_ID: u32 = 0x6d75_0005; -const MUNINN_COMMAND_RUDP_CONNECTION_ID: u32 = 0x61e0_0001; const MUNINN_RUDP_MEDIA_PROFILE_ID: &str = "muninn.rudp.low_latency_h264_lan.v1"; const MUNINN_RUDP_MEDIA_VIDEO_BITRATE_KBPS: u32 = 12_000; const MUNINN_RUDP_MEDIA_VBV_FRAME_BUDGETS: u32 = 1; @@ -217,7 +216,6 @@ struct Options { hid_controller_rudp_target: Option, hid_controller_rudp_bind: Option, hid_controller_rudp_advertise: Option, - command_rudp_bind: Option, command_rudp_advertise: Option, hid_controller_receipt_retention_seconds: u64, } @@ -433,7 +431,6 @@ fn serve(options: Options) -> Result<()> { ); } start_move_hue_program_sync_worker(&options, Arc::clone(&move_hue_program)); - start_provider_command_ingress(&options, Arc::clone(&move_hue_program))?; start_odin_provider_lease_worker(&options); let mut answered_requests: HashMap = HashMap::new(); @@ -607,10 +604,6 @@ fn move_hue_program_key(host_id: &str) -> String { format!("muninn:{host_id}:move-hue-program") } -fn move_hue_surface_key(host_id: &str) -> String { - format!("surface:muninn.telemetry.{host_id}.move-hue") -} - fn load_or_initialize_move_hue_program( options: &Options, ) -> Result>> { @@ -720,135 +713,6 @@ fn start_move_hue_program_sync_worker( }); } -fn start_provider_command_ingress( - options: &Options, - runtime_program: Arc>, -) -> Result<()> { - let Some(bind) = options.command_rudp_bind else { - return Ok(()); - }; - let socket = UdpSocket::bind(bind) - .with_context(|| format!("binding Muninn provider command route at {bind}"))?; - socket.set_read_timeout(Some(Duration::from_millis(5)))?; - let options = options.clone(); - thread::spawn(move || { - if let Err(error) = run_provider_command_ingress(socket, options, runtime_program) { - eprintln!("Muninn provider command ingress stopped: {error:#}"); - } - }); - Ok(()) -} - -fn run_provider_command_ingress( - socket: UdpSocket, - options: Options, - runtime_program: Arc>, -) -> Result<()> { - let mut transport = - CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { - media_delivery: None, - runtime_id: format!("muninn-{}-command-ingress", options.host_id), - socket, - mode: cultnet_rs::CultNetRudpSocketMode::Server, - remote_addr: None, - connection_id: MUNINN_COMMAND_RUDP_CONNECTION_ID, - initial_sequence: 1, - resend_delay_ms: 15, - transport_id: Some("muninn-provider-command-rudp".to_string()), - max_payload_bytes: None, - max_fragment_bytes: Some(1200), - max_pending_reliable_packets: Some(64), - media_reliable_expire_after_ms: None, - reconnect_policy: None, - })?; - loop { - if let Some(frame) = transport.receive_once()? - && frame.channel_id == "schema" - { - let message = decode_cultnet_message_from_slice( - &frame.payload, - CultNetWireContract::CultNetSchemaV0, - )?; - if let CultNetMessage::DocumentPutRaw { document, .. } = message { - apply_provider_command_document(&options, &runtime_program, document)?; - } - } - transport.poll_resends()?; - } -} - -fn apply_provider_command_document( - options: &Options, - runtime_program: &Arc>, - document: CultNetRawDocumentRecord, -) -> Result<()> { - if document.schema_id != "gamecult.eve.command.v1" { - return Ok(()); - } - let value: serde_json::Value = match document.payload_encoding { - CultNetRawPayloadEncoding::Messagepack => rmp_serde::from_slice(&document.payload)?, - }; - let command_type = value - .get("command") - .or_else(|| value.get("type")) - .and_then(serde_json::Value::as_str) - .unwrap_or_default(); - if command_type != "muninn.set-move-hue-program" { - return Ok(()); - } - let payload = value - .get("payload") - .filter(|payload| payload.is_object()) - .unwrap_or(&value); - let provider_id = value - .get("providerId") - .and_then(serde_json::Value::as_str) - .unwrap_or_default(); - if provider_id != muninn_provider_id(options) { - return Err(anyhow!( - "Move hue command targets provider {provider_id}, not {}", - muninn_provider_id(options) - )); - } - let mut program = runtime_program - .lock() - .map_err(|_| anyhow!("Move hue runtime program lock is poisoned"))? - .clone(); - if let Some(mode) = payload.get("mode").and_then(serde_json::Value::as_str) { - program.mode = mode.to_string(); - if mode == "hold" { - program.hold_at_ns = timestamp_ns()?; - } - } - if let Some(order) = payload.get("orderMode").and_then(serde_json::Value::as_str) { - program.order_mode = order.to_string(); - } - if let Some(cycle_ms) = payload.get("cycleMs").and_then(serde_json::Value::as_u64) { - program.cycle_ms = cycle_ms; - } - if let Some(value) = payload - .get("transitionPercent") - .and_then(serde_json::Value::as_u64) - { - program.transition_percent = u8::try_from(value) - .map_err(|_| anyhow!("Move hue transitionPercent must be at most 100"))?; - program.transition_percent_explicit = true; - } - program.requested_by = value - .get("publishedBy") - .and_then(serde_json::Value::as_str) - .unwrap_or("eve-command") - .to_string(); - program.updated_at = timestamp()?; - validate_move_hue_program(&program)?; - let key = move_hue_program_key(&options.host_id); - open_node(options, "muninn-provider-command")?.put(&key, &program)?; - *runtime_program - .lock() - .map_err(|_| anyhow!("Move hue runtime program lock is poisoned"))? = program; - Ok(()) -} - const MUNINN_VIDEO_CODECS: [&str; 1] = ["h264"]; const MUNINN_AUDIO_CODECS: [&str; 1] = ["pcm-f32le-interleaved"]; @@ -2630,155 +2494,6 @@ fn publish_surface( }; node.put("latest", &record)?; node.put(&record.surface_id, &record)?; - publish_move_hue_eve_surface(node, options)?; - Ok(()) -} - -fn publish_move_hue_eve_surface( - node: &mut cultmesh_rs::CultMeshNode, - options: &Options, -) -> Result<()> { - let program_key = move_hue_program_key(&options.host_id); - let program = node - .get::(&program_key)? - .unwrap_or_else(|| bootstrap_move_hue_program(options)); - let provider_id = muninn_provider_id(options); - let surface_key = move_hue_surface_key(&options.host_id); - let action = |id: &str, - label: &str, - mode: Option<&str>, - order_mode: Option<&str>, - cycle_ms: Option, - transition_percent: Option| { - json!({ - "id": format!("{provider_id}.move-hue.{id}"), - "kind": "card", - "props": { - "title": label, - "commandId": "muninn.set-move-hue-program", - "action": { - "type": "muninn.set-move-hue-program", - "providerId": provider_id, - "programId": program_key, - "schema": MUNINN_MOVE_HUE_PROGRAM_SCHEMA, - "mode": mode, - "orderMode": order_mode, - "cycleMs": cycle_ms, - "transitionPercent": transition_percent - } - }, - "children": [] - }) - }; - let surface = EveSurfaceStateRecord { - provider_id: provider_id.clone(), - title: format!("Muninn {} Move Hue Program", options.host_id), - version: SystemTime::now() - .duration_since(UNIX_EPOCH) - .unwrap_or_default() - .as_millis() as i64, - updated_at: timestamp()?, - surface: json!({ - "schema": "gamecult.eve.surface.v1", - "id": format!("{provider_id}.move-hue.surface"), - "title": "Move Hue Program", - "root": { - "id": format!("{provider_id}.move-hue.root"), - "kind": "dashboard", - "props": { - "title": "Move Hue Program", - "summary": format!("{} / {} / {} ms / {}% transition", program.mode, program.order_mode, program.cycle_ms, effective_transition_percent(&program)) - }, - "children": [ - { - "id": format!("{provider_id}.move-hue.state"), - "kind": "pane", - "props": { "title": "State" }, - "children": [ - { "id": format!("{provider_id}.move-hue.state.mode"), "kind": "text", "props": { "text": format!("mode: {}", program.mode) } }, - { "id": format!("{provider_id}.move-hue.state.order"), "kind": "text", "props": { "text": format!("order: {}", program.order_mode) } }, - { "id": format!("{provider_id}.move-hue.state.rate"), "kind": "text", "props": { "text": format!("cycle: {} ms", program.cycle_ms) } }, - { "id": format!("{provider_id}.move-hue.state.transition"), "kind": "text", "props": { "text": format!("transition: {}%", effective_transition_percent(&program)) } } - ] - }, - { - "id": format!("{provider_id}.move-hue.mode"), - "kind": "pane", - "props": { "title": "Mode" }, - "children": [ - action("mode-animated", "Animate", Some("animated"), None, None, None), - action("mode-hold", "Hold Current Colors", Some("hold"), None, None, None), - action("mode-static", "Static Palette", Some("static"), None, None, None) - ] - }, - { - "id": format!("{provider_id}.move-hue.order"), - "kind": "pane", - "props": { "title": "Update Order" }, - "children": [ - action("order-descending", "Descending", None, Some("descending"), None, None), - action("order-ascending", "Ascending", None, Some("ascending"), None, None), - action("order-bounce", "Bounce", None, Some("bounce"), None, None), - action("order-rotating", "Rotating Lead", None, Some("rotating-lead"), None, None), - action("order-golden", "Golden Permutation", None, Some("golden-permutation"), None, None) - ] - }, - { - "id": format!("{provider_id}.move-hue.rate"), - "kind": "pane", - "props": { "title": "Cycle Rate" }, - "children": [ - action("rate-500", "2 Hz", None, None, Some(500), None), - action("rate-1000", "1 Hz", None, None, Some(1000), None), - action("rate-2000", "0.5 Hz", None, None, Some(2000), None) - ] - }, - { - "id": format!("{provider_id}.move-hue.transition"), - "kind": "pane", - "props": { "title": "Transition Duration" }, - "children": [ - action("transition-0", "Off", None, None, None, Some(0)), - action("transition-10", "10%", None, None, None, Some(10)), - action("transition-25", "25%", None, None, None, Some(25)), - action("transition-50", "50%", None, None, None, Some(50)), - action("transition-75", "75%", None, None, None, Some(75)), - action("transition-100", "100%", None, None, None, Some(100)) - ] - } - ] - } - }), - }; - node.put(&surface_key, &surface)?; - if let Some(target) = resolve_odin_cultmesh_uri(options) { - let _ = node.publish_document_to_rudp_catalog( - &program_key, - &program, - CultMeshRudpDocumentPublishOptions { - target, - runtime_id: muninn_daemon_id(options), - source_role: Some("muninn.move-hue-program-state".to_string()), - tags: vec!["muninn".to_string(), "move-hue-program".to_string()], - flush_timeout: Duration::from_millis(300), - resend_delay_ms: 15, - ..CultMeshRudpDocumentPublishOptions::default() - }, - ); - let _ = node.publish_document_to_rudp_catalog( - &surface_key, - &surface, - CultMeshRudpDocumentPublishOptions { - target, - runtime_id: muninn_daemon_id(options), - source_role: Some("muninn.move-hue-eve-surface".to_string()), - tags: vec!["muninn".to_string(), "eve-surface".to_string()], - flush_timeout: Duration::from_millis(300), - resend_delay_ms: 15, - ..CultMeshRudpDocumentPublishOptions::default() - }, - ); - } Ok(()) } @@ -2829,27 +2544,10 @@ fn publish_runtime_boundary_records( .clone() .unwrap_or_else(|| bind.to_string()) }); - let mut provider_routes = vec![json!({ + let provider_routes = vec![json!({ "transport": "cultcache-store", "address": options.store_path.display().to_string() })]; - if let Some(bind) = options.command_rudp_bind { - let address = options - .command_rudp_advertise - .clone() - .unwrap_or_else(|| bind.to_string()); - provider_routes.push(json!({ - "id": "muninn.provider.command", - "role": "muninn provider command ingress", - "uri": format!("cultmesh://{address}/muninn/{}/commands", options.host_id), - "transport": CULTNET_RUDP_PROTOCOL_ID, - "address": address, - "connectionId": MUNINN_COMMAND_RUDP_CONNECTION_ID, - "channel": "schema", - "schema": "gamecult.eve.command.v1", - "tags": ["muninn", "command", "provider-owned"] - })); - } let hid_controller_devices_snake = live_move_sources .iter() .map(|source| { @@ -3070,12 +2768,6 @@ fn publish_runtime_boundary_records( "endpoints": provider_endpoints, "inputStreams": provider_input_streams, "routes": provider_routes, - "surfaces": [{ - "surfaceId": format!("{provider_id}.move-hue.surface"), - "surfaceKind": "gamecult.eve.surface_state.v1", - "recordRef": move_hue_surface_key(&options.host_id), - "title": "Move Hue Program" - }], "commandSurface": { "commandBoundaryId": command_boundary_key, "transportProfileId": transport_profile_key @@ -9664,7 +9356,6 @@ impl Options { hid_controller_rudp_target: None, hid_controller_rudp_bind: None, hid_controller_rudp_advertise: None, - command_rudp_bind: None, command_rudp_advertise: None, hid_controller_receipt_retention_seconds: 3_600, }; @@ -9934,11 +9625,10 @@ impl Options { Some(take_value(&mut args, "--hid-controller-rudp-advertise")?) } "--command-rudp-bind" => { - options.command_rudp_bind = Some( - take_value(&mut args, "--command-rudp-bind")? - .parse() - .context("--command-rudp-bind must be a socket address")?, - ) + let _ = take_value(&mut args, "--command-rudp-bind")?; + return Err(anyhow!( + "--command-rudp-bind has been removed; the Eve command ingress was quarantined (tag parked/Muninn-eve-surface)" + )); } "--command-rudp-advertise" => { options.command_rudp_advertise = @@ -11560,42 +11250,6 @@ mod tests { ); } - #[test] - fn muninn_eve_surface_exposes_live_move_hue_program_controls() { - let store_path = std::env::temp_dir().join(format!( - "muninn-move-hue-eve-{}.cc", - timestamp_ns().unwrap() - )); - let options = Options::parse( - [ - "serve", - "--store", - store_path.to_str().unwrap(), - "--host", - "nightwing", - "--odin-cultmesh-uri", - "none", - ] - .into_iter() - .map(String::from), - ) - .unwrap(); - let _ = load_or_initialize_move_hue_program(&options).unwrap(); - let mut node = open_node(&options, "muninn-move-hue-eve-test").unwrap(); - publish_surface(&mut node, &options, "idle", &[]).unwrap(); - let surface = node - .get_required::(&move_hue_surface_key("nightwing")) - .unwrap(); - let encoded = surface.surface.to_string(); - assert!(encoded.contains("Hold Current Colors")); - assert!(encoded.contains("golden-permutation")); - assert!(encoded.contains("Transition Duration")); - assert!(encoded.contains("transitionPercent")); - assert!(encoded.contains(MUNINN_MOVE_HUE_PROGRAM_SCHEMA)); - drop(node); - let _ = fs::remove_file(store_path); - } - #[test] fn move_hue_program_command_updates_typed_live_state() { let store_path = std::env::temp_dir().join(format!( @@ -11635,115 +11289,6 @@ mod tests { let _ = fs::remove_file(store_path); } - #[test] - fn provider_command_rudp_ingress_applies_move_hue_command() { - let store_path = std::env::temp_dir().join(format!( - "muninn-provider-command-{}.cc", - timestamp_ns().unwrap() - )); - let options = Options::parse( - [ - "serve", - "--store", - store_path.to_str().unwrap(), - "--host", - "nightwing", - "--odin-cultmesh-uri", - "none", - ] - .into_iter() - .map(String::from), - ) - .unwrap(); - let runtime_program = load_or_initialize_move_hue_program(&options).unwrap(); - let server_socket = UdpSocket::bind("127.0.0.1:0").unwrap(); - server_socket - .set_read_timeout(Some(Duration::from_millis(5))) - .unwrap(); - let server_address = server_socket.local_addr().unwrap(); - let server_options = options.clone(); - let server_program = Arc::clone(&runtime_program); - thread::spawn(move || { - run_provider_command_ingress(server_socket, server_options, server_program).unwrap() - }); - - let client_socket = UdpSocket::bind("127.0.0.1:0").unwrap(); - client_socket - .set_read_timeout(Some(Duration::from_millis(5))) - .unwrap(); - let mut client = - CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions { - media_delivery: None, - runtime_id: "muninn-provider-command-test-client".to_string(), - socket: client_socket, - mode: cultnet_rs::CultNetRudpSocketMode::Client, - remote_addr: Some(server_address), - connection_id: MUNINN_COMMAND_RUDP_CONNECTION_ID, - initial_sequence: 1, - resend_delay_ms: 15, - transport_id: Some("muninn-provider-command-test".to_string()), - max_payload_bytes: None, - max_fragment_bytes: Some(1200), - max_pending_reliable_packets: Some(64), - media_reliable_expire_after_ms: None, - reconnect_policy: None, - }) - .unwrap(); - client.connect(Vec::new()).unwrap(); - let deadline = Instant::now() + Duration::from_secs(2); - while !client.connected() && Instant::now() < deadline { - let _ = client.receive_once().unwrap(); - client.poll_resends().unwrap(); - thread::sleep(Duration::from_millis(1)); - } - assert!(client.connected(), "provider command RUDP handshake"); - let command = json!({ - "type": "surface-command", - "schema": "gamecult.eve.command.v1", - "providerId": "muninn.telemetry.nightwing", - "command": "muninn.set-move-hue-program", - "payload": { - "type": "muninn.set-move-hue-program", - "mode": "hold", - "orderMode": "bounce", - "cycleMs": 1500, - "transitionPercent": 25 - }, - "publishedBy": "provider-command-test" - }); - let message = CultNetMessage::DocumentPutRaw { - message_id: "provider-command-test".to_string(), - document: CultNetRawDocumentRecord { - schema_id: "gamecult.eve.command.v1".to_string(), - record_key: "provider-command-test".to_string(), - stored_at: timestamp().unwrap(), - payload_encoding: CultNetRawPayloadEncoding::Messagepack, - payload: rmp_serde::to_vec_named(&command).unwrap(), - source_runtime_id: Some("provider-command-test".to_string()), - source_agent_id: None, - source_role: Some("test".to_string()), - tags: None, - }, - }; - client - .send( - "schema", - encode_cultnet_message_to_vec(&message, CultNetWireContract::CultNetSchemaV0) - .unwrap(), - ) - .unwrap(); - let apply_deadline = Instant::now() + Duration::from_secs(2); - while runtime_program.lock().unwrap().mode != "hold" && Instant::now() < apply_deadline { - client.poll_resends().unwrap(); - thread::sleep(Duration::from_millis(2)); - } - assert_eq!(runtime_program.lock().unwrap().mode, "hold"); - assert_eq!(runtime_program.lock().unwrap().order_mode, "bounce"); - assert_eq!(runtime_program.lock().unwrap().cycle_ms, 1500); - assert_eq!(runtime_program.lock().unwrap().transition_percent, 25); - let _ = fs::remove_file(store_path); - } - #[test] fn move_light_command_writes_ps_move_led_report() { let command = pending_move_light_command(); @@ -12930,8 +12475,6 @@ Device 00:07:04:A8:00:D0 (public) "0.0.0.0:17888", "--hid-controller-rudp-advertise", "198.51.100.66:17888", - "--command-rudp-bind", - "0.0.0.0:17889", "--command-rudp-advertise", "198.51.100.66:17889", ] @@ -12950,21 +12493,6 @@ Device 00:07:04:A8:00:D0 (public) let provider = node .get_required::("muninn.telemetry.starfire") .unwrap(); - let command_route = provider - .value - .get("routes") - .and_then(|value| value.as_array()) - .and_then(|routes| { - routes.iter().find(|route| { - route.get("role").and_then(|value| value.as_str()) - == Some("muninn provider command ingress") - }) - }) - .expect("provider-owned command route"); - assert_eq!( - command_route.get("uri").and_then(|value| value.as_str()), - Some("cultmesh://198.51.100.66:17889/muninn/starfire/commands") - ); let streams = provider .value .get("inputStreams") diff --git a/crates/sleipnir-daemon/src/main.rs b/crates/sleipnir-daemon/src/main.rs index cccedfd..32c9692 100644 --- a/crates/sleipnir-daemon/src/main.rs +++ b/crates/sleipnir-daemon/src/main.rs @@ -9,7 +9,7 @@ use cultnet_rs::{ }; use muninn_contracts::{MUNINN_HID_CONTROLLER_STATE_SCHEMA, MuninnHidControllerStateRecord}; use odin_core::{ - EVE_PROVIDER_ADVERTISEMENT_SCHEMA, EveProviderAdvertisementRecord, EveSurfaceStateRecord, + EVE_PROVIDER_ADVERTISEMENT_SCHEMA, EveProviderAdvertisementRecord, IdunnDaemonHealthRecord, OdinDocuments, OdinEndpointQuery, SleipnirInputMappingRecord, discover_provider_endpoints, }; @@ -341,7 +341,7 @@ fn main() -> Result<()> { None, ) }; - publish_sleipnir_runtime_surface(&mut node, &options, &initial_state, true)?; + publish_sleipnir_provider(&mut node, &options, &initial_state, true)?; let mut last_idunn_health_attempt_at = Instant::now() - Duration::from_secs(60); publish_idunn_health_if_configured(&options, &initial_state, &mut last_idunn_health_attempt_at); @@ -562,7 +562,7 @@ fn main() -> Result<()> { recent_input_latency.as_ref(), ) }; - publish_sleipnir_runtime_surface(&mut node, &options, &runtime_state, true)?; + publish_sleipnir_provider(&mut node, &options, &runtime_state, true)?; publish_idunn_health_if_configured( &options, &runtime_state, @@ -597,7 +597,7 @@ fn main() -> Result<()> { recent_input_latency.as_ref(), ) }; - publish_sleipnir_runtime_surface( + publish_sleipnir_provider( &mut node, &options, &runtime_state, @@ -689,7 +689,7 @@ impl SleipnirRuntimeState { } } -fn publish_sleipnir_runtime_surface( +fn publish_sleipnir_provider( node: &mut cultmesh_rs::CultMeshNode, options: &Options, state: &SleipnirRuntimeState, @@ -744,15 +744,7 @@ fn publish_sleipnir_runtime_surface( "channel": "schema" })); } - let surface = EveSurfaceStateRecord { - provider_id: state.provider_id.clone(), - title: sleipnir_provider_title(options), - version: unix_millis_i64(), - updated_at: state.updated_at.clone(), - surface: sleipnir_surface_document(state), - }; node.put(&state.provider_id, &advertisement)?; - node.put(&state.provider_id, &surface)?; if publish_remote && let Some(target) = resolve_odin_cultmesh_uri(options) { if let Err(error) = node.publish_document_to_rudp_catalog( &state.provider_id, @@ -769,23 +761,6 @@ fn publish_sleipnir_runtime_surface( eprintln!("Sleipnir could not publish provider advertisement to Odin: {error:#}"); } } - if let Err(error) = node.publish_document_to_rudp_catalog( - &state.provider_id, - &surface, - CultMeshRudpDocumentPublishOptions { - target, - runtime_id: sleipnir_daemon_id(options), - source_role: Some("sleipnir.input-mirror-surface".to_string()), - tags: vec!["sleipnir".to_string(), "eve-surface".to_string()], - flush_timeout: Duration::from_millis(300), - resend_delay_ms: 15, - ..CultMeshRudpDocumentPublishOptions::default() - }, - ) { - if options.trace { - eprintln!("Sleipnir could not publish surface state to Odin: {error:#}"); - } - } } Ok(()) } @@ -1019,411 +994,6 @@ fn hid_state_host_id_from_value(value: &serde_json::Value) -> Option { string_field(payload, &["host_id", "hostId"]) } -fn sleipnir_surface_document(state: &SleipnirRuntimeState) -> serde_json::Value { - let preset_cards = remap_preset_cards(state); - let binding_map = xbox_binding_map(state); - let device_cards = state - .available_devices - .iter() - .map(|device| { - let selected = state.selected_device_filter.as_deref() == Some(device.device_id.as_str()) - || state.selected_device_filter.as_deref() == Some(device.device_kind.as_str()) - || state.selected_device_filter.as_deref() == Some(device.stream_id.as_str()); - serde_json::json!({ - "id": format!("{}.device.{}", state.provider_id, stable_id(&device.device_id)), - "kind": "card", - "props": { - "title": format!("{} {}", if selected { "selected" } else { "available" }, device.device_id), - "commandId": "sleipnir.map-hid-device", - "action": { - "type": "sleipnir.map-hid-device", - "providerId": state.provider_id, - "deviceFilter": device.device_id, - "streamId": device.stream_id - } - }, - "children": [ - text_element(format!("{}.device.{}.kind", state.provider_id, stable_id(&device.device_id)), format!("kind: {}", device.device_kind)), - text_element(format!("{}.device.{}.host", state.provider_id, stable_id(&device.device_id)), format!("host: {}", device.host_id)), - text_element(format!("{}.device.{}.endpoint", state.provider_id, stable_id(&device.device_id)), format!("endpoint: {}", device.endpoint)), - text_element(format!("{}.device.{}.path", state.provider_id, stable_id(&device.device_id)), format!("source: {}", device.source_path)) - ] - }) - }) - .collect::>(); - let mut runtime_children = vec![ - serde_json::json!({ - "id": format!("{}.disable", state.provider_id), - "kind": "card", - "props": { - "title": "Stop consuming input", - "commandId": "sleipnir.disable-input", - "action": { - "type": "sleipnir.disable-input", - "providerId": state.provider_id - } - }, - "children": [] - }), - text_element( - format!("{}.state", state.provider_id), - format!("state: {}", state.stream_state), - ), - text_element( - format!("{}.backend", state.provider_id), - format!("virtual backend: {}", state.virtual_backend), - ), - text_element( - format!("{}.presentation", state.provider_id), - format!("presentation: {}", state.presentation), - ), - text_element( - format!("{}.muninn", state.provider_id), - format!( - "muninn endpoint: {}", - state - .selected_muninn_endpoint - .as_deref() - .unwrap_or("discovering") - ), - ), - text_element( - format!("{}.filter", state.provider_id), - format!( - "device filter: {}", - state.selected_device_filter.as_deref().unwrap_or("any") - ), - ), - text_element( - format!("{}.updated", state.provider_id), - format!("updated: {}", state.updated_at), - ), - ]; - runtime_children.push(serde_json::json!({ - "id": format!("{}.devices-inline", state.provider_id), - "kind": "pane", - "props": { "title": "Available HID Devices", "density": "compact" }, - "children": if device_cards.is_empty() { - vec![text_element( - format!("{}.devices.empty", state.provider_id), - "no Muninn HID devices discovered".to_string(), - )] - } else { - device_cards - } - })); - serde_json::json!({ - "schema": "gamecult.eve.surface.v1", - "id": format!("{}.surface", state.provider_id), - "title": "Sleipnir Input Mirror", - "root": { - "id": format!("{}.root", state.provider_id), - "kind": "dashboard", - "props": { - "title": "Sleipnir Input Mirror", - "summary": format!("{} via {}", state.stream_state, state.virtual_backend) - }, - "children": [ - { - "id": format!("{}.runtime", state.provider_id), - "kind": "pane", - "props": { "title": "Runtime" }, - "children": runtime_children - }, - { - "id": format!("{}.input", state.provider_id), - "kind": "pane", - "props": { "title": "Input" }, - "children": [ - text_element(format!("{}.device", state.provider_id), format!("device: {}", state.last_device_id.as_deref().unwrap_or("none"))), - text_element(format!("{}.kind", state.provider_id), format!("kind: {}", state.last_device_kind.as_deref().unwrap_or("unknown"))), - text_element(format!("{}.sequence", state.provider_id), format!("sequence: {}", state.last_sequence.map(|value| value.to_string()).unwrap_or_else(|| "none".to_string()))), - text_element(format!("{}.age", state.provider_id), format!("last frame age ms: {}", state.last_frame_age_ms.map(|value| value.to_string()).unwrap_or_else(|| "none".to_string()))), - text_element(format!("{}.ignored", state.provider_id), format!("ignored stream frames: {}", state.ignored_stream_frames)) - ] - }, - { - "id": format!("{}.latency", state.provider_id), - "kind": "pane", - "props": { "title": "Input Latency" }, - "children": input_latency_elements(state) - }, - { - "id": format!("{}.axis", state.provider_id), - "kind": "pane", - "props": { "title": "Axis Classification" }, - "children": [ - text_element(format!("{}.axis.summary", state.provider_id), format!("mapped axes: {}", state.last_input_latency.as_ref().map(|trace| trace.axis_summary.join(", ")).filter(|text| !text.is_empty()).unwrap_or_else(|| "none".to_string()))) - ] - }, - { - "id": format!("{}.remap", state.provider_id), - "kind": "pane", - "props": { "title": "Remapping Presets" }, - "children": preset_cards - }, - { - "id": format!("{}.binding-map-pane", state.provider_id), - "kind": "pane", - "props": { "title": "Xbox Controller Mapping", "span": "wide" }, - "children": [binding_map] - } - ] - }, - "assets": [] - }) -} - -fn input_latency_elements(state: &SleipnirRuntimeState) -> Vec { - let Some(trace) = state.last_input_latency.as_ref() else { - return vec![text_element( - format!("{}.latency.empty", state.provider_id), - "no emitted input trace yet".to_string(), - )]; - }; - vec![ - text_element( - format!("{}.latency.identity", state.provider_id), - format!( - "device: {} seq={} emitted={}", - trace.device_id, trace.sequence, trace.emitted - ), - ), - text_element( - format!("{}.latency.source-arrival", state.provider_id), - format!( - "signal arrival: {}", - trace - .source_to_arrival_ms - .map(|value| format!("source to arrival {} ms", value)) - .unwrap_or_else(|| "source timestamp unavailable".to_string()) - ), - ), - text_element( - format!("{}.latency.buffer", state.provider_id), - format!("arrival to buffer: {} ms", trace.arrival_to_buffer_ms), - ), - text_element( - format!("{}.latency.axis", state.provider_id), - format!( - "buffer to axis classification: {} ms", - trace.buffer_to_axis_ms - ), - ), - text_element( - format!("{}.latency.hid", state.provider_id), - format!("axis to HID emission: {} ms", trace.axis_to_hid_ms), - ), - text_element( - format!("{}.latency.total", state.provider_id), - format!( - "observed mirror total: {} ms{}", - trace.total_observed_ms, - trace - .source_to_hid_ms - .map(|value| format!(" / source to HID {} ms", value)) - .unwrap_or_default() - ), - ), - ] -} - -fn remap_preset_cards(state: &SleipnirRuntimeState) -> Vec { - vec![ - remap_preset_card( - state, - "nav-to-xbox", - "Nav to Xbox", - "xbox360", - serde_json::json!({ - "leftX": {"source": 0}, - "leftY": {"source": 1, "invert": true}, - "leftTrigger": {"source": 2}, - "rightTrigger": {"source": 5} - }), - serde_json::json!({ - "cross": "a", - "circle": "b", - "square": "x", - "triangle": "y", - "select": "back", - "ps": "guide" - }), - ), - remap_preset_card( - state, - "invert-y", - "Invert Y", - "xbox360", - serde_json::json!({ - "leftX": {"source": 0}, - "leftY": {"source": 1, "invert": true}, - "leftTrigger": {"source": 2}, - "rightTrigger": {"source": 5} - }), - serde_json::json!({}), - ), - ] -} - -fn remap_preset_card( - state: &SleipnirRuntimeState, - preset_id: &str, - title: &str, - presentation: &str, - axis_map: serde_json::Value, - button_map: serde_json::Value, -) -> serde_json::Value { - serde_json::json!({ - "id": format!("{}.remap.{}", state.provider_id, preset_id), - "kind": "card", - "props": { - "title": title, - "commandId": "sleipnir.apply-remap-preset", - "action": { - "type": "sleipnir.apply-remap-preset", - "providerId": state.provider_id, - "deviceFilter": state.selected_device_filter, - "presentation": presentation, - "axisMap": axis_map, - "buttonMap": button_map - } - }, - "children": [ - text_element(format!("{}.remap.{}.detail", state.provider_id, preset_id), format!("presentation: {presentation}")) - ] - }) -} - -fn xbox_binding_map(state: &SleipnirRuntimeState) -> serde_json::Value { - let targets = [ - ( - "leftX", "axis", "Left X", "axis 0", "16%", "34%", "265", "224", - ), - ( - "leftY", "axis", "Left Y", "axis 1", "16%", "49%", "265", "224", - ), - ( - "leftTrigger", - "axis", - "LT", - "axis 2", - "20%", - "12%", - "253", - "68", - ), - ( - "rightTrigger", - "axis", - "RT", - "axis 5", - "80%", - "12%", - "527", - "68", - ), - ("a", "button", "A", "unmapped", "88%", "72%", "568", "244"), - ("b", "button", "B", "unmapped", "92%", "58%", "608", "204"), - ("x", "button", "X", "unmapped", "80%", "58%", "528", "204"), - ("y", "button", "Y", "unmapped", "84%", "44%", "568", "164"), - ("lb", "button", "LB", "unmapped", "22%", "22%", "253", "108"), - ("rb", "button", "RB", "unmapped", "78%", "22%", "527", "108"), - ( - "back", "button", "Back", "unmapped", "40%", "43%", "363", "197", - ), - ( - "start", "button", "Start", "unmapped", "60%", "43%", "419", "197", - ), - ( - "guide", "button", "Guide", "unmapped", "50%", "36%", "391", "224", - ), - ("l3", "button", "L3", "unmapped", "30%", "76%", "265", "224"), - ("r3", "button", "R3", "unmapped", "70%", "76%", "474", "256"), - ( - "up", "button", "D-Up", "unmapped", "12%", "64%", "245", "224", - ), - ( - "down", "button", "D-Down", "unmapped", "12%", "78%", "245", "306", - ), - ( - "left", "button", "D-Left", "unmapped", "12%", "71%", "204", "267", - ), - ( - "right", "button", "D-Right", "unmapped", "26%", "71%", "286", "267", - ), - ]; - let children = targets - .into_iter() - .map( - |(target, kind, label, fallback, x, y, anchor_x, anchor_y)| { - binding_target( - state, - target, - kind, - label, - binding_summary(state, target, kind, fallback), - x, - y, - anchor_x, - anchor_y, - ) - }, - ) - .collect::>(); - serde_json::json!({ - "id": format!("{}.binding-map", state.provider_id), - "kind": "input.binding-map", - "props": { - "label": "Xbox controller remapping" - }, - "children": children - }) -} - -fn binding_target( - state: &SleipnirRuntimeState, - target: &str, - binding_kind: &str, - label: &str, - current: String, - x: &str, - y: &str, - anchor_x: &str, - anchor_y: &str, -) -> serde_json::Value { - let listening = state - .pending_learn - .as_ref() - .is_some_and(|learn| learn.target == target && learn.binding_kind == binding_kind); - serde_json::json!({ - "id": format!("{}.binding.{}", state.provider_id, stable_id(target)), - "kind": "binding.target", - "props": { - "target": target, - "bindingKind": binding_kind, - "label": label, - "current": if listening { "listening..." } else { current.as_str() }, - "x": x, - "y": y, - "anchorX": anchor_x, - "anchorY": anchor_y, - "documentId": format!("cultmesh://sleipnir/{}/binding/{target}", state.provider_id), - "slotId": format!("sleipnir.binding.{target}"), - "schemaId": "gamecult.eve.surface.v1", - "presentationKind": "modal.binding", - "deviceFilter": state.selected_device_filter, - "presentation": "xbox360" - }, - "embeddedDocuments": [{ - "slotId": format!("sleipnir.binding.{target}"), - "documentId": format!("cultmesh://sleipnir/{}/binding/{target}", state.provider_id), - "schemaId": "gamecult.eve.surface.v1", - "presentationKind": "modal.binding" - }] - }) -} - fn binding_summary( state: &SleipnirRuntimeState, target: &str, @@ -1445,23 +1015,6 @@ fn binding_summary( } } -fn axis_binding_label(binding: Option<&AxisBinding>) -> String { - match binding { - Some(binding) if binding.invert => format!("axis {} inverted", binding.source), - Some(binding) => format!("axis {}", binding.source), - None => "unmapped".to_string(), - } -} - -fn text_element(id: String, text: String) -> serde_json::Value { - serde_json::json!({ - "id": id, - "kind": "text", - "props": { "text": text }, - "children": [] - }) -} - fn read_desired_mapping( node: &mut cultmesh_rs::CultMeshNode, options: &Options, @@ -3120,49 +2673,6 @@ mod tests { let _ = fs::remove_file(store_path); } - #[test] - fn surface_exposes_input_latency_and_axis_classification() { - let mapping = default_mapping(); - let state = SleipnirRuntimeState { - provider_id: "sleipnir.input-mirror.test".to_string(), - selected_muninn_endpoint: Some("127.0.0.1:17888".to_string()), - selected_device_filter: Some("nav".to_string()), - presentation: "xbox360".to_string(), - virtual_backend: "logging.dry-run".to_string(), - stream_state: "connected".to_string(), - last_device_id: Some("nav".to_string()), - last_device_kind: Some("ps3-navigation".to_string()), - last_sequence: Some(42), - last_frame_age_ms: Some(3), - last_input_latency: Some(SleipnirInputLatencySnapshot { - device_id: "nav".to_string(), - sequence: 42, - source_to_arrival_ms: Some(2), - arrival_to_buffer_ms: 3, - buffer_to_axis_ms: 1, - axis_to_hid_ms: 1, - source_to_hid_ms: Some(7), - total_observed_ms: 5, - axis_summary: vec!["leftX<-axis0 value=0.500".to_string()], - emitted: true, - }), - ignored_stream_frames: 0, - available_devices: Vec::new(), - axis_map: mapping.axis_map, - button_map: mapping.button_map, - pending_learn: None, - updated_at: "unix-1".to_string(), - }; - - let surface = serde_json::to_string(&sleipnir_surface_document(&state)).unwrap(); - - assert!(surface.contains("Input Latency")); - assert!(surface.contains("arrival to buffer: 3 ms")); - assert!(surface.contains("buffer to axis classification: 1 ms")); - assert!(surface.contains("axis to HID emission: 1 ms")); - assert!(surface.contains("mapped axes: leftX<-axis0 value=0.500")); - } - #[test] fn available_hid_devices_ignore_move_evidence_streams() { let provider = json!({ @@ -3385,44 +2895,6 @@ mod tests { ); } - #[test] - fn endpoint_discovery_does_not_borrow_other_hosts_from_surfaces() { - let (mut node, store_path) = test_node("hid-no-surface-leak"); - node.put( - "sleipnir.input-mirror.raven", - &EveSurfaceStateRecord { - provider_id: "sleipnir.input-mirror.raven".to_string(), - title: "Sleipnir Raven".to_string(), - version: 1, - updated_at: "unix:0".to_string(), - surface: json!({ - "id": "sleipnir.input-mirror.raven.surface", - "root": { - "kind": "dashboard", - "children": [{ - "kind": "text", - "props": { - "text": "raven sees nightwing endpoint 198.51.100.75:17888" - } - }] - } - }), - }, - ) - .unwrap(); - - assert_eq!( - discover_muninn_hid_endpoint( - &node, - Some("xbox-raven"), - Some("raven:xbox-raven:hid-controller-state"), - false, - ), - None - ); - let _ = fs::remove_file(store_path); - } - #[test] fn stream_id_host_hint_filters_provider_routes() { let (mut node, store_path) = test_node("hid-host-hint"); diff --git a/scripts/restart-nightwing-muninn.ps1 b/scripts/restart-nightwing-muninn.ps1 index 5c7392c..58fa1b1 100644 --- a/scripts/restart-nightwing-muninn.ps1 +++ b/scripts/restart-nightwing-muninn.ps1 @@ -21,7 +21,6 @@ param( [string] $OdinCultMeshRudpEndpoint = $(if ($env:CULTMESH_URI_ODIN_RUDP) { $env:CULTMESH_URI_ODIN_RUDP } else { "10.77.0.2:17871" }), [string] $HidControllerRudpBind = "0.0.0.0:17888", [string] $HidControllerRudpAdvertise = $(if ($env:MUNINN_HID_CONTROLLER_RUDP_ADVERTISE) { $env:MUNINN_HID_CONTROLLER_RUDP_ADVERTISE } else { "10.77.0.3:17888" }), - [string] $CommandRudpBind = "0.0.0.0:17889", [string] $CommandRudpAdvertise = "10.77.0.3:17889" ) @@ -126,7 +125,7 @@ if (-not [string]::IsNullOrWhiteSpace($HidControllerRudpAdvertise)) { $hidControllerRudpSetLines += "set -- ""`$@"" --hid-controller-rudp-advertise $(Quote-ShSingle $HidControllerRudpAdvertise)" } $hidControllerRudpSetBlock = ($hidControllerRudpSetLines -join "`n") -$commandRudpSetBlock = "set -- ""`$@"" --command-rudp-bind $(Quote-ShSingle $CommandRudpBind) --command-rudp-advertise $(Quote-ShSingle $CommandRudpAdvertise)" +$commandRudpSetBlock = "set -- ""`$@"" --command-rudp-advertise $(Quote-ShSingle $CommandRudpAdvertise)" $remoteScript = @" set -eu mkdir -p '$LogRoot' From e534ef4937db0c8aad385ffe33918067b09df657 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Thu, 22 Oct 2026 20:42:24 +0200 Subject: [PATCH 41/44] Drop orphaned Sleipnir binding_summary and Muninn imports left by the Eve surface removal Co-Authored-By: Claude Sonnet 5.5 --- crates/muninn-daemon/src/main.rs | 8 +++----- crates/sleipnir-daemon/src/main.rs | 21 --------------------- 2 files changed, 3 insertions(+), 26 deletions(-) diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index 5e7f8f2..bbd1a54 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -14,13 +14,12 @@ use cultmesh_rs::{ CultMeshStreamClock, CultMeshStreamDescriptor, CultMeshStreamKind, }; use cultnet_rs::{ - CultNetMessage, CultNetRawDocumentRecord, CultNetRawPayloadEncoding, CultNetRudpServerHub, - CultNetRudpServerHubOptions, CultNetRudpSocketTransportConnection, - CultNetRudpSocketTransportOptions, CultNetWireContract, + CultNetRudpServerHub, CultNetRudpServerHubOptions, CultNetRudpSocketTransportConnection, + CultNetRudpSocketTransportOptions, GAMECULT_MEDIA_STREAM_ADVERTISEMENT_SCHEMA, GAMECULT_MEDIA_STREAM_REQUEST_SCHEMA, GAMECULT_RUNTIME_PRESENCE_HEALTH_SCHEMA, GameCultMediaStreamAdvertisementRecord, GameCultMediaStreamRequestRecord, - GameCultRuntimePresenceHealthRecord, decode_cultnet_message_from_slice, + GameCultRuntimePresenceHealthRecord, media_stream_request_key, validate_media_stream_request, }; use muninn_contracts::{ @@ -9897,7 +9896,6 @@ fn parse_move_state_source(value: &str) -> Result { mod tests { use super::*; use crate::media_send::{MediaKind, QueuedMediaGroup}; - use cultnet_rs::encode_cultnet_message_to_vec; fn media_stream_request() -> GameCultMediaStreamRequestRecord { GameCultMediaStreamRequestRecord { diff --git a/crates/sleipnir-daemon/src/main.rs b/crates/sleipnir-daemon/src/main.rs index 32c9692..43675ce 100644 --- a/crates/sleipnir-daemon/src/main.rs +++ b/crates/sleipnir-daemon/src/main.rs @@ -994,27 +994,6 @@ fn hid_state_host_id_from_value(value: &serde_json::Value) -> Option { string_field(payload, &["host_id", "hostId"]) } -fn binding_summary( - state: &SleipnirRuntimeState, - target: &str, - binding_kind: &str, - fallback: &str, -) -> String { - if binding_kind == "axis" { - return axis_binding_label(state.axis_map.get(target)); - } - let sources = state - .button_map - .iter() - .filter_map(|(source, mapped)| (mapped == target).then_some(source.as_str())) - .collect::>(); - if sources.is_empty() { - fallback.to_string() - } else { - sources.join(", ") - } -} - fn read_desired_mapping( node: &mut cultmesh_rs::CultMeshNode, options: &Options, From b0df17dddda3d9926bda8609b638138d6485e279 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Thu, 22 Oct 2026 21:19:43 +0200 Subject: [PATCH 42/44] Name the lowercase parked tag in the removed-flag message Co-Authored-By: Claude Sonnet 5.5 --- crates/muninn-daemon/src/main.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/muninn-daemon/src/main.rs b/crates/muninn-daemon/src/main.rs index bbd1a54..0a031d6 100644 --- a/crates/muninn-daemon/src/main.rs +++ b/crates/muninn-daemon/src/main.rs @@ -9626,7 +9626,7 @@ impl Options { "--command-rudp-bind" => { let _ = take_value(&mut args, "--command-rudp-bind")?; return Err(anyhow!( - "--command-rudp-bind has been removed; the Eve command ingress was quarantined (tag parked/Muninn-eve-surface)" + "--command-rudp-bind has been removed; the Eve command ingress was quarantined (tag parked/muninn-eve-surface)" )); } "--command-rudp-advertise" => { From 3e47e27d496c9eb181e7c5681335f7c8a11ee5c0 Mon Sep 17 00:00:00 2001 From: Kiko Date: Fri, 13 Nov 2026 03:24:48 +0000 Subject: [PATCH 43/44] Docs: which Ratatoskr the docs mean (#1) --- README.md | 5 +++++ docs/teardown-map.md | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f1bad58..c5f8283 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,11 @@ Muninn running does not mean Muninn is broadcasting. Each feed it can reach is for input. A stream asks for screen and audio. Muninn does not decide what any of them are for. +**Naming note.** Muninn's docs say "Ratatoskr" for the OBS media receiver, which lives at +[github.com/GameCult/Ratatoskr](https://github.com/GameCult/Ratatoskr) (forge mirror: +[GameCult/Ratatoskr-receiver](https://eureka.gamecult.org/forge/GameCult/Ratatoskr-receiver)). +The forge repo `GameCult/Ratatoskr` is an unrelated project, Void's Cinny-based chat client. + Extracted from [Odin](https://github.com/GameCult/Odin) with its full history. Muninn had lived as three crates inside the repository of the service that discovers it, with its document schemas owned by `odin-core` — an inversion of diff --git a/docs/teardown-map.md b/docs/teardown-map.md index d89ec71..b77d53a 100644 --- a/docs/teardown-map.md +++ b/docs/teardown-map.md @@ -436,7 +436,7 @@ exercising the path it claims to measure; `--metrics` stays in the script. ## Ratatoskr exists (2026-09-10) -https://github.com/GameCult/Ratatoskr — the receiving end, extracted from the +https://github.com/GameCult/Ratatoskr (forge mirror `GameCult/Ratatoskr-receiver`; the forge `GameCult/Ratatoskr` is the unrelated chat client) — the receiving end, extracted from the 6,515-line C++ plugin in `Mimir/native/obs_stem_source/`. Holds one rule: **it implements no transport, it consumes CultNet.** The plugin From 573ffea9562d5e6b4ea6cb95a79e0eaaf4b50e3e Mon Sep 17 00:00:00 2001 From: Kiko Date: Fri, 13 Nov 2026 03:25:05 +0000 Subject: [PATCH 44/44] Deprecation notice: streaming role superseded (no deletions) (#2) --- README.md | 9 +++++++++ docs/streaming-deprecation.md | 37 +++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+) create mode 100644 docs/streaming-deprecation.md diff --git a/README.md b/README.md index c5f8283..c894b34 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,14 @@ # Muninn +> **Deprecation notice (Meta, 2026-11-06).** Muninn's *streaming* role (screen and audio +> capture, the media sender, and the OBS media receiver at +> [github.com/GameCult/Ratatoskr](https://github.com/GameCult/Ratatoskr), not the forge chat +> client of the same name) is superseded in the streaming space. Do not build new work on it. +> Nothing is deleted yet; what depends on it and what looks removable is in +> [docs/streaming-deprecation.md](docs/streaming-deprecation.md). The non-streaming roles +> (sensors, PS Move, input for Sleipnir) are not covered by this notice. + + **Local capture broker for the GameCult swarm.** Muninn resolves what data streams a host can offer, advertises them, and serves diff --git a/docs/streaming-deprecation.md b/docs/streaming-deprecation.md new file mode 100644 index 0000000..8f4085a --- /dev/null +++ b/docs/streaming-deprecation.md @@ -0,0 +1,37 @@ +# Streaming deprecation (Meta, 2026-11-06) + +Muninn's streaming role and the OBS media receiver are superseded in the streaming +space. Scope: screen and loopback-audio capture, the media sender, and the receiver at +github.com/GameCult/Ratatoskr (forge mirror `GameCult/Ratatoskr-receiver`; the forge repo +`GameCult/Ratatoskr` is an unrelated chat client and is not covered). Nothing has been +deleted. The lists below come from file names and docs, not from a consumer audit; +confirm each consumer before cutting. + +## What depends on the streaming role + +- Nothing in StreamPixels on main. StreamPixels `tools/showcheck` (PR #2) read Muninn's + activation log and the receiver's OBS log until it was rescoped on 2026-11-06 (a762f69) + to server, overlay and OBS only; the Muninn and Ratatoskr hops are gone from it and + survive only on its parked branch `kiko/showcheck-muninn-chain`. +- Docs here that describe it: `docs/muninn-media-streaming.md`, + `docs/realtime-robustness-cut.md`, and the receiver sections of `docs/teardown-map.md`. +- Operations: `scripts/activate-muninn-raven-*`, `scripts/health-*`, + `scripts/restart-*`, and `deployment/idunn` (the health and restart scripts also serve + the non-streaming daemon, so they stay). +- The receiver repo's README names Muninn in prose. + +## Removal candidates (streaming only; verify consumers first) + +- `crates/muninn-daemon/src/media_send.rs`, `media_send/tests.rs`, + `media_packetizer.rs`, and the media wiring in `main.rs`. +- Media-related records in `crates/muninn-contracts` (`records.rs`, `lib.rs`), if no + non-streaming consumer reads them. +- `scripts/activate-muninn-raven-av-srt.cmd`, `scripts/activate-muninn-raven-media.ps1`, + `scripts/wasapi-loopback-capture.ps1`. +- `docs/muninn-media-streaming.md` (move to history rather than delete if it is cited). + +## Keep + +Sensor serving, PS Move tracking (`muninn-move-tracker`, `muninn-psmoveapi-tracker`, +`native/`), and `sleipnir-daemon` input are outside this notice. Do not remove them under +it. `idunn_presence.rs` matched a media search term only; it is presence, not streaming.