Module probe 

RFC-004 Tier-1 — connection health probing.

A wire ping sends a probe; the peer’s daemon auto-responds with a probe_ack — no LLM / MCP in the loop (RFC-004 AC-HP2 kill criterion). Both ride the existing kind=100 heartbeat carrier with a body t discriminator (probe / probe_ack), NOT a new top-level kind — per the event-kind-carrier rule (control signals discriminate on a registered generic kind’s body).

Probes are plaintext (they carry only a correlation nonce, no secret), so the receiving daemon reads t directly without decrypting. They are trust-neutral: a probe/ack never mutates a peer’s tier or relay state.

Constants

HEARTBEAT_KIND

The heartbeat carrier kind (registered, special-cased Ephemeral in signing).

HEARTBEAT_TYPE

The event type string paired with HEARTBEAT_KIND.

Functions

is_probe_ack_for

True iff event is a kind=100 probe_ack carrying nonce — the ack a waiting wire ping is looking for.

probe_ack_body

Body of a probe_ack answering the probe carrying nonce.

probe_body

Body of an outbound probe. nonce correlates the ack.

probe_nonce

If event is a kind=100 probe, return its correlation nonce — the signal the daemon uses to decide whether to auto-respond. An event that is heartbeat-kind but carries an unknown/other t (or a sealed body) returns None: it is simply ignored, cursor advances, no reject (RFC-004 AC-HP4).

record_ack_within_rate

Per-peer ack rate gate (RFC-004 AC-HP3 — a 100-probe flood must yield ≤ a handful of acks, bounded responder CPU). Prunes times to the window, then: >= max remaining → refuse the ack (false); else record now and allow (true). Same sliding-window shape as the relay’s intro gate. Pure → unit-tested. The daemon holds times per peer in a process-static map.

respond_to_probes

Daemon-side auto-respond to verified inbound probes (RFC-004 AC-HP2 — no LLM in the loop). For each (peer, nonce), build+sign a probe_ack and deliver it, rate-limited per peer (AC-HP3). Best-effort: one peer’s failure never aborts the rest, and never blocks the pull cycle.

send_probe

Send a probe to peer (synchronous delivery). The caller then waits for the matching probe_ack to land in the inbox.