[Protocol] Host-served raw-proxy path publishes no `openai.exchange.v1` terminal event — and terminal-envelope enrichment (usage, digests, serving provenance): options + a recommendation

[StevenMih]

Companion to #1669 (the routed-to-peer gap). This is about the other uncovered branch — the raw-proxy host-served path — plus the shape of what the terminal envelope should carry. Raising it as a design read before opening PRs, so what follows is small merges rather than a design argument in a PR thread. Everything below exists and is tested on a public fork; nothing here is hypothetical.

What's covered today

#1437 landed openai.exchange.v1 terminal events for exchanges a node serves, on the typed-frontend seam and the raw-proxy plugin-served path. #1668 adds the routed-to-peer path (#1669's gap). The remaining uncovered branch is the raw-proxy host-served path (real weights, route_ingress → route_model_request): it publishes nothing. On a serving node that's most exchanges — so a lifecycle-hook plugin sees every exchange except the ones the host itself served.

What a downstream consumer needs, and why (one line each)

Field	Host already computes it?	Why it's useful
publish on the host-served path	yes — same publish pattern as plugin-served	otherwise served exchanges are invisible to a plugin
usage {prompt, completion, total}	yes — RespondedWithUsage carries it	the honest denominator for anything billing- or audit-shaped
request_digest, response_digest	bytes are in hand at the publish site	binds a record to what was asked / answered without carrying text
served_by_node_id	yes — the node's own endpoint id	which node served (vs. routed)
model identity (model_identity_hash, canonical_ref, revision, quantization, architecture, context_length, parameter_size, layer_count)	yes — ServedModelMetadata / ServedModelIdentity	"a model by a name" → a model by what was actually loaded
hardware (gpu, vram_bytes, is_soc, hostname)	yes — startup hardware survey	which box, as the host itself reports it

Every field is real-or-omitted (skip_serializing_if); nothing is fabricated; no prompt or completion text is ever carried — digests only.

Options

A. One PR, the whole block. Publish on the host-served path + usage + digests + a serving_provenance struct with all of the above.
For: one review, one merge, plugins work on main the next day. Against: ~300 lines touching ingress.rs and the envelope; a 13-field struct lands in one go; reviewers accept the digest construction and the hardware fields together.

B. Three PRs, each independently useful to mesh-llm.

1. Host-served publish — the same effective/terminal pair the plugin-served path already emits, on the host-served branch. Bare envelope. feat(openai): publish Terminal events on the routing node #1668's pattern applied to the branch that forgot to publish. ~40 lines.
2. Usage + digests — usage from the dispatch outcome; request_digest/response_digest as SHA-256 over the bytes as transmitted (no canonicalization dependency; a consumer wanting a canonical digest computes its own and labels it separately). ~80 lines.
3. serving_provenance block — model identity + hardware from descriptors the host already holds. Optional struct, absent when nothing resolved; could be config-gated if you prefer opt-in. ~150 lines.
   For: each reviewable in minutes; 1 and 2 are useful with no plugin at all (billing, logs); 3 is the only one carrying an opinion about what to expose. Against: three review cycles.

C. Generic extension bag. extensions: Map<String, Value> on the envelope; plugins request keys via manifest.
For: you never have to bless fields. Against: an untyped map on a typed envelope; every consumer re-implements the schema; you lose the ability to say what the event means. Listed for completeness; not recommended.

Recommendation: B, in order, with one design ask

Do 1 and 2 as plain PRs now — they fix a real gap (host-served exchanges are invisible) and add facts the host already has; both are useful with no plugin at all. Hold 3 for a short exchange on exactly two questions:

