From fb08ed5b06ae3b084e9bf6604c4de68505b15c02 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 19 May 2026 10:34:18 +0100 Subject: [PATCH] Add native producer ingress ABI --- docs/implementation-plan.md | 6 +- docs/perfect-machine.md | 7 + native/README.md | 7 + .../reservoir/include/localcast_reservoir.h | 18 ++ native/reservoir/src/lib.rs | 171 ++++++++++++++++++ state/evidence.jsonl | 1 + tests/test_perfect_machine_contract.py | 5 + 7 files changed, 213 insertions(+), 2 deletions(-) diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md index 0f82671..7deb2d7 100644 --- a/docs/implementation-plan.md +++ b/docs/implementation-plan.md @@ -28,6 +28,8 @@ shape removes independent per-kind storage from the live foundation. - `LocalcastRuntime` wraps the current reservoir with typed native producer calls and total/typed read functions. It is the intended live spine for Aquarium/Faust bindings. + - `LocalcastProducer` owns native ingress source identity and sequence + assignment before appending live handles into `LocalcastRuntime`. - Repo-local persistence machinery. - First architecture map. - Example config for one video source plus two audio sources. @@ -112,8 +114,8 @@ shape removes independent per-kind storage from the live foundation. diagnostic JSON render-frame adapters, diagnostic JSON LOD adapters, and Python reservoir-window clipping. 2. Bind Aquarium/Faust to the rolling-buffer `LocalcastRuntime`. -3. Move camera/mic/loopback ingest into native capture workers that append - typed sample handles. +3. Move camera/mic/loopback ingest into native capture workers that use + `LocalcastProducer` to append typed sample handles. 4. Move feature extraction, flow, cross-view matching, LOD reconciliation, material fitting, brush/splat rendering, and Spout2 publication into Aquarium GPU compute. diff --git a/docs/perfect-machine.md b/docs/perfect-machine.md index c6e9e3e..e4dd621 100644 --- a/docs/perfect-machine.md +++ b/docs/perfect-machine.md @@ -94,6 +94,11 @@ append into one shared five-second window without crossing a Python file cache. It also exposes total and typed-view reads so Aquarium/Faust can consume that same window without building private histories. +`LocalcastProducer` is the first native capture-worker boundary. It owns sample +kind, source identity, and sequence assignment before appending live handles into +`LocalcastRuntime`; hardware adapters should provide timestamps and payload +handles, not reservoir authority. + ## Visual Fusion Camera fusion is feature matching across the reservoir, not a latest-frame @@ -181,6 +186,8 @@ in `native/reservoir/include/localcast_reservoir.h`: - reject diagnostic/probe/fallback and unknown-flagged samples at the live reservoir boundary via sample provenance flags. - create/destroy an opaque `LocalcastRuntime`; +- create/destroy opaque `LocalcastProducer` ingress helpers; +- push live producer samples while the producer owns sequence/source metadata; - append typed camera/audio/phase/event/render handles through producer calls; - query a native runtime status struct with shared edge, window start, total count, and typed-view counts; diff --git a/native/README.md b/native/README.md index 115dc05..1c6e367 100644 --- a/native/README.md +++ b/native/README.md @@ -45,6 +45,13 @@ runtime path: - it exposes total and typed-view sample reads so Aquarium/Faust can consume the same rolling window producers append to. +`LocalcastProducer` is the native ingress helper for capture workers: + +- it owns sample kind, source hash, and monotonically increasing sequence; +- it creates live sample handles with `flags == 0`; +- it appends into `LocalcastRuntime` without letting hardware adapters invent + reservoir metadata. + 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 diff --git a/native/reservoir/include/localcast_reservoir.h b/native/reservoir/include/localcast_reservoir.h index 0987ccf..587c1f3 100644 --- a/native/reservoir/include/localcast_reservoir.h +++ b/native/reservoir/include/localcast_reservoir.h @@ -22,6 +22,7 @@ enum LocalcastSampleKind { typedef struct LocalcastReservoir LocalcastReservoir; typedef struct LocalcastRuntime LocalcastRuntime; +typedef struct LocalcastProducer LocalcastProducer; typedef struct LocalcastSampleHandle { uint64_t sensor_id_hash; @@ -125,6 +126,23 @@ bool localcast_runtime_latest_for_sensor( LocalcastSampleHandle *out_sample ); +LocalcastProducer *localcast_producer_create( + uint32_t sample_kind, + uint64_t sensor_id_hash, + uint64_t initial_sequence +); +void localcast_producer_destroy(LocalcastProducer *producer); +uint64_t localcast_producer_next_sequence(const LocalcastProducer *producer); + +bool localcast_producer_push( + LocalcastProducer *producer, + LocalcastRuntime *runtime, + uint64_t timestamp_ns, + uint64_t arrival_ns, + uint64_t payload_handle, + LocalcastSampleHandle *out_sample +); + #ifdef __cplusplus } #endif diff --git a/native/reservoir/src/lib.rs b/native/reservoir/src/lib.rs index 7e006c7..c838e50 100644 --- a/native/reservoir/src/lib.rs +++ b/native/reservoir/src/lib.rs @@ -191,6 +191,12 @@ pub struct LocalcastRuntime { reservoir: RollingReservoir, } +pub struct LocalcastProducer { + kind: SampleKind, + sensor_id_hash: u64, + next_sequence: u64, +} + #[repr(C)] #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct LocalcastRuntimeStatus { @@ -260,6 +266,35 @@ impl LocalcastRuntime { } } +impl LocalcastProducer { + fn new(kind: SampleKind, sensor_id_hash: u64, initial_sequence: u64) -> Self { + Self { + kind, + sensor_id_hash, + next_sequence: initial_sequence, + } + } + + fn sample( + &mut self, + timestamp_ns: u64, + arrival_ns: u64, + payload_handle: u64, + ) -> LocalcastSampleHandle { + let sequence = self.next_sequence; + self.next_sequence = self.next_sequence.saturating_add(1); + LocalcastSampleHandle { + sensor_id_hash: self.sensor_id_hash, + timestamp_ns, + arrival_ns, + sequence, + payload_handle, + flags: 0, + reserved: 0, + } + } +} + fn sample_from_handle( kind: SampleKind, sample: LocalcastSampleHandle, @@ -627,6 +662,66 @@ pub extern "C" fn localcast_runtime_latest_for_sensor( true } +#[unsafe(no_mangle)] +pub extern "C" fn localcast_producer_create( + sample_kind: u32, + sensor_id_hash: u64, + initial_sequence: u64, +) -> *mut LocalcastProducer { + let Some(kind) = SampleKind::from_u32(sample_kind) else { + return std::ptr::null_mut(); + }; + if sensor_id_hash == 0 { + return std::ptr::null_mut(); + } + Box::into_raw(Box::new(LocalcastProducer::new( + kind, + sensor_id_hash, + initial_sequence, + ))) +} + +#[unsafe(no_mangle)] +pub extern "C" fn localcast_producer_destroy(ptr: *mut LocalcastProducer) { + if ptr.is_null() { + return; + } + unsafe { + drop(Box::from_raw(ptr)); + } +} + +#[unsafe(no_mangle)] +pub extern "C" fn localcast_producer_next_sequence(ptr: *const LocalcastProducer) -> u64 { + let Some(producer) = (unsafe { ptr.as_ref() }) else { + return 0; + }; + producer.next_sequence +} + +#[unsafe(no_mangle)] +pub extern "C" fn localcast_producer_push( + producer_ptr: *mut LocalcastProducer, + runtime_ptr: *mut LocalcastRuntime, + timestamp_ns: u64, + arrival_ns: u64, + payload_handle: u64, + out_sample: *mut LocalcastSampleHandle, +) -> bool { + let Some(producer) = (unsafe { producer_ptr.as_mut() }) else { + return false; + }; + let Some(runtime) = (unsafe { runtime_ptr.as_mut() }) else { + return false; + }; + let sample = producer.sample(timestamp_ns, arrival_ns, payload_handle); + runtime.push(producer.kind, sample); + if let Some(out) = unsafe { out_sample.as_mut() } { + *out = sample; + } + true +} + fn localcast_runtime_push_typed( ptr: *mut LocalcastRuntime, kind: SampleKind, @@ -1051,6 +1146,82 @@ mod tests { localcast_runtime_destroy(runtime); } + #[test] + fn producer_owns_source_identity_sequence_and_live_flags() { + let runtime = localcast_runtime_create(DEFAULT_RESERVOIR_NS); + let producer = localcast_producer_create(0, 77, 41); + let mut sample = handle(0, 0, 0, 0, 0); + + assert!(!producer.is_null()); + assert_eq!(41, localcast_producer_next_sequence(producer)); + assert!(localcast_producer_push( + producer, + runtime, + 1_000, + 1_010, + 900, + &mut sample, + )); + assert_eq!(77, sample.sensor_id_hash); + assert_eq!(41, sample.sequence); + assert_eq!(0, sample.flags); + assert_eq!(42, localcast_producer_next_sequence(producer)); + + assert!(localcast_producer_push( + producer, + runtime, + 1_100, + 1_110, + 901, + std::ptr::null_mut(), + )); + assert_eq!(43, localcast_producer_next_sequence(producer)); + assert_eq!(2, localcast_runtime_view_len(runtime, 0)); + + assert!(localcast_runtime_latest_for_sensor( + runtime, + 0, + 77, + &mut sample, + )); + assert_eq!(42, sample.sequence); + assert_eq!(901, sample.payload_handle); + + localcast_producer_destroy(producer); + localcast_runtime_destroy(runtime); + } + + #[test] + fn producer_rejects_unknown_kind_null_runtime_and_empty_source() { + assert!(localcast_producer_create(99, 1, 0).is_null()); + assert!(localcast_producer_create(0, 0, 0).is_null()); + assert_eq!(0, localcast_producer_next_sequence(std::ptr::null())); + + let producer = localcast_producer_create(0, 1, 0); + let runtime = localcast_runtime_create(DEFAULT_RESERVOIR_NS); + + assert!(!localcast_producer_push( + std::ptr::null_mut(), + runtime, + 1, + 1, + 1, + std::ptr::null_mut(), + )); + assert!(!localcast_producer_push( + producer, + std::ptr::null_mut(), + 1, + 1, + 1, + std::ptr::null_mut(), + )); + assert_eq!(0, localcast_producer_next_sequence(producer)); + + localcast_producer_destroy(producer); + localcast_runtime_destroy(runtime); + } + #[test] fn runtime_spine_rejects_nulls() { let sample = handle(1, 2, 3, 4, 5); diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 3390c05..78193a1 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -66,3 +66,4 @@ {"ts": "2026-05-19T10:35:00+01:00", "type": "implementation", "status": "ok", "note": "Deleted the Python/OpenGL Spout publisher and diagnostic_stream_spout launcher. The only surviving visual render code in LocalCastBridge is pure diagnostic render_math plus typed visual cache adapters; production OBS publication is now exclusively an Aquarium responsibility."} {"ts": "2026-05-19T10:48:00+01:00", "type": "implementation", "status": "ok", "note": "Removed the Python visual producer from the scripts command surface by moving it to localcast.diagnostics.visual_producer and updating tests/docs to import it as diagnostic code. It remains a fossil to delete after native/Aquarium equivalents own the behavior."} {"ts": "2026-05-19T11:02:00+01:00", "type": "implementation", "status": "ok", "note": "LocalcastRuntime now exposes total and typed-view window reads through the C ABI: len, view_len, sample_at, view_sample_at, and latest_for_sensor. Aquarium/Faust consumers can walk the same rolling buffer that native producers append to instead of building private caches."} +{"ts": "2026-05-19T11:20:00+01:00", "type": "implementation", "status": "ok", "note": "Added LocalcastProducer to the native ABI. Producers own sample kind, source hash, and sequence assignment, create live flags==0 handles, and append into LocalcastRuntime so hardware adapters do not manufacture reservoir metadata by hand."} diff --git a/tests/test_perfect_machine_contract.py b/tests/test_perfect_machine_contract.py index fefc98a..dee8c6f 100644 --- a/tests/test_perfect_machine_contract.py +++ b/tests/test_perfect_machine_contract.py @@ -35,6 +35,7 @@ class PerfectMachineContractTests(unittest.TestCase): header = (ROOT / "native" / "reservoir" / "include" / "localcast_reservoir.h").read_text(encoding="utf-8") self.assertIn("typedef struct LocalcastReservoir LocalcastReservoir;", header) + self.assertIn("typedef struct LocalcastProducer LocalcastProducer;", header) self.assertIn("typedef struct LocalcastSampleHandle", header) self.assertIn("uint64_t payload_handle;", header) self.assertIn("uint32_t flags;", header) @@ -77,6 +78,10 @@ class PerfectMachineContractTests(unittest.TestCase): "localcast_runtime_sample_at", "localcast_runtime_view_sample_at", "localcast_runtime_latest_for_sensor", + "localcast_producer_create", + "localcast_producer_destroy", + "localcast_producer_next_sequence", + "localcast_producer_push", ]: self.assertIn(function, header)