-spec advertise(pool(), <<_:256>>, binary(), handler()) -> ok | {error, term()}.

Register a procedure handler on every healthy link. Stored in pool state so a respawned link registers it again. A caller reaches this provider only through a procedure_advertisement record that names it; registering the handler publishes none. Returns ok when at least one link accepted the registration. A handler that answers {error, Text} with a binary or a printable charlist sends that text to its caller, up to 256 bytes of it; any other error reason reaches the caller as its name only.

-spec advertise(pool(), <<_:256>>, binary(), handler(), auth_policy()) -> ok | {error, term()}.

Advertise with an auth policy -- see auth_policy() above for the full set (open | {ucan_required, Issuer} | {realm_member_required, RealmDid, RequiredCan}).

-spec advertise(pool(), <<_:256>>, binary(), handler(), auth_policy(), binary() | undefined) ->
                   ok | {error, term()}.

As advertise/5, with the pool-signed provider advertisement (EncodedAd, the resolved D25 authorization included) fanned out to every link as an ADVERTISE frame. The facade resolves the authorization before calling here; a undefinedEncodedAd registers the handler locally and sends no frame (legacy behaviour).

-spec advertise_stream(pool(), <<_:256>>, binary(), macula_frame:stream_mode(), stream_handler()) ->
                          ok | {error, term()}.

Advertise a streaming procedure handler on every healthy link. Stored in pool state so links respawned later replay the advertisement. Returns ok when at least one link accepted the registration. Same as advertise_stream/6 with policy open.

-spec advertise_stream(pool(),
                       <<_:256>>,
                       binary(),
                       macula_frame:stream_mode(),
                       stream_handler(),
                       auth_policy()) ->
                          ok | {error, term()}.

Advertise a streaming procedure with an auth policy -- the same auth_policy() set advertise/5 takes. The policy is stored with the procedure, so a link respawned later re-advertises it still gated.

-spec advertise_stream(pool(),
                       <<_:256>>,
                       binary(),
                       macula_frame:stream_mode(),
                       stream_handler(),
                       auth_policy(),
                       binary() | undefined) ->
                          ok | {error, term()}.

As advertise_stream/6, with the pool-signed provider advertisement (EncodedAd, the resolved D25 authorization included) fanned out to every link as an ADVERTISE frame. undefined registers the handler locally and sends no frame (legacy behaviour).

-spec call_linked_station(pool(), <<_:256>>, binary(), term(), 1..600000) ->
                             {ok, term()} | {error, term()}.

Issue a CALL for a procedure the pool's linked stations serve themselves, such as _dht.*: first success across the pool's healthy links, each CALL targeting the station its link is connected to. It moves on to the next link only when the CALL never went out on the one before (macula_station_link:not_sent/1). Returns {error, no_healthy_station} when no link has completed its CONNECT/HELLO handshake. A procedure a provider serves is called through macula:call/5, which resolves the provider.

Realm is per-call (32 bytes). TimeoutMs is from 1 ms to ten minutes, the deadline window a provider accepts.

-spec call_station(pool(), seed(), <<_:256>>, <<_:256>>, binary(), term(), 1..600000) ->
                      {ok, term()} | {error, term()}.

Issue a CALL to Target, a provider's node_id, at ONE specific station, dialing it directly even if it is not in the pool's seed set. Station is a seed URL (e.g. <<"quic://[::1]:4433">>). The pool ensures a link to it (reusing an existing one, or dialing and monitoring a new one exactly like a seed), waits for the handshake within the deadline, and calls through that link; the station delivers the CALL to the provider Target names. This is the direct-dial data path: resolve a provider's serving_station to its endpoint, then reach it in one hop here, with no mesh relay.

Returns {error, not_connected} if the link does not complete its handshake before the deadline.

-spec call_station(pool(), seed(), <<_:256>>, <<_:256>>, binary(), term(), 1..600000, binary()) ->
                      {ok, term()} | {error, term()}.

As call_station/7, presenting a capability token (UCAN) to a gated provider. Empty token = none. Slice 7b.

