Add native producer ingress ABI

This commit is contained in:
Meta Vens 2026-05-19 10:34:18 +01:00
commit fb08ed5b06
7 changed files with 213 additions and 2 deletions

View file

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

View file

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

View file

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

View file

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

View file

@ -191,6 +191,12 @@ pub struct LocalcastRuntime {
reservoir: RollingReservoir<LocalcastSampleHandle>,
}
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);

View file

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

View file

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