chore(openspec): archive the last two changes, plus pymmseqs and Colab fixes

[tsenoner]

OpenSpec housekeeping plus two small apps/protspace fixes that came out of it. Reconciles and archives the last two OpenSpec changes. Both shipped months ago and were left part-ticked, so openspec/specs/ had no record of guarantees the code has been enforcing since June.

Follow-up to #444, which archived the four changes that needed no judgement. These two did. After this, openspec/changes/ holds no active change for the first time in months.

1. merge-protspace-monorepo (was 16/30)

Two problems, either of which would have made a plain archive worse than leaving it alone:

Its delta would have created a competing capability. It declares bundle-contract; bundle-format-contract already exists, created a month later by add-bundle-contract-test. Two specs on one subject, nothing saying which is authoritative.

Its phase 5 was reversed, not skipped. The shipped design deliberately contradicts it:

	This change's plan	What shipped (bundle-format-contract)
Fixtures	"SHALL commit golden fixtures"	"SHALL NOT read any .parquetbundle checked into the repository"
CI trigger	wire into the path-filtered CI	"without a hand-maintained path filter — a filter is a copy of an import graph, and when it is wrong the job does not fail, it silently does not run"
Bundle shapes	3- and 4-part, no mention of statistics	3, 4 and 5-part, plus the zero-byte settings sentinel

