trimgate 0.0.1__py3-none-any.whl

trimgate/__init__.py

@@ -0,0 +1,10 @@
+"""TrimGate: deterministic, test-time auditor for RAG access-control trimming.
+
+v1 verdict is binary PASS or LEAK: for every (identity, probe) the set of
+chunk-IDs a RAG pipeline surfaces must be a subset of that identity's authorized
+chunk-set, derived from the access-matrix. Zero LLM in the trust path.
+
+See the reconciled v1 contract (handoff doc, section 0) for the normative shapes.
+"""
+
+__version__ = "0.0.1"

trimgate/adapter.py

@@ -0,0 +1,63 @@
+"""The adapter contract: the single seam between TrimGate and a host RAG system.
+
+Per the reconciled v1 contract (section 0): one REQUIRED method `retrieve`, plus
+two OPTIONAL methods `fetch_resource` and `list_resources`, all returning
+chunk-IDs. The optional methods are detected at runtime (a probe that needs an
+unimplemented one is skipped and logged, never silently passed), so the base
+protocol declares only the required method.
+
+The adapter is the only impure boundary. It may do I/O and be non-deterministic;
+TrimGate judges exactly what it returned. A genuine backend failure should raise
+AdapterError, which TrimGate records fail-closed.
+"""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Sequence
+from typing import Protocol, cast, runtime_checkable
+
+Identity = str  # access-matrix key
+
+# Optional adapter method names, detected via hasattr by the engine.
+FETCH_RESOURCE = "fetch_resource"
+LIST_RESOURCES = "list_resources"
+
+
+@runtime_checkable
+class RagAdapter(Protocol):
+    def retrieve(self, query: str, identity: Identity) -> Sequence[str]:
+        """Return the chunk-IDs the host retriever would surface for (query, identity)."""
+        ...
+
+
+class AdapterError(Exception):
+    """Genuine backend failure (timeout, auth error). Recorded fail-closed."""
+
+
+def validate_adapter(adapter: object) -> RagAdapter:
+    """Fail loudly if the object cannot serve as an adapter.
+
+    runtime_checkable Protocols only check attribute presence, so a `retrieve`
+    that is a string or has the wrong arity would pass isinstance and surface
+    later as an opaque error. This checks the seam explicitly at resolve time.
+    """
+    retrieve = getattr(adapter, "retrieve", None)
+    if not callable(retrieve):
+        raise TypeError(
+            f"adapter {type(adapter).__name__!r} has no callable retrieve(query, identity)"
+        )
+    return cast("RagAdapter", adapter)
+
+
+def resolve_adapter(spec: str) -> RagAdapter:
+    """Resolve a MODULE:ATTR import path to an adapter instance.
+
+    ATTR may be a class (instantiated no-args) or a factory (called); an already
+    constructed instance is used as-is.
+    """
+    module_name, sep, attr = spec.partition(":")
+    if not sep or not attr:
+        raise ValueError(f"adapter must be MODULE:ATTR, got {spec!r}")
+    obj = getattr(importlib.import_module(module_name), attr)
+    return validate_adapter(obj() if callable(obj) else obj)

trimgate/adapters/__init__.py

@@ -0,0 +1 @@
+"""Concrete TrimGate adapters for real RAG backends."""

trimgate/adapters/azure.py

