Module capability 

Backend capability enforcement: does each backend provide what the catalog requires?

Two declarations, two roles:

• Provides: BackendRef::engines + BackendRef::capabilities + BackendRef::mint_key_types: what the server instance supports. In nix this comes from a version preset (VAULT_2_0, OPENBAO_2_5); a hand-written catalog supplies the same JSON (so a non-nix adapter works too). It is the version→capability table, in config rather than hardcoded in the binary.
• Requires: what this deployment needs. Mostly derived (and so it can’t drift): each key’s effective Engine and its KeyAlgorithm’s required_capability. For the few non-key-derivable needs there is the explicit BackendRef::requires list, unioned with the derived set.

Enforcement is required ⊆ provided. It is a pure catalog check: no backend I/O and no extra Vault privilege, so it runs both at startup and in the offline check lint, and needs no reachable server. The live cross-check against a server’s real version is a separate (future) concern.

Policy

CapabilityPolicy is the operator’s stance, a ceiling over each key’s MissingPolicy:

• strict (default, secure): any unmet requirement aborts startup; every gap is reported together.
• degraded, which defers to per-key missing: a gap on a missing="error" key is still fatal; on any other key it is logged and the broker serves the rest (the runtime Unsupported backstop catches the op if it is ever made).
• off skips the check entirely.

Undeclared backends

A backend that declares no provides (engines, capabilities, and mint_key_types all empty) is capability-unknown: the check is skipped with a warning, even under strict. The agent can’t manufacture the data, and failing closed on absence would punish every minimal catalog. Real enforcement is opt-in by declaring the provides set (which the nix presets make trivial).

Structs

CapabilityError

A fatal capability-enforcement failure (fail closed). Carries every gap, not just the first, so one startup attempt surfaces all the misfits.

CapabilityGap

One unmet capability requirement, for a single key, or (when key is None) a backend-level explicit requires entry.

CapabilitySummary

Summary of a non-fatal capability pass, for the startup log.

Enums

CapabilityPolicy

How startup handles a backend that cannot satisfy a required capability.

Functions

enforce_capabilities

Validate every backend’s declared provides against what its keys (and its explicit requires) need, applying policy.