fix(embed): one completeness contract for both backends, and a FASTA coverage check

[tsenoner]

Stacked on #430 — base is fix/embed-silent-partial-failure, so merge #430 first. Do not squash (apps/protspace/ is touched).

Why

#430 made the Biocentral backend fail on an incomplete embedding. The local backend still did not: it dropped every sequence over max_length (2000 aa, not exposed on the CLI) and every sequence that OOMed at batch size 1, logged a warning, and exited 0 as long as one embedding landed. resolve_default_backend() returns "local" on any Colab GPU runtime — so the unguarded backend was the default for exactly the audience BIOCENTRAL_UNAVAILABLE routes to Colab.

The divergence was accretion, not design. The tell is local.py's import line:

from protspace.data.embedding.biocentral import load_existing_ids, save_embeddings

One backend importing its HDF5 layer from its sibling backend means a shared layer already existed — it just had no home, so the parts that were not shared drifted.

The contract

expected = requested − skipped, in a new data/embedding/store.py owned by neither backend.

	before	after
/ in an identifier	local rejected up front; Biocentral had no guard	shared validate_headers, both backends, before any work
> max_length	local: warn, exit 0	skipped — named with its reason, exit 0
OOM at batch size 1	local: warn, exit 0, bar advances	skipped — named (previously existed only as a log line)
anything else missing	local: undetected	fails
everything skipped	local: exit 0 if the file was non-empty from a prior run	fails — nothing usable was produced
empty request	—	succeeds: resume already covered it

Skips go to stderr at warning level (the hosted prep service discards stdout and passes no -v); the counts go to the end-of-run line; a clean run stays quiet. Every new message avoids all eight _BIOCENTRAL_DOWN_PATTERNS substrings, so a coverage problem can never be re-tagged as a service outage and routed to Colab, which would not fix it.

Done. Embedded 1 sequence(s), skipped 1.
WARNING  Skipped 1 sequence(s) — GPU OOM at batch size 1: hungry
Embedding:  50%|█████     | 1/2          ← the bar counts what was written

--max-length is now exposed on embed and prepare, and rejected for --backend biocentral (no length cap — silently ignoring it would let a user believe they had raised a limit that does not exist). Without a lever, "skipped 3 sequences" is a dead end.

The FASTA check is not cosmetic

Nothing anywhere compared an embedding set to the FASTA it came from. compute_similarity zero-fills the row for a protein it cannot find, leaving its self-similarity at 0, and base_processor only converts similarity → distance when np.allclose(np.diag(data), 1). One uncovered protein makes that false for the whole matrix, so MDS consumes raw similarities as distances:

all covered      -> converted;      d(A,B)=0.224  d(A,C)=0.949   A,B closest
one uncovered    -> NOT converted;  d(A,B)=0.950  d(A,C)=0.000   A,B furthest

Near-identical proteins placed furthest apart, silently, for every pair.

The check is directional. h5 − fasta is the damaging direction and the only one reported; fasta − h5 is routine, because a resumed embedding cache legitimately covers fewer proteins than the FASTA it was built from. Uncovered proteins fail under -s/--similarity and warn otherwise — failing outright would break deliberately projecting a subset, warning alone would let the inverted bundle ship. Both sides go through parse_identifier, since load_h5 keeps raw HDF5 keys while FASTA ids are always parsed. Placed before compute_similarity in both prepare and project; project had the same exposure and no plumbing for it.

Verification

• 880 passed, 2 skipped; -m "not slow": 876 passed. +24 tests.
• ruff check + ruff format --check clean over src/ packages/ tests/.
• End-to-end through the real CLI with a stubbed API, and in a real subprocess with stdout=DEVNULL, stderr=PIPE exactly as apps/prep/_run_step invokes it — exit 1 and the message lands on stderr where the service captures it.
• Resume still converges: 8 → 14 → 20 keys, exit 1 → 1 → 0, model_name stamped only on the successful run.

Scope

OpenSpec change embed-completeness-contract (proposal, design, spec deltas, 29 tasks), archived on this branch per AGENTS.md so openspec/specs/ is true at merge.

Deliberately not fixed here, filed instead:

• MDS: similarity-to-distance conversion is inferred from the diagonal, so one bad row inverts the whole projection #471 — the np.allclose(np.diag(data), 1) heuristic itself. This PR stops a partially-covered FASTA reaching it; it does not make it robust.
• Two disagreeing views of an .h5's identifiers: resume re-embeds and silently swaps grouped datasets #472 — load_existing_ids (flat) disagrees with the loader's grouped view: a grouped third-party .h5 re-embeds everything and silently swaps stale for fresh.
• protspace embed and protspace prepare write different .h5 keys for the same FASTA #473 — embed writes raw sp|… keys where prepare writes parsed accessions.

Two gaps in the -f wiring, now closed

Both sat upstream of the coverage check and let -f do nothing without saying so.

fasta_path was attached only in the single-file branch, so -i dir/ -f x.fasta dropped the FASTA on the floor. Coverage was still checked — that keys off the option, not the set — but _extract_sequences found nothing and the bundle shipped without sequences. Both branches now build the set and share one attach.

Neither -f had exists=True, so a typo was swallowed by the .exists() guard in _extract_sequences. On project that was total silence: without -s the FASTA is never read, so a typo'd path exited 0 having quietly done nothing with it. Now a usage error (exit 2) on both commands, which is what the added tests pin — exit codes, not panel text that reflows with terminal width. dir_okay=False comes along; parse_fasta cannot read a directory either.