Source reading map
Read the contracts before the implementation. The links below point to the current main snapshot
recorded in the site baseline.
| Order | Start with | Then inspect | Why |
|---|---|---|---|
| 1. Overall entry | README.md, settings.gradle.kts | overall architecture, terminology, commit protocol | Establish layers, terms, and the single logical commit point |
| 2. L0 API and coordinates | StreamStorage.java | AppendEntry.java, AppendResult.java, ReadRequest.java, ReadTarget | See the protocol-neutral values and target union |
| 3. Append and recovery | DefaultStreamStorage.java | AppendCoordinator.java, AppendSessionManager.java, recovery package | Follow session fencing, provider WAL, head CAS, and uncertain outcomes |
| 4. Oxia metadata | OxiaMetadataStore.java | OxiaKeyspace.java, StreamHeadRecord.java, codecs/stores for generation/task/checkpoint/root | Understand conditional records, scans, watches, and hydration |
| 5. Read and generation | ReadResolver.java | GenerationReadResolver.java, ReadTargetDispatcher.java, Future 4 | Verify view, coverage, pin, fallback, and repair rules |
| 6. Object Store | nereus-object-store | ObjectStore.java, object format and guarded upload code | Follow immutable identity, HEAD, checksum, and delete capability |
| 7. BookKeeper | nereus-bookkeeper | BookKeeperPrimaryWalRuntime.java, BookKeeperAppendRecoveryCoordinator.java, BK contract | Review ledger identity, taint, reservation, retention, and recovery |
| 8. Pulsar | nereus-managed-ledger | nereus-pulsar-adapter, Phase 2, Phase 3 | Map Position/MessageId and cursor state without exposing physical IDs |
| 9. Native Kafka | nereus-kafka-adapter | phase 9 contract, ranged API, fork integration, binding/checkpoint, transactions/retention | Keep KRaft, producer, transaction, HW/LSO, and internal-topic authority in Kafka |
Review order
For a change that touches several layers, inspect in this order: public value/contract, metadata authority, provider identity and response-loss behavior, adapter projection, then runtime lifecycle and tests. If a lower layer starts importing an upper protocol type, stop and revisit the boundary.