@@ -0,0 +1,113 @@
+"""Azure AI Search + Entra reference adapter.
+
+Reproduces the production security-trimming pattern: resolve the identity to its
+Entra group ids, build the OData intersection filter against the document
+`accessGroups`-style field, and run the search so only authorized chunks come
+back. The chunk-IDs returned are exactly what the host would feed the LLM, which
+is what TrimGate then audits against the access-matrix.
+
+The adapter is duck-typed against the search client (no azure-sdk import at module
+load), so it can be unit-tested with a fake client and runs in CI without the
+optional `trimgate[azure]` dependency. `make_search_client` lazily imports the
+SDK only when a real client is actually constructed.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from typing import TYPE_CHECKING, Any, Protocol, cast
+
+DEFAULT_GROUP_FIELD = "authorized_principals"
+DEFAULT_CHUNK_ID_FIELD = "chunk_id"
+# Auditing needs a large top: a small top-k can rank an unauthorized chunk out of
+# the observed window and hide a real leak. For a sound audit, `top` must be at
+# least the number of chunks that could pass the (possibly over-broad) filter.
+DEFAULT_AUDIT_TOP = 1000
+
+# A group id must not contain characters that could break out of the OData
+# literal, split a delimited value list, or pad/mismatch an ACL. Entra object ids
+# are GUIDs and claim-derived principals look like 'clearance:secret', so this is
+# permissive for real ids while rejecting commas, quotes, whitespace, and control.
+_UNSAFE_GROUP = re.compile(r"[,'\"\s\x00-\x1f]")
+# The field name is interpolated raw into the filter, so it must be a plain OData
+# identifier -- never a caller-supplied expression like "true or x".
+_FIELD_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+if TYPE_CHECKING:
+    from azure.core.credentials import AzureKeyCredential, TokenCredential
+
+    from trimgate.adapter import Identity
+
+
+def build_security_filter(group_field: str, groups: Sequence[str]) -> str:
+    """Build the OData security-trimming filter for a Collection(Edm.String) field.
+
+    Matches documents whose `group_field` shares at least one element with the
+    caller's groups, as ORed per-group `eq` clauses (no delimiter to collide with,
+    unlike search.in). Fails closed on an empty group set or an unsafe group id.
+    """
+    if not _FIELD_NAME.match(group_field):
+        raise ValueError(f"unsafe OData field name: {group_field!r}")
+    if not groups:
+        raise ValueError("build_security_filter requires at least one group (fail-closed)")
+    for group in groups:
+        if not group or _UNSAFE_GROUP.search(group):
+            raise ValueError(f"unsafe group id for OData filter: {group!r}")
+    return " or ".join(f"{group_field}/any(g: g eq '{group}')" for group in groups)
+
+
+class SearchClientLike(Protocol):
+    def search(
+        self, *, search_text: str, top: int, filter: str, select: list[str]
+    ) -> Iterable[Mapping[str, Any]]: ...
+
+
+class AzureSearchAdapter:
+    def __init__(
+        self,
+        client: SearchClientLike,
+        group_resolver: Callable[[str], Sequence[str]],
+        *,
+        group_field: str = DEFAULT_GROUP_FIELD,
+        chunk_id_field: str = DEFAULT_CHUNK_ID_FIELD,
+        top: int = DEFAULT_AUDIT_TOP,
+    ) -> None:
+        self._client = client
+        self._group_resolver = group_resolver
+        self._group_field = group_field
+        self._chunk_id_field = chunk_id_field
+        self._top = top
+
+    def retrieve(self, query: str, identity: Identity) -> list[str]:
+        groups = list(self._group_resolver(identity))
+        if not groups:
+            # No groups -> nothing group-gated is authorized. Fail closed without
+            # issuing a query (an empty filter's semantics are backend-dependent).
+            return []
+        filter_expr = build_security_filter(self._group_field, groups)
+        results = self._client.search(
+            search_text=query,
+            top=self._top,
+            filter=filter_expr,
+            select=[self._chunk_id_field],
+        )
+        return [str(doc[self._chunk_id_field]) for doc in results]
+
+
+def make_search_client(
+    endpoint: str,
+    index_name: str,
+    credential: AzureKeyCredential | TokenCredential | None = None,
+) -> SearchClientLike:
+    """Construct a real Azure AI Search client (requires `trimgate[azure]`).
+
+    Defaults to DefaultAzureCredential (managed identity), aligning with a secure
+    Azure posture. Imported lazily so this module loads without the SDK.
+    """
+    from azure.identity import DefaultAzureCredential
+    from azure.search.documents import SearchClient
+
+    cred = credential or DefaultAzureCredential()
+    client = SearchClient(endpoint=endpoint, index_name=index_name, credential=cred)
+    return cast("SearchClientLike", client)

trimgate/cli.py

@@ -0,0 +1,223 @@
+"""The `trimgate` command-line interface.
+
+`trimgate run` loads the access-matrix, labeled corpus, and probeset, resolves the
+adapter (MODULE:ATTR, instantiated/called if callable), runs the deterministic
+probe runner, prints a human-readable summary, and exits non-zero on any leak so
+CI can gate on it. Exit codes: 0 = clean, 1 = leak detected, 2 = fail-closed
+error (config/adapter), matching the handoff's contract.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import secrets
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from pathlib import Path
+
+from trimgate.adapter import resolve_adapter
+from trimgate.corpus import load_corpus
+from trimgate.diff import trim_gap
+from trimgate.engine import Outcome
+from trimgate.matrix import load_matrix
+from trimgate.probe import load_probeset
+from trimgate.receipt import build_receipt, canonical_json, seal_receipt, to_markdown
+from trimgate.runner import RunResult, run
+from trimgate.signing import (
+    generate_private_key,
+    key_fingerprint,
+    load_private_key,
+    load_public_key,
+    private_key_to_pem,
+    public_key_to_pem,
+    sign,
+    verify,
+)
+
+_MARK = {
+    Outcome.PASS: "[ ok ]",
+    Outcome.LEAK: "[FAIL]",
+    Outcome.ERROR: "[ERR ]",
+    Outcome.SKIPPED: "[SKIP]",
+}
+
+
+def _print_summary(result: RunResult) -> None:
+    for verdict in result.verdicts:
+        line = (
+            f"{_MARK[verdict.status]} {verdict.probe_id} "
+            f"{verdict.identity} {verdict.probe_class.value}"
+        )
+        if verdict.status is Outcome.LEAK:
+            line += "  LEAK: " + ", ".join(sorted(verdict.leaked_ids))
+        elif verdict.detail:
+            line += f"  {verdict.detail}"
+        print(line)
+
+    identities = len({v.identity for v in result.verdicts})
+    verdict_word = "PASS" if result.passed else "FAIL"
+    print(
+        f"TrimGate: {identities} identities, {len(result.verdicts)} probes, "
+        f"{result.total_leaks} leak(s), {result.total_errors} error(s), "
+        f"{result.total_skipped} skipped == VERDICT: {verdict_word}"
+    )
+    if result.total_skipped:
+        print(
+            f"NOTE: {result.total_skipped} probe(s) SKIPPED (adapter lacks the method) "
+            f"-- those access paths were NOT audited"
+        )
+
+
+def _execute(args: argparse.Namespace) -> RunResult:
+    matrix = load_matrix(args.matrix)
+    corpus = load_corpus(args.corpus)
+    probeset = load_probeset(args.probes)
+    adapter = resolve_adapter(args.adapter)
+    return run(probeset, adapter, matrix, corpus)
+
+
+def _exit_code(result: RunResult) -> int:
+    if result.passed:
+        return 0
+    # 1 = leak; 2 = fail-closed error or a vacuous (zero-probe) run.
+    return 1 if result.total_leaks else 2
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    result = _execute(args)
+    _print_summary(result)
+
+    if args.out or args.report_md or args.sign:
+        receipt = build_receipt(
+            result, matrix_path=args.matrix, corpus_path=args.corpus, adapter=args.adapter
+        )
+        if args.report_md:
+            Path(args.report_md).write_text(to_markdown(receipt), encoding="utf-8", newline="\n")
+        if args.sign:
+            if not args.out:
+                raise SystemExit("--sign requires --out")
+            if not args.key:
+                raise SystemExit("--sign requires --key (an Ed25519 private key PEM)")
+            private_key = load_private_key(Path(args.key).read_bytes())
+            sealed = seal_receipt(
+                receipt,
+                signed_at=datetime.now(UTC).isoformat(),
+                nonce=secrets.token_hex(16),
+                key_fingerprint=key_fingerprint(private_key.public_key()),
+            )
+            canonical = canonical_json(sealed)
+            Path(args.out).write_text(canonical + "\n", encoding="utf-8", newline="\n")
+            signature = sign(canonical.encode("utf-8"), private_key)
+            Path(args.out + ".sig").write_text(signature + "\n", encoding="utf-8", newline="\n")
+        elif args.out:
+            Path(args.out).write_text(
+                canonical_json(receipt) + "\n", encoding="utf-8", newline="\n"
+            )
+
+    return _exit_code(result)
+
+
+def _cmd_keygen(args: argparse.Namespace) -> int:
+    private_key = generate_private_key()
+    Path(args.private).write_bytes(private_key_to_pem(private_key))
+    Path(args.public).write_bytes(public_key_to_pem(private_key.public_key()))
+    print(f"wrote private key {args.private} and public key {args.public}")
+    return 0
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    receipt = json.loads(Path(args.receipt).read_text(encoding="utf-8"))
+    canonical = canonical_json(receipt).encode("utf-8")
+    sig_path = args.sig or (args.receipt + ".sig")
+    signature = Path(sig_path).read_text(encoding="utf-8").strip()
+    public_key = load_public_key(Path(args.public).read_bytes())
+
+    if not verify(canonical, signature, public_key):
+        print(f"INVALID: {args.receipt} signature does not verify (tampered or wrong key)")
+        return 1
+
+    # The signed payload binds the signer's key fingerprint; confirm the supplied
+    # key actually signed it, and (if pinned) that it is the trusted signer.
+    provenance = receipt.get("provenance") or {}
+    declared = provenance.get("key_fingerprint")
+    actual = key_fingerprint(public_key)
+    if declared != actual:
+        print(f"INVALID: {args.receipt} was not signed by the provided key (unsigned receipt?)")
+        return 1
+    if args.expect_fingerprint and args.expect_fingerprint != actual:
+        print("INVALID: signer fingerprint does not match the pinned --expect-fingerprint")
+        return 1
+
+    # A valid signature over a FAIL receipt is still a fail: do not report it OK.
+    verdict = receipt.get("verdict")
+    if verdict != "pass":
+        print(f"INVALID: signature valid, but the audit verdict is {verdict!r} (not pass)")
+        return 1
+
+    trust = "trusted (pinned)" if args.expect_fingerprint else "UNTRUSTED -- signer not pinned"
+    print(
+        f"OK: verdict=pass, signer {actual[:16]} [{trust}], "
+        f"self-reported signed_at {provenance.get('signed_at')}"
+    )
+    return 0
+
+
+def _cmd_diff(args: argparse.Namespace) -> int:
+    result = _execute(args)
+    gap = trim_gap(result)
+    for identity in sorted(gap):
+        print(f"{identity} improperly reachable: {', '.join(sorted(gap[identity]))}")
+
+    if result.total_errors or not result.verdicts:
+        # An errored or vacuous audit is NOT clean; never report "none" for it.
+        print(
+            f"trim gap: INCOMPLETE -- {result.total_errors} error(s) over "
+            f"{len(result.verdicts)} probe(s); audit did not run cleanly"
+        )
+    elif not gap:
+        print("trim gap: none -- every identity stayed inside its authorized set")
+    return _exit_code(result)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="trimgate")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run_parser = sub.add_parser("run", help="run a probeset against an adapter")
+    _add_common_args(run_parser)
+    run_parser.add_argument("--out", help="write the canonical JSON receipt to this path")
+    run_parser.add_argument("--report-md", help="write a human-readable Markdown report")
+    run_parser.add_argument("--sign", action="store_true", help="Ed25519-sign the receipt")
+    run_parser.add_argument("--key", help="Ed25519 private key PEM (required with --sign)")
+    run_parser.set_defaults(func=_cmd_run)
+
+    diff_parser = sub.add_parser("diff", help="emit the per-identity trim gap")
+    _add_common_args(diff_parser)
+    diff_parser.set_defaults(func=_cmd_diff)
+
+    keygen_parser = sub.add_parser("keygen", help="generate an Ed25519 signing keypair")
+    keygen_parser.add_argument(
+        "--private", required=True, help="output path for the private key PEM"
+    )
+    keygen_parser.add_argument("--public", required=True, help="output path for the public key PEM")
+    keygen_parser.set_defaults(func=_cmd_keygen)
+
+    verify_parser = sub.add_parser("verify", help="verify a signed receipt offline")
+    verify_parser.add_argument("receipt", help="path to the receipt JSON")
+    verify_parser.add_argument("--sig", help="path to the signature (default: <receipt>.sig)")
+    verify_parser.add_argument("--public", required=True, help="path to the public key PEM")
+    verify_parser.add_argument(
+        "--expect-fingerprint", help="pin the trusted signer's key fingerprint"
+    )
+    verify_parser.set_defaults(func=_cmd_verify)
+
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+def _add_common_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--adapter", required=True, help="MODULE:ATTR adapter import path")
+    parser.add_argument("--matrix", required=True, help="path to access-matrix YAML")
+    parser.add_argument("--corpus", required=True, help="path to labeled-corpus JSONL")
+    parser.add_argument("--probes", required=True, help="path to probes YAML")

