toolplane: one tool for the reads, so asking a new question is not a release

[traviswu-bigstack]

What

The three hand-written cube-cos-api reads become keys of one tool, cube_cos_read, over a catalogue of 21 paths. New Tool.Catalog field, CubeCOSReads and cubeCOSReadsHeldBack as data, and the vendored operation list gains methods so a read can be checked as a read.

Why

Nine tools against an API that declares 102 paths made every "can you also check X" a new allowlist entry, a build and a deploy. That is a release cycle, not a security property. The property is that a caller cannot express a request the allowlist does not contain — and a finite set of twenty-one reads has it exactly as a finite set of three does.

A key is a map lookup, which is the finite-value-set rule Params already applies, in its strongest form: no grammar to get wrong, and nothing outside the set to reject because a value outside the set is not a key. The method is GET structurally, as Get is. Query parameters are not expressible, so watch=true and the event stream behind it are unreachable by construction rather than by exclusion.

Reviewer notes

One tool, not twenty-one. Twenty-one names and descriptions would sit in front of the model every turn for reads differing only in which noun they return, and a tool spec is part of the SaaS's prompt stamp — so a tool per path would move that stamp every time the catalogue grew. One tool with a key set costs one name and one enum.

⚠️ This moves the prompt stamp (the tool set changed). Both baseline arms are already non-comparable since slice 3 added a fifth stamp; the re-record is batched and nothing here touches evals/baseline.json.

Admission is opt-in, and visibility is enforced. A path is reachable because it is in CubeCOSReads, not because the API serves it — an exclusion list would make the next sensitive endpoint upstream reachable the day it shipped. Held back: settings and the delivery settings under it (SMTP credentials, webhook URLs), integrations/* (storage-vendor logins), licenses, me, notifications, supportFiles (unbounded — a 32 KiB slice of an archive is not a read), grafana/* (payloads that may embed a token), and the two .csv duplicates.

Opt-in alone would leave a read the API gains tomorrow silently unreachable, so the held-back set is data and TestEverySimpleGetIsAdmittedOrHeldBack requires the two sets to cover every zero-parameter GET. A new upstream read fails a test naming it.

How a reviewer sees the whole surface: two maps in allowlist.go, one admitted with its paths and one held back with its reasons, and a test that they are exhaustive and disjoint.

Testdata now records METHOD PATH. A path-only list could not tell a read from a write sharing a URL, which is exactly what a catalogue claiming to reach only reads needs checked.

One fetch, not two. Both read forms end in fetch, so the result cap, the truncation marker and the audit record are written once — a second copy is a second place for the marker to go missing, and tool-0010 measures whether the model reports a cut it was told about.

Reads are served at every level, observe included. This widens observe clusters; reading is what observe is for, and TestTheCatalogueIsServedAtObserve pins it.

Deletion hole: unchanged in kind, wider in scope — a path dropped upstream still passes against the snapshot, now across 21 paths rather than 3. The failure is a 404 at runtime, not an unintended reach.

Breaks proved, each watched to fail a named test and restored: the catalogue key check short-circuited (TestAKeyOutsideTheCatalogueIsRefused), and the unfilled-placeholder validation disabled (TestACatalogueEntryMustBeAWellFormedRead/unfilled_placeholder).

go test ./... green, gofmt/go vet clean.

Docs

bigstack-handbook#612 — as-built in read-only-plane-end-to-end.md.