BookKeeper WAL
Why it is a Nereus provider
The BookKeeper WAL uses the public BookKeeper client API but keeps Nereus stream head, ReadTarget, generation, and retention semantics in Nereus metadata. It does not make a stock ManagedLedger ledger the core logical truth.
Nereus maintains ledger allocation intent, root lifecycle, stream writer state, append reservations, exact entry ranges, range protection, reader slots, and retention state.
Ledger ownership
An active writable ledger belongs to one stream/session epoch and is not shared across Nereus streams. This lets whole-ledger retention reason about one stream's history instead of copying unrelated slices out of a shared ledger.
Ranged entries
BookKeeperEntryRangeReadTarget records a cluster alias, ledger ID, first entry ID, entry count, mapping, and range checksum. One Nereus append batch uses a contiguous range and does not cross a ledger boundary:
- Pulsar complete Entry → one BK entry and
recordCount = 1; - Kafka complete RecordBatch → one BK entry and
recordCountmay cover several logical offsets.
Therefore “one Nereus offset equals one BK entry” is only true for the single-record mapping. The stable statement is: one append entry maps to one complete BookKeeper entry, and that entry may cover one or more logical offsets.
Rollover and taint
If the current ledger cannot contain the next append, Nereus seals it and creates a new one. An append is never split across two ledgers. Uncertain create results, partial writes, ownership changes, or stale completions taint a ledger and prevent unsafe tail reuse.
Normal reads use non-recovery open. Recovery-open is restricted to owner recovery and fencing because it may close the ledger and change physical facts such as LAC.
Reserved ledger ID namespace
BookKeeper delete is not a versioned conditional operation. If another system can later create the same ledger ID, a stale delete can remove a different physical ledger (an ABA hazard). Nereus requires a precise, verifiable reserved positive 63-bit namespace and persists its reservation/capability proof. Without proof, first-create and physical delete are rejected.