# Capstan v0.1.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)

## Modules

- 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.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.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.

