Module source 

SecretSource trait + supporting types per ADR-021 §1.

A source is any backend able to answer questions about secrets: the OS keychain, the encrypted local vault from ADR-023, the 1Password CLI, a HashiCorp Vault server, an env-store mount, or a community subprocess plugin. The router (epic phase P5.2 / P5.3) maps an ADR-020 path to a (source, reference) pair and then invokes the source’s SecretSource::get / list / validate through this trait.

Two design choices worth knowing:

1. Sources do not understand ADR-020 paths. They take an opaque reference: &str. Mapping a path to a reference is the router’s job. This separation lets a source plugin be written without any awareness of the manifest layer, which keeps the plugin protocol (P15) tiny.
2. Capabilities are explicit, not inferred. A source whose only operation is READ declares exactly that. The router refuses to call WRITE on it without trying — the failure is structured (SourceError::UnsupportedCapability) rather than a network round-trip that returns “method not allowed”.

What this module does not define

• The router itself (P5.2).
• Any specific source impl (keychain, local-vault, 1password, …) — those land in P6.
• The recursion check that enforces the __sources/<source>/<profile> invariant — that’s P5.5.
• The Capabilities-aware in-memory cache — P5.4.

Structs

Capabilities

What a source can do, plus two descriptive flags consumed by doctor and the agent provisioning surface.

GetOutcome

Successful payload of SecretSource::get.

RemoteRef

One entry returned by SecretSource::list.

Enums

CredentialRef

What a source needs to be operational.

SourceError

All the ways a source operation can fail.

SourceStatus

Snapshot of a source’s connectivity at the moment of the call.

Traits

SecretSource

Backend-agnostic interface for any “place secrets live.”