trimgate/corpus.py

@@ -0,0 +1,76 @@
+"""Labeled corpus: chunks under test, each carrying the label that decides who
+may see it. Authorization is resolved against the access-matrix (section 0):
+authorized(identity) = chunk-IDs whose label is in the identity's allowed labels.
+
+The corpus is validated at construction: a chunk-ID must map to exactly one label.
+A duplicated chunk-ID is rejected, because authorization unions over chunks, so a
+public copy of a secret chunk-ID would otherwise silently authorize the secret.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from trimgate.matrix import AccessMatrix
+
+
+class CorpusError(ValueError):
+    """The corpus is malformed or internally inconsistent (fail-closed)."""
+
+
+@dataclass(frozen=True)
+class Chunk:
+    chunk_id: str
+    label: str
+
+
+@dataclass(frozen=True)
+class Corpus:
+    chunks: tuple[Chunk, ...]
+
+    def __post_init__(self) -> None:
+        seen: dict[str, str] = {}
+        for chunk in self.chunks:
+            if chunk.chunk_id in seen:
+                raise CorpusError(
+                    f"duplicate chunk_id {chunk.chunk_id!r} "
+                    f"(labels {seen[chunk.chunk_id]!r} and {chunk.label!r})"
+                )
+            seen[chunk.chunk_id] = chunk.label
+
+    def authorized_for(self, matrix: AccessMatrix, identity: str) -> frozenset[str]:
+        allowed = matrix.allowed_labels(identity)
+        return frozenset(c.chunk_id for c in self.chunks if c.label in allowed)
+
+    def chunk_ids(self) -> frozenset[str]:
+        return frozenset(c.chunk_id for c in self.chunks)
+
+
+def _reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    seen: dict[str, object] = {}
+    for key, value in pairs:
+        if key in seen:
+            raise CorpusError(f"duplicate JSON key {key!r} (last-key-wins could relabel a chunk)")
+        seen[key] = value
+    return seen
+
+
+def load_corpus(path: str) -> Corpus:
+    chunks: list[Chunk] = []
+    with open(path, encoding="utf-8") as fh:
+        for lineno, raw in enumerate(fh, start=1):
+            line = raw.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line, object_pairs_hook=_reject_duplicate_keys)
+            except json.JSONDecodeError as exc:
+                raise CorpusError(f"{path}:{lineno}: invalid JSON: {exc}") from exc
+            chunk_id, label = obj.get("chunk_id"), obj.get("label")
+            if not isinstance(chunk_id, str) or not isinstance(label, str):
+                raise CorpusError(f"{path}:{lineno}: chunk needs string 'chunk_id' and 'label'")
+            chunks.append(Chunk(chunk_id=chunk_id, label=label))
+    return Corpus(chunks=tuple(chunks))

trimgate/demo.py

@@ -0,0 +1,46 @@
+"""Demo adapter factories for the quickstart seed (examples/quickstart).
+
+These model a host RAG system under test. `clean_adapter` trims correctly for
+every quickstart probe; `leaky_adapter` reproduces a real ACL-drift failure where
+bob's retrieval and direct-fetch surface the finance salary chunk he may not see.
+Both are constructible with no arguments so the CLI can reference them as
+`trimgate.demo:clean_adapter` / `trimgate.demo:leaky_adapter`.
+
+The adapter is the system under test; it is authored independently of the
+access-matrix. TrimGate's job is to catch when the two disagree.
+"""
+
+from __future__ import annotations
+
+from trimgate.fake import FakeAdapter
+
+_BOB_SALARY_QUERY = "what are the engineering salary bands?"
+_CAROL_SALARY_QUERY = "what are the engineering salary bands?"
+
+
+def clean_adapter() -> FakeAdapter:
+    """Every probe stays inside the identity's authorized set: a PASS run."""
+    return FakeAdapter(
+        retrievals={
+            ("alice", "what is the parental leave policy?"): ["c-parental"],
+            ("bob", _BOB_SALARY_QUERY): ["c-readme"],  # correctly trimmed
+            ("carol", _CAROL_SALARY_QUERY): ["c-salary"],  # carol may see fin-secret
+        },
+        fetches={
+            ("bob", "doc-salary-bands"): [],  # correctly denied
+        },
+    )
+
+
+def leaky_adapter() -> FakeAdapter:
+    """ACL drift: bob's retrieval and direct-fetch leak the finance chunk."""
+    return FakeAdapter(
+        retrievals={
+            ("alice", "what is the parental leave policy?"): ["c-parental"],
+            ("bob", _BOB_SALARY_QUERY): ["c-readme", "c-salary"],  # LEAK
+            ("carol", _CAROL_SALARY_QUERY): ["c-salary"],
+        },
+        fetches={
+            ("bob", "doc-salary-bands"): ["c-salary"],  # LEAK
+        },
+    )

