Create producers from source ids

This commit is contained in:
Meta Vens 2026-05-19 12:40:39 +01:00
commit cd9b3fd059
7 changed files with 57 additions and 0 deletions

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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