refactor(intrinsics): guardian.py IOContract subclasses + Adapter constants (Epic #929 Phase 1 follow-up) #1332

Parent epic: #929
Phase: 1 (Wave 3 follow-up — guardian.py)
Deferred from: #1139 (guardian.py whole-file migration — PR #1323)
Blocked by: #1139 must merge; #1137 must merge (adds io_contract= to call_intrinsic in _util.py)
Independent of: #1138 (requirement_check), #1140 (Phase 2)
Blocks: nothing directly; Phase 2 (#1140) can start once all Phase 1 work is done

Background

#1139 (PR #1323) completed the guardian.py behavioural migration: Google-style docstrings, documents= keyword-only on the factuality functions, model_options= on all four helpers, and the policy_guardrails XOR fix. One acceptance-criteria item was explicitly deferred:

"Construct via new types" — create IOContract subclasses and module-level Adapter constants for each guardian helper, following the per-module migration pattern established in #1137 (rag.py).

The deferral was necessary because the call_intrinsic(io_contract=…) parameter that wires IOContract into the call path is being added to _util.py by #1137. Using it before #1137 merges would add a mid-wave cross-PR dependency.

What this issue covers

For each of the four helpers in mellea/stdlib/components/intrinsic/guardian.py:

1. IOContract subclasses

Create a private _*Contract class for each helper that extends IOContract (from mellea.backends.adapters). Each class implements parse(result_json) to:

• Validate required keys are present
• Raise AdapterSchemaMismatchError on schema violations (replacing the current implicit KeyError)
• Return the typed parsed value

Follow the pattern established by the _DictContract / _ListContract classes in rag.py (PR #1321).

2. Module-level Adapter constants

Add one Adapter constant per helper (e.g. _POLICY_GUARDRAILS_ADAPTER, _GUARDIAN_CHECK_ADAPTER, etc.) that couples the adapter name to its IOContract. Pass the constant into the call_intrinsic call via io_contract=.

3. Wire into existing call sites

Update the four call_intrinsic(...) calls in guardian.py to pass io_contract= using the new constants. Remove any inline key-access that is now handled by the contract's parse() method.

Success criteria

• One IOContract subclass per helper, matching the output schema documented in the HF README for each adapter
• AdapterSchemaMismatchError raised (not KeyError) when the adapter returns an unexpected schema
• Module-level Adapter constants wired into call_intrinsic calls
• All 19 existing unit tests in test_guardian_documents.py still pass unchanged
• Existing qualitative tests in test_guardian.py still pass
• ruff, mypy clean; docstring quality gate passes

What to look at first

• rag.py implementation in PR refactor(intrinsics): migrate rag.py to new Adapter types (Epic #929 Phase 1 Wave 3) #1321 — the canonical reference for how _*Contract classes and Adapter constants should look
• mellea/backends/adapters/adapter.py — IOContract, Adapter, AdapterSchemaMismatchError definitions
• mellea/stdlib/components/intrinsic/_util.py — call_intrinsic signature (extended in refactor(intrinsics): rag.py whole-file migration to new Adapter types (Epic #929 Phase 1) #1137 to accept io_contract=)
• HF READMEs for each guardian adapter (see AGENTS.md §14 for URL pattern)