refactor(adapters): decouple KNOWN_CAPABILITIES from catalog entry names (#1186)

[planetf1]

Fixes #1186. Part of Epic #929 Phase 0 (adapter lifecycle refactor).

Background

Epic #929 is a multi-phase refactor of how Mellea loads and identifies adapters (LoRA/aLoRA fine-tuned modules). Phase 0 (#1134, #1135, this PR) lays the scaffolding; later phases wire it into the live loading paths.

This PR fixes a coupling introduced in #1134: KNOWN_CAPABILITIES was built directly from catalog entry name fields, so the capability vocabulary was tied to the names HuggingFace uses for their adapters. When an upstream adapter gets renamed, Mellea capability strings break too. The requirement-check / requirement_check mismatch (hyphens vs underscores) had already forced several edits.

Change

Before — capability vocabulary = upstream adapter names:

# capabilities.py
KNOWN_CAPABILITIES = frozenset(e.name for e in _INTRINSICS_CATALOG_ENTRIES)
# → {"requirement-check", "context-attribution", "policy-guardrails", ...}

# catalog.py
IntriniscsCatalogEntry(name="requirement-check", repo_id=..., revision=...)

After — capability vocabulary is declared independently:

# capabilities.py
KNOWN_CAPABILITIES = frozenset(e.effective_capability for e in _INTRINSICS_CATALOG_ENTRIES)
# → {"requirement_check", "context_attribution", "policy_guardrails", ...}

# catalog.py
IntriniscsCatalogEntry(
    name="requirement-check",       # upstream HF adapter name — may change
    capability="requirement_check", # stable Mellea token — must not change without deprecation
    repo_id=...,
    revision=...,
)

effective_capability returns capability when set, falling back to name — so entries whose name is already a clean identifier (answerability, citations, etc.) need no explicit capability field.

The six hyphenated catalog entries (Core + Guardian groups) get explicit underscore capabilities. The seven underscore-named RAG entries are unchanged.

The issue also called out updating call sites that hardcode adapter names as capabilities. There are none: Identity is Phase 0 scaffolding not yet wired into production adapter loading — nothing in production code constructs Identity objects today. That migration is Phase 1/2 work.

Validation hardening

As part of ensuring effective_capability genuinely guarantees a non-empty, clean token, this PR extends validation consistently across all three string token fields on IntriniscsCatalogEntry:

• name, capability, and revision all now reject empty strings, whitespace-only strings, and strings with leading or trailing whitespace
• Validators raise; they do not silently strip — consistent with the existing codebase convention throughout mellea/
• validate_revision (pre-existing, exported) updated to match

Relationship to #1256

Independent of #1256 (terminology sweep) — can merge in either order. Both touch catalog.py and capabilities.py but in different lines. Whoever merges second needs a one-line docstring rebase.

Test plan

uv run pytest test/backends/test_adapters/test_catalog.py \
               test/backends/test_adapters/test_catalog_revision.py \
               test/backends/test_adapters/test_core_types.py -v

60 tests pass. Key assertions:

• "requirement_check" in KNOWN_CAPABILITIES, "requirement-check" not in KNOWN_CAPABILITIES
• All six hyphenated entries carry explicit underscore capabilities
• No hyphenated string can leak into KNOWN_CAPABILITIES (regression guard)
• len(KNOWN_CAPABILITIES) == len(_INTRINSICS_CATALOG_ENTRIES) (no duplicates)
• name, capability, revision all reject empty, whitespace-only, and leading/trailing whitespace

[psschwei]

Will actually review later, but there were a few non-blocking optional things that an AI review put forward (so treat them as such):

1. effective_capability non-emptiness isn't enforced. The property docstring says "guaranteed non-empty," and test_all_catalog_effective_capabilities_are_nonempty checks current entries — but nothing prevents a future entry with capability="" (empty string is not None, so it'd be returned as-is). If you want the guarantee to be real rather than conventional, a @field_validator("capability") rejecting empty/whitespace strings would enforce it. Reasonable to defer to a later phase given this is scaffolding.

2. No uniqueness validator on capability. Two entries resolving to the same token would silently collapse in the frozenset. The test catches it for the catalog as it stands, but it's a test-time guard, not a structural one. Again, fine to defer.

3. Pre-existing (not introduced here): the class name IntriniscsCatalogEntry is misspelled ("Intriniscs"). Out of scope for this PR.

[planetf1]

Thanks @psschwei.

1 and 2 are fixed in the latest commit: now rejects empty/whitespace strings via a field validator, and the catalog asserts uniqueness of values at import time rather than relying on the test alone.

3 (the class name misspelling) is tracked in #1268. Deferred to a standalone PR after #1256 and this one merge — both have open diffs against the same files and adding a rename now would create unnecessary conflict for one of them.

[psschwei]

lgtm outside of the things @ajbozarth already mentioned

[akihikokuroda]

LGTM