From 2bf5abbd57083421573dd5fe34f077a5fc284c29 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 19 May 2026 07:42:58 +0100 Subject: [PATCH] Expose native reservoir C ABI --- docs/implementation-plan.md | 3 +- docs/perfect-machine.md | 16 +- native/README.md | 18 ++ native/reservoir/Cargo.toml | 2 +- .../reservoir/include/localcast_reservoir.h | 56 +++++ native/reservoir/src/lib.rs | 214 +++++++++++++++++- notes/current-system-map.md | 4 +- state/map.yaml | 4 +- tests/test_perfect_machine_contract.py | 14 ++ 9 files changed, 320 insertions(+), 11 deletions(-) create mode 100644 native/reservoir/include/localcast_reservoir.h diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md index 6fae140..207a527 100644 --- a/docs/implementation-plan.md +++ b/docs/implementation-plan.md @@ -6,6 +6,7 @@ - `docs/perfect-machine.md` defines the target native machine: one five-second spatiotemporal reservoir, Aquarium-owned dense visual fusion/material/brush rendering, Faust-owned hot audio DSP, OBS-owned broadcast controls, and LocalCastBridge-owned calibration/config/status. - `config/perfect-machine.example.json` declares the contract shape for six cameras, six microphones, reservoir rings, native authorities, outputs, and the demotion of bridge scripts to tooling. - `native/reservoir` is the first native Rust crate. It implements shared-edge five-second reservoir rings and proves that all rings expire against the newest sample, not private per-source clocks. + - `native/reservoir/include/localcast_reservoir.h` exposes the Aquarium/Faust C ABI: opaque reservoir create/destroy, sample-handle push, edge/window queries, ring counts, and latest sample lookup by sensor hash. Payload memory remains owned by Aquarium/GPU/Faust; the reservoir owns timing and retention. - Repo-local persistence machinery. - First architecture map. - Example config for one video source plus two audio sources. @@ -75,7 +76,7 @@ ## Next -1. Add a C ABI and Aquarium-facing binding around `native/reservoir`. +1. Add the Aquarium-side binding that loads `localcast_reservoir` and maps GPU/audio buffer handles to `LocalcastSampleHandle`. 2. Move camera ingest into native capture workers that append `camera_frame` samples to the reservoir. 3. Move feature extraction, flow, cross-view matching, LOD reconciliation, and material fitting into Aquarium GPU compute. 4. Move mic alignment, voice separation, room suppression, Ambisonic/HOA spatialization, and stem generation into Faust/native DSP. diff --git a/docs/perfect-machine.md b/docs/perfect-machine.md index ac334ae..305fb43 100644 --- a/docs/perfect-machine.md +++ b/docs/perfect-machine.md @@ -157,6 +157,16 @@ five-second reservoir invariant: - evict every ring against the same edge; - query the latest valid sample per sensor. -This is intentionally below Aquarium and Faust. The crate owns retention and -sample-window semantics; Aquarium owns GPU interpretation and rendering, Faust -owns DSP interpretation. +It now builds as `rlib`, `cdylib`, and `staticlib`, with a small C ABI declared +in `native/reservoir/include/localcast_reservoir.h`: + +- create/destroy an opaque `LocalcastReservoir`; +- push timestamped sample metadata into a typed ring; +- advance/query the shared edge and window start; +- query ring length; +- query the latest sample for a sensor hash. + +The ABI carries `payload_handle`, not payload bytes. Aquarium owns image, +feature, surface, material, and GPU memory interpretation. Faust/native DSP owns +audio buffer interpretation. The reservoir owns only retention, ring identity, +timestamp order, and the five-second shared-edge invariant. diff --git a/native/README.md b/native/README.md index 5bab682..d5a3b23 100644 --- a/native/README.md +++ b/native/README.md @@ -10,4 +10,22 @@ tests, and offline analysis. It does not own dense live fusion or DSP. - `reservoir`: the first native five-second spatiotemporal reservoir core. It owns shared-edge retention and typed sample rings. Aquarium/Faust integration should build on this invariant instead of copying the deadline bridge cache. + It exports `rlib`, `cdylib`, and `staticlib` artifacts plus the C header at + `reservoir/include/localcast_reservoir.h`. +## Reservoir ABI + +The ABI is intentionally small: + +- `LocalcastReservoir` is opaque. +- `LocalcastSampleHandle` is sample metadata plus a `payload_handle`. +- Ring ids match the Perfect Machine reservoir rings: + camera frame, camera feature, scene ray, surface claim, material claim, audio + block, phase claim, event claim, and render packet. +- The reservoir can create/destroy, push, set/query edge, query window start, + count a ring, and fetch the latest sample for a sensor hash. + +Payload handles are owned by the caller. Aquarium should treat them as handles +to GPU/native visual memory; Faust/native DSP should treat them as handles to +audio buffers. This crate does not interpret those bytes. It is the clocked +retention authority, not the renderer or DSP engine in a tiny hat. diff --git a/native/reservoir/Cargo.toml b/native/reservoir/Cargo.toml index 13cd157..3de6d90 100644 --- a/native/reservoir/Cargo.toml +++ b/native/reservoir/Cargo.toml @@ -5,6 +5,6 @@ edition = "2024" description = "Native five-second spatiotemporal reservoir core for LocalCastBridge" [lib] -crate-type = ["rlib"] +crate-type = ["rlib", "cdylib", "staticlib"] [dependencies] diff --git a/native/reservoir/include/localcast_reservoir.h b/native/reservoir/include/localcast_reservoir.h new file mode 100644 index 0000000..c764cf1 --- /dev/null +++ b/native/reservoir/include/localcast_reservoir.h @@ -0,0 +1,56 @@ +#pragma once + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +enum LocalcastRingKind { + LOCALCAST_RING_CAMERA_FRAME = 0, + LOCALCAST_RING_CAMERA_FEATURE = 1, + LOCALCAST_RING_SCENE_RAY = 2, + LOCALCAST_RING_SURFACE_CLAIM = 3, + LOCALCAST_RING_MATERIAL_CLAIM = 4, + LOCALCAST_RING_AUDIO_BLOCK = 5, + LOCALCAST_RING_PHASE_CLAIM = 6, + LOCALCAST_RING_EVENT_CLAIM = 7, + LOCALCAST_RING_RENDER_PACKET = 8 +}; + +typedef struct LocalcastReservoir LocalcastReservoir; + +typedef struct LocalcastSampleHandle { + uint64_t sensor_id_hash; + uint64_t timestamp_ns; + uint64_t arrival_ns; + uint64_t sequence; + uint64_t payload_handle; +} LocalcastSampleHandle; + +LocalcastReservoir *localcast_reservoir_create(uint64_t duration_ns); +void localcast_reservoir_destroy(LocalcastReservoir *reservoir); + +bool localcast_reservoir_push( + LocalcastReservoir *reservoir, + uint32_t ring_kind, + LocalcastSampleHandle sample +); + +bool localcast_reservoir_set_edge(LocalcastReservoir *reservoir, uint64_t edge_ns); +uint64_t localcast_reservoir_edge_ns(const LocalcastReservoir *reservoir); +uint64_t localcast_reservoir_window_start_ns(const LocalcastReservoir *reservoir); +size_t localcast_reservoir_ring_len(const LocalcastReservoir *reservoir, uint32_t ring_kind); + +bool localcast_reservoir_latest_for_sensor( + const LocalcastReservoir *reservoir, + uint32_t ring_kind, + uint64_t sensor_id_hash, + LocalcastSampleHandle *out_sample +); + +#ifdef __cplusplus +} +#endif diff --git a/native/reservoir/src/lib.rs b/native/reservoir/src/lib.rs index 2a7b204..c8efa95 100644 --- a/native/reservoir/src/lib.rs +++ b/native/reservoir/src/lib.rs @@ -15,6 +15,23 @@ pub enum RingKind { RenderPacket, } +impl RingKind { + fn from_u32(value: u32) -> Option { + match value { + 0 => Some(Self::CameraFrame), + 1 => Some(Self::CameraFeature), + 2 => Some(Self::SceneRay), + 3 => Some(Self::SurfaceClaim), + 4 => Some(Self::MaterialClaim), + 5 => Some(Self::AudioBlock), + 6 => Some(Self::PhaseClaim), + 7 => Some(Self::EventClaim), + 8 => Some(Self::RenderPacket), + _ => None, + } + } +} + #[derive(Debug, Clone, PartialEq)] pub struct Sample { pub sensor_id: String, @@ -98,8 +115,9 @@ impl ReservoirRing { fn evict_expired(&mut self) { let start_ns = self.window_start_ns(); - self.samples - .retain(|sample| sample.timestamp_ns >= start_ns && sample.timestamp_ns <= self.edge_ns); + self.samples.retain(|sample| { + sample.timestamp_ns >= start_ns && sample.timestamp_ns <= self.edge_ns + }); } } @@ -158,6 +176,133 @@ impl Default for Reservoir { } } +#[repr(C)] +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct LocalcastSampleHandle { + pub sensor_id_hash: u64, + pub timestamp_ns: u64, + pub arrival_ns: u64, + pub sequence: u64, + pub payload_handle: u64, +} + +pub struct LocalcastReservoir { + inner: Reservoir, +} + +#[unsafe(no_mangle)] +pub extern "C" fn localcast_reservoir_create(duration_ns: u64) -> *mut LocalcastReservoir { + let duration = if duration_ns == 0 { + DEFAULT_RESERVOIR_NS + } else { + duration_ns + }; + Box::into_raw(Box::new(LocalcastReservoir { + inner: Reservoir::new(duration), + })) +} + +#[unsafe(no_mangle)] +pub extern "C" fn localcast_reservoir_destroy(ptr: *mut LocalcastReservoir) { + if ptr.is_null() { + return; + } + unsafe { + drop(Box::from_raw(ptr)); + } +} + +#[unsafe(no_mangle)] +pub extern "C" fn localcast_reservoir_push( + ptr: *mut LocalcastReservoir, + ring_kind: u32, + sample: LocalcastSampleHandle, +) -> bool { + let Some(reservoir) = (unsafe { ptr.as_mut() }) else { + return false; + }; + let Some(kind) = RingKind::from_u32(ring_kind) else { + return false; + }; + reservoir.inner.push( + kind, + Sample::new( + sample.sensor_id_hash.to_string(), + sample.timestamp_ns, + sample.arrival_ns, + sample.sequence, + sample, + ), + ); + true +} + +#[unsafe(no_mangle)] +pub extern "C" fn localcast_reservoir_set_edge(ptr: *mut LocalcastReservoir, edge_ns: u64) -> bool { + let Some(reservoir) = (unsafe { ptr.as_mut() }) else { + return false; + }; + reservoir.inner.set_edge(edge_ns); + true +} + +#[unsafe(no_mangle)] +pub extern "C" fn localcast_reservoir_edge_ns(ptr: *const LocalcastReservoir) -> u64 { + let Some(reservoir) = (unsafe { ptr.as_ref() }) else { + return 0; + }; + reservoir.inner.edge_ns() +} + +#[unsafe(no_mangle)] +pub extern "C" fn localcast_reservoir_window_start_ns(ptr: *const LocalcastReservoir) -> u64 { + let Some(reservoir) = (unsafe { ptr.as_ref() }) else { + return 0; + }; + reservoir.inner.window_start_ns() +} + +#[unsafe(no_mangle)] +pub extern "C" fn localcast_reservoir_ring_len( + ptr: *const LocalcastReservoir, + ring_kind: u32, +) -> usize { + let Some(reservoir) = (unsafe { ptr.as_ref() }) else { + return 0; + }; + let Some(kind) = RingKind::from_u32(ring_kind) else { + return 0; + }; + reservoir.inner.ring(kind).map_or(0, ReservoirRing::len) +} + +#[unsafe(no_mangle)] +pub extern "C" fn localcast_reservoir_latest_for_sensor( + ptr: *const LocalcastReservoir, + ring_kind: u32, + sensor_id_hash: u64, + out_sample: *mut LocalcastSampleHandle, +) -> bool { + let Some(reservoir) = (unsafe { ptr.as_ref() }) else { + return false; + }; + let Some(kind) = RingKind::from_u32(ring_kind) else { + return false; + }; + let Some(out) = (unsafe { out_sample.as_mut() }) else { + return false; + }; + let Some(ring) = reservoir.inner.ring(kind) else { + return false; + }; + let key = sensor_id_hash.to_string(); + let Some(sample) = ring.latest_for_sensor(&key) else { + return false; + }; + *out = sample.payload; + true +} + #[cfg(test)] mod tests { use super::*; @@ -208,4 +353,69 @@ mod tests { assert_eq!("a1", latest.payload); assert_eq!(1, latest.sequence); } + + #[test] + fn c_abi_pushes_and_queries_latest_sample() { + let reservoir = localcast_reservoir_create(DEFAULT_RESERVOIR_NS); + let pushed = localcast_reservoir_push( + reservoir, + 0, + LocalcastSampleHandle { + sensor_id_hash: 42, + timestamp_ns: 10, + arrival_ns: 11, + sequence: 7, + payload_handle: 99, + }, + ); + let mut out = LocalcastSampleHandle { + sensor_id_hash: 0, + timestamp_ns: 0, + arrival_ns: 0, + sequence: 0, + payload_handle: 0, + }; + let found = localcast_reservoir_latest_for_sensor(reservoir, 0, 42, &mut out); + + assert!(pushed); + assert!(found); + assert_eq!(1, localcast_reservoir_ring_len(reservoir, 0)); + assert_eq!(99, out.payload_handle); + localcast_reservoir_destroy(reservoir); + } + + #[test] + fn c_abi_rejects_nulls_and_unknown_ring_kinds() { + let sample = LocalcastSampleHandle { + sensor_id_hash: 1, + timestamp_ns: 2, + arrival_ns: 3, + sequence: 4, + payload_handle: 5, + }; + let mut out = sample; + + assert!(!localcast_reservoir_push(std::ptr::null_mut(), 0, sample)); + assert!(!localcast_reservoir_set_edge(std::ptr::null_mut(), 10)); + assert_eq!(0, localcast_reservoir_edge_ns(std::ptr::null())); + assert_eq!(0, localcast_reservoir_window_start_ns(std::ptr::null())); + assert_eq!(0, localcast_reservoir_ring_len(std::ptr::null(), 0)); + assert!(!localcast_reservoir_latest_for_sensor( + std::ptr::null(), + 0, + 1, + &mut out, + )); + + let reservoir = localcast_reservoir_create(0); + assert!(!localcast_reservoir_push(reservoir, 99, sample)); + assert_eq!(0, localcast_reservoir_ring_len(reservoir, 99)); + assert!(!localcast_reservoir_latest_for_sensor( + reservoir, + 0, + 1, + std::ptr::null_mut(), + )); + localcast_reservoir_destroy(reservoir); + } } diff --git a/notes/current-system-map.md b/notes/current-system-map.md index eccef36..d0c9509 100644 --- a/notes/current-system-map.md +++ b/notes/current-system-map.md @@ -27,9 +27,9 @@ Ownership: - Faust owns hot audio DSP and program stem generation. - OBS owns broadcast controls. - Python remains tooling, not the stream hot path. -- `native/reservoir` is the first native crate. It owns shared-edge five-second sample retention for typed rings and is the seed of the Aquarium/Faust runtime boundary. +- `native/reservoir` is the first native crate. It owns shared-edge five-second sample retention for typed rings and exposes the small C ABI in `native/reservoir/include/localcast_reservoir.h`: opaque reservoir lifetime, sample-handle push, edge/window queries, ring counts, and latest-by-sensor lookup. -Invariant: the five-second spatiotemporal reservoir is the live authority. Producers append, optimizers refine, Aquarium/Faust sample. No private history outlives the reservoir. +Invariant: the five-second spatiotemporal reservoir is the live authority. Producers append sample handles, optimizers refine, Aquarium/Faust sample and interpret the pointed-to payloads. No private history outlives the reservoir, and the reservoir does not pretend to own GPU image memory or Faust audio buffers. ```mermaid flowchart TD diff --git a/state/map.yaml b/state/map.yaml index 3e6bdd7..effaced 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -34,7 +34,7 @@ invariants: accepted_design: - `docs/perfect-machine.md` and `config/perfect-machine.example.json` define the native target: one five-second spatiotemporal reservoir, Aquarium GPU fusion/rendering, Faust DSP, OBS output controls, and LocalCastBridge tooling. - - `native/reservoir` is the first native Rust crate. It implements shared-edge reservoir rings so all sample types expire from the newest live sample rather than private source histories. + - `native/reservoir` is the first native Rust crate. It implements shared-edge reservoir rings so all sample types expire from the newest live sample rather than private source histories, and exposes a small C ABI for Aquarium/Faust handle-based integration. - `config/localcast.example.json` defines receiver address, base port, video encode settings, and audio sources. - `scripts/sender-discover.ps1` lists FFmpeg devices, protocols, and encoders. - `scripts/sender-start.ps1` launches one FFmpeg process per enabled source. @@ -42,7 +42,7 @@ accepted_design: - Persistence follows the active repo pattern: map, scratch, evidence, branches, handoff, system map, implementation plan, state helpers. active_subgoals: - - Implement the Perfect Machine native reservoir contract described by `docs/perfect-machine.md` and `config/perfect-machine.example.json`. + - Bind Aquarium/Faust to the native reservoir C ABI described by `native/reservoir/include/localcast_reservoir.h`. - Move dense visual fusion/material fitting/brush generation into Aquarium GPU compute. - Move hot audio DSP/voice separation/room suppression/spatialization into Faust/native runtime. - Validate the actual sender FFmpeg build and capture device names. diff --git a/tests/test_perfect_machine_contract.py b/tests/test_perfect_machine_contract.py index 2d25ff3..6b2bad0 100644 --- a/tests/test_perfect_machine_contract.py +++ b/tests/test_perfect_machine_contract.py @@ -30,6 +30,20 @@ class PerfectMachineContractTests(unittest.TestCase): }) self.assertIn("dense-feature-extraction", data["bridgeDemotion"]["notPython"]) + def test_native_reservoir_header_exposes_small_c_abi(self): + header = (ROOT / "native" / "reservoir" / "include" / "localcast_reservoir.h").read_text(encoding="utf-8") + + self.assertIn("typedef struct LocalcastReservoir LocalcastReservoir;", header) + self.assertIn("typedef struct LocalcastSampleHandle", header) + self.assertIn("uint64_t payload_handle;", header) + self.assertIn("LocalcastReservoir *localcast_reservoir_create", header) + self.assertIn("void localcast_reservoir_destroy", header) + self.assertIn("bool localcast_reservoir_push", header) + self.assertIn("uint64_t localcast_reservoir_edge_ns", header) + self.assertIn("uint64_t localcast_reservoir_window_start_ns", header) + self.assertIn("size_t localcast_reservoir_ring_len", header) + self.assertIn("bool localcast_reservoir_latest_for_sensor", header) + if __name__ == "__main__": unittest.main()