End-to-end cheatsheet
Use the relevant authority and identity checks at every arrow. A provider response or workflow state does not replace the conditional metadata boundary.
Append
protocol validation and encoding
-> profile/capability admission
-> per-stream lane
-> append session/authority
-> primary WAL durable
-> provider metadata
-> physical protection
-> immutable commit intent
-> stream head CAS
-> profile completion boundary
-> stable AppendResult
The head CAS is the logical commit point. Unknown completion reuses the original attempt; it is not a new producer dedup key.
Read
protocol coordinate
-> projection/binding
-> consistent stream snapshot
-> trim/end checks
-> requested read view
-> generation/index resolution
-> generation-0 repair if needed
-> reader pin/slot
-> exact target revalidation
-> physical reader
-> boundary/limit handling
-> protocol response
Fallback is same-view only. Trim, EOF, candidate failure, and checksum quarantine remain distinct outcomes.
Materialization
registration discovery
-> authoritative re-read
-> planner freezes source/policy
-> task claim and heartbeat
-> source protection
-> exact source read
-> bounded staging/spill
-> guarded Object PUT
-> full verification
-> PREPARED index
-> final revalidation
-> COMMITTED CAS
-> protection transfer
-> checkpoint and task cleanup
Only the generation-index CAS changes read selection.
Retention and GC
cursor ack or Kafka retention policy
-> logical-trim permit
-> trimOffset advance
-> higher replacement/checkpoint proof
-> source retirement
-> root MARKED
-> all-domain reference revalidation and reader drain
-> DELETING journal
-> physical DELETE
-> response-loss recovery
-> DELETED and delayed audit retirement
Object LIST is discovery only, and BookKeeper retention deletes whole sealed ledgers rather than individual entries.
Protocol projections
| Protocol | Adapter-owned coordinate | Nereus-owned coordinate |
|---|---|---|
| Pulsar | Position/MessageId, subscription, batch index | Stream offset, head, ReadTarget, cursor root |
| Native Kafka | RecordBatch, leader epoch, HW/LSO, transaction visibility | Ranged entry, stable head, generation, checkpoint |