@spec cache_routing_entry(
  ref(),
  {Bedrock.key(), Bedrock.key(), {String.t(), String.t()}}
) :: :ok

Caches one covering entry fetched from a commit proxy.

@spec fetch_coordinator(ref(), opts :: [{:timeout_in_ms, Bedrock.timeout_in_ms()}]) ::
  {:ok, Bedrock.ControlPlane.Coordinator.ref()}
  | {:error, :unavailable | :timeout | :unknown}

Fetch the current known coordinator reference. Returns the coordinator if available, or error if coordinator discovery is pending.

@spec fetch_coordinator!(ref(), opts :: [{:timeout_in_ms, Bedrock.timeout_in_ms()}]) ::
  Bedrock.ControlPlane.Coordinator.ref()

Get the current known coordinator reference. Raises if unavailable.

@spec fetch_covering_entry(module(), Bedrock.key()) ::
  {:ok, {Bedrock.key_range(), {String.t(), String.t()}}} | {:error, :not_cached}

The cached covering entry for one key: the shard range and its raw {worker_id, node} materializer ref.

Read DIRECTLY from the node's routing cache — no message to the Link. Every transaction on the node looks up every key, so routing a key must not require the Link to be scheduled.

The Link still owns that cache (FDB's DatabaseContext locationCache), a partial coalescing index that only stores. On a miss the caller fetches the single covering entry from a commit proxy and caches it back with cache_routing_entry/2.

@spec fetch_descriptor(ref(), opts :: [{:timeout_in_ms, Bedrock.timeout_in_ms()}]) ::
  {:ok, Bedrock.Cluster.Descriptor.t()}
  | {:error, :unavailable | :timeout | :unknown}

Fetch the cluster descriptor. This includes the coordinator nodes and other cluster configuration.

@spec fetch_descriptor!(ref(), opts :: [{:timeout_in_ms, Bedrock.timeout_in_ms()}]) ::
  Bedrock.Cluster.Descriptor.t()

Get the cluster descriptor. Raises if unavailable.

@spec fetch_transaction_system_layout(
  ref(),
  opts :: [{:timeout_in_ms, Bedrock.timeout_in_ms()}]
) ::
  {:ok, Bedrock.ControlPlane.Config.TransactionSystemLayout.t()}
  | {:error, :unavailable | :timeout | :unknown}

Fetch the cached Transaction System Layout. Returns the TSL if coordinator is connected and TSL has been received.

@spec fetch_transaction_system_layout!(
  ref(),
  opts :: [{:timeout_in_ms, Bedrock.timeout_in_ms()}]
) ::
  Bedrock.ControlPlane.Config.TransactionSystemLayout.t()

Get the cached Transaction System Layout. Raises if unavailable.

@spec invalidate_routing(ref(), opts :: [{:timeout_in_ms, Bedrock.timeout_in_ms()}]) ::
  :ok | {:error, :unavailable | :timeout | :unknown}

Drops the cached routing entries — the whole index, never a patch.

Called by the client retry loop when a read fails in a routing-shaped way (unroutable key, dead materializer, unavailable) - a dead pid is exactly what a stale snapshot looks like, so the next transaction refetches. Coarse on purpose (a named divergence from FDB's per-range eviction): failures are rare and simple beats surgical.

Synchronous on purpose: the retry that invalidates must not be able to read the stale entries back on its next fetch. A cast would be ordered only by accident of the intervening wiring call.