-spec cancel_reminder(term()) -> ok.

Cancel a pending reminder cluster-wide. Stability: beta.

-spec delete_map(atom()) -> ok.

Stop a map on this node (node-local; not a cluster-wide erase). Stability: beta.

-spec fence(term()) -> {ok, non_neg_integer()} | {error, not_leader}.

This node's fencing token for Name, valid only while it leads. Stability: beta.

-spec is_leader(term()) -> boolean().

Whether this node currently holds leadership for Name. Stability: beta.

-spec is_owner(term()) -> boolean().

Whether this node currently owns Key. Stability: beta.

-spec lead(term()) -> {ok, {leader, non_neg_integer()}} | {ok, follower} | {error, term()}.

Campaign for leadership of the singleton Name. The calling process becomes a candidate and is monitored; if it dies it stops being a candidate. The return value is the caller's initial role: - {ok, {leader, Fence}} if it holds leadership now - {ok, follower} otherwise On every later transition the caller is sent one of: - {barrel_p2p_leader, Name, {elected, Fence}} - {barrel_p2p_leader, Name, revoked}

Fence is a non_neg_integer() fencing token, strictly increasing across leadership terms within a connected partition. Stamp it on writes to a shared resource and have the resource reject any operation whose token is not strictly greater than the highest it has accepted; that is what makes "exactly one" safe when an old leader is paused or partitioned.

Partition caveat: under a network partition each side may elect its own leader, and token monotonicity is only guaranteed within a connected component. Safety then rests on the resource's fence check.

Stability: beta. The message and return shapes may change across a 0.x minor bump.

-spec lead(term(), map()) -> {ok, {leader, non_neg_integer()}} | {ok, follower} | {error, term()}.

As lead/1 with options. #{priority => integer()} (default 0) biases the election: higher priority wins, ties fall back to the lowest node atom. Stability: beta.

-spec leader(term()) -> {ok, node(), pid()} | {error, no_leader}.

The current leader for Name cluster-wide, if any. Stability: beta.

-spec members() -> [node()].

The current live member set (sorted). Stability: beta.

-spec migrate_peer(node()) -> ok | {error, term()}.

Trigger RFC 9000 §9 path migration on the QUIC connection backing the dist channel to Node. The connection rebinds to a new local 4-tuple via PATH_CHALLENGE/PATH_RESPONSE; keys, streams, and any open circuits ride through transparently. Useful when the local network changes (NIC/IP swap, tethering, multi-link policy).

Returns ok on successful path validation. Common errors: - {error, not_connected} — no current dist channel to Node - {error, no_conn} — controller alive but underlying conn gone - {error, peer_disable_migration} — peer set the transport-param flag forbidding migration; treat as terminal for this connection - {error, timeout} — path validation didn't complete in time

Stability: beta. The opts map may grow keys; existing keys stay.

-spec new_map(atom()) -> {ok, pid()} | {error, term()}.

Start a replicated map named Name on this node. A map is node-local: to be cluster-wide it must run on every participating node (declare it in the replicated_maps env, or call this on each node). Idempotent. See barrel_p2p_map for the full API and caveats. Stability: beta.

-spec owners(term(), pos_integer()) -> [node()].

The top-N distinct owner nodes for Key (best first), for replicated placement. Stability: beta.

-spec partition(term()) -> non_neg_integer().

The ring partition Key falls in (0..ring_size-1). Use it to map keys to partitions when reacting to ownership events. Stability: beta.

-spec place(term()) -> node() | undefined.

The node that should own Key cluster-wide. Agreement is eventual: under churn nodes can briefly disagree until the member set converges. Stability: beta.

-spec remind(term(), integer(), term()) -> ok.

Set a reminder for Key to fire at absolute wall-clock FireAtMs (erlang:system_time(millisecond) scale), delivering Payload to subscribers on the owning node. Re-setting a Key replaces it. Fires exactly once in steady state; best-effort under churn or a crash at the fire instant. Stability: beta.

-spec remind_after(term(), non_neg_integer(), term()) -> ok.

Like remind/3 but DelayMs from now, converted to an absolute target so all nodes agree. Stability: beta.

-spec resign(term()) -> ok.

Stop campaigning for Name and yield leadership if held. No revoked message is sent (the caller asked to step down). Stability: beta.

-spec subscribe_map(atom()) -> ok | {error, no_such_map}.

Subscribe the caller to a map's change events: {barrel_p2p_map, Name, {put, Key, Value} | {remove, Key}}. Stability: beta.

-spec subscribe_reminders() -> ok.

Subscribe the caller to reminder deliveries. Receives {barrel_p2p_reminder, Key, Payload, Fence} on the node that owns the key when it fires. Subscribe on every node where the handler may run. Stability: beta.

-spec subscribe_shard() -> ok.

Subscribe the caller to ownership events. Receives {barrel_p2p_shard, {acquired, Partition}} when this node gains a partition and {barrel_p2p_shard, {released, Partition}} when it loses one. Stability: beta.