-spec call_station(pool(), seed(), <<_:256>>, <<_:256>>, binary(), term(), 1..600000, binary(), map()) ->
                      {ok, term()} | {error, term()}.

As call_station/8, with a per-call TLS trust override for THIS dial only — verify (webpki | none), expected_node_id (pin the station's node_id), and/or pin_tls_cert (false to enforce that pin at the application layer only — see macula_peering_conn:connect_opts() — needed against a station whose TLS is terminated by a PKI unrelated to its macula identity, e.g. production behind Let's Encrypt) in LinkOpts. The pool's own connect/2-time verify/expected_node_id are fixed at connect time and apply uniformly to every link the pool dials (seeds and every call_station target alike) — unworkable for direct-dial, whose whole point is reaching a station not known until resolved at call time. This lets a direct-dial caller pin trust to the specific pubkey a signed DHT record just resolved, without weakening (or needing to know in advance) the pool's default verification for its other links. Only applies when a NEW link is dialed for Station — an already-connected link keeps whatever trust it was dialed under.

-spec call_station(pool(),
                   seed(),
                   <<_:256>>,
                   <<_:256>>,
                   binary(),
                   term(),
                   1..600000,
                   binary(),
                   map(),
                   pos_integer()) ->
                      {ok, term()} | {error, term()}.

As call_station/9, waiting at most DialTimeoutMs of TimeoutMs for a freshly-dialed link's handshake; the CALL gets whatever remains of TimeoutMs. {error, not_connected} then comes back after DialTimeoutMs, before any CALL was sent, so a direct-dial caller can move on to another station within its own deadline.

-spec call_stream_station(pool(), seed(), <<_:256>>, <<_:256>>, binary(), term(), map()) ->
                             {ok, pid()} | {error, term()}.

Open a streaming RPC to Target, a provider's node_id, by DIALING a specific station directly (direct-dial). The streaming analogue of call_station/7: ensure (reuse or dial) a link to Station, await the handshake, then open the stream there, naming Target. Opts may set dial_timeout_ms (default 10_000) for the dial and handshake, plus any stream option (e.g. mode). Opts also carries the per-call TLS trust override for this dial: verify, expected_node_id, pin_tls_cert, same as call_station/8. They are kept apart as the dial's own options, so they reach ensure_link/3 and not the stream open.

-spec child_spec(term(), [seed()], opts()) -> supervisor:child_spec().

OTP child spec — drop the pool into a caller's supervision tree. Id is the supervisor child id. A supervisor keeps the spec for its child's life, so the spec names how to load the node identity key and never holds the key: give node_identity as a loader {Module, Function, Args} that returns {ok, Key}. Args say where the key is, such as a file name, and never hold the key, because a supervisor that fails to start the pool logs the spec, Args included. A key, or a function that could hold one, given here raises {node_identity, loader_required}.

-spec close(pool()) -> ok.

Stop the pool. Every subscriber receives a final {macula_event_gone, SubRef, pool_closed} message; every link terminates with the pool.

-spec connect([seed()], opts()) -> {ok, pool()} | {error, term()}.

Spawn a pool with one link per seed. Returns immediately; link handshakes complete asynchronously. Publish/subscribe block until at least one link is connected (or fail with {error, {transient, no_healthy_station}} on the publish path). A node with no crypto profile, or a node_identity that is not an identity key in the node's profile, starts no pool: the refusal is returned and no link is dialed. Nor does a seed that names no node_id it expects, in the seed or in the expected_node_id option: the start returns {error, {seeds, expected_node_id_required}}.

-spec ensure_station_link(pool(), seed(), map(), pos_integer()) -> {ok, pid()} | {error, term()}.

As pick_connected_link/1, but for a SPECIFIC station — reuse a live link to Station or dial (and wait up to TimeoutMs for the handshake on) a fresh one, per-call trust-overridable via LinkOpts (verify / expected_node_id / pin_tls_cert, mirroring call_station/9). This is direct-dial's content-transfer primitive: the returned pid is pinned for a whole put_content/get_content dedicated-stream transfer exactly like pick_connected_link/1, just against a caller-resolved station instead of whichever pool link is already up.

