verdant-cache-wire 0.4.0

Shared HTTP wire schema for the verdant cache server and RemoteStore client
Documentation

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.