Crate verdant_wire 

verdant-server HTTP wire schema.

Four endpoints in M4:

• POST /v1/cache/lookup — return the payload for a (user, key) pair, or a Miss if absent; for shared-promotable keys the lookup may fall through to the _shared namespace and return the payload plus provenance recording the original author.
• POST /v1/cache/persist — write a new payload under (user, key), optionally promoting to _shared. The server admits the promotion on the client’s deterministic-tool claim and records the declared file_roots verbatim; it does not re-hash them at persist time. Soundness is enforced on the read side: every consumer revalidates the recorded roots against its own checkout before trusting the bytes.
• POST /v1/cache/invalidate-upstream — walk the upstream dependency edge and drop every entry whose declared upstreams include the given key, exactly as LiveCache::invalidate_upstream does locally; this is the cross-machine analog so a file edit on Alice’s host invalidates the matching LlmCall entries Bob would otherwise hit.
• GET /v1/cache/stats — per-user usage and global stats so clients can render quota state.

Auth: every request carries Authorization: Bearer <token>; the server resolves the token to a user_id and uses that to scope reads and writes. The wire schema does not carry the user id explicitly because the auth layer is the source of truth.

This module is the wire shape only; transport binding lives in server.rs, storage in storage.rs, auth in auth.rs. Splitting them lets each layer evolve independently and lets tests exercise the shape without touching disk or a socket.

Structs

ErrorBody

ErrorEnvelope

Structured error envelope returned on any non-2xx response. Mirrors the OpenAI error: { message, type } shape so client libraries that already parse that pattern work without modification.

FileRootSpec

One declared file dependency of a cache entry. The path is a workspace-relative path (e.g., src/foo.rs) so the same entry can serve two clients with different absolute checkout layouts. Every consumer joins path against its own workspace base before re-hashing on revalidation; this is the mechanism that catches cross-machine drift where Bob’s tree differs from Alice’s. Legacy absolute paths still revalidate correctly because PathBuf::join with an absolute argument replaces the base, so single-machine deployments continue to work without migration.

InvalidateUpstreamRequest

InvalidateUpstreamResponse

LookupRequest

PersistRequest

Provenance

Provenance for a _shared-namespace entry: who first persisted the bytes, when, and which version of which tool. Carried on every shared-namespace lookup so a paranoid client can decide whether to trust the upstream author.

StatsResponse

Enums

LookupResponse

PersistResponse