# `Capstan.Position`
[🔗](https://github.com/baselabs/capstan/blob/v1.3.1/lib/capstan/position.ex#L1)

A replication position: the processed GTID set plus diagnostic binlog coordinates.

`gtid_set` is AUTHORITATIVE and the ONLY persisted field (ADR-0001). `file`
and `pos` are DIAGNOSTIC ONLY — **never an ordering key**. A scalar ordinal built
from `file`/`pos` moves backward after failover or `RESET BINARY LOGS AND GTIDS`
while the GTID set moves forward, so no `ordinal` field is exported.

`to_persisted/1` and `from_persisted/1` round-trip only `gtid_set`: persisting a
`Position` and restoring it always yields `file: nil, pos: nil`, even when the
original carried diagnostic coordinates. There is exactly one durable value.

# `t`

```elixir
@type t() :: %Capstan.Position{
  file: String.t() | nil,
  gtid_set: String.t(),
  pos: non_neg_integer() | nil
}
```

# `from_persisted`

```elixir
@spec from_persisted(String.t()) :: t()
```

Builds a `Position` from a persisted `gtid_set` string.

`file` and `pos` are always `nil` — they are diagnostic-only and never survive
persistence.

# `to_persisted`

```elixir
@spec to_persisted(t()) :: String.t()
```

Returns the persisted representation of `position` — the `gtid_set` string alone.

`file`/`pos` are diagnostic and are never persisted.

---

*Consult [api-reference.md](api-reference.md) for complete listing*