-spec links(pool()) -> {ok, [link_info()]}.

Per-link snapshot of the pool — one link_info() per configured seed that currently has a spawned link worker. Unlike status/1 (which only aggregates counts), this exposes each link's node_id (peer station pubkey), dial host, pid, and connected flag, so a caller can resolve a specific station (by pubkey or hostname) to its link and address it directly.

One is_connected/1 + peer_node_id/1 probe per spawned link (each capped at 1s). Not for hot-loop polling.

-spec pick_connected_link(pool()) -> {ok, pid()} | {error, no_healthy_station}.

Pick one currently-connected link and return its pid, without issuing a call. For a caller that needs to pin ONE link across a sequence of related calls — a dedicated QUIC stream, opened once on the returned pid (via the internal station-link module's content-stream API), only isolates one link's traffic, so every call in the sequence must go over that same link. call_linked_station/5 picks fresh per call (call_first_success/5) and is the wrong primitive for that.

Selection matches call_first_success/5's ordering (first connected link wins) so behaviour is unsurprising relative to the existing pool-routed path.

-spec publish(pool(), <<_:256>>, binary(), term(), map()) -> ok | {error, term()}.

Publish a frame to replication_factor currently-connected links. Partial success = success. Realm is per-call (32 bytes) and identical across every replicated link — a wrong Realm here blackholes the publish on every selected station alike, regardless of replication_factor; see ?DEFAULT_REPLICATION's own doc for what raising the factor does and does not protect against.

The payload is checked for wire admissibility HERE, in the caller's process, before the pool is touched. Downstream the send is a gen_statem:cast into a shared peering connection that encodes without a try/catch, so an unrepresentable term would kill that connection and every other producer's in-flight traffic with it, asynchronously, after this function had already answered ok. Checking first is what makes the ok falsifiable.

Returns {error, {unsupported_payload_type, Type, Path}} naming the offending value and where it sits in the term. Floats are the common case: scale them to integers (micro-units) or send binary strings. A topic over 512 bytes or not UTF-8 is refused first, as {error, {text_too_long, topic}} or {error, {invalid_text, topic}}.

-spec realm_key(pool(), <<_:256>>) -> {ok, binary()} | none.

The realm key the pool pinned for RealmId when it started, from its realm_trust option, or none. Direct dial checks an org namespaced advertisement's authorization against this key alone.

-spec sign_domain_record(pool(), macula_record:m_record()) ->
                            {ok, macula_record:m_record()} |
                            {error,
                             not_a_domain_type | invalid_subject | lifetime_too_long |
                             lifetime_reversed | record_too_large | malformed_record}.

Sign a domain record (tags 0x20 to 0xFF) as this node, with the pool's node identity key, in the pool's own process, and return the signed record, stored under this node's key id with its subject when it has one. Build it with macula_record:envelope/3. The pool stamps it with a new version and created_at, keeping the lifetime it was built with. Only the record's type, created_at, expires_at, payload and subject reach the pool, and each of these is refused before the call: a type outside 0x20 to 0xFF, {error, not_a_domain_type}; a subject that is not a non-empty binary, {error, invalid_subject}; a lifetime past the domain maximum of 7 days, or running backwards, {error, lifetime_too_long} or {error, lifetime_reversed}, never shortened to fit; a payload and subject over 256 KiB together, {error, record_too_large}; and a term that is no domain record, {error, malformed_record}. A signed record that would pass 256 KiB is {error, record_too_large} from the pool. Withdraw a domain record with withdraw_node_record/3.

-spec sign_node_record(pool(), macula_record:m_record()) ->
                          {ok, macula_record:m_record()} |
                          {error,
                           not_a_node_signed_type | key_id_mismatch | lifetime_too_long |
                           lifetime_reversed | record_too_large | malformed_record}.

Sign a record this node signs about itself with the pool's node identity key, in the pool's own process, and return the signed record: the node record, a procedure advertisement or a content announcement that names this node. The pool stamps it with a new version and created_at, keeping the lifetime it was built with. The key never leaves the pool, so a caller never holds it. Only the record's type, created_at, expires_at and payload reach the pool. A record of another type, a tombstone included, is {error, not_a_node_signed_type}; one that names another node {error, key_id_mismatch}; one whose lifetime passes its type's maximum or runs backwards {error, lifetime_too_long} or {error, lifetime_reversed}; a payload over 256 KiB, refused before the call, or a signed record that would pass 256 KiB {error, record_too_large}; a record with a subject, which no type a node signs about itself carries, refused before the call, and anything else the pool cannot sign {error, malformed_record}.

-spec sign_node_record(pool(), macula_record:m_record(), map()) ->
                          {ok, macula_record:m_record()} |
                          {error,
                           not_a_node_signed_type | key_id_mismatch | lifetime_too_long |
                           lifetime_reversed | record_too_large | malformed_record | not_after_passed}.

As sign_node_record/2, bounded by Optsnot_after (a Unix millisecond). The pool judges the bound on its own clock: one already passed is {error, not_after_passed}; one before the record's lifetime runs out ends the record at the bound; one after keeps the built lifetime. The refusals of sign_node_record/2 stand under a bound. Opts without not_after signs as sign_node_record/2 does, and a not_after that is not an integer raises function_clause in the caller.

-spec status(pool()) -> {ok, status()}.

Aggregate health snapshot of the pool. Single round-trip to the pool's gen_server plus one is_connected probe per spawned link (each capped at 1s). Suitable for /health or /status endpoints; not for hot-loop polling.

Counts:

• healthy_links — links whose worker pid is alive and whose CONNECT/HELLO handshake has completed.
• failed_links — every other configured seed (link not yet spawned, dead, or still handshaking).

-spec subscribe(pool(), <<_:256>>, binary(), pid(), map()) ->
                   {ok, reference()} | {error, {text_too_long | invalid_text, topic}}.

Subscribe Subscriber to (Realm, Topic). The pool subscribes every currently-spawned link and dedupes inbound events before fan-out. Returns {ok, SubRef}, or the topic's refusal when a SUBSCRIBE cannot carry it (over 512 bytes, or not UTF-8); Subscriber receives {macula_event, SubRef, Topic, Payload, Meta} for each delivered event and {macula_event_gone, SubRef, Reason} once when the pool closes or the subscriber pid dies.

-spec unadvertise(pool(), <<_:256>>, binary()) -> ok.

Drop a previously-advertised procedure on every healthy link and remove it from the pool's replay state. Idempotent.

-spec unadvertise_stream(pool(), <<_:256>>, binary()) -> ok.

Drop a streaming procedure on every healthy link and remove it from the pool's replay state. Idempotent.

-spec unsubscribe(pool(), reference()) -> ok.

Drop a subscription. Idempotent — unknown SubRef is a no-op. The wire-level link subscription persists for the pool's lifetime (one wire sub per (Realm, Topic) multiplexed across local consumers); Phase 4 will tighten this.

-spec withdraw_node_record(pool(), macula_record:m_record() | binary(), macula_record:reason()) ->
                              {ok, macula_record:m_record()} |
                              {error,
                               not_this_nodes_record | not_a_node_signed_type | lifetime_too_long |
                               lifetime_reversed | record_too_large | malformed_record |
                               macula_record:refusal()}.

Sign a tombstone that withdraws a record this node signed, with the pool's node identity key, in the pool's own process. The pool first verifies the record, as its wire form or its signed map, under its profile, and withdraws it only when it is of a type a node signs about itself or a domain type, and it carries the pool's own key, so the tombstone lands on the record's own slot. A record that does not verify gets its refusal; one of another type {error, not_a_node_signed_type}; another node's {error, not_this_nodes_record}; a wire form over 256 KiB, or a signed map whose key, tbs and signature pass 256 KiB together, {error, record_too_large}, refused before the call; and anything else the pool cannot sign, a map whose key, tbs or signature is not a binary included, {error, malformed_record}. Of a signed map, only its key, tbs and signature reach the pool. The tombstone lives until the record has expired plus the clock tolerance.