Expose native reservoir C ABI

This commit is contained in:
Meta Vens 2026-05-19 07:42:58 +01:00
commit 2bf5abbd57
9 changed files with 320 additions and 11 deletions

View file

@ -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.

View file

@ -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.

View file

@ -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.

View file

@ -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]

View file

@ -0,0 +1,56 @@
#pragma once
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#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

View file

@ -15,6 +15,23 @@ pub enum RingKind {
RenderPacket,
}
impl RingKind {
fn from_u32(value: u32) -> Option<Self> {
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<T> {
pub sensor_id: String,
@ -98,8 +115,9 @@ impl<T> ReservoirRing<T> {
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<T> Default for Reservoir<T> {
}
}
#[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<LocalcastSampleHandle>,
}
#[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);
}
}

View file

@ -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

View file

@ -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.

View file

@ -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()