Module protocol 

mcpmesh-local/1 protocol types (spec §6.1). Shared vocabulary between the daemon and its clients (porcelain, connect proxy, later the host shell). Wire framing is the family NDJSON codec — carried by the caller, not defined here (D-A).

Request/response asymmetry: requests are one typed, closed enum (Request); responses are per-method typed structs deserialized from the JSON-RPC result Value — Status → StatusResult, RegisterService → an ack, OpenSession → no JSON-RPC result at all: the socket STOPS being JSON-RPC and becomes a raw byte pipe.

Additive-only (§6.1): new fields (capabilities on Hello, groups/user_id on PeerInfo, device on OpenSession — M3+) MUST land as #[serde(default, skip_serializing_if = ...)] so older payloads still deserialize.

Structs

AuditSummaryResult

Result of Request::AuditSummary (spec §11.3): LOCAL per-peer / per-service session counts aggregated from this node’s OWN audit log — NEVER transmitted (§11.3 local-only). Surface-clean (§1.5): peer names are petnames / user_ids (NEVER EndpointIds), service names are the registered service names (NEVER transport vocabulary). A “session” is one SessionOpen record. per_peer / per_service are sorted ascending by name (deterministic). Tuples mirror kb’s InsightResponse::per_peer_contribution — ["bob", 2] on the wire.

BlobFetchResult

Result of Request::BlobFetch: the verified hash + byte length written to dest_path. Additive-only (§6.1).

BlobPublishResult

Result of Request::BlobPublish: the copyable mcpmesh/blob/1 ticket + the blob’s blake3 hash. A ticket/hash here is the §9 blob-reference vocabulary (NOT a §1.5 transport-vocab leak — the same carve-out as the pairing invite line). Additive-only (§6.1).

BlobScopeList

Result of Request::BlobList: the daemon’s scopes. Additive-only (§6.1).

Hello

The first exchange on any *-local/N socket (spec §6.1 “hello convention”).

InviteResult

Result of an Request::Invite request: the copyable mcpmesh-invite: artifact (spec §1.5 surface #2 — the ONE pairing artifact deliberately carved out of the transport-vocabulary blocklist, so this is NOT a transport-vocab leak) plus its absolute expiry in epoch seconds (≤ now + 24h).

OrgJoinResult

Result of Request::OrgJoin — the pinned org id echoed back (surface-clean; the fingerprint is computed porcelain-side from the invite’s org_root_pk). Additive-only (§6.1).

PairResult

Result of a Request::Pair request: the inviter’s suggested petname (the redeemer’s local name for the new peer) plus the display-only short authentication code (SAS, spec §4.2) — a few words the human reads aloud to a second channel to catch a whole-invite forgery / address-swap MITM. The SAS is a pairing-ceremony artifact (like the invite line), NOT a §1.5 transport-vocabulary leak.

PeerInfo

A known peer as reported by status (petname only — never the EndpointId, §1.5).

PresencePeer

One reachable roster peer device as reported by status (spec §10.1 advisory presence read). ADVISORY — this is a display convenience, never an authorization surface. Surface-clean (§1.5/§17): FLAT vocabulary ONLY — a user_id, a human device_label, its role word, and an online boolean. It carries NO EndpointId / pubkey / hash / ALPN or any transport vocabulary.

RecentPairing

One recently completed INVITER-side pairing, surfaced by status so the inviter’s human can read the short authentication code (SAS) and compare it with the redeemer’s out-of-band — spec §4.2’s ceremony is “both humans compare the code”: the redeemer sees it in its PairResult; this is the inviter’s porcelain surface for the same words. DISPLAY-ONLY ceremony state: held in-memory by the daemon (a small ring), lost on restart, NEVER an authorization input or trust data. Surface-clean (§1.5): a petname + the SAS wordlist words + an epoch — never an EndpointId.

RosterInstallResult

Result of a Request::RosterInstall request (spec §4.3 manual path): the installed roster’s org id + serial (roster-status vocabulary the confirmation line is permitted to render) plus how many live sessions the install severed (D8). Surface-clean: NO keys / EndpointIds / paths.

RosterStatus

Roster-mode status (spec §4.4). Surface-clean roster VOCABULARY only: org_id, serial, a plain state word, and the pinned org-root FINGERPRINT in short words — never raw keys/EndpointIds/serials- as-transport-vocab (§1.5). Absent in a pure-pairing daemon.

ScopeInfo

One scope in a BlobScopeList (spec §9): its name + the hashes it contains + the principals it grants. Flat vocabulary ONLY (§1.5) — no EndpointId/pubkey/ALPN. Additive-only (§6.1).

ServiceInfo

A registered service as reported by status (no transport vocabulary — §17).

StatusResult

Enums

BackendKind

The kind of backend answering a service — the two valid values, enforced at the type level and kept in lockstep with BackendSpec’s variants. Status reports the kind only, never the command/path (§17 no transport vocabulary).

BackendSpec

How a service is answered (spec §6.2). Mirrors the config [services.*] kinds; Config→BackendSpec is a hand-written match (Task 4/9), not a serde passthrough.

Request

Control-API requests. Serialized as { "method": "...", "params": {...} } (JSON-RPC-shaped; the id/jsonrpc envelope is added by the transport layer).

Constants

API_NAME

API_VERSION

Functions

method_of

Extract the method tag from a raw request value without deserializing the whole message. Task 3’s dispatcher uses this: match on the method string, then deserialize params per-method — which tolerates omitted / null / {} params for parameterless methods (adjacent tagging rejects params:{} on unit variants).