Matt Cockayne authored Aug 17, 2026 and Matt Cockayne committed Aug 17, 2026

connection_failure_is_not_cached treated any post-heal error as proof the
failure had been cached. The first real adapter to use it — config-consul —
healed to an empty prefix, whose Load correctly returns fs.ErrNotExist, and the
suite reported 'the failure was cached' about a connection that had plainly
just worked.

fs.ErrNotExist after healing now passes. That is safe rather than lax because
the two cases compose: connection_failure_is_an_error forbids reporting an
unreachable connection with that sentinel, so this case can trust it to mean
connected-but-empty. Both mutants — a backend that remembers its failure, and
one that reports unreachable as absent — still fail.

It matters because a healed fixture serving nothing is far less work than one
seeding data, so most of the remaining adapters will heal to an empty source.
The failure message now also names the fixture mistake it cannot distinguish
from a real one, and a panic in the post-heal Load is caught rather than taking
the suite down.

Thirteen how-to guides gain a 'Getting a client' section listing the rungs that
adapter actually has, with signatures taken from go doc rather than from memory
— the explanation page had drifted from the API in four places because it was
written before the code.

The explanation page is rewritten against the shipped surface, and gains what
only the completed set could show:

  - an ambient rung supplies CREDENTIALS; the target is always explicit, with a
    table of the thirteen sentinels that enforce it
  - the Close obligation follows who built the client AND whether the SDK gives
    anything to release — gRPC clients must be closed, storage.Client need not
    be at exit, azblob.Client has no Close at all, and config-sftp closes its
    subsystem but never the caller's transport
  - the three adapters that stop short, and the different reasons they do

explanation/adapters.md and explanation/dynamic-backends.md record that
injection is now the default rather than the only option.

dynamic-backends.md's Key Vault paragraph is corrected rather than quietly
dropped. It said the release would wait on a real-vault run; it did not, and
the suite's own comment had predicted the consequence. The claims all held when
it finally ran — but the HARNESS failed three ways a fake could not show, which
is the argument for real-service testing in miniature.

how-to/custom-backend.md gains the obligations a self-connecting backend takes
on, and — because this is the mistake that costs a day — how to write the heal
fixture so it changes the world rather than the backend under test.

No broken internal links; docs-claim tests and the full gate pass.