> > > SpecAdr011AkashaReaderSideReliability

ADR-011: Akasha Reader-Side Reliability and Raw-Faithful Default

Status

Proposed

Context

ADR-007 established the save-first, interpret-later boundary for asynchronous M2M APIs. Akasha extends that boundary into the ledger layer: the tape records facts, while readers turn the raw tape into operational streams, projections, reports, and interpretations.

Akasha is append-only and may be unreliable at the transport level in remote or relayed deployments. Facts may be duplicated, delayed, reordered, or missing. The design must decide where reliability lives and what a reader does by default.

The governing epistemic rule is that read-time cleanup is itself an interpretation. A reader that silently deduplicates, hides gaps, or reorders events performs post-hoc manipulation at read time.

Decision

Akasha is the raw, best-effort substrate. It records what reaches the tape and does not provide delivery guarantees, deduplication, completeness, ordering by source, or interpretation.

LedgerReader reliability features are optional reader-side lenses. They may track sequence numbers, expose transport gaps, deduplicate by stable IDs, or assemble a source-ordered stream. These lenses are explicit and opt-in.

The default reader mode is raw-faithful:

duplicates are surfaced as duplicates;
gaps are surfaced as gaps;
reordering is surfaced as reordering;
late facts remain visible and may revise downstream projections.

The generic reader owns mechanism, not policy. It may provide primitives for gap detection and deduplication. Native readers or ERP systems own prediction, significance, domain thresholds, and the choice of which lenses to enable.

Rationale

Audit requires fidelity before convenience. A duplicate, gap, or reorder may be the thing an auditor needs to see. Treating cleanup as a default would censor evidence and weaken the ledger's purpose.

The network analogy is useful but limited. Akasha resembles an IP-like substrate. Optional reader lenses resemble TCP-like reassembly. Unlike TCP, Akasha readers cannot request retransmission from the emitter. They can only wait, reconcile, project with a warning, or revise later.

Consequences

Positive

Audit readers can inspect source-system failure modes directly.
Multiple readers can construct different interpretations over the same tape.
Reliability logic is reusable without becoming mandatory.

Negative

Consumers must explicitly choose their lens behavior.
Downstream projections must tolerate late revision.

Neutral or Operational

LedgerReader should be available as a library/SDK, not only as a service.
Prediction state belongs in native readers or emitters, not in Akasha.

Alternatives Considered

Smart Akasha Sink

Rejected. Deduplication and gap hiding in the write path would make Akasha an interpreter rather than a raw ledger.

Always-On Reliable Reader

Rejected. A mandatory reliable stream would be convenient for application code but inappropriate for audit use, where duplicates and gaps are evidence.

Migration or Adoption

Reader APIs should expose raw reading first and lenses as named options. Any existing reader that silently cleans the stream should be treated as a projection or application-specific reader, not as the default ledger reader.

SOTER