diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md index fd01029..868b2f5 100644 --- a/docs/implementation-plan.md +++ b/docs/implementation-plan.md @@ -27,6 +27,8 @@ shape removes independent per-kind storage from the live foundation. The ABI now exposes total rolling-buffer length and typed-view length. - `localcast_hash_source_id` owns stable FNV-1a source hashing for native producers; empty/null source ids produce zero and are rejected. + - `localcast_producer_create_for_source` is the preferred producer constructor + for adapters because it keeps source-id hashing inside the native ABI. - `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. diff --git a/native/README.md b/native/README.md index df6fc11..ae4a122 100644 --- a/native/README.md +++ b/native/README.md @@ -22,6 +22,9 @@ The reservoir ABI is intentionally small: - `localcast_hash_source_id` is the stable FNV-1a source-id hash used before creating producers. Empty or null source ids hash to zero and are rejected by producer creation. +- `localcast_producer_create_for_source` is the preferred producer constructor + for adapters that have source-id bytes; it hashes through the same native + authority before creating the producer. - `LocalcastSampleHandle` is sample metadata plus a `payload_handle` and provenance flags. Live samples must have `flags == 0`; diagnostic or unknown flagged samples are rejected by the live reservoir. diff --git a/native/reservoir/include/localcast_reservoir.h b/native/reservoir/include/localcast_reservoir.h index 5d81ad1..e1f5122 100644 --- a/native/reservoir/include/localcast_reservoir.h +++ b/native/reservoir/include/localcast_reservoir.h @@ -174,6 +174,12 @@ LocalcastProducer *localcast_producer_create( uint64_t sensor_id_hash, uint64_t initial_sequence ); +LocalcastProducer *localcast_producer_create_for_source( + uint32_t sample_kind, + const uint8_t *source_id_bytes, + size_t source_id_byte_len, + uint64_t initial_sequence +); void localcast_producer_destroy(LocalcastProducer *producer); uint64_t localcast_producer_next_sequence(const LocalcastProducer *producer); diff --git a/native/reservoir/src/lib.rs b/native/reservoir/src/lib.rs index 9804ad4..afd5cdb 100644 --- a/native/reservoir/src/lib.rs +++ b/native/reservoir/src/lib.rs @@ -750,6 +750,17 @@ pub extern "C" fn localcast_producer_create( ))) } +#[unsafe(no_mangle)] +pub extern "C" fn localcast_producer_create_for_source( + sample_kind: u32, + source_id_bytes: *const u8, + source_id_byte_len: usize, + initial_sequence: u64, +) -> *mut LocalcastProducer { + let hash = localcast_hash_source_id(source_id_bytes, source_id_byte_len); + localcast_producer_create(sample_kind, hash, initial_sequence) +} + #[unsafe(no_mangle)] pub extern "C" fn localcast_producer_destroy(ptr: *mut LocalcastProducer) { if ptr.is_null() { @@ -1378,6 +1389,8 @@ mod tests { 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!(localcast_producer_create_for_source(0, std::ptr::null(), 4, 0).is_null()); + assert!(localcast_producer_create_for_source(0, b"".as_ptr(), 0, 0).is_null()); assert_eq!(0, localcast_producer_next_sequence(std::ptr::null())); let producer = localcast_producer_create(0, 1, 0); @@ -1405,6 +1418,34 @@ mod tests { localcast_runtime_destroy(runtime); } + #[test] + fn producer_can_be_created_from_source_id_bytes() { + let source_id = b"kiyo-primary"; + let producer = localcast_producer_create_for_source( + SampleKind::CameraFrame.id(), + source_id.as_ptr(), + source_id.len(), + 5, + ); + let runtime = localcast_runtime_create(DEFAULT_RESERVOIR_NS); + let mut sample = handle(0, 0, 0, 0, 0); + + assert!(!producer.is_null()); + assert!(localcast_producer_push( + producer, + runtime, + 1_000, + 1_010, + 90, + &mut sample, + )); + assert_eq!(hash_source_id(source_id), sample.sensor_id_hash); + assert_eq!(5, sample.sequence); + + localcast_producer_destroy(producer); + localcast_runtime_destroy(runtime); + } + #[test] fn audio_block_descriptor_is_typed_payload_boundary_not_reservoir_storage() { let runtime = localcast_runtime_create(DEFAULT_RESERVOIR_NS); diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index 1337c4c..9f7f51a 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -35,6 +35,8 @@ Get-Content .\state\evidence.jsonl -Tail 8 capture workers. - `localcast_hash_source_id` owns stable FNV-1a source-id hashing for native producer creation. +- `localcast_producer_create_for_source` is the preferred producer constructor + for adapters with source-id bytes. - `LocalcastAudioBlockDescriptor` is the first typed audio payload descriptor: caller-owned float32 interleaved audio blocks cross the ABI by descriptor pointer, while the reservoir still owns only timing/retention metadata. diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 5daff97..506c1ae 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -87,3 +87,4 @@ {"ts": "2026-05-19T11:30:58+00:00", "type": "implementation", "status": "ok", "note": "Native reservoir ABI now owns source-id hashing through localcast_hash_source_id, a stable FNV-1a hash for producer source identity; null/empty sources hash to zero and producer creation still rejects zero."} {"ts": "2026-05-19T11:34:44+00:00", "type": "implementation", "status": "ok", "note": "Aquarium-Engine commit 924aa2f exposes LocalCastNativeSourceId.HashUtf8 as a safe wrapper over native localcast_hash_source_id, avoiding managed reimplementation of source identity hashing."} {"ts": "2026-05-19T11:38:44+00:00", "type": "implementation", "status": "ok", "note": "Aquarium-Engine commit c06d4cb makes LocalCastNativeVisualFrameSource use the descriptor plus native point-buffer decoder by default, while retaining injected decoder seams for tests and richer future payloads."} +{"ts": "2026-05-19T11:40:31+00:00", "type": "implementation", "status": "ok", "note": "Native reservoir ABI now includes localcast_producer_create_for_source, the preferred producer constructor for adapters with source-id bytes because it hashes through native localcast_hash_source_id before creation."} diff --git a/state/map.yaml b/state/map.yaml index 227b7c5..9b56efb 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -58,6 +58,8 @@ accepted_design: before hardware adapters append live sample handles. - `localcast_hash_source_id` owns stable native source-id hashing so capture workers do not each invent incompatible sensor hashes. + - `localcast_producer_create_for_source` keeps the preferred adapter path from + bypassing native source-id hashing. - `LocalcastAudioBlockDescriptor` is the first typed payload descriptor for caller-owned float32 interleaved audio blocks; the reservoir stores only the descriptor pointer as a payload handle and does not own DSP memory.