aarondb/durable_log

durable_log — independent deterministic durable-log reference

This pure local reference is deliberately separate from fact storage. It models the port contract used by later durable adapters: ordered offsets, retained tails, verified snapshots, idempotent append, and an atomic projection-checkpoint boundary. It is not a filesystem implementation.

Types

CheckpointFault

pub type CheckpointFault {
  NoFault
  FailBeforeCommit
}

Constructors

```
NoFault
```
```
FailBeforeCommit
```

DurableLog

pub type DurableLog {
  DurableLog(
    source: String,
    next_offset: Int,
    entries: List(Entry),
    snapshots: List(Snapshot),
    checkpoints: List(ProjectionCheckpoint),
  )
}

Constructors

DurableLog(
  source: String,
  next_offset: Int,
  entries: List(Entry),
  snapshots: List(Snapshot),
  checkpoints: List(ProjectionCheckpoint),
)

DurableLogError

pub type DurableLogError {
  CursorExpired(requested: Int, earliest_available: Int)
  CorruptEntry(offset: Int)
  SnapshotUnavailable(offset: Int)
  CheckpointFaultInjected
}

Constructors

CursorExpired(requested: Int, earliest_available: Int)

```
CorruptEntry(offset: Int)
```
```
SnapshotUnavailable(offset: Int)
```
```
CheckpointFaultInjected
```

Entry

pub type Entry {
  Entry(
    offset: Int,
    payload: String,
    idempotency_key: String,
    checksum: String,
  )
}

Constructors

Entry(
  offset: Int,
  payload: String,
  idempotency_key: String,
  checksum: String,
)

Offset

pub type Offset =
  Int

ProjectionCheckpoint

pub type ProjectionCheckpoint {
  ProjectionCheckpoint(projection: String, offset: Int)
}

Constructors

ProjectionCheckpoint(projection: String, offset: Int)

Snapshot

pub type Snapshot {
  Snapshot(offset: Int, state: String, checksum: String)
}

Constructors

Snapshot(offset: Int, state: String, checksum: String)

SourceId

pub type SourceId =
  String

Values

append

pub fn append(
  log: DurableLog,
  payload: String,
  idempotency_key: String,
) -> #(DurableLog, Entry)

Append is idempotent for a source-local key. Retrying returns its first entry.

checkpoint

pub fn checkpoint(
  log: DurableLog,
  projection: String,
) -> option.Option(ProjectionCheckpoint)

commit_checkpoint

pub fn commit_checkpoint(
  log: DurableLog,
  checkpoint: ProjectionCheckpoint,
  fault: CheckpointFault,
) -> Result(DurableLog, DurableLogError)

This boundary represents one storage transaction: projection state is owned by the adapter, and its successful application advances this checkpoint together.

corrupt_entry

pub fn corrupt_entry(log: DurableLog, offset: Int) -> DurableLog

Test-only fault-model hook: a decoder must fail rather than skip altered bytes.

new

pub fn new(source: String) -> DurableLog

retain_after

pub fn retain_after(
  log: DurableLog,
  offset: Int,
) -> Result(DurableLog, DurableLogError)

Drop entries through an offset only when a verified recovery snapshot covers it.

scan_after

pub fn scan_after(
  log: DurableLog,
  cursor: Int,
) -> Result(List(Entry), DurableLogError)

Read the retained tail strictly after cursor after validating every entry.

snapshot

pub fn snapshot(
  log: DurableLog,
  offset: Int,
  state: String,
) -> Result(DurableLog, DurableLogError)

Persist a verified snapshot at an already committed position.

snapshot_then_tail

pub fn snapshot_then_tail(
  log: DurableLog,
  through: Int,
) -> Result(#(Snapshot, List(Entry)), DurableLogError)

Bootstrap state from the latest verified snapshot at or before through, then tail it.