0637 — The pool builder is client-package API

Context. [0636] took PostgresDatastore off the user’s path, and the concept left the doc site with it — but the package name did not. NewPostgresPool and PostgresConnectionConfig still lived in pkg/datastore, so the client guide’s pool section named that package twice, and any program using the guided builder imported datastore for a function that never touches a datastore. It builds a *pgxpool.Pool out of five strings; the noun in its name is Postgres, not the datastore. Meanwhile the samples that avoided it reached for pgxpool.New(ctx, os.Getenv("DATABASE_URL")) and imported pgx directly, so a first program imported two packages to get one pool either way.

Decision. NewPostgresPool and PostgresConnectionConfig move to pkg/vulkan (pool.go, postgres_connection_config.go), with the DSN round-trip test. The signature is unchanged — the params still read as the exploded URL, postgres://user:password@host:port/database — and so is the division of labour: the builder assembles and does not dial, NewClient pings [0636]. The doc site leads with it, so the quickstart’s first program imports vulkan and nothing else of ours. pgxpool.New(ctx, dsn) stays documented one paragraph down as the path for a DATABASE_URL deployment and for an application whose pool predates Vulkan; NewClient takes any *pgxpool.Pool, so nothing about that path changed. pkg/datastore keeps PostgresDatastore, PostgresDatastoreConfig, and Querier — the seam every domain imports — and stops being something a user’s import block ever names.

Consequences. 31 of the 77 programs in the repo dropped the datastore import outright, the thirteen playground scenarios among them; the 46 that keep it are labs holding a *PostgresDatastore to drive controllers directly, which is what the package is for. It settles what the ## Package layout kinds left open: an API package may own a constructor for the infrastructure value it hands the user, because the alternative is the user importing infrastructure to reach it. tools/compat follows the move, and a release-era pin at a tag older than this record will name the builder in its old home — expected, and the pin flow’s own problem, not a compatibility gate concern, since nothing about the SQL or schema changed. Rejected: an alias in pkg/vulkan pointing at the datastore’s copy — the ROADMAP already wants aliases gone, and two names for one constructor is the indirection this removes; giving NewPostgresPool a DSN parameter so it could replace pgxpool.New — [0633] rejected a DSN constructor and the reason stands, pgx already parses DSNs and Vulkan refereeing DSN-vs-config conflicts buys nothing.