Consumer-usage facts are restated in four places and have already drifted

[turner]

Part of #466. Fell out of the #468 code review.

The same class of fact — which host app reads which member — is now written down in four places, in prose, with nothing keeping them in sync.

Place	What it says
docs/adr/0003-public-api-contract.md	the measured table (dataset | ✔ (3 sites) | ✔), plus a Last measured: line pinning both consumer SHAs
js/publicApi.js	"activeDataset is here because Spacewalk reads it"
js/hicBrowser.js	four accessor JSDoc lines naming files — juicebox/hicMapState.js, juicebox/juiceboxPanel.js (4 sites)
test/testAccessorVocabulary.js	its docstring repeats "Spacewalk, juiceboxPanel.js, four sites"

docs/architecture-review.html is a fifth, though it is a dated snapshot and arguably exempt.

It has already drifted, within a week

#468's spec comment cited Spacewalk's sessionServices.js:158,:229 as the browser.dataset reader. By the time #468 was implemented, aidenlab/spacewalk#84 had landed and moved that read into src/juicebox/hicMapState.js. The decision in the comment was still right; the citation was already wrong, and the review caught it only because someone grepped the sibling checkout by hand.

ADR-0003's Last measured: line pins spacewalk 2776a3a; that repo's HEAD is now 730da58. Same shape as the contactMatrixView.viewportElement miss ADR-0003 already admits to — a hand-built table incomplete within a week.

Why nothing catches it

These facts are about repos juicebox.js does not build or test against, so no check here can fail when they rot.

Note the asymmetry #468 landed with. The rule — nothing internal reads the alias — is enforced automatically and forever by test/testAccessorVocabulary.js. The facts the rule exists to serve are prose in four files, verified only by a human running a grep in two other checkouts.

And precision makes it worse, not better: a file-and-line citation rots the moment the consumer refactors, while the vague "Spacewalk uses this" that would not rot is exactly what fails to stop a future cleanup pass. That tension is the issue. Do not resolve it by deleting the citations — naming the consumer at the accessor is deliberate (#468: "Naming the consumer is the point"), because that is where someone stands when they are about to delete it.

Options, cheapest first

1. One source, pointers elsewhere. ADR-0003's table stays the only place with counts and filenames; the JSDoc and test docstrings say "read by a host — see ADR-0003". Cheap, keeps one thing to update, but weakens the JSDoc exactly where it does its work.
2. Re-measure in the release ceremony. Add "re-measure ADR-0003's table and update the Last measured: line" to the pre-release checklist in Tracking: architecture review candidates (docs/architecture-review.html) #466. Cheap, but it is another manual step, and Refactor: one accessor vocabulary for dataset and state #468 drifted between releases.
3. A script that greps the sibling checkouts. npm run measure-consumers looks for ../spacewalk and ../juicebox-web, greps for every name in BROWSER_SURFACE, and diffs the result against ADR-0003's table. The only option that can actually fail. Skips (does not fail) when the checkouts are absent, so CI is unaffected. Would have caught the sessionServices.js move and the viewportElement omission both.

Not obviously worth doing before the release — but if it is done, 3 is the one with teeth, and 2 is worth doing regardless since it is one line.

Verification

Whichever option: ADR-0003's table, js/publicApi.js, the js/hicBrowser.js accessor JSDoc and test/testAccessorVocabulary.js's docstring must agree with a fresh grep of both consumer checkouts at the time it lands.