# Capstan v0.2.0 - Table of Contents

> Framework-agnostic Elixir CDC consumer for MySQL binary-log replication (row-based binlog) — streams committed transactions to a pluggable sink, fail-closed, at-least-once (sink-owned effect-once mode planned).

## Pages

- [capstan](readme.md)
- [capstan usage rules](usage-rules.md)
- [Changelog](changelog.md)
- [ADR-0001 — Position and dedup model](0001-position-and-dedup-model.md)
- [ADR-0002 — Fail-closed server preconditions](0002-fail-closed-server-preconditions.md)
- [ADR-0003 — Transaction shape and checkpoint semantics](0003-transaction-shape-and-checkpoint-semantics.md)
- [ADR-0004 — C1 scope: lib-owned checkpoint mode only](0004-c1-scope-lib-owned-checkpoint-only.md)
- [ADR-0005 — Initial snapshot: cursor-gated suppression + brief per-chunk lock](0005-initial-snapshot-cursor-gate-brief-lock.md)

## Modules

- [Capstan.Query](Capstan.Query.md): A `COM_QUERY`-only connection for the initial-snapshot path (C2 Task 4).

- Consumer API
  - [Capstan](Capstan.md): Framework-agnostic Elixir CDC consumer for MySQL row-based binary-log replication,
delivering committed transactions to a pluggable **sink** with fail-closed,
transaction-granularity delivery: the checkpoint advances only after the sink has
durably applied a transaction (ADR-0003). In C1's lib-owned checkpoint mode this
is **at-least-once** — a crash between the sink write and the checkpoint re-delivers the
transaction on restart (a bounded duplicate window). Effect-once delivery is the
sink-owned atomic path (the sink persisting its write and the position together), which
C1 validates but does not yet run — see `Capstan.Sink` and ADR-0004.
  - [Capstan.Change](Capstan.Change.md): A single row change within a `Capstan.Transaction`.
  - [Capstan.CheckpointStore](Capstan.CheckpointStore.md): The lib-owned checkpoint persistence contract.
  - [Capstan.CheckpointStore.InMemory](Capstan.CheckpointStore.InMemory.md): A process-lifetime `Capstan.CheckpointStore` reference implementation.
  - [Capstan.Error](Capstan.Error.md): A typed, **value-free** error — the boundary normaliser that scrubs a raw driver /
socket error, exception, or reason tuple to a stable atom `reason` (Rule 1, design
§ Rule 1 / F11).
  - [Capstan.Gtid](Capstan.Gtid.md): MySQL GTID-set algebra — the dedup correctness core.
  - [Capstan.Position](Capstan.Position.md): A replication position: the processed GTID set plus diagnostic binlog coordinates.
  - [Capstan.SchemaChange](Capstan.SchemaChange.md): A DDL change: the self-committing DDL transaction's structured effect (ADR-0003).
  - [Capstan.Sink](Capstan.Sink.md): The consumer behaviour: a capstan pipeline delivers committed transactions and
DDL schema changes to a sink and, in sink-owned checkpoint mode, reads the durable
processed position back through `c:checkpoint/0`.
  - [Capstan.Snapshot.Meta](Capstan.Snapshot.Meta.md): The value-free metadata delivered alongside a snapshot chunk to
`c:Capstan.Sink.handle_snapshot/2`.
  - [Capstan.Snapshot.State](Capstan.Snapshot.State.md): The durable snapshot-progress state — one value per pipeline identity, persisted through
