ci: verify the client's wire shapes against the committed openapi.json

[MattJackson]

The gap

busbar-admin is a hand-rolled mirror of another repo's wire shapes, and nothing checked the mirror.

The spec-drift CI job compares jq -r .info.version openapi.json against the latest busbar release tag. That is a version string. It says nothing about whether src/client.rs still matches the schemas inside the very document sitting in the same commit, and it degrades to a warning when the GitHub API is unreachable. A struct could drift arbitrarily from the committed spec and every gate stayed green.

The gate

tests/openapi_conformance.rs include_str!s the real committed openapi.json (not a copy) and, for every request/response type in src/client.rs, asserts:

• Field set. The Rust WIRE key set (taken from a real serialize) vs the schema's properties. A Rust field with no property fails. A property with no Rust field fails unless it is listed in that case's unmodelled allowlist, and that allowlist is itself checked for staleness in both directions (an entry that is no longer a property, or that the Rust type now carries, fails).
• Optionality, proven behaviourally. A property the schema marks required and non-nullable must reject an explicit null, which is only true if the Rust field is not an Option. A nullable property must accept it, which is only true if it is. The two directions together pin every field.
• Round trip. A schema-shaped value deserializes, re-serializes, and every modelled property keeps its value.
• Endpoint wiring. Every path the client calls exists in paths with that method, and its 2xx response still points at the schema the client's method decodes into.
• Enum vocabulary. The error code enum is the only closed enum on any shape this client touches; the client models it as a String, so the set is pinned here and every member is decoded.
• The untyped seam. POST /config/apply has no Rust type (the CLI passes the file through as a serde_json::Value), so its required config key and its refusal of unknown top-level keys are pinned directly against the spec. Nothing else in the crate would notice a change.

Red before green

Each check class was proven to be a real gate, then restored.

1. Rename a Rust field (PluginInstallView.publisher -> publisher_name):

---- plugin_install_view_matches_schema stdout ----
PluginInstallView: Rust field(s) ["publisher_name"] have no property in the committed
openapi.json schema (renamed field, or a field the spec never had)

2. Flip a schema-required field to Option (HookView.on_error: String -> Option<String>):

---- hook_view_matches_schema stdout ----
HookView.on_error: the schema marks this property REQUIRED and non-nullable, but the Rust
type accepted an explicit null, which means the field is an Option (or otherwise nullable).
A required non-nullable property must be a plain field

3. Add a property to the schema (RevokeView.revocation_reason added to openapi.json):

---- revoke_view_matches_schema stdout ----
RevokeView: schema propert(ies) ["revocation_reason"] have no Rust field. The client reads
this response, so either model them or add them to this case's `unmodelled` list with a reason

Drift the mapping surfaced

Every type mapped cleanly to a components.schemas entry. Three types read fewer properties than the schema carries; each is now recorded as an unmodelled entry with a reason rather than silently tolerated, so it is a deliberate, reviewed omission:

Type	Schema	Not modelled
PluginView	PluginView	target, interface_version, schema_url, schema_error
PluginInstallView	PluginInstallView	interface_version
HookView	HookView	settings_keys

GET /config (EffectiveConfigView) and the POST /config/apply request body have no Rust type by design; both are still checked at the endpoint/body level.

Supporting changes

• Add a lib target (src/lib.rs). A [[bin]]-only crate cannot be imported by an integration test, which is why these shapes could previously only be tested from an inline #[cfg(test)] module.
• Move the two inline #[cfg(test)] modules into tests/wire_shapes.rs and tests/cli_args.rs, per the convention that tests live in their own file. The pure CLI mappings they cover move to src/argmap.rs so the tests call the same functions main.rs does.
• Publish ErrorEnvelope/ErrorDetail so the error envelope is checked like every other shape.
• README: correct the stated spec version to 1.5.3 (matches openapi.json) and describe the new gate.

.github/workflows/ci.yml already ran cargo test --locked --verbose, so the suite is gated on every push and PR; the job comments now say which check answers which question.

Local run: cargo fmt --check, cargo clippy --all-targets -- -D warnings, and cargo test --locked (36 tests) all pass.

[MattJackson]

Landed on main as a --no-ff merge commit (30d8eeb) rather than through the button, so GitHub did not auto-close this. Every commit on ci/openapi-shape-tests is now an ancestor of origin/main; CI on main is green (run 31568430064: build, integration, spec-mirror, spec-drift all pass).