Context

The Go standard library uses a clear convention for extended and experimental packages:

• golang.org/x/ are stable extensions maintained by the Go team with compatibility guarantees (e.g., x/crypto, x/oauth2, x/net)
• golang.org/x/exp/ are experimental packages with no compatibility guarantees (e.g., x/exp/slices, x/exp/slog before promotion to stdlib)

The Go Driver currently uses x/ to house low-level driver internals (e.g., x/mongo/driver, x/bsonx), treating it as "exported but not stable." This deviates from Go conventions and creates confusion about stability guarantees.

GODRIVER-3684 proposed creating a separate repository for experimental code. However, this adds maintenance overhead and fragments the codebase. A simpler, more Go-idiomatic approach is to restructure x/ in-place:

x/: stable extensions (e.g., AWS auth provider, advanced driver APIs) with semver guarantees
x/exp/: experimental features, candidates for promotion with no semver guaruntees

The AWS credential provider signer added in GODRIVER-3615 is an example of something that should live in a conventional x/ package.

Definition of done

• Create x/exp/ package for experimental code
• Audit current x/ contents and categorize as experimental, extension, or internal-only.
• Migrate experimental code from x/ to x/exp/
• Establish structure for extension modules: x/auth/aws/, x/auth/gcp/, etc.
• Update documentation to explain x/ vs x/exp/ guarantees
• Add package-level doc comments clarifying stability expectations

Pitfalls

1. Breaking changes for existing x/ users
2. Determining what is "stable" vs "experimental", we may have to make this an epic.