diff --git a/docs/native-rebuild-plan.md b/docs/native-rebuild-plan.md index d7ecc36..5e5c1d0 100644 --- a/docs/native-rebuild-plan.md +++ b/docs/native-rebuild-plan.md @@ -65,6 +65,7 @@ sample has: - arrival timestamp - sequence - payload handle +- provenance flags Typed ring views may exist as indexes over the rolling buffer, but they do not own retention. Expiry happens once, against the reservoir edge. No private diff --git a/docs/perfect-machine.md b/docs/perfect-machine.md index 8319b8d..fe253bb 100644 --- a/docs/perfect-machine.md +++ b/docs/perfect-machine.md @@ -176,6 +176,8 @@ in `native/reservoir/include/localcast_reservoir.h`: - query total length and typed-view length; - read samples by total rolling-buffer index or typed-view index; - query the latest sample for a sensor hash. +- reject diagnostic/probe/fallback samples at the live reservoir boundary via + sample provenance flags. - 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, total diff --git a/native/README.md b/native/README.md index dd6e48f..62b21aa 100644 --- a/native/README.md +++ b/native/README.md @@ -19,7 +19,9 @@ tests, and offline analysis. It does not own dense live fusion or DSP. The reservoir ABI is intentionally small: - `LocalcastReservoir` is opaque. -- `LocalcastSampleHandle` is sample metadata plus a `payload_handle`. +- `LocalcastSampleHandle` is sample metadata plus a `payload_handle` and + provenance flags. Samples marked `LOCALCAST_SAMPLE_FLAG_DIAGNOSTIC` are + rejected by the live reservoir. - 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. diff --git a/native/reservoir/include/localcast_reservoir.h b/native/reservoir/include/localcast_reservoir.h index 5fc430f..b61f39f 100644 --- a/native/reservoir/include/localcast_reservoir.h +++ b/native/reservoir/include/localcast_reservoir.h @@ -29,8 +29,14 @@ typedef struct LocalcastSampleHandle { uint64_t arrival_ns; uint64_t sequence; uint64_t payload_handle; + uint32_t flags; + uint32_t reserved; } LocalcastSampleHandle; +enum LocalcastSampleFlags { + LOCALCAST_SAMPLE_FLAG_DIAGNOSTIC = 1u << 0 +}; + typedef struct LocalcastRuntimeStatus { uint64_t edge_ns; uint64_t window_start_ns; diff --git a/native/reservoir/src/lib.rs b/native/reservoir/src/lib.rs index b8b97cb..55d6f45 100644 --- a/native/reservoir/src/lib.rs +++ b/native/reservoir/src/lib.rs @@ -1,6 +1,7 @@ use std::collections::VecDeque; pub const DEFAULT_RESERVOIR_NS: u64 = 5_000_000_000; +pub const LOCALCAST_SAMPLE_FLAG_DIAGNOSTIC: u32 = 1 << 0; #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] pub enum SampleKind { @@ -164,6 +165,8 @@ pub struct LocalcastSampleHandle { pub arrival_ns: u64, pub sequence: u64, pub payload_handle: u64, + pub flags: u32, + pub reserved: u32, } pub struct LocalcastReservoir { @@ -257,6 +260,10 @@ fn sample_from_handle( ) } +fn is_live_sample(sample: LocalcastSampleHandle) -> bool { + sample.flags & LOCALCAST_SAMPLE_FLAG_DIAGNOSTIC == 0 +} + #[unsafe(no_mangle)] pub extern "C" fn localcast_reservoir_create(duration_ns: u64) -> *mut LocalcastReservoir { Box::into_raw(Box::new(LocalcastReservoir { @@ -286,6 +293,9 @@ pub extern "C" fn localcast_reservoir_push( let Some(kind) = SampleKind::from_u32(sample_kind) else { return false; }; + if !is_live_sample(sample) { + return false; + } reservoir.inner.push(sample_from_handle(kind, sample)); true } @@ -518,6 +528,9 @@ fn localcast_runtime_push_typed( let Some(runtime) = (unsafe { ptr.as_mut() }) else { return false; }; + if !is_live_sample(sample) { + return false; + } runtime.push(kind, sample); true } @@ -526,6 +539,43 @@ fn localcast_runtime_push_typed( mod tests { use super::*; + fn handle( + sensor_id_hash: u64, + timestamp_ns: u64, + arrival_ns: u64, + sequence: u64, + payload_handle: u64, + ) -> LocalcastSampleHandle { + LocalcastSampleHandle { + sensor_id_hash, + timestamp_ns, + arrival_ns, + sequence, + payload_handle, + flags: 0, + reserved: 0, + } + } + + fn diagnostic_handle( + sensor_id_hash: u64, + timestamp_ns: u64, + arrival_ns: u64, + sequence: u64, + payload_handle: u64, + ) -> LocalcastSampleHandle { + LocalcastSampleHandle { + flags: LOCALCAST_SAMPLE_FLAG_DIAGNOSTIC, + ..handle( + sensor_id_hash, + timestamp_ns, + arrival_ns, + sequence, + payload_handle, + ) + } + } + #[test] fn rolling_reservoir_expires_every_kind_from_one_edge() { let mut reservoir = RollingReservoir::new(DEFAULT_RESERVOIR_NS); @@ -705,24 +755,8 @@ mod tests { #[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, - 0, - LocalcastSampleHandle { - sensor_id_hash: 42, - timestamp_ns: 10, - arrival_ns: 11, - sequence: 7, - payload_handle: 99, - }, - ); - let mut out = LocalcastSampleHandle { - sensor_id_hash: 0, - timestamp_ns: 0, - arrival_ns: 0, - sequence: 0, - payload_handle: 0, - }; + let pushed = localcast_reservoir_push(reservoir, 0, handle(42, 10, 11, 7, 99)); + let mut out = handle(0, 0, 0, 0, 0); let found = localcast_reservoir_latest_for_sensor(reservoir, 0, 42, &mut out); assert!(pushed); @@ -739,45 +773,21 @@ mod tests { assert!(localcast_reservoir_push( reservoir, 0, - LocalcastSampleHandle { - sensor_id_hash: 10, - timestamp_ns: 10, - arrival_ns: 11, - sequence: 0, - payload_handle: 100, - }, + handle(10, 10, 11, 0, 100), )); assert!(localcast_reservoir_push( reservoir, 5, - LocalcastSampleHandle { - sensor_id_hash: 20, - timestamp_ns: 12, - arrival_ns: 13, - sequence: 0, - payload_handle: 200, - }, + handle(20, 12, 13, 0, 200), )); assert!(localcast_reservoir_push( reservoir, 0, - LocalcastSampleHandle { - sensor_id_hash: 30, - timestamp_ns: 14, - arrival_ns: 15, - sequence: 0, - payload_handle: 300, - }, + handle(30, 14, 15, 0, 300), )); let mut kind = 99; - let mut sample = LocalcastSampleHandle { - sensor_id_hash: 0, - timestamp_ns: 0, - arrival_ns: 0, - sequence: 0, - payload_handle: 0, - }; + let mut sample = handle(0, 0, 0, 0, 0); assert!(localcast_reservoir_sample_at( reservoir, @@ -809,15 +819,24 @@ mod tests { localcast_reservoir_destroy(reservoir); } + #[test] + fn c_abi_rejects_diagnostic_samples_from_live_reservoir() { + let reservoir = localcast_reservoir_create(DEFAULT_RESERVOIR_NS); + + assert!(!localcast_reservoir_push( + reservoir, + 0, + diagnostic_handle(66, 10, 11, 0, 666), + )); + assert_eq!(0, localcast_reservoir_len(reservoir)); + assert_eq!(0, localcast_reservoir_view_len(reservoir, 0)); + + localcast_reservoir_destroy(reservoir); + } + #[test] fn c_abi_rejects_nulls_and_unknown_sample_kinds() { - let sample = LocalcastSampleHandle { - sensor_id_hash: 1, - timestamp_ns: 2, - arrival_ns: 3, - sequence: 4, - payload_handle: 5, - }; + let sample = handle(1, 2, 3, 4, 5); let mut out = sample; assert!(!localcast_reservoir_push(std::ptr::null_mut(), 0, sample)); @@ -848,27 +867,9 @@ mod tests { #[test] 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, - timestamp_ns: 1_000_000_000, - arrival_ns: 1_000_000_001, - sequence: 1, - payload_handle: 100, - }; - let audio = LocalcastSampleHandle { - sensor_id_hash: 20, - timestamp_ns: 7_000_000_001, - arrival_ns: 7_000_000_010, - sequence: 2, - payload_handle: 200, - }; - let phase = LocalcastSampleHandle { - sensor_id_hash: 30, - timestamp_ns: 7_000_000_010, - arrival_ns: 7_000_000_020, - sequence: 3, - payload_handle: 300, - }; + let camera = handle(10, 1_000_000_000, 1_000_000_001, 1, 100); + let audio = handle(20, 7_000_000_001, 7_000_000_010, 2, 200); + let phase = handle(30, 7_000_000_010, 7_000_000_020, 3, 300); assert!(localcast_runtime_push_camera_frame(runtime, camera)); assert!(localcast_runtime_push_audio_block(runtime, audio)); @@ -888,13 +889,7 @@ mod tests { #[test] fn runtime_spine_rejects_nulls() { - let sample = LocalcastSampleHandle { - sensor_id_hash: 1, - timestamp_ns: 2, - arrival_ns: 3, - sequence: 4, - payload_handle: 5, - }; + let sample = handle(1, 2, 3, 4, 5); let mut status = LocalcastRuntimeStatus::default(); assert!(!localcast_runtime_push_camera_frame( @@ -906,4 +901,21 @@ mod tests { assert!(!localcast_runtime_status(runtime, std::ptr::null_mut())); localcast_runtime_destroy(runtime); } + + #[test] + fn runtime_spine_rejects_diagnostic_samples() { + let runtime = localcast_runtime_create(DEFAULT_RESERVOIR_NS); + + assert!(!localcast_runtime_push_camera_frame( + runtime, + diagnostic_handle(1, 2, 3, 4, 5), + )); + + let mut status = LocalcastRuntimeStatus::default(); + assert!(localcast_runtime_status(runtime, &mut status)); + assert_eq!(0, status.total_sample_count); + assert_eq!(0, status.camera_frame_count); + + localcast_runtime_destroy(runtime); + } } diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 51b2e83..4a22e82 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -57,3 +57,4 @@ {"ts": "2026-05-19T08:01:04+00:00", "type": "implementation", "status": "ok", "note": "Python visual producer quarantined by name: scripts/live_sensor_fusion.py is now scripts/diagnostic_live_sensor_fusion.py, tests/docs import the diagnostic path, and future native/Aquarium work should delete or split its pure pieces rather than extend it."} {"ts": "2026-05-19T08:03:24+00:00", "type": "implementation", "status": "ok", "note": "Diagnostic Spout launcher renamed: scripts/stream_spout.py is now scripts/diagnostic_stream_spout.py, keeping the OpenGL bridge visibly outside the production path while Aquarium Spout publication remains the target."} {"ts": "2026-05-19T08:07:19+00:00", "type": "implementation", "status": "ok", "note": "Native reservoir ABI now exposes indexed reads over the total rolling buffer and typed views via localcast_reservoir_sample_at and localcast_reservoir_view_sample_at, allowing Aquarium/Faust consumers to walk the live window without owning private histories."} +{"ts": "2026-05-19T09:11:35+01:00", "type": "implementation", "status": "ok", "note": "Native reservoir provenance guard added: LocalcastSampleHandle now carries flags/reserved fields, diagnostic samples are rejected by localcast_reservoir_push and LocalcastRuntime producer calls, and tests prove fallback/diagnostic handles cannot enter the live rolling buffer."} diff --git a/tests/test_perfect_machine_contract.py b/tests/test_perfect_machine_contract.py index 40acf8c..da9189c 100644 --- a/tests/test_perfect_machine_contract.py +++ b/tests/test_perfect_machine_contract.py @@ -37,6 +37,8 @@ class PerfectMachineContractTests(unittest.TestCase): self.assertIn("typedef struct LocalcastReservoir LocalcastReservoir;", header) self.assertIn("typedef struct LocalcastSampleHandle", header) self.assertIn("uint64_t payload_handle;", header) + self.assertIn("uint32_t flags;", header) + self.assertIn("LOCALCAST_SAMPLE_FLAG_DIAGNOSTIC", header) self.assertIn("LocalcastReservoir *localcast_reservoir_create", header) self.assertIn("void localcast_reservoir_destroy", header) self.assertIn("bool localcast_reservoir_push", header)