a `Capstan.SnapshotStore` (mirrors `Capstan.CheckpointStore`'s one-durable-value model).
  - [Capstan.SnapshotStore](Capstan.SnapshotStore.md): The durable snapshot-progress persistence contract (C2), the sibling of
`Capstan.CheckpointStore`.
  - [Capstan.SnapshotStore.InMemory](Capstan.SnapshotStore.InMemory.md): A process-lifetime `Capstan.SnapshotStore` reference implementation.
  - [Capstan.Transaction](Capstan.Transaction.md): A decoded, committed transaction delivered to a `Sink`.

- Internals
  - [Capstan.Assembler](Capstan.Assembler.md): The three-terminator fold — a **pure** assembler over a `%Capstan.Binlog.Event{}`
stream (ADR-0003; the owning GenServer is `Capstan.AssemblerServer`).
  - [Capstan.AssemblerServer](Capstan.AssemblerServer.md): The composition point: the GenServer that turns a `Capstan.Connection`'s frame stream
into durable, fail-closed, at-least-once delivery (lib-owned checkpoint mode — the
checkpoint advances only after the sink's `{:ok, _}`, so a crash in between re-delivers;
see `Capstan` and ADR-0004. Effect-once is the deferred sink-owned atomic path).
  - [Capstan.Binlog.Decoder](Capstan.Binlog.Decoder.md): Per-type binlog event body decoder — the second decode layer, over
`Capstan.Binlog.Event`.
  - [Capstan.Binlog.Event](Capstan.Binlog.Event.md): Binlog event header parse + CRC32 integrity check — the first decode layer.
  - [Capstan.Binlog.Rows](Capstan.Binlog.Rows.md): Decodes a full row image from the `Capstan.Binlog.Decoder`'s raw tuple and the
resolved `%Capstan.Binlog.TableMap{}`.
  - [Capstan.Binlog.TableMap](Capstan.Binlog.TableMap.md): A fully-decoded MySQL `TABLE_MAP_EVENT` body.
  - [Capstan.Binlog.TableRegistry](Capstan.Binlog.TableRegistry.md): The `table_id` → `%Capstan.Binlog.TableMap{}` registry — the schema-resolution core
(ADR-0002).
  - [Capstan.Casting.Types](Capstan.Casting.Types.md): Casts one column's raw row-image bytes to an Elixir term, and owns the per-column
metadata-width split of a `TABLE_MAP`'s raw `column_metadata` blob.
  - [Capstan.Config](Capstan.Config.md): Option validation and the fail-closed server-precondition gate.
  - [Capstan.Connection](Capstan.Connection.md): The socket-owning GenServer: handshake, auth, the fail-closed gap gate, the dump,
and frame forwarding.
  - [Capstan.Pipeline](Capstan.Pipeline.md): Pipeline entry — the per-mode `Sink` validation and the child-spec wiring for one
supervised pipeline (a `Capstan.CheckpointStore` process, a `Capstan.AssemblerServer`,
and a `Capstan.Connection`).
  - [Capstan.Protocol.Command](Capstan.Protocol.Command.md): MySQL replication commands and text-resultset decoding.
  - [Capstan.Protocol.Handshake](Capstan.Protocol.Handshake.md): MySQL connection handshake, authentication and TLS upgrade.
  - [Capstan.Protocol.Packet](Capstan.Protocol.Packet.md): MySQL client/server protocol framing.
  - [Capstan.Snapshot](Capstan.Snapshot.md): Initial-snapshot public config validation + the **bootstrap orchestration** (C2 Task 10 —
the `P0` pre-seed that avoids C1b, design Q10 / Ch5).
  - [Capstan.Snapshot.Chunk](Capstan.Snapshot.Chunk.md): A transient, in-memory backfill chunk awaiting the advance gate.
  - [Capstan.Snapshot.ChunkReader](Capstan.Snapshot.ChunkReader.md): The brief-lock exact-`G` capture + PK-range paging + structural fingerprint (C2 Task 5,
design Ch1 — THE linchpin).
  - [Capstan.Snapshot.Coordinator](Capstan.Snapshot.Coordinator.md): The initial-snapshot orchestration core (C2 Task 8): a GenServer that interposes as the
`Capstan.AssemblerServer`'s sink and its `:watermark_observer`, runs the cursor-gate over
the live stream, drives the `Capstan.Snapshot.ChunkReader`, and emits each backfill chunk
through the real sink's `c:Capstan.Sink.handle_snapshot/2` once the stream's processed
watermark covers the chunk's exact GTID position `G`.
  - [Capstan.Snapshot.CursorGate](Capstan.Snapshot.CursorGate.md): The pure strict-once classification core of the initial snapshot (C2, design §Architecture).
  - [Capstan.Snapshot.PrimaryKey](Capstan.Snapshot.PrimaryKey.md): The order-faithful primary-key core of the initial snapshot (C2, design Ch3/Ch4).
  - [Capstan.Supervisor](Capstan.Supervisor.md): The pipeline supervisor: it owns one pipeline's
checkpoint store, `Capstan.AssemblerServer`, and `Capstan.Connection`, wired so the
`Connection`'s `:receiver` is the `AssemblerServer` PID.
  - [Capstan.Telemetry](Capstan.Telemetry.md): Value-free telemetry emission. Provides the metadata **allowlist** for "no row values
and no passwords in telemetry" (Rule 1): `event/3` routes
through `validate!/1`, which **raises** on any key outside the allowlist, so a stray row
value or password cannot ride a payload emitted through this module.

