Collapse reservoir into rolling buffer

This commit is contained in:
Meta Vens 2026-05-19 08:53:25 +01:00
commit 78230347bf
10 changed files with 298 additions and 240 deletions

View file

@ -5,7 +5,7 @@
"clockAuthority": "presentation",
"lateSamplePolicy": "accept-inside-window",
"expiredSamplePolicy": "offline-calibration-only",
"storageLayout": "struct-of-arrays-native-rings"
"storageLayout": "single-native-rolling-buffer-with-typed-views"
},
"authorities": {
"configurationCalibrationLaunchStatus": "LocalCastBridge",

View file

@ -9,25 +9,22 @@ live data stores. Edge JSON may define CultNet schema or export diagnostics, but
the real process/network data stays typed because every subsystem is under our
control.
The native reservoir must become one time-ordered rolling buffer with typed
indexes/views. The current shared-edge typed rings proved the retention
invariant, but independent rings are still too much duplicated structure for the
live foundation.
The native reservoir is now one time-ordered rolling buffer with typed views.
The previous shared-edge typed rings proved the retention invariant; the new
shape removes independent per-kind storage from the live foundation.
## Implemented
- Perfect Machine contract:
- `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 currently implements
shared-edge five-second typed rings and proves that every kind expires from
the newest live sample. That proof survives; the structure does not get a
pardon. The next foundation is one rolling buffer plus typed indexes/views.
- `config/perfect-machine.example.json` declares the contract shape for six cameras, six microphones, reservoir typed views, native authorities, outputs, and the demotion of bridge scripts to tooling.
- `native/reservoir` is the first native Rust crate. It implements one
shared-edge five-second rolling buffer with typed views and proves that
every kind expires from the newest live sample.
- `native/reservoir/include/localcast_reservoir.h` exposes the initial
Aquarium/Faust C ABI: opaque reservoir create/destroy, sample-handle push,
edge/window queries, ring counts, and latest sample lookup by sensor hash.
This ABI should be revised around the rolling-buffer model before
Aquarium/Faust bind to it.
The ABI now exposes total rolling-buffer length and typed-view length.
- `LocalcastRuntime` wraps the current reservoir with typed native producer
calls. It is the intended live spine, but must be rebuilt on the single
rolling-buffer invariant before new runtime work.
@ -103,19 +100,16 @@ live foundation.
## Next
1. Rewrite `native/reservoir` as one rolling buffer with typed indexes/views.
2. Update ABI/tests so single-edge expiry, typed view queries, latest lookup,
and diagnostic/fallback exclusion are enforced by construction.
3. Quarantine or delete production use of `scripts/live_sensor_fusion.py`,
1. Quarantine or delete production use of `scripts/live_sensor_fusion.py`,
`localcast.sensor_fusion.spout_output`, JSON render-frame stores, JSON LOD
stores, and Python reservoir-window clipping.
4. Bind Aquarium/Faust to the rebuilt `LocalcastRuntime`.
5. Move camera/mic/loopback ingest into native capture workers that append
2. Bind Aquarium/Faust to the rolling-buffer `LocalcastRuntime`.
3. Move camera/mic/loopback ingest into native capture workers that append
typed sample handles.
6. Move feature extraction, flow, cross-view matching, LOD reconciliation,
4. Move feature extraction, flow, cross-view matching, LOD reconciliation,
material fitting, brush/splat rendering, and Spout2 publication into
Aquarium GPU compute.
7. Move mic alignment, room suppression, voice separation, Ambisonic/HOA
5. Move mic alignment, room suppression, voice separation, Ambisonic/HOA
spatialization, and stem generation into Faust/native DSP.
8. Keep FFmpeg/SRT scripts as simple LAN ingest/capture utilities, not the
6. Keep FFmpeg/SRT scripts as simple LAN ingest/capture utilities, not the
synchronized program authority.

View file

@ -67,9 +67,11 @@ flowchart TD
## Reservoir Contract
The reservoir stores struct-of-arrays blocks, not one giant JSON-ish object.
The reservoir stores one time-ordered rolling buffer of sample handles, not one
giant JSON-ish object and not independent per-kind histories. Typed views over
that buffer expose the kinds consumers need.
Required rings:
Required sample kinds / typed views:
- `camera_frame`: raw or GPU-importable image handles plus timestamps.
- `camera_feature`: keypoints, descriptors, optical flow, confidence, sensor id.
@ -86,9 +88,9 @@ The reservoir owns retention. Producers append. Optimizers refine. Renderers
sample. No stage owns a private history that can outlive the reservoir.
`LocalcastRuntime` is the first native owner above the raw reservoir. It exposes
typed producer calls for each ring so camera capture, audio capture, phase
estimation, material fitting, event detection, and render planning all append
into one shared five-second window without crossing a Python file cache.
typed producer calls for each sample kind so camera capture, audio capture,
phase estimation, material fitting, event detection, and render planning all
append into one shared five-second window without crossing a Python file cache.
## Visual Fusion
@ -97,7 +99,8 @@ operation.
The visual path should:
- ingest all cameras continuously into pinned/native rings;
- ingest all cameras continuously into pinned/native buffers referenced by
reservoir sample handles;
- extract features and flow on GPU where possible;
- match every plausible cross-view feature within time and epipolar bounds;
- use Leap as the strongest near-field timing/spatial witness when live;
@ -147,7 +150,7 @@ Keep these as tooling:
1. Define the native reservoir ABI from `config/perfect-machine.example.json`.
2. Build a native reservoir process or Aquarium module that owns the five-second
rings.
rolling buffer.
3. Move camera ingest into native capture workers that write reservoir samples.
4. Move audio ingest/phase claims into the same presentation-clock reservoir.
5. Let Aquarium consume reservoir surfaces/material claims directly on GPU.
@ -157,27 +160,27 @@ Keep these as tooling:
## Native Work Started
`native/reservoir` is the first native crate. It implements the shared-edge
five-second reservoir invariant:
five-second rolling reservoir invariant:
- append samples into named rings;
- append samples into one rolling buffer with typed views;
- advance the reservoir edge from the newest sample;
- evict every ring against the same edge;
- query the latest valid sample per sensor.
- evict all sample kinds against the same edge;
- query the latest valid sample per sensor inside a typed view.
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;
- push timestamped sample metadata into a typed view of the rolling buffer;
- advance/query the shared edge and window start;
- query ring length;
- query total length and typed-view length;
- query the latest sample for a sensor hash.
- create/destroy an opaque `LocalcastRuntime`;
- append typed camera/audio/phase/event/render handles through producer calls;
- query a native runtime status struct with shared edge, window start, and ring
counts.
- query a native runtime status struct with shared edge, window start, total
count, and typed-view counts.
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,
audio buffer interpretation. The reservoir owns only retention, sample kind,
timestamp order, and the five-second shared-edge invariant.

View file

@ -8,8 +8,9 @@ tests, and offline analysis. It does not own dense live fusion or DSP.
## Crates
- `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.
owns one shared-edge rolling buffer with typed sample views.
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`.
@ -19,11 +20,12 @@ The reservoir ABI is intentionally small:
- `LocalcastReservoir` is opaque.
- `LocalcastSampleHandle` is sample metadata plus a `payload_handle`.
- Ring ids match the Perfect Machine reservoir rings:
- Sample kind ids match the Perfect Machine reservoir views:
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.
count the whole rolling buffer, count a typed view, and fetch the latest
sample for a sensor hash inside a typed view.
## Runtime ABI
@ -35,7 +37,7 @@ runtime path:
rays, surface claims, material claims, audio blocks, phase claims, event
claims, and render packets;
- it exposes `LocalcastRuntimeStatus` so Aquarium/Faust can inspect the shared
edge, window start, and per-ring sample counts without polling JSON or
edge, window start, total sample count, and typed-view counts without polling JSON or
MessagePack files.
Payload handles are owned by the caller. Aquarium should treat them as handles

View file

@ -8,16 +8,16 @@
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
enum LocalcastSampleKind {
LOCALCAST_SAMPLE_CAMERA_FRAME = 0,
LOCALCAST_SAMPLE_CAMERA_FEATURE = 1,
LOCALCAST_SAMPLE_SCENE_RAY = 2,
LOCALCAST_SAMPLE_SURFACE_CLAIM = 3,
LOCALCAST_SAMPLE_MATERIAL_CLAIM = 4,
LOCALCAST_SAMPLE_AUDIO_BLOCK = 5,
LOCALCAST_SAMPLE_PHASE_CLAIM = 6,
LOCALCAST_SAMPLE_EVENT_CLAIM = 7,
LOCALCAST_SAMPLE_RENDER_PACKET = 8
};
typedef struct LocalcastReservoir LocalcastReservoir;
@ -34,6 +34,7 @@ typedef struct LocalcastSampleHandle {
typedef struct LocalcastRuntimeStatus {
uint64_t edge_ns;
uint64_t window_start_ns;
size_t total_sample_count;
size_t camera_frame_count;
size_t camera_feature_count;
size_t scene_ray_count;
@ -50,18 +51,19 @@ void localcast_reservoir_destroy(LocalcastReservoir *reservoir);
bool localcast_reservoir_push(
LocalcastReservoir *reservoir,
uint32_t ring_kind,
uint32_t sample_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);
size_t localcast_reservoir_len(const LocalcastReservoir *reservoir);
size_t localcast_reservoir_view_len(const LocalcastReservoir *reservoir, uint32_t sample_kind);
bool localcast_reservoir_latest_for_sensor(
const LocalcastReservoir *reservoir,
uint32_t ring_kind,
uint32_t sample_kind,
uint64_t sensor_id_hash,
LocalcastSampleHandle *out_sample
);

View file

@ -1,9 +1,9 @@
use std::collections::{BTreeMap, VecDeque};
use std::collections::VecDeque;
pub const DEFAULT_RESERVOIR_NS: u64 = 5_000_000_000;
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum RingKind {
pub enum SampleKind {
CameraFrame,
CameraFeature,
SceneRay,
@ -15,7 +15,7 @@ pub enum RingKind {
RenderPacket,
}
impl RingKind {
impl SampleKind {
fn from_u32(value: u32) -> Option<Self> {
match value {
0 => Some(Self::CameraFrame),
@ -33,7 +33,8 @@ impl RingKind {
}
#[derive(Debug, Clone, PartialEq)]
pub struct Sample<T> {
pub struct ReservoirSample<T> {
pub kind: SampleKind,
pub sensor_id: String,
pub timestamp_ns: u64,
pub arrival_ns: u64,
@ -41,8 +42,9 @@ pub struct Sample<T> {
pub payload: T,
}
impl<T> Sample<T> {
impl<T> ReservoirSample<T> {
pub fn new(
kind: SampleKind,
sensor_id: impl Into<String>,
timestamp_ns: u64,
arrival_ns: u64,
@ -50,6 +52,7 @@ impl<T> Sample<T> {
payload: T,
) -> Self {
Self {
kind,
sensor_id: sensor_id.into(),
timestamp_ns,
arrival_ns,
@ -60,22 +63,26 @@ impl<T> Sample<T> {
}
#[derive(Debug, Clone)]
pub struct ReservoirRing<T> {
pub struct RollingReservoir<T> {
duration_ns: u64,
edge_ns: u64,
samples: VecDeque<Sample<T>>,
samples: VecDeque<ReservoirSample<T>>,
}
impl<T> ReservoirRing<T> {
impl<T> RollingReservoir<T> {
pub fn new(duration_ns: u64) -> Self {
Self {
duration_ns,
duration_ns: if duration_ns == 0 {
DEFAULT_RESERVOIR_NS
} else {
duration_ns
},
edge_ns: 0,
samples: VecDeque::new(),
}
}
pub fn push(&mut self, sample: Sample<T>) {
pub fn push(&mut self, sample: ReservoirSample<T>) {
self.edge_ns = self.edge_ns.max(sample.timestamp_ns);
self.samples.push_back(sample);
self.evict_expired();
@ -102,15 +109,29 @@ impl<T> ReservoirRing<T> {
self.samples.is_empty()
}
pub fn iter(&self) -> impl Iterator<Item = &Sample<T>> {
pub fn iter(&self) -> impl Iterator<Item = &ReservoirSample<T>> {
self.samples.iter()
}
pub fn latest_for_sensor(&self, sensor_id: &str) -> Option<&Sample<T>> {
pub fn view(&self, kind: SampleKind) -> impl Iterator<Item = &ReservoirSample<T>> {
self.samples
.iter()
.filter(move |sample| sample.kind == kind)
}
pub fn view_len(&self, kind: SampleKind) -> usize {
self.view(kind).count()
}
pub fn latest_for_sensor(
&self,
kind: SampleKind,
sensor_id: &str,
) -> Option<&ReservoirSample<T>> {
self.samples
.iter()
.rev()
.find(|sample| sample.sensor_id == sensor_id)
.find(|sample| sample.kind == kind && sample.sensor_id == sensor_id)
}
fn evict_expired(&mut self) {
@ -121,56 +142,7 @@ impl<T> ReservoirRing<T> {
}
}
#[derive(Debug, Clone)]
pub struct Reservoir<T> {
duration_ns: u64,
edge_ns: u64,
rings: BTreeMap<RingKind, ReservoirRing<T>>,
}
impl<T> Reservoir<T> {
pub fn new(duration_ns: u64) -> Self {
Self {
duration_ns,
edge_ns: 0,
rings: BTreeMap::new(),
}
}
pub fn push(&mut self, kind: RingKind, sample: Sample<T>) {
self.edge_ns = self.edge_ns.max(sample.timestamp_ns);
for ring in self.rings.values_mut() {
ring.set_edge(self.edge_ns);
}
let ring = self
.rings
.entry(kind)
.or_insert_with(|| ReservoirRing::new(self.duration_ns));
ring.push(sample);
ring.set_edge(self.edge_ns);
}
pub fn set_edge(&mut self, edge_ns: u64) {
self.edge_ns = self.edge_ns.max(edge_ns);
for ring in self.rings.values_mut() {
ring.set_edge(self.edge_ns);
}
}
pub fn ring(&self, kind: RingKind) -> Option<&ReservoirRing<T>> {
self.rings.get(&kind)
}
pub fn edge_ns(&self) -> u64 {
self.edge_ns
}
pub fn window_start_ns(&self) -> u64 {
self.edge_ns.saturating_sub(self.duration_ns)
}
}
impl<T> Default for Reservoir<T> {
impl<T> Default for RollingReservoir<T> {
fn default() -> Self {
Self::new(DEFAULT_RESERVOIR_NS)
}
@ -187,11 +159,11 @@ pub struct LocalcastSampleHandle {
}
pub struct LocalcastReservoir {
inner: Reservoir<LocalcastSampleHandle>,
inner: RollingReservoir<LocalcastSampleHandle>,
}
pub struct LocalcastRuntime {
reservoir: Reservoir<LocalcastSampleHandle>,
reservoir: RollingReservoir<LocalcastSampleHandle>,
}
#[repr(C)]
@ -199,6 +171,7 @@ pub struct LocalcastRuntime {
pub struct LocalcastRuntimeStatus {
pub edge_ns: u64,
pub window_start_ns: u64,
pub total_sample_count: usize,
pub camera_frame_count: usize,
pub camera_feature_count: usize,
pub scene_ray_count: usize,
@ -215,6 +188,7 @@ impl Default for LocalcastRuntimeStatus {
Self {
edge_ns: 0,
window_start_ns: 0,
total_sample_count: 0,
camera_frame_count: 0,
camera_feature_count: 0,
scene_ray_count: 0,
@ -230,59 +204,55 @@ impl Default for LocalcastRuntimeStatus {
impl LocalcastRuntime {
fn new(duration_ns: u64) -> Self {
let duration = if duration_ns == 0 {
DEFAULT_RESERVOIR_NS
} else {
duration_ns
};
Self {
reservoir: Reservoir::new(duration),
reservoir: RollingReservoir::new(duration_ns),
}
}
fn push(&mut self, kind: RingKind, sample: LocalcastSampleHandle) {
self.reservoir.push(
kind,
Sample::new(
sample.sensor_id_hash.to_string(),
sample.timestamp_ns,
sample.arrival_ns,
sample.sequence,
sample,
),
);
fn push(&mut self, kind: SampleKind, sample: LocalcastSampleHandle) {
self.reservoir.push(sample_from_handle(kind, sample));
}
fn ring_len(&self, kind: RingKind) -> usize {
self.reservoir.ring(kind).map_or(0, ReservoirRing::len)
fn view_len(&self, kind: SampleKind) -> usize {
self.reservoir.view_len(kind)
}
fn status(&self) -> LocalcastRuntimeStatus {
LocalcastRuntimeStatus {
edge_ns: self.reservoir.edge_ns(),
window_start_ns: self.reservoir.window_start_ns(),
camera_frame_count: self.ring_len(RingKind::CameraFrame),
camera_feature_count: self.ring_len(RingKind::CameraFeature),
scene_ray_count: self.ring_len(RingKind::SceneRay),
surface_claim_count: self.ring_len(RingKind::SurfaceClaim),
material_claim_count: self.ring_len(RingKind::MaterialClaim),
audio_block_count: self.ring_len(RingKind::AudioBlock),
phase_claim_count: self.ring_len(RingKind::PhaseClaim),
event_claim_count: self.ring_len(RingKind::EventClaim),
render_packet_count: self.ring_len(RingKind::RenderPacket),
total_sample_count: self.reservoir.len(),
camera_frame_count: self.view_len(SampleKind::CameraFrame),
camera_feature_count: self.view_len(SampleKind::CameraFeature),
scene_ray_count: self.view_len(SampleKind::SceneRay),
surface_claim_count: self.view_len(SampleKind::SurfaceClaim),
material_claim_count: self.view_len(SampleKind::MaterialClaim),
audio_block_count: self.view_len(SampleKind::AudioBlock),
phase_claim_count: self.view_len(SampleKind::PhaseClaim),
event_claim_count: self.view_len(SampleKind::EventClaim),
render_packet_count: self.view_len(SampleKind::RenderPacket),
}
}
}
fn sample_from_handle(
kind: SampleKind,
sample: LocalcastSampleHandle,
) -> ReservoirSample<LocalcastSampleHandle> {
ReservoirSample::new(
kind,
sample.sensor_id_hash.to_string(),
sample.timestamp_ns,
sample.arrival_ns,
sample.sequence,
sample,
)
}
#[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),
inner: RollingReservoir::new(duration_ns),
}))
}
@ -299,25 +269,16 @@ pub extern "C" fn localcast_reservoir_destroy(ptr: *mut LocalcastReservoir) {
#[unsafe(no_mangle)]
pub extern "C" fn localcast_reservoir_push(
ptr: *mut LocalcastReservoir,
ring_kind: u32,
sample_kind: u32,
sample: LocalcastSampleHandle,
) -> bool {
let Some(reservoir) = (unsafe { ptr.as_mut() }) else {
return false;
};
let Some(kind) = RingKind::from_u32(ring_kind) else {
let Some(kind) = SampleKind::from_u32(sample_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,
),
);
reservoir.inner.push(sample_from_handle(kind, sample));
true
}
@ -347,40 +308,45 @@ pub extern "C" fn localcast_reservoir_window_start_ns(ptr: *const LocalcastReser
}
#[unsafe(no_mangle)]
pub extern "C" fn localcast_reservoir_ring_len(
pub extern "C" fn localcast_reservoir_len(ptr: *const LocalcastReservoir) -> usize {
let Some(reservoir) = (unsafe { ptr.as_ref() }) else {
return 0;
};
reservoir.inner.len()
}
#[unsafe(no_mangle)]
pub extern "C" fn localcast_reservoir_view_len(
ptr: *const LocalcastReservoir,
ring_kind: u32,
sample_kind: u32,
) -> usize {
let Some(reservoir) = (unsafe { ptr.as_ref() }) else {
return 0;
};
let Some(kind) = RingKind::from_u32(ring_kind) else {
let Some(kind) = SampleKind::from_u32(sample_kind) else {
return 0;
};
reservoir.inner.ring(kind).map_or(0, ReservoirRing::len)
reservoir.inner.view_len(kind)
}
#[unsafe(no_mangle)]
pub extern "C" fn localcast_reservoir_latest_for_sensor(
ptr: *const LocalcastReservoir,
ring_kind: u32,
sample_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 {
let Some(kind) = SampleKind::from_u32(sample_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 {
let Some(sample) = reservoir.inner.latest_for_sensor(kind, &key) else {
return false;
};
*out = sample.payload;
@ -407,7 +373,7 @@ pub extern "C" fn localcast_runtime_push_camera_frame(
ptr: *mut LocalcastRuntime,
sample: LocalcastSampleHandle,
) -> bool {
localcast_runtime_push_typed(ptr, RingKind::CameraFrame, sample)
localcast_runtime_push_typed(ptr, SampleKind::CameraFrame, sample)
}
#[unsafe(no_mangle)]
@ -415,7 +381,7 @@ pub extern "C" fn localcast_runtime_push_camera_feature(
ptr: *mut LocalcastRuntime,
sample: LocalcastSampleHandle,
) -> bool {
localcast_runtime_push_typed(ptr, RingKind::CameraFeature, sample)
localcast_runtime_push_typed(ptr, SampleKind::CameraFeature, sample)
}
#[unsafe(no_mangle)]
@ -423,7 +389,7 @@ pub extern "C" fn localcast_runtime_push_scene_ray(
ptr: *mut LocalcastRuntime,
sample: LocalcastSampleHandle,
) -> bool {
localcast_runtime_push_typed(ptr, RingKind::SceneRay, sample)
localcast_runtime_push_typed(ptr, SampleKind::SceneRay, sample)
}
#[unsafe(no_mangle)]
@ -431,7 +397,7 @@ pub extern "C" fn localcast_runtime_push_surface_claim(
ptr: *mut LocalcastRuntime,
sample: LocalcastSampleHandle,
) -> bool {
localcast_runtime_push_typed(ptr, RingKind::SurfaceClaim, sample)
localcast_runtime_push_typed(ptr, SampleKind::SurfaceClaim, sample)
}
#[unsafe(no_mangle)]
@ -439,7 +405,7 @@ pub extern "C" fn localcast_runtime_push_material_claim(
ptr: *mut LocalcastRuntime,
sample: LocalcastSampleHandle,
) -> bool {
localcast_runtime_push_typed(ptr, RingKind::MaterialClaim, sample)
localcast_runtime_push_typed(ptr, SampleKind::MaterialClaim, sample)
}
#[unsafe(no_mangle)]
@ -447,7 +413,7 @@ pub extern "C" fn localcast_runtime_push_audio_block(
ptr: *mut LocalcastRuntime,
sample: LocalcastSampleHandle,
) -> bool {
localcast_runtime_push_typed(ptr, RingKind::AudioBlock, sample)
localcast_runtime_push_typed(ptr, SampleKind::AudioBlock, sample)
}
#[unsafe(no_mangle)]
@ -455,7 +421,7 @@ pub extern "C" fn localcast_runtime_push_phase_claim(
ptr: *mut LocalcastRuntime,
sample: LocalcastSampleHandle,
) -> bool {
localcast_runtime_push_typed(ptr, RingKind::PhaseClaim, sample)
localcast_runtime_push_typed(ptr, SampleKind::PhaseClaim, sample)
}
#[unsafe(no_mangle)]
@ -463,7 +429,7 @@ pub extern "C" fn localcast_runtime_push_event_claim(
ptr: *mut LocalcastRuntime,
sample: LocalcastSampleHandle,
) -> bool {
localcast_runtime_push_typed(ptr, RingKind::EventClaim, sample)
localcast_runtime_push_typed(ptr, SampleKind::EventClaim, sample)
}
#[unsafe(no_mangle)]
@ -471,7 +437,7 @@ pub extern "C" fn localcast_runtime_push_render_packet(
ptr: *mut LocalcastRuntime,
sample: LocalcastSampleHandle,
) -> bool {
localcast_runtime_push_typed(ptr, RingKind::RenderPacket, sample)
localcast_runtime_push_typed(ptr, SampleKind::RenderPacket, sample)
}
#[unsafe(no_mangle)]
@ -491,7 +457,7 @@ pub extern "C" fn localcast_runtime_status(
fn localcast_runtime_push_typed(
ptr: *mut LocalcastRuntime,
kind: RingKind,
kind: SampleKind,
sample: LocalcastSampleHandle,
) -> bool {
let Some(runtime) = (unsafe { ptr.as_mut() }) else {
@ -506,54 +472,140 @@ mod tests {
use super::*;
#[test]
fn ring_expires_from_newest_shared_edge() {
let mut ring = ReservoirRing::new(DEFAULT_RESERVOIR_NS);
ring.push(Sample::new("cam-a", 1_000_000_000, 1_000_000_010, 0, 1));
ring.push(Sample::new("cam-b", 4_000_000_000, 4_000_000_010, 0, 2));
ring.push(Sample::new("cam-a", 7_100_000_000, 7_100_000_010, 1, 3));
fn rolling_reservoir_expires_every_kind_from_one_edge() {
let mut reservoir = RollingReservoir::new(DEFAULT_RESERVOIR_NS);
reservoir.push(ReservoirSample::new(
SampleKind::CameraFrame,
"cam-a",
1_000_000_000,
1_000_000_010,
0,
"old-camera",
));
reservoir.push(ReservoirSample::new(
SampleKind::AudioBlock,
"audio",
7_000_000_001,
7_000_000_020,
0,
"audio-edge",
));
let timestamps = ring
.iter()
.map(|sample| sample.timestamp_ns)
.collect::<Vec<_>>();
assert_eq!(vec![4_000_000_000, 7_100_000_000], timestamps);
assert_eq!(2_100_000_000, ring.window_start_ns());
}
#[test]
fn reservoir_edge_expires_all_rings() {
let mut reservoir = Reservoir::default();
reservoir.push(
RingKind::CameraFrame,
Sample::new("cam-a", 1_000_000_000, 1_000_000_010, 0, "old-camera"),
);
reservoir.push(
RingKind::AudioBlock,
Sample::new("audio", 7_000_000_001, 7_000_000_020, 0, "audio-edge"),
);
let camera_ring = reservoir.ring(RingKind::CameraFrame).unwrap();
assert!(camera_ring.is_empty());
assert_eq!(1, reservoir.len());
assert_eq!(0, reservoir.view_len(SampleKind::CameraFrame));
assert_eq!(1, reservoir.view_len(SampleKind::AudioBlock));
assert_eq!(2_000_000_001, reservoir.window_start_ns());
}
#[test]
fn latest_for_sensor_ignores_other_sources() {
let mut ring = ReservoirRing::new(DEFAULT_RESERVOIR_NS);
ring.push(Sample::new("cam-a", 10, 11, 0, "a0"));
ring.push(Sample::new("cam-b", 12, 13, 0, "b0"));
ring.push(Sample::new("cam-a", 14, 15, 1, "a1"));
fn typed_views_share_storage_without_owning_retention() {
let mut reservoir = RollingReservoir::new(DEFAULT_RESERVOIR_NS);
reservoir.push(ReservoirSample::new(
SampleKind::CameraFrame,
"cam-a",
10,
11,
0,
"a0",
));
reservoir.push(ReservoirSample::new(
SampleKind::AudioBlock,
"mic",
12,
13,
0,
"m0",
));
reservoir.push(ReservoirSample::new(
SampleKind::CameraFrame,
"cam-b",
14,
15,
0,
"b0",
));
let latest = ring.latest_for_sensor("cam-a").unwrap();
let all = reservoir
.iter()
.map(|sample| sample.payload)
.collect::<Vec<_>>();
let camera = reservoir
.view(SampleKind::CameraFrame)
.map(|sample| sample.payload)
.collect::<Vec<_>>();
assert_eq!("a1", latest.payload);
assert_eq!(vec!["a0", "m0", "b0"], all);
assert_eq!(vec!["a0", "b0"], camera);
assert_eq!(3, reservoir.len());
}
#[test]
fn latest_for_sensor_is_scoped_to_kind_and_sensor() {
let mut reservoir = RollingReservoir::new(DEFAULT_RESERVOIR_NS);
reservoir.push(ReservoirSample::new(
SampleKind::CameraFrame,
"cam-a",
10,
11,
0,
"frame-a0",
));
reservoir.push(ReservoirSample::new(
SampleKind::AudioBlock,
"cam-a",
12,
13,
0,
"audio-a0",
));
reservoir.push(ReservoirSample::new(
SampleKind::CameraFrame,
"cam-a",
14,
15,
1,
"frame-a1",
));
let latest = reservoir
.latest_for_sensor(SampleKind::CameraFrame, "cam-a")
.unwrap();
assert_eq!("frame-a1", latest.payload);
assert_eq!(1, latest.sequence);
}
#[test]
fn c_abi_pushes_and_queries_latest_sample() {
fn late_samples_outside_the_window_cannot_be_observed() {
let mut reservoir = RollingReservoir::new(DEFAULT_RESERVOIR_NS);
reservoir.push(ReservoirSample::new(
SampleKind::AudioBlock,
"audio",
8_000_000_000,
8_000_000_010,
0,
"edge",
));
reservoir.push(ReservoirSample::new(
SampleKind::CameraFrame,
"fallback-camera",
1_000_000_000,
8_000_000_020,
0,
"too-late",
));
assert_eq!(1, reservoir.len());
assert_eq!(0, reservoir.view_len(SampleKind::CameraFrame));
assert!(
reservoir
.latest_for_sensor(SampleKind::CameraFrame, "fallback-camera")
.is_none()
);
}
#[test]
fn c_abi_pushes_and_queries_latest_sample_from_view() {
let reservoir = localcast_reservoir_create(DEFAULT_RESERVOIR_NS);
let pushed = localcast_reservoir_push(
reservoir,
@ -577,13 +629,14 @@ mod tests {
assert!(pushed);
assert!(found);
assert_eq!(1, localcast_reservoir_ring_len(reservoir, 0));
assert_eq!(1, localcast_reservoir_len(reservoir));
assert_eq!(1, localcast_reservoir_view_len(reservoir, 0));
assert_eq!(99, out.payload_handle);
localcast_reservoir_destroy(reservoir);
}
#[test]
fn c_abi_rejects_nulls_and_unknown_ring_kinds() {
fn c_abi_rejects_nulls_and_unknown_sample_kinds() {
let sample = LocalcastSampleHandle {
sensor_id_hash: 1,
timestamp_ns: 2,
@ -597,7 +650,8 @@ mod tests {
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_eq!(0, localcast_reservoir_len(std::ptr::null()));
assert_eq!(0, localcast_reservoir_view_len(std::ptr::null(), 0));
assert!(!localcast_reservoir_latest_for_sensor(
std::ptr::null(),
0,
@ -607,7 +661,7 @@ mod tests {
let reservoir = localcast_reservoir_create(0);
assert!(!localcast_reservoir_push(reservoir, 99, sample));
assert_eq!(0, localcast_reservoir_ring_len(reservoir, 99));
assert_eq!(0, localcast_reservoir_view_len(reservoir, 99));
assert!(!localcast_reservoir_latest_for_sensor(
reservoir,
0,
@ -618,7 +672,7 @@ mod tests {
}
#[test]
fn runtime_spine_routes_typed_producers_into_one_reservoir() {
fn runtime_spine_routes_typed_producers_into_one_rolling_buffer() {
let runtime = localcast_runtime_create(DEFAULT_RESERVOIR_NS);
let camera = LocalcastSampleHandle {
sensor_id_hash: 10,
@ -650,6 +704,7 @@ mod tests {
assert!(localcast_runtime_status(runtime, &mut status));
assert_eq!(7_000_000_010, status.edge_ns);
assert_eq!(2_000_000_010, status.window_start_ns);
assert_eq!(2, status.total_sample_count);
assert_eq!(0, status.camera_frame_count);
assert_eq!(1, status.audio_block_count);
assert_eq!(1, status.phase_claim_count);

View file

@ -31,9 +31,8 @@ Ownership:
offline analysis, and diagnostics. It is not the stream hot path.
- OpenGL is not the production Spout sink. Aquarium owns production Spout2
publication.
- `native/reservoir` is the first native crate. Its current shared-edge typed
rings proved the retention invariant, but the target is one time-ordered
rolling buffer with typed indexes/views. Retention has one owner.
- `native/reservoir` is the first native crate. It now uses one time-ordered
rolling buffer with typed views. Retention has one owner.
Invariant: the five-second spatiotemporal reservoir is the live authority.
Producers append sample handles through typed native calls, optimizers refine,

View file

@ -52,3 +52,4 @@
{"ts": "2026-05-19T06:31:33+00:00", "type": "decision", "status": "ok", "note": "Perfect Machine target is now explicit: LocalCastBridge owns config/calibration/status, Aquarium owns dense GPU fusion/material/brush rendering and Spout publication, Faust owns hot audio DSP, and one five-second native reservoir is the live authority. Python remains tooling and compatibility, not the stream hot path."}
{"ts": "2026-05-19T06:35:13+00:00", "type": "implementation", "status": "ok", "note": "Started native Perfect Machine runtime with native/reservoir Rust crate. It owns shared-edge five-second sample retention for typed rings and passes cargo tests; Aquarium/Faust bindings should build on this invariant instead of copying deadline bridge caches."}
{"ts": "2026-05-19T07:39:41+00:00", "type": "decision", "status": "ok", "note": "Native rebuild cut line recorded: live path must abandon Python producers, OpenGL Spout sink, JSON live stores, and independent typed rings; next foundation is one native rolling reservoir with typed indexes/views feeding Aquarium, Faust, OBS, and typed CultNet docs."}
{"ts": "2026-05-19T07:52:44+00:00", "type": "implementation", "status": "ok", "note": "Native reservoir first cut complete: native/reservoir now uses one time-ordered rolling buffer with typed views, total/view length ABI, latest-by-kind/source lookup, and tests proving single-edge expiry plus stale late-sample exclusion. Python/OpenGL bridge remains next quarantine target."}

View file

@ -48,10 +48,9 @@ accepted_design:
deadline Python/OpenGL bridge as a foundation and defines the next coherent
rebuild target.
- `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. Its current shared-edge
typed rings proved the expiry invariant, but the live target is stricter:
one time-ordered rolling buffer with typed indexes/views, so retention has
exactly one owner.
- `native/reservoir` is the first native Rust crate. It now uses one
time-ordered rolling buffer with typed views, so retention has exactly one
owner while Aquarium/Faust still get kind-scoped queries.
- `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.
@ -59,8 +58,8 @@ accepted_design:
- Persistence follows the active repo pattern: map, scratch, evidence, branches, handoff, system map, implementation plan, state helpers.
active_subgoals:
- Rewrite `native/reservoir` from independent typed rings into one rolling
buffer with typed indexes/views and a single edge.
- Bind Aquarium/Faust to the rolling-buffer `LocalcastRuntime` in the native
reservoir C ABI described by `native/reservoir/include/localcast_reservoir.h`.
- Delete or quarantine Python live producers and the OpenGL Spout sink before
adding new live features.
- Bind Aquarium/Faust to `LocalcastRuntime` in the native reservoir C ABI described by `native/reservoir/include/localcast_reservoir.h`.
@ -348,9 +347,8 @@ current_status:
stochastic transient hypotheses, and synthetic fusion support while still
seeing lower-priority fallback diagnostics when the Leap capture path stalls.
next_action: >
Stop live feature work on the Python/OpenGL bridge. First rewrite
`native/reservoir` into a single time-ordered rolling buffer with typed
indexes/views, update the ABI/tests around that invariant, and quarantine
Python/OpenGL code as diagnostics. Then bind Aquarium/Faust to the native
runtime and resume hardware calibration through typed CultNet/native
surfaces only.
Stop live feature work on the Python/OpenGL bridge. The first native cut is
complete: `native/reservoir` is now a single time-ordered rolling buffer
with typed views and updated ABI/tests. Next quarantine Python/OpenGL code
as diagnostics, then bind Aquarium/Faust to the native runtime and resume
hardware calibration through typed CultNet/native surfaces only.

View file

@ -16,7 +16,7 @@ class PerfectMachineContractTests(unittest.TestCase):
self.assertEqual("Faust", data["authorities"]["hotAudioDsp"])
self.assertEqual("Aquarium", data["outputs"]["video"]["owner"])
def test_contract_covers_six_cameras_six_mics_and_required_rings(self):
def test_contract_covers_six_cameras_six_mics_and_required_sample_views(self):
data = json.loads((ROOT / "config" / "perfect-machine.example.json").read_text(encoding="utf-8"))
self.assertEqual(6, len(data["visualSensors"]))
@ -29,6 +29,7 @@ class PerfectMachineContractTests(unittest.TestCase):
"phase_claim",
})
self.assertIn("dense-feature-extraction", data["bridgeDemotion"]["notPython"])
self.assertEqual("single-native-rolling-buffer-with-typed-views", data["reservoir"]["storageLayout"])
def test_native_reservoir_header_exposes_small_c_abi(self):
header = (ROOT / "native" / "reservoir" / "include" / "localcast_reservoir.h").read_text(encoding="utf-8")
@ -41,7 +42,9 @@ class PerfectMachineContractTests(unittest.TestCase):
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("enum LocalcastSampleKind", header)
self.assertIn("size_t localcast_reservoir_len", header)
self.assertIn("size_t localcast_reservoir_view_len", header)
self.assertIn("bool localcast_reservoir_latest_for_sensor", header)
def test_native_runtime_header_exposes_typed_producer_spine(self):
@ -50,6 +53,7 @@ class PerfectMachineContractTests(unittest.TestCase):
self.assertIn("typedef struct LocalcastRuntime LocalcastRuntime;", header)
self.assertIn("typedef struct LocalcastRuntimeStatus", header)
self.assertIn("uint64_t edge_ns;", header)
self.assertIn("size_t total_sample_count;", header)
self.assertIn("size_t camera_frame_count;", header)
self.assertIn("LocalcastRuntime *localcast_runtime_create", header)
self.assertIn("void localcast_runtime_destroy", header)