So the section is marked superseded with both reversals recorded, rather than ticked. Every other open task was already done or moot: the freeze was never needed (1.4's deterministic re-sync handled it), #295 is closed, both publish paths have since run for real (4.11.1 to PyPI; the prep image on every PR), and tsenoner/protspace-legacy is archived: true with its last stale links repointed in #391.

schema.json is dropped by decision. With one producer and one consumer, both in-repo and both covered by a CI job that cannot be silently skipped, a declarative schema would be a third copy of the format to keep in step rather than a guarantee.

One requirement was alive and hiding. The delta's fourth requirement has nothing to do with bundles: prep must consume protspace from workspace source so a break surfaces in the same change, not after a release. It is already true — protspace = { workspace = true } — and was only "unfinished" because it names services/protspace-prep, the path the restructure itself renamed to apps/prep. It lands as prep-source-coupling.

2. unified-visibility-model (was 20/22)

No design call needed here — point-visibility collides with nothing, and every requirement in it is already pinned: the spec's eleven rules map one-to-one onto eleven describe blocks in visibility-model.test.ts (35 tests, 95 opacity assertions).

Both open boxes were manual checks, which leave no artifact. Rather than tick them because the code shipped nine weeks ago, each was re-checked against what is now automated:

• 5.2 (no full re-sort on legend toggle) — superseded by automation. The invalidation contract is pinned by scatter-plot.lifecycle.test.ts and webgl-renderer.signature.test.ts, a stronger guarantee than the one-off manual observation the task asked for.
• 5.3 (UX parity sweep) — mostly automated since: clickability is unit rule 11, zero-opacity is rule 1, isolate/reset are covered by three e2e specs.

3. pymmseqs floor raised to 1.2.0

pymmseqs 1.2.0 (published 2026-08-11, after #391 merged) fixes both reasons that dependency was moved into the similarity extra. Every release through 1.1.0 shipped cp310-only wheels, so against requires-python = ">=3.12" it compiled from sdist for every user on every platform; and it pinned ipython<9, which upgraded Colab's pinned ipython and produced the dependency-conflict wall in the notebook. 1.2.0 ships six py3-none-* wheels (macOS x86_64/arm64, manylinux and musllinux x86_64/aarch64) and drops both ipython and scikit-learn, leaving numpy/pandas/pyyaml — all already core.

The old floor was >=1.0.4, so a fresh install already resolved 1.2.0 and already got wheels. Raising the floor makes that a guarantee rather than an accident: a constrained or older resolver can no longer land on a cp310-only release and silently go back to compiling from source. The lock moves 1.1.0 → 1.2.0 so dev and CI match what users get.

It stays an extra. Both original arguments are gone, but it is reachable through exactly one flag and a smaller base install stands on its own. CLAUDE.md records that upstream fixed both problems and why the extra remains, so its rationale does not quietly become another stale claim.

The published upgrade note did need a correction, though — see §5.

Verified against the artifact rather than the metadata: installed 1.2.0 as a wheel and ran compute_similarity end to end on a 5-sequence FASTA — three single-residue variants score 0.974–0.987 mutually and 0.0 against two unrelated sequences, diagonal 1.0. The full 3.12/3.13/3.14 CI matrix is the real proof the py3-none wheels install everywhere supported.

4. esm2_3b is gated on what the runtime can actually hold

Closes #448. Closes #449.

esm2_3b failed partway through a Colab run that had already paid for setup and input handling, and the panel only warned, which does not stop the selection. The notebook already had the mechanism pointing the other way — _drop_incompatible drops esmc_* on Biocentral, whose ESM-C returns embeddings orthogonal to the real model — so both constraints now read from one table that drives the checkbox gating and the drop-at-Generate backstop. Previously those were separate code paths and had already diverged: the first knew one rule, the second knew both.

The gate keys on host memory, not on the model name. The first cut blocked esm2_3b on every Colab tier, including the paid L4/A100 runtimes where it fits — a capability that worked before this PR. It is now conditional:

Runtime	Host RAM	esm2_3b
Free	12.7 GB	blocked
High-RAM / L4 / A100	51–83 GB	available
Probe unavailable	—	blocked

Host memory rather than VRAM because that is what actually decides. setup_model passes no dtype for ESM, so esm2_3b loads fp32 — 11.4 GB of weights, materialized on the host by from_pretrained before model.to(device). Against the free tier's 12.7 GB that is the binding constraint, and it is the worst failure available: a host-RAM blowout kills the kernel with no traceback, taking the fetched sequences with it, and setup_model sits outside the OutOfMemoryError backoff that only wraps _embed_batch. Running out of VRAM merely raises. A VRAM probe would also change no outcome on any current tier while building a CUDA context to do it.

The set stays identity-keyed rather than computed: esm2_3b is 10.59 GiB of weights, the runner-up (ankh_large, encoder-only) is 4.29 GiB, and nothing sits between them — so there is no boundary to tune, and a per-model GB column would rot silently across a transformers bump.

The remedy no longer names a service that may be down. prep-failure-routing guarantees a Biocentral outage routes users into this notebook, where auto resolves to local on a GPU runtime — and the panel answered by telling them to use Biocentral. The table's third field now carries a whole remedy instead of a backend name.

The same flow strands users more broadly, which is #449: a Colab runtime is CPU-only until a GPU is attached, so auto falls back to the very service that just failed, silently. The panel now discloses that fallback and names the fix, and the same hint joins the generation-failure troubleshooting list.

Still scoped to the notebook deliberately: these are limits of a hosted environment, not of the package. protspace prepare --backend local -e esm2_3b stays correct on real hardware, and the CLI enforces neither rule.

5. Corrections found while reviewing the above

Three defects in this PR's own earlier commits, plus one stale published claim:

• The notebook would have died for every user. Cell 1 imported COLAB_OVERSIZED, a name added in the same commit — but cell 1 pip-installs the released protspace while the notebook is served from main, and 4.11.1 does not have it (verified against the actual wheel). Its ImportError handler raises SystemExit telling the user to restart the session. Both blocked sets now import behind a tolerant fallback, so main and PyPI are allowed to be out of step.
• _ESMC was a bare notebook literal that nothing pinned. It moves to biocentral.py as BIOCENTRAL_INVALID, beside COLAB_OVERSIZED in local.py, and a test asserts each resolves to a real shortcut — a typo in either would have silently gated nothing. Each set is pinned to the registry it actually constrains (COLAB_OVERSIZED→LOCAL_CHECKPOINTS, BIOCENTRAL_INVALID→ALL_SHORT_KEYS); they coincide today, so pinning both to Biocentral's would have made the first local-only oversized checkpoint fail a test whose message is about Biocentral shortcuts.
• The blocked-reason named the wrong resource ("a Colab GPU", "~15 GB VRAM"). Corrected in the notebook, the package warning, and the comments.
• The published similarity note was stale. It told -s users the base install "no longer compiles MMseqs2 from source". Scoped to the base install that stayed literally true, but after 1.2.0 the extra does not compile either — so an upgrade note telling people to install that extra warned about a cost that no longer exists on the path it recommends. Both synced copies (README.md, docs/guide/python-cli.md) move together; the sync test compares them line-for-line.
  The replacement needed a hedge of its own: 1.2.0 publishes six py3-none wheels and no win_amd64, so a flat "installs from a prebuilt wheel" is false on Windows, where pip still builds the sdist. Qualified to macOS and Linux.

6. embedding-backend-selection capability

Closes #450.

The local backend shipped through #320 with no OpenSpec change, so nothing in openspec/specs/ described it — grepping the corpus for esm / embedder / colab hits only prep-failure-routing's Colab-routing copy. That is why §4's two rules lived as literals in one notebook cell and drifted.

Authored spec-first per AGENTS.md and through the real workflow rather than hand-adding a file (all 19 existing specs were written by a commit that also archived a change): openspec new change → proposal/design/tasks/delta → validate --strict --type change → archive, as the last commit on the branch.

Six requirements: auto resolution and its failure modes, the fallback disclosure, gating-plus-backstop from one declaration with rejection before expensive input acquisition, the two compatibility rules, the capacity condition on the size rule, and the deliberate CLI non-enforcement.

Gaps carried forward, not closed

• Bundle contract: the TS-write → Python-read seam is untested #445 — the TS-write → Python-read bundle seam is untested. Task 5.6 asked whether a web-export → CLI round-trip exists and to add the test only if so. It does: the TS side writes .parquetbundle and protspace transfer -b / style read one, but the contract only covers the other direction.
• Visibility parity: axes re-fit and PNG export have no regression coverage #447 — axes re-fit and PNG export have no regression coverage. The only axes match under apps/web/tests is an unrelated PNG-chunk comment, and figure-editor.spec.ts never mentions hidden state.

Not closed here, and deliberately: loading ESM/ESM-C in fp16 on GPU would halve esm2_3b to 5.29 GiB and let §4's size rule be deleted rather than conditioned. It changes numerics for every esm2_* and esmc_* key, so it needs the local↔Biocentral parity cross-check re-run and CLAUDE.md updated — and esm2_3b was never in that cross-check. Recorded in #448.

7. Cleanup pass over §4's gating

A review of the above found the gating correct but doubled, and the pin protecting it
weaker than advertised.

The duplication. The select/resolve/drop/bail block was written out in both the
query and fasta branches of _on_gen, and only the query copy was moved ahead of the
UniProt fetch. Extracted as _embedders_and_backend(), so the "reject before paying for
input" ordering is structural rather than a comment, and there is one copy to edit.

Alongside it: _INCOMPATIBLE's values drop from a 3-tuple to a 2-tuple (why and
remedy were stored apart but re-joined with the same "; " at both call sites);
_host_ram_gb() becomes _ram_below_gb(gb), returning the boolean actually wanted
instead of a float plus a magic 0.0 "unreadable" sentinel; the two red-<span>
branches append plain text to one list wrapped once; and _INCOMPATIBLE[eff] becomes
.get(...), since an unknown backend blocked nothing anyway but used to raise
KeyError at panel-build time and take the whole control panel down with it.

The pin had the failure mode it existed to prevent. The new notebook-fallback guard
asserted only inside a loop over whatever its matcher found, so when the matcher found
nothing it passed green. Three natural edits silently disarmed it: writing the emptied
fallback as frozenset() (zero args), using the package's own annotated-assignment
style, or deleting the fallback outright. It also called raw ast.parse on cell source
— in the one test module whose entire reason for existing is that notebook cells are not
plain Python, and ProtSpace_Transfer.ipynb already has a !protspace transfer cell
that raw parse cannot read.

Rebuilt to key off the try/except structure rather than scanning for assignments, so
a missing fallback is a failure instead of an empty result, and to parse
IPython-transformed source. Mutation-tested, notebook restored byte-identically after
each:

Mutation	Before	After
stale non-empty literal	caught	caught
emptied via frozenset()	passed	caught
annotated (package style), wrong	passed	caught
bare set literal, wrong	passed	caught
fallback deleted outright	passed	caught
correct, written differently	passed	passed

local.py's warning generalised to %s but still hardcoded esm2_3b's ~11.4 GB, so a
second name in COLAB_OVERSIZED would have emitted a wrong figure; dropped. Behaviour is
otherwise preserved — the KeyError hardening is the one intentional change — verified by
executing the rewritten gating against stub widgets across auto/local/biocentral/unknown.

Bookkeeping fixes found reviewing the archive. #66/#55/#60 in the monorepo
change's reconciled tasks are protspace-legacy PRs, but bare #N autolinks against
this repo — and #66 is the silent case, resolving to a merged, unrelated frontend PR
("enhance StructureService with 3D Beacons API integration") instead of 404ing, so the
link renders fine and points somewhere wrong. Qualified; #306/#295/#233/#445 are
genuine refs here and stay bare. design.md still described _INCOMPATIBLE as
(blocked set, why, remedy) because the archive commit predates the refactor above. And a
5.3 checkbox was ticked while its own text read "carried forward to #447 rather than
ticked" — reworded so the box and the sentence agree.

Notes

proposal.md and design.md keep the superseded plan as history with the supersession marked at the top of each affected section — archiving freezes them, and an unmarked stale rationale reads as intent.

All three new capabilities got a real ## Purpose. openspec archive writes a TBD - update Purpose after archive placeholder that passes validate --strict, so it survives unless somebody looks — which is how two from an earlier archive sat there until #444.

Verification

openspec validate --all --strict → 20 passed, 0 failed, re-run after precommit's prettier pass (it rewraps markdown, and --strict only scans a requirement's first line for the normative clause). openspec list → no active changes. pnpm precommit green on every commit. uv run pytest -m "not slow" → 825 passed.

The gating was exercised across the full matrix — released-lag × capacity × both backends — and renders identically whether or not the installed package carries the new constants.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ar6ME3o6VYLYsie3J4kxE5