diff --git a/config/perfect-machine.example.json b/config/perfect-machine.example.json index dbe7b30..ab97e73 100644 --- a/config/perfect-machine.example.json +++ b/config/perfect-machine.example.json @@ -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", diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md index 04e429a..e904d79 100644 --- a/docs/implementation-plan.md +++ b/docs/implementation-plan.md @@ -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. diff --git a/docs/perfect-machine.md b/docs/perfect-machine.md index 0d73759..6895012 100644 --- a/docs/perfect-machine.md +++ b/docs/perfect-machine.md @@ -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. diff --git a/native/README.md b/native/README.md index a4b3b97..a73fa55 100644 --- a/native/README.md +++ b/native/README.md @@ -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 diff --git a/native/reservoir/include/localcast_reservoir.h b/native/reservoir/include/localcast_reservoir.h index d7d14ca..f73fe0e 100644 --- a/native/reservoir/include/localcast_reservoir.h +++ b/native/reservoir/include/localcast_reservoir.h @@ -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 ); diff --git a/native/reservoir/src/lib.rs b/native/reservoir/src/lib.rs index 27917c8..218aaf5 100644 --- a/native/reservoir/src/lib.rs +++ b/native/reservoir/src/lib.rs @@ -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 { match value { 0 => Some(Self::CameraFrame), @@ -33,7 +33,8 @@ impl RingKind { } #[derive(Debug, Clone, PartialEq)] -pub struct Sample { +pub struct ReservoirSample { + pub kind: SampleKind, pub sensor_id: String, pub timestamp_ns: u64, pub arrival_ns: u64, @@ -41,8 +42,9 @@ pub struct Sample { pub payload: T, } -impl Sample { +impl ReservoirSample { pub fn new( + kind: SampleKind, sensor_id: impl Into, timestamp_ns: u64, arrival_ns: u64, @@ -50,6 +52,7 @@ impl Sample { payload: T, ) -> Self { Self { + kind, sensor_id: sensor_id.into(), timestamp_ns, arrival_ns, @@ -60,22 +63,26 @@ impl Sample { } #[derive(Debug, Clone)] -pub struct ReservoirRing { +pub struct RollingReservoir { duration_ns: u64, edge_ns: u64, - samples: VecDeque>, + samples: VecDeque>, } -impl ReservoirRing { +impl RollingReservoir { 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) { + pub fn push(&mut self, sample: ReservoirSample) { self.edge_ns = self.edge_ns.max(sample.timestamp_ns); self.samples.push_back(sample); self.evict_expired(); @@ -102,15 +109,29 @@ impl ReservoirRing { self.samples.is_empty() } - pub fn iter(&self) -> impl Iterator> { + pub fn iter(&self) -> impl Iterator> { self.samples.iter() } - pub fn latest_for_sensor(&self, sensor_id: &str) -> Option<&Sample> { + pub fn view(&self, kind: SampleKind) -> impl Iterator> { + 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> { 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 ReservoirRing { } } -#[derive(Debug, Clone)] -pub struct Reservoir { - duration_ns: u64, - edge_ns: u64, - rings: BTreeMap>, -} - -impl Reservoir { - 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) { - 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> { - 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 Default for Reservoir { +impl Default for RollingReservoir { fn default() -> Self { Self::new(DEFAULT_RESERVOIR_NS) } @@ -187,11 +159,11 @@ pub struct LocalcastSampleHandle { } pub struct LocalcastReservoir { - inner: Reservoir, + inner: RollingReservoir, } pub struct LocalcastRuntime { - reservoir: Reservoir, + reservoir: RollingReservoir, } #[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 { + 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::>(); - - 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::>(); + let camera = reservoir + .view(SampleKind::CameraFrame) + .map(|sample| sample.payload) + .collect::>(); - 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); diff --git a/notes/current-system-map.md b/notes/current-system-map.md index 3ca35b7..846f2a7 100644 --- a/notes/current-system-map.md +++ b/notes/current-system-map.md @@ -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, diff --git a/state/evidence.jsonl b/state/evidence.jsonl index e471be2..82f5702 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -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."} diff --git a/state/map.yaml b/state/map.yaml index c1ef243..0b2a264 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -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. diff --git a/tests/test_perfect_machine_contract.py b/tests/test_perfect_machine_contract.py index 469f295..60d43c9 100644 --- a/tests/test_perfect_machine_contract.py +++ b/tests/test_perfect_machine_contract.py @@ -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)