The lib-owned checkpoint persistence contract.

A checkpoint store persists exactly one value per pipeline identity: the processed gtid_set STRING. file/pos are never persisted — they are diagnostic only and are derived on read (Capstan.Position.from_persisted/1 restores them as nil). Because the callback surface only ever sees the persisted string, an implementation cannot accidentally persist file/pos; there is exactly one durable value and no two-representation divergence to occur on.

The checkpoint is a processed watermark (ADR-0003): it records every committed GTID the pipeline has processed, delivered or filtered — see Capstan.Sink.

Behaviour

An implementation persists and reads back the gtid_set string for one pipeline:

• read/1 — {:ok, gtid_set | nil} (nil = never written) or a value-free {:error, term()}.

• write/2 — durably store the gtid_set string (idempotent: writing the same value twice is indistinguishable from writing it once) or {:error, term()}.

Capstan.CheckpointStore.InMemory is a process-lifetime reference implementation for tests and ephemeral pipelines — it is NOT durable across a restart.

Position boundary

read_position/2 and write_position/3 bridge Capstan.Position and the persisted string through Capstan.Position.to_persisted/1 and from_persisted/1. They are the one place the persist boundary is applied, so a caller advancing the checkpoint never hand-rolls it and can never leak file/pos.

Retry budget

default_max_retries/0, retry_decision/2, and permanent_reason?/1 mirror replicant/lib/replicant/checkpoint_store.ex so a store fault is retried a bounded number of times and then halts fail-closed, with the same counter semantics the connect-read and mid-stream write sites share (they cannot drift). A permanent reason halts immediately without spending the budget.