Name the switch, and use it from every worktree

The switch lived in the checkout as ./_opam, which a worktree outside
the checkout cannot see, so the Makefile found it through git. It is
now opam's own, hypha-postgres-eio, which the checkout and every worktree reach
by name; make setup creates it empty, so opam takes the compiler from
the declared bounds rather than a version written here.

Author: zaiev

.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
         with:
           ocaml-compiler: ${{ matrix.ocaml }}
       - run: opam install . --deps-only --with-test --with-dev-setup -y
-      # Use setup-ocaml's switch instead of the Makefile's local one.
+      # Use setup-ocaml's switch instead of the Makefile's.
       - run: make lint OPAM="opam exec --"
       - run: make test OPAM="opam exec --"
 

.gitignore

@@ -1,3 +1,2 @@
 _build/
-_opam
 .DS_Store

AGENTS.md

@@ -6,7 +6,7 @@ for anyone changing it, human or agent. Users start at [README.md](README.md).
 ## Commands
 
 ```sh
-make setup   # once: local opam switch in ./_opam, all dependencies
+make setup   # once: the switch hypha-postgres-eio, all dependencies
 make test    # starts the test Postgres in Docker, runs every test
 make lint    # formatting, odoc, and the release build
 make fmt     # format in place

Makefile

@@ -1,8 +1,5 @@
-# The opam switch is the checkout's (./_opam), so OCaml commands go through
-# opam exec. A worktree lives outside its checkout and uses its switch,
-# found through git.
-CHECKOUT := $(patsubst %/.git,%,$(shell git rev-parse --path-format=absolute --git-common-dir))
-OPAM = opam exec --switch=$(CHECKOUT) --
+SWITCH ?= hypha-postgres-eio
+OPAM = opam exec --switch=$(SWITCH) --
 
 PG_TEST_PORT ?= 5435
 PG_TEST_URL  ?= postgres://postgres_eio:postgres_eio@localhost:$(PG_TEST_PORT)/postgres_eio
@@ -15,10 +12,10 @@ help: ## list targets
 	@grep -hE '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
 	  | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-10s %s\n", $$1, $$2}'
 
-setup: ## create the local switch and install dependencies
+setup: ## create the switch and install dependencies
 	@docker compose version >/dev/null 2>&1 || echo "The tests need docker compose."
-	@[ -d $(CHECKOUT)/_opam ] || opam switch create $(CHECKOUT) 5.5.1 --no-install -y
-	opam install . --switch=$(CHECKOUT) --deps-only --with-test --with-dev-setup -y
+	@opam switch list --short | grep -qx $(SWITCH) || opam switch create $(SWITCH) --empty -y
+	opam install . --switch=$(SWITCH) --deps-only --with-test --with-dev-setup -y
 
 build: ## build everything
 	$(OPAM) dune build @all

OCAML.md

@@ -170,9 +170,9 @@ the next where they expect it.
   writes the opam files from it. A Hypha library another depends on is
   pinned in the `*.opam.template`'s `pin-depends`, at a release's tag on
   GitHub, until the libraries are in opam-repository and the pins go.
-  `make setup` makes the checkout's switch, `./_opam`, and installs into
+  `make setup` makes the repository's switch, empty, and installs into
   it with `opam install . --deps-only`, which resolves everything, the
-  pins included; a new release is taken by moving its tag and the bound
+  compiler and the pins included; a new release is taken by moving its tag and the bound
   and running `make setup` again. An application commits its solution as
   an opam lock (`make lock` after an upgrade); a library commits none,
   its users solving their own. Why: it is how the libraries' users get
@@ -360,14 +360,15 @@ language server (the `LSP` tool) or, without one, Merlin's command line;
 every user of an export is found this way, since a shadowed, re-exported
 or aliased name defeats a text search.
 
-Nothing is on PATH. Every OCaml tool runs through the checkout's local
-switch, `./_opam`, as `opam exec --switch=<checkout> --` or through the
-Makefile; no `eval`. A worktree has no switch of its own: it uses its
-checkout's, the directory `git rev-parse --git-common-dir` is in, as the
-Makefile and the language server find it. `make setup` installs Merlin
-and `ocaml-lsp-server` with the rest.
+Nothing is on PATH. Every OCaml tool runs through the repository's opam
+switch, named `hypha-<name>` after the `(name)` its `dune-project`
+declares, as `opam exec --switch=hypha-<name> --` or through the
+Makefile, whose `SWITCH` names it; no `eval`. The checkout and every
+worktree of it use that one switch, by its name, so a worktree needs no
+setup of its own. `make setup` installs Merlin and `ocaml-lsp-server` with
+the rest.
 
-**`ocamllsp` runs as the agent's language server**, from the checkout's
+**`ocamllsp` runs as the agent's language server**, from the repository's
 switch. It answers every edit to OCaml source with its type errors,
 and gives a name's definition, its references, tests included, its type
 and a file's symbols; ask for the symbols before reading a long file
@@ -385,9 +386,10 @@ project`, `locate -position LINE:COL`, `type-enclosing -position LINE:COL`,
 a use**, never from its declaration in the `.mli`, which answers with that
 declaration alone; a value asked from its `.mli` finds every use.
 
-**A dependency's API is read where it is installed**, from its `.mli`
-under `_opam/lib/<package>/` or the server's hover, never from memory: the
-version in the switch is the one the code builds against.
+**A dependency's API is read where it is installed**, from its `.mli` in
+the switch (`opam var --switch=hypha-<name> lib`, then `<package>/`) or the
+server's hover, never from memory: the version in the switch is the one
+the code builds against.
 
 **The stdlib is 5.5's, and nothing newer.** A function whose odoc says
 `@since` a later version is not used until every `dune-project` asks for
@@ -396,7 +398,7 @@ that version.
 **A generated file is changed at its source.** An `*.opam` file is written
 by dune from `dune-project`, and from an `*.opam.template` beside it for
 what dune cannot say, so either of those is edited, never the `.opam`.
-Nothing under `_build/` or `_opam/` is edited; a test's new expected
+Nothing under `_build/` or in the switch is edited; a test's new expected
 output is taken with `dune promote`.
 
 **A worktree is outside the checkout** (`GIT.md`), so dune takes it as
@@ -407,9 +409,8 @@ missed when the whole project is read.
 
 **Search text with `rg`, always with a path**, never `grep -r` or `find`:
 with no path `rg` reads standard input, which an agent's shell never
-closes, and `_build/` and `_opam/` are gitignored, so `rg` skips them
-where `find . -name '*.ml'` returns every copy of the source under
-`_build/` and every package under `_opam/`.
+closes, and `_build/` is gitignored, so `rg` skips it where `find . -name
+'*.ml'` returns every copy of the source under `_build/`.
 
 `opam list --installed` says what the switch holds; `opam list
 --required-by --recursive` resolves against what is available, not what is