# Native Runtime

This directory is for the hot path.

## Crates

- `reservoir`: the first native five-second spatiotemporal reservoir core. It
  owns one shared-edge rolling buffer with typed sample views.
  Fensalir/Faust integration should build on this invariant instead of copying
  the deadline bridge cache.
  It exports `rlib`, `cdylib`, and `staticlib` artifacts plus the C header at
  `reservoir/include/localcast_reservoir.h`.

## Reservoir ABI

The reservoir ABI is intentionally small:

- `LocalcastReservoir` is opaque.
- `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.
- 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.
- The reservoir can create/destroy, push, set/query edge, query window start,
  count the whole rolling buffer, count a typed view, read samples by total
  buffer index or typed-view index, and fetch the latest sample for a sensor
  hash inside a typed view.

## Runtime ABI

`LocalcastRuntime` is the live spine for Fensalir/Faust integration:

- it owns one native reservoir;
- it exposes typed producer functions for camera frames, camera features, scene
  rays, surface claims, material claims, audio blocks, phase claims, event
  claims, and render packets;
- it exposes `LocalcastRuntimeStatus` so Fensalir/Faust can inspect the shared
  edge, window start, total sample count, and typed-view counts without polling JSON or
  MessagePack files;
- it exposes total and typed-view sample reads so Fensalir/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.

`LocalcastAudioBlockDescriptor` is the first typed payload descriptor:

- it describes the caller-owned audio block handle, frame count, channel count,
  sample rate, sample format, start sample, and channel-layout hash;
- `localcast_producer_push_audio_block` only accepts `AudioBlock` producers and
  stores the descriptor pointer as the sample payload handle;
- the reservoir still does not copy or own audio memory.

`LocalcastRenderPacketDescriptor` is the visual equivalent:

- it describes the caller-owned point buffer handle, point count/stride, target
  dimensions, source-time span, presentation time, audio-alignment time, and an
  optional metadata handle;
- `localcast_producer_push_render_packet` only accepts `RenderPacket`
  producers and stores the descriptor pointer as the sample payload handle;
- Fensalir owns decoding and GPU upload. The reservoir only indexes when this
  render packet exists in the shared rolling window.

`LocalcastRenderPoint` is the fixed point-buffer element shape for the initial
native/Fensalir render path. It carries a stable-key hash, source timestamp,
position, radius, color/alpha, and confidence. Richer material/brush payloads
can get their own descriptors later; this point shape exists to kill the old
JSON/CultCache render-frame dependency first.

Payload handles are owned by the caller. Fensalir 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
retention authority, not the renderer or DSP engine in a tiny hat.