buzz/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/README.md

# Provider wire fixtures

The shared arbiter for the stdin/stdout contract between the desktop
(`agents_deploy.rs`) and this provider (spec §Provider Protocol).

Each `*.request.json` is a request the desktop can emit; each matching
`*.response.json` is the exact response this provider produces for it. The
provider side is asserted by `tests/wire_fixtures.rs`; the desktop side should
assert that its emitted payloads parse as the corresponding request.

Three rules keep these useful rather than decorative:

* **Requests are recorded, not invented.** A fixture that no caller emits
  tests a contract nobody has. "Recorded" means *executed and transcribed* —
  `deploy-full-launch.request.json` is the output of the desktop's real
  `build_launch_block` → `deploy_payload_json` path, not a shape derived by
  reading those functions. Deriving it is how this fixture acquired four
  impossible values at once: a `respond_to` that was a pubkey where the
  desktop serializes a kebab-case `RespondTo` enum, allowlist and owner
  values failing `validate_respond_to_allowlist`'s 64-hex rule
  (`types.rs:897`), an invented `BUZZ_ACP_PARALLELISM` where the emitter
  writes `BUZZ_ACP_AGENTS` (`runtime.rs:729`), and a `launch.env` key from
  no layer of `resolve_effective_harness_descriptor`.
* **The provider cannot police this file, so the desktop must.** Every field
  above is one this provider is deliberately indifferent to — `respond_to` is
  an opaque `Option<String>`, the allowlist an opaque `Vec<String>`,
  `policy_env` an arbitrary map — so `the_full_desktop_payload_is_accepted`
  passes on invented data exactly as happily as on recorded data. The
  enforcement is the desktop's whole-object equality test, which *builds* the
  payload and compares it to this file. A completeness guard (the case-list
  directory scan in `wire_fixtures.rs`) stops a case from going missing; it
  cannot tell you a case is false.
* **Responses are byte-compared after key-sorted re-serialization**, so a
  field rename or a type change fails here rather than in a desktop that
  silently reads `undefined`.

`deploy-*` fixtures cover only responses reachable without a cluster —
refusals and malformed input. A successful deploy needs an apiserver and is
covered by the conformance suite, not by a static fixture.