fix(adapters): raise or fall back when an aLoRA cannot activate

[planetf1]

Pull Request

Issue

Fixes #1678

Description

Before this PR: if an aLoRA's declared activation trigger doesn't appear in the
prompt Mellea builds, PEFT quietly leaves the base model running instead and says
nothing — no warning, no error. list_adapters() still shows the adapter loaded,
generation still returns a normal-looking result, and a requirement check that should
have failed can come back as a confident pass. Nothing tells you the adapter never
switched on. This is the exact failure diagnosed in #1679: the published
requirement-check aLoRA can never activate on Granite 4.1, and its verdicts skew
towards false passes as a result.

After this PR: Mellea checks, on every generation call, whether the adapter it
just loaded can actually activate for the prompt it just built — before that call
happens, so a doomed generation is never attempted. If it can't activate, behaviour
depends on how you reached it:

• Calling an adapter function directly — core.check_certainty(...),
  core.requirement_check(...), etc. — now raises AloraActivationError instead of
  returning a fabricated score.
• Using req(...)/Requirement.validate()'s automatic aLoRA routing — the path
  bug(adapters): published requirement-check aLoRA never activates, and scores worse than the LoRA #1679's regression actually sits on — now falls back to LLM-as-a-judge
  automatically, with a one-line warning. This is the same fallback Mellea already
  gives an adapter that was never registered at all; it now also covers "registered
  but proven unable to activate."

# Before: silent wrong answer.
score = core.requirement_check(ctx, backend, "The response is in French.")
# -> a confident (and wrong) score; nothing indicates the adapter never activated.

# After: fails loudly instead of lying.
score = core.requirement_check(ctx, backend, "The response is in French.")
# -> raises AloraActivationError naming the capability, base model, and the
#    declared invocation sequence that never appeared in the prompt.

# Before: same silent wrong answer, via automatic routing (#1679's actual failure mode).
result = await req("The response should be a greeting.").validate(backend, ctx)
# -> a confident pass/fail from the base model, presented as if from the aLoRA.

# After: degrades gracefully instead of lying.
result = await req("The response should be a greeting.").validate(backend, ctx)
# WARNING  not using the requirement-check adapter for this call: ... falling
#          back to LLM-as-a-judge instead.
# -> result now comes from LLM-as-a-judge, same as if the adapter had never
#    been registered.

The one real behaviour change: a direct adapter-function call against a broken
aLoRA now raises where it used to silently return a value. Everything else is
additive — no behaviour change for LoRA/embedded/server-mediated adapters, or for an
aLoRA that activates correctly (the overwhelming majority of calls).

The check itself has no false positives: it's an exact match against the same
alora_invocation_tokens sequence PEFT itself looks for, run against the exact prompt
tokens about to be sent to model.generate().

What changed

• mellea/backends/adapters/_core.py — new AloraActivationError.
• mellea/backends/adapters/adapter.py — new alora_invocation_sequence_present(),
  the pure token-subsequence check.
• mellea/backends/huggingface.py — the guard itself, wired into
  _generate_from_intrinsic before any model call; _generate_from_context's
  Requirement-routing branch catches the error and falls back to LLM-as-a-judge.
  A guard abort still fires adapter_function_invocation_complete with outcome
  error, so adapter metrics show the failure. For the legacy IntrinsicAdapter
  shim it reports local_file and the pinned catalogue SHA, matching what a
  successful call reports (from review).
• mellea/backends/adapters/catalog.py — comment above the pinned adapter SHAs
  naming the evidence AC3 requires before a pin bump promotes an aLoRA rung.
• docs/docs/advanced/lora-and-alora-adapters.md — documents the guard and folds it
  into the existing "adapter unavailable → fallback" routing rule.
• test/backends/test_adapters/test_activation_guard.py (new), plus additions to
  test/backends/test_huggingface_unit.py — unit coverage for the token check and
  every adapter shape, plus end-to-end tests through both real call sites.

Deviations from the literal issue spec

• AC1 ("either reported clearly or treated as unavailable") is delivered as
  both, split by call site to match each caller's actual recovery options, rather
  than one global policy.
• AC5 (added to the issue after this branch started, once feat(adapters)!: prompt fallback for adapter functions without a trained adapter #1654 was under
  review): flipping the resolve-time probe order to prefer aLoRA lives in
  _register_available_composed_adapter, which is part of feat(adapters)!: prompt fallback for adapter functions without a trained adapter #1654 and doesn't exist on
  main yet. AC5 itself gates that reorder on "once the guard exists and the evidence
  question in bug(adapters): published requirement-check aLoRA never activates, and scores worse than the LoRA #1679 is settled" — bug(adapters): published requirement-check aLoRA never activates, and scores worse than the LoRA #1679 is still open, so that reorder is explicitly
  not in this PR.
• This PR implements the generation-time guard only, not a resolve-time gate: at
  resolve time Mellea doesn't yet have the chat-templated prompt the check needs.

Acceptance criteria

• 1. Reported clearly or treated as unavailable, on every backend that loads
  adapters itself (currently only LocalHFBackend).
• 2. Tests cover both arms — present activates and stays quiet; absent is
  reported (raises) or skipped (falls back).
• 3. Not exercised here (no pin bumped); established as a standing requirement
  via the AC4 comment.
• 4. Comment added beside the pinned SHAs in catalog.py.
• 5. Deferred — see "Deviations" above.

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code was added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

uv run pytest test/ -m "not qualitative" -q
# 4544 passed, 158 skipped, 0 failed
uv run ruff format --check . && uv run ruff check .   # clean
uv run mypy .                                          # clean on every touched file
npx markdownlint-cli2 "docs/docs/**/*.md"              # clean

Attribution

• AI coding assistants used

---

Adding a new component, requirement, sampling strategy, or tool?

• Component
• Requirement
• Sampling Strategy
• Tool

NOTE: Please ensure you have an issue that has been acknowledged by a core contributor and routed you to open a pull request against this repository. Otherwise, please open an issue before continuing with this pull request.