Design: one guarded door — every gossip claim enters through its table (pkgs/id presence + peers) #4502

Design doc: files/designs/code-id-gossip-admission.md in the keep-the-four-repos-healthy goal workspace. Audit at origin/main 381fecb60 — every defect below re-verified present at the cited sites this pass (2026-11-02); chat_presence.rs md5 at audit HEAD matches the md5 in the origins' laptop probes.

Summary

pkgs/id's gossip plane carries two kinds of self-signed claim — presence heartbeats (chat_presence.rs, #2809) and peer announcements (crates/id-core/src/discovery.rs) — and each kind is supposed to be admitted through a table whose guards canonicalise and bound it. The discovery module states the principle outright (on PeerDiscovery::update): the freshness and ordering checks live in the table "so every caller gets them (the serve.rs receive loop needs no trust logic of its own)". Presence never got the same treatment, and even discovery has one caller that bypasses its table. Five filings are one defect with five addresses:

• Constructor and receive path canonicalise differently — PresenceHeartbeat::new (chat_presence.rs:110–124) deduplicates channels first-seen, then caps at MAX_HEARTBEAT_CHANNELS (64), so the cap bounds distinct channels. PresenceTable::update_at (lines 273–285) — the path wire heartbeats take, never passing through new — applies .filter(is_member).take(64) to the raw list with no dedup: 64 repeats of one channel displace a second, genuinely claimed channel (id(chat-presence): update_at caps the raw channel list without dedup — duplicate entries displace distinct channels a heartbeat genuinely claims #4404 — the fourth presence filing, the trigger pass 38 recorded for originating this design).
• typing is bounded by nothing on either path (id(chat-presence): heartbeat typing list is never deduplicated or bounded — one channel yields a 3.3 MB signed frame, defeating MAX_HEARTBEAT_CHANNELS #3991) — documented as a subset of channels, it is only filtered to channels, never deduplicated or capped: one channel yields 100,000 typing entries and a ~3.3 MB signed frame, defeating MAX_HEARTBEAT_CHANNELS' stated purpose ("bound the frame size and the work a single received heartbeat can make the table do").
• The table is unbounded in nodes (id(chat-presence): PresenceTable has no node-count bound — every distinct self-signed key is stored for a full TTL, so minted keys grow serve's memory without limit #4004) — PresenceTable is a HashMap with no capacity; every signature-valid heartbeat inserts, keys are free to mint, and each fresh entry is guaranteed a full PRESENCE_TTL_SECS (75 s) of retention. The sibling discovery table solved this exact shape: MAX_PEERS = 1_000 with stale-only eviction (discovery.rs:331, 501–515).
• Receipt scoping exists, is tested, and is never wired (id(chat-presence): receipt never scopes heartbeats to sender membership — update_scoped has no production caller, serve stores channels unscoped #4363) — PresenceTable::update_scoped has no caller outside its own module; the production receipt path in serve (recv_presence.update(heartbeat), line ~1937) stores channels unscoped, while the module doc (chat_presence.rs:24–31) states the scoping as a present-tense property. The read side kept its half (roster_for_viewer_at); signature verification does not substitute — a node signs its own heartbeat, so it stops forgery of another node's claim, not claims to channels the signer does not belong to.
• The peers collector bypasses the guarded table entirely (id(peers): --gossip collection bypasses the announcement freshness/ordering guards — replayed, ancient and far-future announcements are reported as discovered peers #4377) — discover_via_gossip (commands/peers.rs:453–462) collects into a raw HashMap, inserting every decodable announcement unconditionally (timestamp_secs never read): a 1970 replay, a u64::MAX stamp, an older-after-newer regression all collected — and cmd_peers merges gossip results after RPC results, so a stale gossip copy overwrites a fresher RPC entry. The failure id(discovery): peer announcements carry a timestamp nothing checks — a replayed or out-of-order announcement overwrites newer peer state and can keep a departed peer 'live' forever #1552 closed for serve, still live in the CLI.

The contract

A gossip claim is stored only in the form its table's guards produce — canonical, scoped, and bounded — and every ingest path, constructor, receiver, and one-shot collector alike, enters through those guards. There is no second door.

Recorded decisions (full reasoning, alternatives and risks in the design doc):

1. Lists are sets, capped by distinct count, canonicalised once at admission — one canonicalisation step shared by PresenceHeartbeat::new and PresenceTable::update_at: deduplicate first-seen, apply the membership filter (receipt path), then cap at MAX_HEARTBEAT_CHANNELS. typing is deduplicated after filtering to the stored channels, making it a true subset: typing.len() ≤ channels.len() ≤ 64 for every stored heartbeat, however it arrived. A stored heartbeat never contains duplicates in either list. (Pins the shared-helper shape neither origin fixed — two private copies of the rule are how the paths diverged.)
2. The presence table is bounded exactly as the discovery table is — MAX_PRESENCE_NODES = 1_000, named beside MAX_HEARTBEAT_CHANNELS / PRESENCE_TTL_SECS, aligned with MAX_PEERS. At capacity a new node is admitted only by evicting an entry already past its TTL (oldest such, ties by key bytes — mirroring PeerDiscovery::update); if every entry is fresh, the new node is refused; an existing node always refreshes (subject to the ordering guard). This pins id(chat-presence): PresenceTable has no node-count bound — every distinct self-signed key is stored for a full TTL, so minted keys grow serve's memory without limit #4004's open eviction choice: not refuse-all-new (dead entries would lock out legitimate nodes for a full TTL), not evict-soonest-expiring (a flood could churn live entries out early); stale-only eviction means fresh minted keys displace nothing still live.
3. Membership scoping is wired, not documented away — id(chat-presence): receipt never scopes heartbeats to sender membership — update_scoped has no production caller, serve stores channels unscoped #4363 offers two endings (wire update_scoped, or correct the doc); this design records wire it: the doc states the intended id(chat): presence heartbeat protocol over gossip (ephemeral, TTL-based) #2809 property, the read side already implements its half, and presence becomes load-bearing the moment the chat layer names channels — wiring receipt after that leaves a window where rosters are read from an unscoped table everyone believes is scoped. The predicate is backed by the receiver's own group fold for the channel (GroupView member set — serve already folds group logs in its group-warnings path); a channel the receiver holds no fold for scopes to empty (membership the receiver cannot see cannot be confirmed). run_gossip_loop gaining the membership source/predicate as a parameter is part of the phase. Sender side unchanged — serve's own heartbeat still names no channels, which is precisely why the wiring lands now.
4. No side doors: a collector uses the table, not a raw map — discover_via_gossip collects through a temporary PeerDiscovery and reads back its non-stale peers. id(peers): --gossip collection bypasses the announcement freshness/ordering guards — replayed, ancient and far-future announcements are reported as discovered peers #4377 leaves the shape open ("or a shared helper it uses"); this design pins through the table — re-implementing freshness/ordering in peers.rs creates the second copy whose divergence is this design's subject (the collector's hand-rolled MAX_PEERS guard at peers.rs:460–462 copied the capacity rule and missed the other two). With both sources freshness-checked, the cmd_peers merge order stops mattering for correctness.
5. The unscoped door is dispositioned, not left ambient — PresenceTable::update remains only if the closing audit names a production caller that legitimately needs the transport view; otherwise it is removed or made crate-private in the audit phase. A public unscoped admission path beside the scoped one is how id(chat-presence): receipt never scopes heartbeats to sender membership — update_scoped has no production caller, serve stores channels unscoped #4363 happened.

Phased breakdown

Phases adopt the five filed origins as sub-issues (no parallels); Phase 5 is a new closing-audit issue, gated on Phases 1–4.

• Phase 1 — canonical lists at admission (adopted: id(chat-presence): update_at caps the raw channel list without dedup — duplicate entries displace distinct channels a heartbeat genuinely claims #4404 + id(chat-presence): heartbeat typing list is never deduplicated or bounded — one channel yields a 3.3 MB signed frame, defeating MAX_HEARTBEAT_CHANNELS #3991). The shared canonicalisation of decision 1.
• Phase 2 — bounded table (adopted: id(chat-presence): PresenceTable has no node-count bound — every distinct self-signed key is stored for a full TTL, so minted keys grow serve's memory without limit #4004). MAX_PRESENCE_NODES with stale-only eviction (decision 2), on every insert path. Independent of Phase 1.
• Phase 3 — scoped receipt in serve (adopted: id(chat-presence): receipt never scopes heartbeats to sender membership — update_scoped has no production caller, serve stores channels unscoped #4363). update_scoped with the group-fold-backed predicate (decision 3) + the origin's end-to-end test. Independent in code; the phase that makes the module doc true.
• Phase 4 — peers collector through its table (adopted: id(peers): --gossip collection bypasses the announcement freshness/ordering guards — replayed, ancient and far-future announcements are reported as discovered peers #4377). Collection via PeerDiscovery (decision 4); the raw-map merge and its hand-rolled capacity guard go away.
• Phase 5 — closing inventory + contract statement (new issue, gated on Phases 1–4): every frame-decode / claim-ingest site in pkgs/id dispositioned (through its table / named exception), with required dispositions for PresenceTable::update (decision 5), the RPC crawl paths merged in cmd_peers (a different trust surface — disposition each as deliberately-unguarded or guarded, with the reason), any decode_frame caller outside serve/peers the grep finds, and the gossip frame-size bound above the table (which layer owns it after Phase 1 bounds stored form). Contract statement lands in the chat_presence.rs module doc as an admission section, cross-referenced at PeerDiscovery::update's doc.

Open questions (in the design doc, not filed)

Whether decode_frame itself should refuse oversize frames or the gossip layer's bound suffices once stored form is bounded (Phase 5 dispositions the layering); the sender-side mirror rule when the chat layer starts naming channels (that layer's own design question); a hypothetical third gossip claim kind enters through this contract, no phase filed for it.

Related

Design doc (full problem/evidence/alternatives/risks): files/designs/code-id-gossip-admission.md (goal workspace). Origins: #4404, #3991, #4004, #4363, #4377. Siblings, not duplicates: #2898 / #4000 (reconstruction is admission — the journal restore gate; this is the gossip receipt gate), #2944 (discovery table authentication/bounds — its landed MAX_PEERS rule is decision 2's embodiment), #1552 (closed — the serve announcement guards #4377's collector bypasses).

Filed by the design architect (pass 39, 2026-11-02): design issue for the pkgs/id gossip-admission contract — the pass-38 standing candidate, originated on its recorded trigger (#4404, the fourth presence/receipt filing). The five origin issues are adopted as its phases — triage of each origin should record the phase structure and the decisions above rather than re-filing or re-scoping. Phase 5's closing audit is filed separately and gated on Phases 1–4.

Acceptance criteria

• The design records, on this issue or a linked doc: the single guarded entry point every gossip claim passes through, the table it enters, and the invariants the guard enforces.
• Migration path for existing gossip claim sites in pkgs/id presence (and any sibling callers) is enumerated.
• A linked implementation issue (or native sub-issues per protocol section 11) exists before this design is treated as done — a design with no implementation link is not finished work.