datum-core 0.9.0

# `datum-core/src/` — crate source map

Navigation map for the `datum-core` crate (published as `datum-core`, imported as `use datum::…`).
**Read [`../../CLAUDE.md`](../../CLAUDE.md) first** — it owns the build/test/lint/bench commands, the
architecture overview, and the Akka-mirroring + performance conventions. This file is only a map; it
does not duplicate that content. Planning and the benchmark record live in
[`../../roadmap/`](../../roadmap/README.md).

`lib.rs` is the crate root: `#![forbid(unsafe_code)]`, edition 2024. It declares the modules, flatly
re-exports the public surface, and defines `prelude`. **Do not put logic here** — it is wiring only.

## Directory modules (each has its own `AGENTS.md`)

| Module | What it is | Guide |
| --- | --- | --- |
| `stream/` | The primary public surface: linear `Source`/`Flow`/`Sink` DSL, `RunnableGraph`, and the `Runtime`/`Materializer` (same type), plus the fused pull-based executor, restart/retry/rate/timer stages. | [`stream/AGENTS.md`](stream/AGENTS.md) |
| `graph/` | Akka-style GraphDSL: typed `Inlet`/`Outlet`, `Shape`s, junctions, `GraphStage`/`GraphStageLogic`, the builder, and the three-tier fused executor (typed-linear / queued-erased / erased oracle, `ExecutorMode::Auto`). | [`graph/AGENTS.md`](graph/AGENTS.md) |
| `actor/` | Ractor interop. `actor.rs` is the module root (submodules in `actor/`): `ActorFlow::ask`, `ReplyPort`, `StreamRefs`, and the remote StreamRef protobuf protocol. Spin-then-park; per-message Ractor box. | [`actor/AGENTS.md`](actor/AGENTS.md) |
| `io/` | Streaming I/O: delimiter/JSON `Framing`, sync + Tokio file sources/sinks, TCP, `Compression`, and `StreamConverters` bridging to `std::io::Read`/`Write`. | [`io/AGENTS.md`](io/AGENTS.md) |
| `dynamic/` | Dynamic controls: `KillSwitches` and the `MergeHub`/`BroadcastHub`/`PartitionHub` attachment points (batched per-lane wakeup). | [`dynamic/AGENTS.md`](dynamic/AGENTS.md) |

> The network carriers (TLS/UDP/QUIC + remote StreamRefs transport) live in the sibling crate
> `crates/datum-net/`, not here.

## Single-file modules

| File | One-liner |
| --- | --- |
| `queue.rs` | External-boundary queues: `Source::queue_bounded` (lock-free `ArrayQueue`, no overflow strategy), `Source::queue` (`OverflowStrategy`, `maxConcurrentOffers = 1`), and `Sink::queue` (blocking `pull`). |
| `context.rs` | `SourceWithContext` / `FlowWithContext` — thin `(value, context)` wrappers exposing only one-to-one operators so context can't be detached. |
| `testkit.rs` | `TestSource` / `TestSink` probes (always-on, no feature gate). Pull-based: terminal signals surface only after a `request`. |
| `attributes.rs` | Private `mod`, re-exported as `Attribute`/`Attributes` — Akka-style metadata (`Name`/`InputBuffer`/`Dispatcher`) attached to stages/blueprints and surfaced to `setup` closures. |

## Other

- `bin/` — one `*_compare.rs` release runner per benchmark area (source-flow, materialization,
  graph, actor-ask, dynamic-streams, streaming-io, substreams, queues), used by the
  `benches/*_compare/run.sh` Datum-vs-Akka comparison harnesses.
- Tests are inline `#[cfg(test)]` modules per file; doc-page code lives in
  `crates/datum-core/tests/docs/` (anchored snippets referenced by `docs/`).