trimgate/diff.py

@@ -0,0 +1,19 @@
+"""Access-diff: the trim gap.
+
+The trim gap is the headline artifact: per identity, the set of chunk-IDs the
+pipeline made improperly reachable (surfaced but not authorized), aggregated
+across every probe in a run. An empty gap for every identity is a clean audit.
+"""
+
+from __future__ import annotations
+
+from trimgate.engine import Outcome
+from trimgate.runner import RunResult
+
+
+def trim_gap(result: RunResult) -> dict[str, frozenset[str]]:
+    gap: dict[str, set[str]] = {}
+    for verdict in result.verdicts:
+        if verdict.status is Outcome.LEAK:
+            gap.setdefault(verdict.identity, set()).update(verdict.leaked_ids)
+    return {identity: frozenset(ids) for identity, ids in gap.items()}

trimgate/engine.py

@@ -0,0 +1,114 @@
+"""The assertion engine: the heart of the trust path.
+
+For each probe it compares the chunk-IDs the adapter surfaced against the set the
+identity is authorized to see (derived from the access-matrix), by pure set
+arithmetic. No model, no fuzzy match, no randomness. Binary verdict: a probe is a
+LEAK iff it surfaced any chunk outside the authorized set, else PASS.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any, cast
+
+from trimgate.adapter import RagAdapter
+from trimgate.corpus import Corpus
+from trimgate.matrix import AccessMatrix, UnknownIdentityError
+from trimgate.probe import Probe, ProbeClass
+
+# Probe class -> the optional adapter method it requires (retrieval needs the
+# required `retrieve`, so it is absent here and never skips).
+_REQUIRED_OPTIONAL_METHOD = {
+    ProbeClass.DIRECT_FETCH: "fetch_resource",
+    ProbeClass.ENUMERATION: "list_resources",
+}
+
+
+class Outcome(StrEnum):
+    PASS = "pass"
+    LEAK = "leak"
+    ERROR = "error"
+    SKIPPED = "skipped"
+
+
+@dataclass(frozen=True)
+class Verdict:
+    probe_id: str
+    identity: str
+    probe_class: ProbeClass
+    status: Outcome
+    surfaced_ids: frozenset[str]
+    leaked_ids: frozenset[str]
+    detail: str = ""
+
+
+def _surface(probe: Probe, adapter: RagAdapter) -> list[str]:
+    """Call the adapter method the probe's class selects, returning chunk-IDs.
+
+    The optional methods are reached via getattr so the base protocol need only
+    declare `retrieve`; presence is checked by the caller before dispatch.
+    """
+    if probe.probe_class is ProbeClass.RETRIEVAL:
+        if probe.query is None:
+            raise ValueError(f"retrieval probe {probe.id} has no query")
+        return list(adapter.retrieve(probe.query, probe.identity))
+    if probe.probe_class is ProbeClass.DIRECT_FETCH:
+        if probe.resource_ref is None:
+            raise ValueError(f"direct_fetch probe {probe.id} has no resource_ref")
+        return list(cast("Any", adapter).fetch_resource(probe.resource_ref, probe.identity))
+    if probe.probe_class is ProbeClass.ENUMERATION:
+        return list(cast("Any", adapter).list_resources(probe.identity))
+    raise ValueError(f"unknown probe_class: {probe.probe_class!r}")
+
+
+def _verdict(
+    probe: Probe,
+    status: Outcome,
+    surfaced: frozenset[str],
+    leaked: frozenset[str],
+    detail: str = "",
+) -> Verdict:
+    return Verdict(probe.id, probe.identity, probe.probe_class, status, surfaced, leaked, detail)
+
+
+def evaluate(probe: Probe, adapter: RagAdapter, matrix: AccessMatrix, corpus: Corpus) -> Verdict:
+    empty: frozenset[str] = frozenset()
+
+    # A probe whose class needs an unimplemented optional method is skipped and
+    # logged (never silently passed).
+    needed = _REQUIRED_OPTIONAL_METHOD.get(probe.probe_class)
+    if needed is not None and not hasattr(adapter, needed):
+        return _verdict(
+            probe,
+            Outcome.SKIPPED,
+            empty,
+            empty,
+            detail=f"adapter has no optional method {needed!r}",
+        )
+
+    # The adapter is the only impure boundary; any failure is fail-closed.
+    try:
+        surfaced = frozenset(_surface(probe, adapter))
+    except Exception as exc:  # noqa: BLE001 - fail-closed on any backend failure
+        return _verdict(probe, Outcome.ERROR, empty, empty, detail=f"adapter error: {exc}")
+
+    # An identity not declared in the matrix is a config error, never a pass.
+    try:
+        authorized = corpus.authorized_for(matrix, probe.identity)
+    except UnknownIdentityError:
+        return _verdict(
+            probe, Outcome.ERROR, surfaced, empty, detail=f"unknown identity {probe.identity!r}"
+        )
+
+    # A surfaced chunk-ID that the corpus cannot classify is fail-closed, never
+    # treated as authorized.
+    unknown = surfaced - corpus.chunk_ids()
+    if unknown:
+        return _verdict(
+            probe, Outcome.ERROR, surfaced, empty, detail=f"unknown chunk(s): {sorted(unknown)}"
+        )
+
+    leaked = surfaced - authorized
+    status = Outcome.LEAK if leaked else Outcome.PASS
+    return _verdict(probe, status, surfaced, leaked)