• Digest construction: raw bytes as transmitted (our recommendation — simplest, no canonicalization for mesh-llm to maintain) vs. a canonical-JSON digest. A downstream consumer can carry its own separately-labeled canonical digest, so the host choosing raw bytes costs nothing downstream and keeps mesh-llm free of an RFC 8785 dependency.
• Hardware fields: gpu / vram_bytes / is_soc / hostname as the survey reports them, plus a per-field capture_method (this is the fix(system): report the real macOS GPU name (not the CPU brand string) #1625 resolution — provenance of the value, not a different display string). Open question: should hostname default off?

A "looks right / change X" on the shape — especially the digest and hardware questions — is worth more than any merge; it lets 1–3 land as small, uncontroversial PRs. Happy to walk through the record format any time.

[StevenMih]

Implemented the serving-provenance half of this on a branch cut fresh off origin/main — up-serving-provenance, head 76622474adf42996c0459884f903fd1ed4fefd64 (StevenMih/mesh-llm).

Why this is worth landing alongside #1708. The blocker raised on #1708 is that the terminal event carries no served-model identity block at all, so the weights_digest that PR computes has nowhere to ride. This is the other half of that pair: it adds the block. Here is the envelope; there is the field — so "nothing consumes it" becomes in-flight rather than hypothetical.

Objective

A consumer of openai.exchange.v1 can see that an exchange completed but not what served it. The terminal envelope carries exchange_id, model and status; it does not carry the facts a downstream reader needs to tell one serving configuration from another — which node, which quantisation, which context length, which weights.

Why it matters

Two nodes can advertise the same model name and serve materially different things. A node running a reduced KV-cache policy returns a different quality of answer under an identical model reference, and nothing in the current event distinguishes them. Anything reconciling exchanges across nodes — billing, capacity accounting, or a receipts plugin (#1332) — has to guess.

Proposal

Add an optional serving_provenance block to the terminal envelope, populated from facts the host already resolves at serve time: served node id, hostname, GPU and VRAM, quantisation, architecture, native context length, parameter size, layer count, model identity hash, canonical ref, revision. Absent when the host does not know a value — never a fabricated one.

Scope

The host-served path only. No gossip-wire change. No new dependency. Values omitted rather than defaulted. Parent #1233; follows #1331 (lifecycle spec) and #1437 (its implementation).

Acceptance

• Terminal envelope carries the block on the host-served path
• Every field omitted when unresolved; no placeholder values
• Existing consumers unaffected — additive, Option-shaped
• Unit coverage for the populated and the fully-absent case

Verification

ci-local.sh (Linux/Docker) run in full on head 76622474a:

[quality_contracts] actionlint / python_contract_tests / xtask_ci_crate_lists /
                    xtask_publish_crates / release_targets_and_deps / no_console_print  PASS
[rust_fmt]  cargo_fmt_check         PASS
[rust_clippy] cargo_clippy_workspace PASS
[cli_docs_sync] cli_inventory_check  SKIP (no cli-domain file changed)

cargo test -p mesh-llm-host-runtime — 77 passed in the touched modules (plugin::openai_exchange, network::openai::ingress), 0 failed. Each new test was shown red against a reverted implementation, then green restored:

• terminal_carries_serving_provenance_and_omits_unknown_fields — reverting with_serving_provenance to a no-op drops every field to null.
• effective_envelope_has_no_serving_provenance — catches provenance leaking onto the pre-serve event.
• terminal_carries_real_usage_when_attached / terminal_omits_usage_when_none_attached — catches usage failing to attach, and a fabricated all-zero usage record replacing a genuine absence.
• request_body_digest_matches_python_reference / request_body_digest_does_not_normalize_absent_fields — catches float handling and absent-field normalization drifting from the cross-implementation digest contract.
• terminal_carries_request_digest_when_attached / terminal_omits_request_digest_when_none_attached — catches the digest failing to attach, and a fake digest replacing a genuine absence.
• exchange_usage_from_outcome_extracts_real_counts_and_omits_otherwise — catches real usage silently failing to reach the envelope.

Cross-implementation note (found during this cut, not a defect in this branch): request_body_digest deliberately does not apply the profile's absent-field normalize step — the current agent_action_capsule.canonical.json_digest reference reserves normalize for the vintage format-2 Capsule-ID path only (confirmed by running the live Python capsule_sidecar.digest_json reference with and without null-valued optional fields). A separate plugin in our stack still normalizes and thus drifts from the current Python reference; we're tracking that as its own follow-up, out of scope for this change.

Happy to open this as a PR whenever it's useful to review the diff directly — flagging it here first since #1702 is the umbrella and it pairs with #1708.

[i386]

Moved to the 0.77.0 milestone because the protocol work is still incomplete.

Current state:

• spec(openai-frontend): OpenAI exchange lifecycle hooks for out-of-process plugins (#1331) #1437 landed the existing openai.exchange.v1 lifecycle hooks for the typed frontend and raw-proxy plugin-served path.
• feat(mesh): weights_digest — SHA-256 of served GGUF bytes, alongside identity_hash #1708, which adds weights_digest, is still open.
• The raw-proxy host-served path still needs effective/terminal event publication.
• The terminal envelope still needs usage, request/response digests, and the serving-provenance fields described here.
• The digest construction and hardware/hostname exposure choices still need to be resolved before the provenance portion lands.

Maintainer: @StevenMih, based on authorship of the landed #1437 work and the active #1708 follow-up.