unicode-logic-kit 0.31.0__py3-none-any.whl

unicode_logic_kit/eval/theory_check.py

@@ -0,0 +1,1170 @@
+"""Deductive verification layer for a collection of predicate definitions.
+
+An LLM translates chemical class definitions to FOL, and classification is
+then MODEL CHECKING a definition against a molecule structure
+(:mod:`unicode_logic_kit.semantics.model_eval`). That measures whether the
+definitions are individually *useful* against real data (a definition that
+is too general matches far too much, and the precision cost stays invisible
+until it is measured against a corpus). It says nothing about whether the
+definitions are *coherent as a theory*: an auxiliary predicate is optimised
+only in the context of the one class that introduces it and then silently
+inherited by every subclass, which overfits it to that one context, and a
+prover-backed OWL-subsumption check reports only proved/not proved, with
+**no counterexample** when a subsumption fails. This module is the layer that
+sits between "does this predicate fire on real molecules" and "is this
+DEFINITION SET internally consistent" — it never touches a molecule; every
+question here is decided purely from the definitions' own logical content,
+via the kit's existing prover chain (:mod:`unicode_logic_kit.atp.protocol`)
+and finite model finder.
+
+Data model — why a plain ``name -> body`` mapping
+---------------------------------------------------
+A "definition" is a **named 0-ary predicate** with a defining FORMULA: exactly
+the ``className <=> body`` shape such a translation produces, e.g.::
+
+    molecule <=> net_charge_neutral
+    organicMolecularEntity <=> ?[A1]: (molecule & c(A1))
+    carboxylicAcid <=> (carbonOxoacid & ?[A1,A2,A3]: (c(A1) & o(A2) & o(A3) &
+                         has_1_hs(A3) & bDOUBLE(A1,A2) & bSINGLE(A1,A3)))
+
+Every LHS here (``molecule``, ``organicMolecularEntity``, ``carboxylicAcid``,
+``carbonOxoacid``) is used with NO arguments — a ChEBI class membership fact is
+a global property of "the one molecule this structure represents"
+(:class:`~unicode_logic_kit.semantics.structures.FiniteStructure` already builds
+its 0-ary extension exactly this way: ``frozenset()`` or ``frozenset({()})``).
+So this module represents a definition set as ``Mapping[str, Node]``: the key
+is the defined 0-ary predicate's name, the value is its BODY (the right-hand
+side of the ``<=>`` — never re-wrap it in ``Iff(Atom(name, ()), body)``, the
+mapping key already carries the left-hand side). This is a deliberate,
+narrower choice than a general "Definition object with parameters" — a
+parametrised definition (``isRing(x) <=> ...``) would need a substitution-
+with-arguments mechanic none of these definitions exercise; admitting it
+here would be a real design expansion, not a small one, so a body atom that
+names a defined predicate is only ever recognised as a USE of that definition
+when it appears with ZERO arguments (:func:`dependency_graph`, :func:`unfold`)
+— a same-named atom used elsewhere with arguments is simply a different,
+primitive symbol, left completely alone.
+
+Why unfolding is the hard part
+-------------------------------
+Definitions reference each other (``carboxylicAcid`` names ``carbonOxoacid``,
+``organicMolecularEntity`` names ``molecule``), and a subsumption or
+satisfiability question is only meaningful against the CLOSED formula in
+terms of primitive (undefined) predicates — a prover asked to check
+``carboxylicAcid -> carbonOxoacid`` while ``carbonOxoacid`` is still an
+uninterpreted 0-ary atom would trivially fail to see that the axioms actually
+force it (nothing tells the prover ``carbonOxoacid`` unfolds to anything).
+:func:`unfold` collects that background theory correctly by *substituting*
+every defined-predicate use with its own (recursively unfolded) body, so what
+reaches the prover is a single sentence over only primitive vocabulary — no
+separate list of background axioms is needed or possible, because a defined
+0-ary predicate reused in two different bodies is DEFINITIONALLY (not just
+materially) identical to its expansion everywhere, and substitution is the
+operation that makes that identity explicit to a syntactic prover.
+
+Plain substitution like this is only correct when every body is CLOSED
+(no free variable): pasting a body verbatim into an enclosing definition's
+own ``∃``/``∀`` scope would otherwise silently CAPTURE a free variable that
+never meant to refer to that binder at all. :func:`unfold` therefore refuses
+up front — see :class:`NonClosedDefinition` — rather than attempt
+capture-avoiding (alpha-renaming) substitution: this module's data model is
+0-ARY class-membership definitions (see "Data model" above), for which a
+free variable is a malformed input, not a feature to accommodate.
+
+Circular definitions are MEANINGLESS, not merely hard
+-------------------------------------------------------
+``className <=> P(..., className, ...)`` pins down no fact: any truth value
+of ``className`` is self-consistent with such a biconditional (a fixed point
+is not guaranteed to be UNIQUE — the classical case for why circular
+"definitions" are not definitions at all). This module never guesses a
+reading for one (least/greatest fixed point, etc.) — :func:`unfold` refuses
+with :class:`CyclicDefinition` the moment substitution would revisit a name
+already being expanded on the current path, and :func:`find_cycles` reports
+every such cycle in the STATIC dependency graph up front so a caller can see
+the problem without triggering it via a substitution call. A definition
+reachable from a cycle cannot be unfolded at all, so :func:`check_satisfiable`
+/ :func:`check_subsumption` report it as its own status, ``"cyclic"`` —
+distinct from ``"unknown"`` (an honest "we could not decide this within the
+budget") because a cyclic definition is not merely undecided, it is a PROVEN
+defect in the definition set, on exactly the same footing as an unsatisfiable
+one (see :attr:`TheoryReport.proved_problems`).
+
+Three-valued honesty, end to end
+-----------------------------------
+Every check in this module returns one of a definitive PROVEN status
+(``"unsatisfiable"`` / ``"entailed"`` / ``"refuted"``, the last always
+carrying a countermodel — see :func:`check_subsumption`), the definitive
+defect status ``"cyclic"``, or ``"unknown"``. ``"unknown"`` is never
+downgraded to ``False``/``"refuted"`` and never upgraded to ``True``/
+``"entailed"`` — a timeout, a step-bound, or an incomplete backend all mean
+exactly "not decided", full stop, matching this kit's house rule (see
+CLAUDE.md) that an unknown result is never reported as a false one.
+:func:`check_satisfiable` and :func:`check_subsumption` are thin, honest
+wrappers around :func:`unicode_logic_kit.api.prove` (which already returns this
+same three/four-valued :class:`~unicode_logic_kit.atp.protocol.Verdict`
+contract over its whole backend chain — Z3, the kit's own tableau/resolution
+provers, and the finite model finder by default): they add nothing but the
+unfolding step and the translation from "prove/refute a goal" to "is this
+definition satisfiable" / "does this subsumption hold", so an unsatisfiable
+result is exactly a Z3/tableau/resolution-checkable PROOF of a contradiction
+and a refuted subsumption's countermodel is exactly the model the backend
+that refuted it actually produced (never fabricated or approximated).
+
+What this module is deliberately silent about
+-------------------------------------------------
+It never runs a definition against real data (that is model_eval's job) and
+it never suggests a fix for a broken definition — it only proves, precisely,
+THAT something is broken (dead classifier, meaningless cycle, missing
+conjunct) and, for a refuted subsumption, exhibits WHY via a concrete
+countermodel. That is the whole value-add over a bare prover-backed
+subsumption check, which reports only proved/not proved with no witness.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, FrozenSet, List, Mapping, Optional, Sequence, Tuple
+
+from ..fol.nodes import Node, Atom, Not, Implies
+from ..atp.protocol import PROVED, REFUTED, UNKNOWN
+# eval -> atp is already the established direction in this module (see the
+# PROVED/REFUTED/UNKNOWN import above), so to_html() reuses the small,
+# private HTML-page helper the atp Fitch/sequent renderers share rather than
+# reimplementing page-wrapping/escaping a third time — see atp/_html's own
+# module docstring for why it is safe to import across the package boundary
+# this way (it imports nothing back).
+from ..atp._html import esc_html, html_page
+
+__all__ = [
+    "Definitions",
+    "CyclicDefinition", "UnfoldDepthExceeded", "NonClosedDefinition",
+    "DEFAULT_MAX_DEPTH",
+    "dependency_graph", "find_cycles", "unfold",
+    "SatisfiabilityResult", "check_satisfiable",
+    "SubsumptionResult", "check_subsumption",
+    "TheoryReport", "check_theory",
+]
+
+#: A definition set: defined 0-ary predicate name -> its defining BODY (the
+#: right-hand side of ``name <=> body``). See the module docstring's "Data
+#: model" section for why this shape and not a parametrised Definition object.
+Definitions = Mapping[str, Node]
+
+#: How many nested definitional expansions :func:`unfold` will perform along
+#: one substitution path before giving up with :class:`UnfoldDepthExceeded`.
+#: Chosen generously relative to any real ChEBI-style class hierarchy (a
+#: handful to a few dozen levels of subclassing) while still catching a
+#: genuinely runaway/undetected-cycle situation instead of recursing forever.
+DEFAULT_MAX_DEPTH = 50
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+class CyclicDefinition(ValueError):
+    """:func:`unfold` refuses to expand a definition through a cycle.
+
+    Raised the moment substitution would revisit a name already being
+    expanded on the CURRENT path (a live on-stack check, the standard DFS
+    cycle test) — see the module docstring's "Circular definitions are
+    MEANINGLESS" section for why this is a refusal, not an approximation.
+    """
+
+
+class UnfoldDepthExceeded(ValueError):
+    """:func:`unfold`'s substitution chain exceeded ``max_depth`` without
+    terminating in primitive-only vocabulary.
+
+    This is a SEPARATE failure mode from :class:`CyclicDefinition`: the
+    on-stack check catches every cycle regardless of depth, so hitting this
+    instead means either a definition chain that is genuinely deeper than
+    ``max_depth`` (raise it), or — mixed with sibling reuse of the same name
+    at different points of a body — a combinatorial expansion that never
+    revisits a name on any single path yet keeps growing (rare, but not
+    provably impossible for a hand-written definition set); either way this
+    is reported rather than silently truncating the formula.
+    """
+
+
+class NonClosedDefinition(ValueError):
+    """:func:`unfold` refuses to substitute a definition body that is not a
+    CLOSED sentence (has a free logical variable).
+
+    Why this matters: :func:`unfold` substitutes a defined 0-ary atom
+    IN PLACE, wherever it occurs — including inside an enclosing definition's
+    own ``∃``/``∀`` scopes. If the substituted body itself has a free
+    variable with the SAME NAME as one of those enclosing binders, plain
+    (non-capture-avoiding) substitution silently re-binds it: the free
+    occurrence, which denoted "whatever the definition's own body meant by
+    that name" (nothing, since it was never bound — an ill-formed input to
+    begin with), now denotes "the enclosing definition's witness" instead —
+    two occurrences that do not denote the same thing get silently
+    identified. That is a SOUNDNESS bug, not a decidability one, so it is
+    caught up front rather than risked on every substitution.
+
+    Why refuse rather than substitute capture-freely (alpha-rename the
+    clashing binder before substituting): every definition in this module's
+    data model is a 0-ARY class-membership fact (see the module docstring's
+    "Data model" section) — its body is only ever quantified INTERNALLY
+    (auxiliary existentials over its own chemical-substructure witnesses,
+    say), never parametrised by a variable a caller substitutes in from
+    outside. A body with a genuine free variable is therefore not a
+    well-formed 0-ary definition at all — it is a typo, an accidentally
+    unbound witness, or an attempt at a parametrised definition this module
+    was never designed to represent (see the module docstring's "why a plain
+    name -> body mapping" section: admitting parametrised definitions would
+    be a real design expansion, not a small one). Capture-avoiding
+    substitution would quietly accept and "fix" that malformed input by
+    inventing a reading for it, rather than reporting the actual defect —
+    exactly the kind of silent approximation this kit's house rules forbid.
+    This mirrors the ``KeyError`` :func:`unfold` already raises for a name
+    that is not even a key of ``definitions``: both are input-validation
+    failures decided BEFORE any unfolding/proving work begins, not
+    proof-budget questions like :class:`UnfoldDepthExceeded`.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Dependency graph / cycle detection
+# ---------------------------------------------------------------------------
+
+def _direct_uses(body: Node, definitions: Definitions) -> FrozenSet[str]:
+    """The defined names ``body`` uses AS A DEFINITION (0-ary atom, name is a
+    key of ``definitions``) — direct references only, not transitive."""
+    used = set()
+    for node in body.walk():
+        if isinstance(node, Atom) and not node.args and node.predicate in definitions:
+            used.add(node.predicate)
+    return frozenset(used)
+
+
+def dependency_graph(definitions: Definitions) -> Dict[str, FrozenSet[str]]:
+    """Direct definitional dependencies: ``name -> frozenset(names it uses)``.
+
+    A name is counted as "used" only where it occurs as a bare 0-ary atom
+    whose predicate is itself a key of ``definitions`` — matching exactly what
+    :func:`unfold` will substitute (see the module docstring). This is the
+    DIRECT (one-hop) graph; :func:`find_cycles` walks it to find cycles, and
+    a topological/transitive closure is deliberately not offered here — a
+    caller that needs it can compute it from this graph, and adding it would
+    just be more surface for something one line of graph code already covers.
+    """
+    return {name: _direct_uses(body, definitions) for name, body in definitions.items()}
+
+
+def _normalize_cycle(cycle: Tuple[str, ...]) -> Tuple[str, ...]:
+    """Canonical form of a cycle (``(n0, n1, ..., n0)``, first==last) for
+    deduplication: rotate to start at the lexicographically smallest name,
+    keeping direction (A->B->A and B->A->B are the SAME cycle; A->B->A and
+    A->C->A, if both exist, are DIFFERENT cycles and stay distinct)."""
+    core = cycle[:-1]
+    best = None
+    for i in range(len(core)):
+        rotated = core[i:] + core[:i]
+        candidate = rotated + (rotated[0],)
+        if best is None or candidate < best:
+            best = candidate
+    return best
+
+
+def find_cycles(definitions: Definitions) -> Tuple[Tuple[str, ...], ...]:
+    """Every elementary cycle in the definitional dependency graph.
+
+    Each cycle is a name sequence ``(n0, n1, ..., nk, n0)`` — first and last
+    entry identical, tracing the dependency chain that closes the loop. A
+    direct self-reference (``A <=> ... A ...``) appears as ``("A", "A")``.
+    Results are deduplicated (see :func:`_normalize_cycle`) and returned in
+    sorted order, so the output is deterministic regardless of dict iteration
+    order.
+
+    Implementation: plain DFS from every node with an explicit "on the current
+    path" set — the standard cycle test, and exactly what :func:`unfold`'s
+    live on-stack check also performs (this function just runs it eagerly,
+    up front, over the whole graph, rather than only along the one path a
+    particular :func:`unfold` call happens to take). Complexity is bounded by
+    the number of simple paths in the graph, which is fine for a definition
+    set the size of a class hierarchy (sparse, near-tree-shaped with the
+    occasional bug introducing a 2-3 node loop) but is NOT guaranteed
+    polynomial on a dense graph — this is a correctness-first, not a
+    scalability-first, implementation.
+    """
+    deps = dependency_graph(definitions)
+    cycles: set = set()
+
+    def dfs(node: str, path: Tuple[str, ...], on_path: FrozenSet[str]) -> None:
+        for nxt in sorted(deps.get(node, ())):
+            if nxt in on_path:
+                idx = path.index(nxt)
+                cycles.add(_normalize_cycle(path[idx:] + (nxt,)))
+            else:
+                dfs(nxt, path + (nxt,), on_path | {nxt})
+
+    for start in sorted(deps):
+        dfs(start, (start,), frozenset({start}))
+
+    return tuple(sorted(cycles))
+
+
+# ---------------------------------------------------------------------------
+# Unfolding
+# ---------------------------------------------------------------------------
+
+def _require_closed_definitions(definitions: Definitions) -> None:
+    """Raise :class:`NonClosedDefinition` if any body in ``definitions`` is
+    not a closed sentence.
+
+    Reuses :func:`unicode_logic_kit.eval.validate.validate`'s own closedness
+    check (``ValidationReport.is_closed``, which counts a free ``Variable``
+    OR a free ``LambdaVar`` against closedness) rather than reimplementing
+    it. Checks EVERY body in ``definitions``, not just ones reachable from a
+    particular call's starting name: :func:`unfold`'s substitution walk can
+    reach any definition transitively, and which ones it actually reaches
+    depends on ``name`` and on the bodies themselves, so a check narrower
+    than "the whole set" would make whether a malformed body gets caught
+    depend on which name happens to be unfolded first — see
+    :class:`NonClosedDefinition` for why this is refused at all.
+    """
+    from .validate import validate  # lazy: mirrors this module's other lazy imports
+
+    offenders = []
+    for name, body in definitions.items():
+        report = validate(body)
+        if not report.is_closed:
+            offenders.append((name, report.free_variable_names))
+    if offenders:
+        detail = "; ".join(
+            f"{name!r} has free variable(s) {', '.join(free_names)}"
+            for name, free_names in offenders
+        )
+        raise NonClosedDefinition(
+            "unfold: every definition body must be a CLOSED sentence — this "
+            "module's data model is 0-ary class-membership definitions, not "
+            f"parametrised ones (see the module docstring): {detail}. See "
+            "NonClosedDefinition's docstring for why this is refused rather "
+            "than patched via capture-avoiding substitution."
+        )
+
+
+def _substitute(node: Node, definitions: Definitions, active: Tuple[str, ...],
+                depth: int, max_depth: int) -> Node:
+    """Recursively replace every 0-ary defined-predicate atom in ``node`` with
+    its (further-unfolded) body. ``active`` is the ordered stack of names
+    currently being expanded ON THIS PATH — membership in it is the live
+    cycle check; ``depth`` is how many substitutions deep this path already
+    is. Sibling reuse of the same name (e.g. ``A & A`` in one body) is NOT a
+    cycle: each occurrence recurses independently with the SAME ``active``/
+    ``depth`` it was called with, since neither branch is "inside" the
+    other's expansion."""
+    if isinstance(node, Atom) and not node.args and node.predicate in definitions:
+        pred = node.predicate
+        if pred in active:
+            raise CyclicDefinition(
+                f"unfold: definitional cycle detected: {' -> '.join(active + (pred,))} "
+                "— a circular biconditional like this pins down no fact (any truth "
+                "value is self-consistent with it), so it is refused rather than "
+                "evaluated. See find_cycles() to locate every such cycle up front."
+            )
+        if depth >= max_depth:
+            raise UnfoldDepthExceeded(
+                f"unfold: expanding {active[0]!r} did not reach a primitive-only "
+                f"formula within max_depth={max_depth} steps (currently expanding: "
+                f"{' -> '.join(active + (pred,))}). Raise max_depth if this chain is "
+                "genuinely this deep, or check find_cycles() for an undetected cycle."
+            )
+        body = definitions[pred]
+        return _substitute(body, definitions, active + (pred,), depth + 1, max_depth)
+    return node.map_children(
+        lambda c: _substitute(c, definitions, active, depth, max_depth))
+
+
+def unfold(name: str, definitions: Definitions, *,
+          max_depth: int = DEFAULT_MAX_DEPTH) -> Node:
+    """Expand ``definitions[name]`` until only primitive predicates remain.
+
+    Every 0-ary atom in the body whose predicate is itself a key of
+    ``definitions`` is replaced by that key's own (recursively unfolded)
+    body — see the module docstring's "Why unfolding is the hard part". The
+    result is a single formula a prover can check directly, with no separate
+    background-axiom list needed (there is nothing FOR such a list to say
+    that substitution has not already said).
+
+    Raises:
+        KeyError: ``name`` is not a key of ``definitions``.
+        NonClosedDefinition: some body in ``definitions`` has a free
+            variable — checked over the WHOLE ``definitions`` mapping before
+            any substitution begins (see :class:`NonClosedDefinition` for
+            why: substituting a non-closed body can silently capture its
+            free variable in an unrelated enclosing binder of the same
+            name).
+        CyclicDefinition: expanding ``name`` would revisit a name already
+            being expanded on the current path — see :func:`find_cycles` to
+            locate the cycle without triggering this.
+        UnfoldDepthExceeded: the expansion did not terminate within
+            ``max_depth`` nested substitutions.
+    """
+    if name not in definitions:
+        raise KeyError(
+            f"unfold: {name!r} is not a defined name (known: {sorted(definitions)})")
+    _require_closed_definitions(definitions)
+    return _substitute(definitions[name], definitions, (name,), 0, max_depth)
+
+
+# ---------------------------------------------------------------------------
+# Satisfiability
+# ---------------------------------------------------------------------------
+
+_SATISFIABILITY_STATUSES = ("satisfiable", "unsatisfiable", "unknown", "cyclic")
+
+
+@dataclass(frozen=True)
+class SatisfiabilityResult:
+    """Outcome of :func:`check_satisfiable`.
+
+    ``status``:
+        ``"unsatisfiable"`` — PROVEN: the unfolded definition is a
+            contradiction, so ``name`` can hold of no possible molecule/object
+            whatsoever — a dead classifier that silently returns 0 matches
+            forever. ``detail`` names the backend that proved it.
+        ``"satisfiable"`` — PROVEN: some model makes ``name`` true.
+            ``witness`` is that model, in the SAME JSON-able shape as
+            :attr:`unicode_logic_kit.atp.protocol.Verdict.countermodel`
+            (``{"kind": ..., ...}``) — it may occasionally be ``None`` even
+            on this status, for a backend that can refute unsatisfiability
+            without producing a readable model (rare; the default chain's
+            Z3/model-finder members always attach one).
+        ``"unknown"`` — neither was established within the backend chain's
+            budget. NEVER a claim of unsatisfiability — see the module
+            docstring's three-valued-honesty section.
+        ``"cyclic"`` — ``name`` could not even be unfolded (it is reachable
+            from a definitional cycle); ``unfolded`` is ``None`` in this case.
+            This is its own PROVEN-defect status, not folded into
+            ``"unknown"`` — see :func:`find_cycles`.
+    """
+
+    name: str
+    status: str
+    unfolded: Optional[Node]
+    witness: Optional[dict]
+    backend: Optional[str]
+    detail: Optional[str]
+
+    def __post_init__(self):
+        if self.status not in _SATISFIABILITY_STATUSES:
+            raise ValueError(
+                f"SatisfiabilityResult: unknown status {self.status!r} "
+                f"(use one of {_SATISFIABILITY_STATUSES})")
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "status": self.status,
+            "unfolded": self.unfolded.to_dict() if self.unfolded is not None else None,
+            "witness": self.witness,
+            "backend": self.backend,
+            "detail": self.detail,
+        }
+
+
+def check_satisfiable(name: str, definitions: Definitions, *,
+                      timeout: int = 10000,
+                      backends: Optional[Sequence[str]] = None,
+                      max_depth: int = DEFAULT_MAX_DEPTH,
+                      **options) -> SatisfiabilityResult:
+    """Is ``name``'s (unfolded) definition satisfiable by ANY object at all?
+
+    Decided by handing ``Not(unfold(name, definitions))`` to
+    :func:`unicode_logic_kit.api.prove` (empty premises, i.e. a validity check)
+    over its FOL backend chain (Z3, the kit's tableau/resolution provers, and
+    the finite model finder, by default — see
+    :func:`unicode_logic_kit.atp.protocol.default_chain`): proving
+    ``¬unfolded`` valid is exactly proving ``unfolded`` unsatisfiable, and
+    REFUTING ``¬unfolded`` means some backend produced an actual model of
+    ``unfolded`` — a genuine, checkable witness rather than a guess. This is
+    the "und/oder api.prove" reading: the model finder is already one member
+    of that chain, so this one call already uses both routes the finder and
+    the prover can offer.
+
+    ``backends``/``timeout``/``**options`` are forwarded verbatim to
+    :func:`~unicode_logic_kit.api.prove` — as there, extra ``options`` (e.g.
+    ``max_steps=``) are sent to EVERY backend in the chain, so only combine
+    them with an explicit single-backend ``backends=[...]`` list unless every
+    member of the chain genuinely accepts that keyword.
+
+    Raises:
+        KeyError: ``name`` is not a key of ``definitions``.
+        NonClosedDefinition: some body in ``definitions`` is not closed —
+            see :func:`unfold`.
+    """
+    if name not in definitions:
+        raise KeyError(
+            f"check_satisfiable: {name!r} is not a defined name "
+            f"(known: {sorted(definitions)})")
+    try:
+        unfolded = unfold(name, definitions, max_depth=max_depth)
+    except CyclicDefinition as exc:
+        return SatisfiabilityResult(name=name, status="cyclic", unfolded=None,
+                                    witness=None, backend=None, detail=str(exc))
+    except UnfoldDepthExceeded as exc:
+        # NOT the same finding as CyclicDefinition: budget exhaustion proves
+        # nothing about whether name's definition chain is actually acyclic
+        # (it may well be a long but perfectly acyclic hierarchy — see
+        # UnfoldDepthExceeded's own docstring) — reporting "cyclic" here would
+        # upgrade an undecided budget question into a PROVEN-defect claim
+        # (see TheoryReport.proved_problems, which treats "cyclic" as exactly
+        # that). Honest status is "unknown".
+        return SatisfiabilityResult(name=name, status="unknown", unfolded=None,
+                                    witness=None, backend=None, detail=str(exc))
+
+    from .. import api  # lazy: avoids importing the whole facade at module load
+
+    verdict = api.prove(Not(unfolded), timeout=timeout, backends=backends, **options)
+    if verdict.status == PROVED:
+        return SatisfiabilityResult(
+            name=name, status="unsatisfiable", unfolded=unfolded, witness=None,
+            backend=verdict.backend,
+            detail=f"{name} can hold of no object: its unfolded definition is a "
+                   f"contradiction, proved by {verdict.backend}.")
+    if verdict.status == REFUTED:
+        return SatisfiabilityResult(
+            name=name, status="satisfiable", unfolded=unfolded,
+            witness=verdict.countermodel, backend=verdict.backend,
+            detail=f"a model satisfying {name} was found by {verdict.backend}.")
+    return SatisfiabilityResult(
+        name=name, status="unknown", unfolded=unfolded, witness=None,
+        backend=verdict.backend if verdict.backend != "chain" else None,
+        detail=verdict.detail or "neither proved unsatisfiable nor witnessed "
+                                  "satisfiable within the given backend budget")
+
+
+# ---------------------------------------------------------------------------
+# Subsumption
+# ---------------------------------------------------------------------------
+
+_SUBSUMPTION_STATUSES = ("entailed", "refuted", "unknown", "cyclic")
+
+
+@dataclass(frozen=True)
+class SubsumptionResult:
+    """Outcome of :func:`check_subsumption` — does ``Def(sub) |= Def(sup)``?
+
+    ``status``:
+        ``"entailed"`` — PROVEN: every object satisfying ``sub``'s unfolded
+            definition also satisfies ``sup``'s.
+        ``"refuted"`` — PROVEN false: ``countermodel`` is ALWAYS populated
+            here (never ``None`` — see the defensive fallback in
+            :func:`check_subsumption`'s implementation), a concrete witness
+            where ``sub`` holds and ``sup`` does not. This is the module's
+            main value-add over a bare prover's witness-free "not proved": a
+            reader can see EXACTLY which conjunct of the superclass the
+            subclass definition forgot.
+        ``"unknown"`` — neither proved nor refuted within the backend
+            budget (e.g. a timeout, or a deliberately tiny step bound) —
+            NEVER reported as ``"refuted"``.
+        ``"cyclic"`` — ``sub`` or ``sup`` could not be unfolded (reachable
+            from a definitional cycle); ``verdict``/``countermodel`` are
+            ``None`` in this case.
+
+    ``verdict`` is the underlying :class:`~unicode_logic_kit.atp.protocol.Verdict`
+    (as a dict, via its own ``to_dict()``) for full provenance — ``None`` only
+    for ``"cyclic"``. ``explanation`` is a short plain-English gloss: for
+    ``"refuted"`` it is built the same way ``api.countermodel`` builds
+    ``explanation_nl`` (:func:`unicode_logic_kit.eval.explain.explain_countermodel`),
+    for every other status it falls back to the verdict's own ``detail``/the
+    cycle message.
+    """
+
+    sub: str
+    sup: str
+    status: str
+    verdict: Optional[dict]
+    countermodel: Optional[dict]
+    explanation: Optional[str]
+
+    def __post_init__(self):
+        if self.status not in _SUBSUMPTION_STATUSES:
+            raise ValueError(
+                f"SubsumptionResult: unknown status {self.status!r} "
+                f"(use one of {_SUBSUMPTION_STATUSES})")
+        if self.status == "refuted" and self.countermodel is None:
+            raise ValueError(
+                "SubsumptionResult: status='refuted' must always carry a "
+                "countermodel — a refutation claim with no witness is exactly "
+                "what this module exists to never emit (see check_subsumption's "
+                "defensive fallback, which downgrades to 'unknown' instead of "
+                "constructing a result like this).")
+
+    def to_dict(self) -> dict:
+        return {
+            "sub": self.sub,
+            "sup": self.sup,
+            "status": self.status,
+            "verdict": self.verdict,
+            "countermodel": self.countermodel,
+            "explanation": self.explanation,
+        }
+
+
+def check_subsumption(sub: str, sup: str, definitions: Definitions, *,
+                      timeout: int = 10000,
+                      backends: Optional[Sequence[str]] = None,
+                      max_depth: int = DEFAULT_MAX_DEPTH,
+                      **options) -> SubsumptionResult:
+    """Does ``Def(sub)`` entail ``Def(sup)`` — ``sub`` really a subclass?
+
+    Both definitions are unfolded (see :func:`unfold`), and
+    :func:`unicode_logic_kit.api.prove` is asked to decide
+    ``unfold(sub) -> unfold(sup)`` (empty premises: a plain validity check of
+    the implication) over its FOL backend chain. A ``"refuted"`` result is
+    NEVER handed back without a countermodel: if the chain's own
+    :class:`~unicode_logic_kit.atp.protocol.Verdict` reports REFUTED but (for
+    some backend combination) carries no witness, :func:`api.countermodel`
+    is tried once more before conceding — and if that also finds nothing,
+    the result is downgraded to ``"unknown"`` rather than asserting an
+    unwitnessed refutation (see :class:`SubsumptionResult`'s invariant).
+
+    ``backends``/``timeout``/``**options`` are forwarded verbatim to
+    :func:`~unicode_logic_kit.api.prove` — see :func:`check_satisfiable`'s
+    docstring for the same caveat about mixing ``**options`` with a
+    multi-backend chain.
+
+    Raises:
+        KeyError: ``sub`` or ``sup`` is not a key of ``definitions``.
+        NonClosedDefinition: some body in ``definitions`` is not closed —
+            see :func:`unfold`.
+    """
+    for role, class_name in (("sub", sub), ("sup", sup)):
+        if class_name not in definitions:
+            raise KeyError(
+                f"check_subsumption: {role}={class_name!r} is not a defined name "
+                f"(known: {sorted(definitions)})")
+
+    try:
+        unfolded_sub = unfold(sub, definitions, max_depth=max_depth)
+        unfolded_sup = unfold(sup, definitions, max_depth=max_depth)
+    except CyclicDefinition as exc:
+        return SubsumptionResult(sub=sub, sup=sup, status="cyclic", verdict=None,
+                                 countermodel=None, explanation=str(exc))
+    except UnfoldDepthExceeded as exc:
+        # See check_satisfiable's identical split: a depth-budget exhaustion
+        # is not a proof of a cycle (find_cycles proves that structurally,
+        # via find_cycles/CyclicDefinition), so it must not be reported as
+        # "cyclic" — that status is documented (TheoryReport.proved_problems)
+        # as a PROVEN defect. Honest status is "unknown".
+        return SubsumptionResult(sub=sub, sup=sup, status="unknown", verdict=None,
+                                 countermodel=None, explanation=str(exc))
+
+    from .. import api  # lazy, matching check_satisfiable
+
+    goal = Implies(unfolded_sub, unfolded_sup)
+    verdict = api.prove(goal, timeout=timeout, backends=backends, **options)
+
+    if verdict.status == PROVED:
+        return SubsumptionResult(
+            sub=sub, sup=sup, status="entailed", verdict=verdict.to_dict(),
+            countermodel=None,
+            explanation=f"Def({sub}) |= Def({sup}) — proved by {verdict.backend}.")
+
+    if verdict.status == REFUTED:
+        countermodel = verdict.countermodel
+        if countermodel is None:
+            # Defensive fallback: every default-chain member that can REFUTE
+            # (z3, modelfinder) already attaches one, but a caller-supplied
+            # backends= list could in principle name one that cannot (see
+            # VampireBackend's documented CounterSatisfiable-without-model
+            # case). Try the dedicated countermodel search once before
+            # conceding — see the module/class docstrings for why an
+            # unwitnessed "refuted" is never acceptable here.
+            cm_result = api.countermodel(goal, timeout=timeout, backends=backends)
+            countermodel = cm_result.model if cm_result.found else None
+        if countermodel is None:
+            return SubsumptionResult(
+                sub=sub, sup=sup, status="unknown", verdict=verdict.to_dict(),
+                countermodel=None,
+                explanation="a backend reported refutation without a recoverable "
+                            "countermodel witness; treated as undecided rather "
+                            "than asserting an unwitnessed refutation.")
+        explanation = None
+        try:
+            from .explain import explain_countermodel
+            explanation = explain_countermodel(countermodel)
+        except Exception:
+            pass
+        if explanation is None:
+            explanation = (f"{verdict.backend} found a countermodel: {sub} holds "
+                           f"but {sup} does not.")
+        return SubsumptionResult(
+            sub=sub, sup=sup, status="refuted", verdict=verdict.to_dict(),
+            countermodel=countermodel, explanation=explanation)
+
+    return SubsumptionResult(
+        sub=sub, sup=sup, status="unknown", verdict=verdict.to_dict(),
+        countermodel=None,
+        explanation=verdict.detail or "neither proved nor refuted within the "
+                                       "given backend budget")
+
+
+# ---------------------------------------------------------------------------
+# Whole-theory report
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class TheoryReport:
+    """The combined verification result over a definition set.
+
+    ``cycles`` is :func:`find_cycles`'s output (the authoritative structural
+    view — a name inside a cycle also shows up with ``status="cyclic"`` in
+    ``satisfiability``/``subsumptions``, individually, but ``cycles`` is what
+    names the actual loop). ``satisfiability`` covers EVERY name in the
+    definition set (not just ones mentioned in ``subsumptions``); a dead
+    classifier is exactly as reportable on its own as a broken subsumption.
+
+    :attr:`proved_problems` / :attr:`undecided` are the split the module
+    docstring promises: the first is every finding this module actually
+    PROVED (a cycle, an unsatisfiable definition, a refuted subsumption —
+    each with its evidence), the second is every finding that stayed
+    genuinely open. A caller building a pass/fail gate should fail on the
+    first and merely flag the second for human attention.
+    """
+
+    cycles: Tuple[Tuple[str, ...], ...]
+    satisfiability: Mapping[str, SatisfiabilityResult]
+    subsumptions: Tuple[SubsumptionResult, ...]
+
+    @property
+    def proved_problems(self) -> Tuple[dict, ...]:
+        """Every DEFINITIVELY established defect — never an 'unknown'."""
+        problems = []
+        for cycle in self.cycles:
+            problems.append({"kind": "cycle", "names": list(cycle)})
+        for name, result in sorted(self.satisfiability.items()):
+            if result.status == "unsatisfiable":
+                problems.append({"kind": "unsatisfiable", "name": name,
+                                 "detail": result.detail})
+        for result in self.subsumptions:
+            if result.status == "refuted":
+                problems.append({"kind": "subsumption_refuted", "sub": result.sub,
+                                 "sup": result.sup, "explanation": result.explanation})
+        return tuple(problems)
+
+    @property
+    def undecided(self) -> Tuple[dict, ...]:
+        """Every check that ended in 'unknown' — genuinely open, not a defect."""
+        open_items = []
+        for name, result in sorted(self.satisfiability.items()):
+            if result.status == "unknown":
+                open_items.append({"kind": "satisfiability", "name": name,
+                                   "detail": result.detail})
+        for result in self.subsumptions:
+            if result.status == "unknown":
+                open_items.append({"kind": "subsumption", "sub": result.sub,
+                                   "sup": result.sup, "detail": result.explanation})
+        return tuple(open_items)
+
+    def to_dict(self) -> dict:
+        return {
+            "cycles": [list(c) for c in self.cycles],
+            "satisfiability": {name: r.to_dict()
+                               for name, r in sorted(self.satisfiability.items())},
+            "subsumptions": [r.to_dict() for r in self.subsumptions],
+            "proved_problems": list(self.proved_problems),
+            "undecided": list(self.undecided),
+        }
+
+    def to_markdown(self) -> str:
+        """Render this report as a plain-formatted Markdown document.
+
+        One top summary line (:attr:`proved_problems` vs :attr:`undecided`
+        counts), then a section each for ``cycles`` (the name chains
+        :func:`find_cycles` found), ``satisfiability`` (grouped by status; a
+        ``"satisfiable"`` witness is glossed by :func:`_witness_gloss` when
+        one was recovered — honestly, as an existential witness rather than
+        an implication countermodel; see that function's own docstring and
+        :class:`SatisfiabilityResult`), and ``subsumptions`` (grouped by
+        status; each row's own ``.explanation`` is rendered verbatim,
+        falling back to
+        :func:`~unicode_logic_kit.eval.explain.explain_countermodel` on
+        ``.countermodel`` only in the defensive case where ``.explanation``
+        is itself ``None``).
+
+        Every rendered name/detail/explanation is put through
+        :func:`_md_cell`, so a hostile string (one containing ``|`` or a
+        newline — a molecule name or an error message is never under this
+        module's control) cannot corrupt a table's row/column structure.
+        Calling this twice on the same report always returns the identical
+        string (nothing here depends on dict/set iteration order — every
+        grouping is walked in the fixed, sorted order already used by
+        :meth:`to_dict`/:attr:`proved_problems`).
+        """
+        return "\n".join(_theory_markdown_lines(self))
+
+    def to_html(self, title: str = "Theory report") -> str:
+        """Render as a self-contained, theme-aware HTML page.
+
+        Same idiom as :meth:`unicode_logic_kit.fol.derivation.CCGDerivation.to_html`
+        and the ``atp`` Fitch/sequent renderers built on
+        :mod:`unicode_logic_kit.atp._html`: one ``<!doctype html>`` page with
+        the shared colour tokens, headings/tables for the same three sections
+        :meth:`to_markdown` renders, and every user-supplied string
+        (definition name, detail, explanation) HTML-escaped via
+        :func:`~unicode_logic_kit.atp._html.esc_html`.
+        """
+        return html_page(title, _theory_html_body(self), _THEORY_HTML_CSS)
+
+
+def check_theory(definitions: Definitions, *,
+                 subsumptions: Sequence[Tuple[str, str]] = (),
+                 timeout: int = 10000,
+                 backends: Optional[Sequence[str]] = None,
+                 max_depth: int = DEFAULT_MAX_DEPTH,
+                 **options) -> TheoryReport:
+    """Run every check this module offers over a whole definition set.
+
+    Cycles (:func:`find_cycles`), satisfiability of every definition
+    (:func:`check_satisfiable`, one call per name), and every requested
+    subsumption pair (:func:`check_subsumption`, one call per pair in
+    ``subsumptions``) — see :class:`TheoryReport` for how the results are
+    organised and split into proved-vs-undecided. ``timeout``/``backends``/
+    ``max_depth``/``**options`` apply uniformly to every underlying call.
+
+    Raises:
+        KeyError: a name in ``subsumptions`` is not a key of ``definitions``.
+        NonClosedDefinition: some body in ``definitions`` is not closed —
+            see :func:`unfold`. Raised by the first underlying
+            :func:`check_satisfiable`/:func:`check_subsumption` call that
+            reaches it, so ``cycles`` (computed first, structurally, with no
+            unfolding involved) is never the cause of this and is simply not
+            returned when it happens.
+    """
+    cycles = find_cycles(definitions)
+    satisfiability = {
+        name: check_satisfiable(name, definitions, timeout=timeout,
+                                backends=backends, max_depth=max_depth, **options)
+        for name in sorted(definitions)
+    }
+    sub_results = tuple(
+        check_subsumption(sub, sup, definitions, timeout=timeout,
+                          backends=backends, max_depth=max_depth, **options)
+        for sub, sup in subsumptions
+    )
+    return TheoryReport(cycles=cycles, satisfiability=satisfiability,
+                        subsumptions=sub_results)
+
+
+# ---------------------------------------------------------------------------
+# TheoryReport.to_markdown() / to_html() — display only, no new proof/model-
+# finding logic (see the roadmap item this implements: a pure formatting
+# layer over already-verified TheoryReport/SatisfiabilityResult/
+# SubsumptionResult data, so it introduces no soundness risk).
+# ---------------------------------------------------------------------------
+
+def _md_cell(value) -> str:
+    """Escape a value for safe embedding in one Markdown table cell.
+
+    A bare ``|`` would be read as a new column and an embedded newline would
+    split the row across lines, silently corrupting every column after it —
+    so both are neutralised. This only ever touches the RENDERED copy: the
+    original string on the result object is never modified.
+    """
+    text = "" if value is None else str(value)
+    text = text.replace("|", "\\|")
+    return text.replace("\r\n", " ").replace("\n", " ").replace("\r", " ")
+
+
+def _witness_gloss(witness: Optional[dict]) -> Optional[str]:
+    """A short, honest gloss of a :class:`SatisfiabilityResult` witness, or
+    ``None`` if there is none.
+
+    ``witness`` here is documented (see :class:`SatisfiabilityResult`) to be
+    in the exact same JSON-able shape as
+    :class:`~unicode_logic_kit.atp.protocol.Verdict.countermodel` — but it is
+    NOT itself an implication countermodel: :func:`check_satisfiable` proves
+    ``Not(unfolded)`` REFUTED with EMPTY premises, so the model this witness
+    describes is a single-formula existential witness of ``unfolded``, not a
+    model where "premises hold and the goal fails" (the shape an actual
+    countermodel, e.g. :class:`SubsumptionResult`'s, has).
+    :func:`~unicode_logic_kit.eval.explain.explain_countermodel`'s Z3-assignment
+    branch is hardcoded to that implication wording ("... the two sides
+    differ"), which would misstate what was computed here — so any witness
+    carrying an ``"assignment"`` dict (a bare ``{name: value}`` witness, or a
+    ``{"kind": ..., "assignment": {...}}`` one — ``"z3_model"`` is the common
+    case since Z3 leads the default backend chain, but
+    :mod:`unicode_logic_kit.atp.cvc5_backend` emits the identical
+    ``{"kind": "cvc5_model", "assignment": {...}}`` shape and would otherwise
+    have no branch of its own here) is glossed locally instead, via
+    :func:`_z3_satisfiability_gloss`. This mirrors
+    :func:`unicode_logic_kit.eval.chem_batch._gloss_chem_witness`'s reasoning
+    for the exact same class of problem on that module's own (differently
+    shaped) row witnesses.
+
+    Every other witness kind that carries a ``"repr"`` fallback (a Kripke
+    model, the modelfinder's own ``{"kind": "finite_structure", "repr": ...}``,
+    a Nitpick counterexample, ...) has no implication-specific sentence in
+    :func:`explain_countermodel`'s output, so those are still glossed through
+    it as-is — reusing its richer world/domain/relation rendering rather than
+    duplicating it. A witness with neither an ``"assignment"`` dict nor a
+    ``"repr"`` key — e.g. the clingo/minizinc backends' own
+    ``{"kind": "finite_structure", "data": {...}}`` (a different key from the
+    modelfinder's ``"repr"`` shape above) — would make
+    :func:`explain_countermodel` raise ``ValueError`` (it has nothing to
+    explain), which must never propagate out of a report-rendering method, so
+    that case falls back to :func:`_generic_satisfiability_gloss` instead.
+    """
+    if witness is None:
+        return None
+    kind = witness.get("kind") if isinstance(witness, dict) else None
+    assignment: Optional[dict] = None
+    if isinstance(witness, dict):
+        if kind is None:
+            assignment = witness  # bare {name: value}, no "kind" key
+        elif isinstance(witness.get("assignment"), dict):
+            assignment = witness["assignment"]  # any *_model kind: z3_model, cvc5_model, ...
+    if assignment is not None:
+        return _z3_satisfiability_gloss(assignment)
+    if isinstance(witness, dict) and "repr" in witness:
+        from .explain import explain_countermodel  # lazy, mirrors check_subsumption's own import
+        return explain_countermodel(witness)
+    return _generic_satisfiability_gloss(witness)
+
+
+def _z3_satisfiability_gloss(assignment: dict) -> str:
+    """Render a Z3/cvc5-style ``{name: value}`` SATISFIABILITY witness
+    honestly.
+
+    Despite the name (kept for the common Z3 case, and for the existing test
+    surface), this is used for any backend's ``"assignment"``-shaped witness
+    — see :func:`_witness_gloss`'s docstring. Deliberately NOT
+    :func:`~unicode_logic_kit.eval.explain.explain_countermodel`: this
+    assignment satisfies the definition directly — there is no second side
+    to compare it against, and that function does not accept a non-Z3 kind
+    with an assignment at all (it would raise).
+    """
+    if not assignment:
+        return "a model was found, but it recorded no variable assignments."
+    items = sorted(assignment.items(), key=lambda kv: str(kv[0]))
+    assigned_str = ", ".join(f"{k} := {v}" for k, v in items)
+    return f"Under the assignment {assigned_str}, the definition is satisfied."
+
+
+def _generic_satisfiability_gloss(witness: object) -> str:
+    """A minimal, honest, NEVER-raising gloss for a satisfiability witness
+    that :func:`_witness_gloss` could not route anywhere more specific: no
+    ``"assignment"`` dict (so :func:`_z3_satisfiability_gloss` does not
+    apply) and no ``"repr"`` fallback (so
+    :func:`~unicode_logic_kit.eval.explain.explain_countermodel` would raise
+    ``ValueError`` rather than render anything).
+
+    The real shape hitting this today is the clingo/minizinc backends'
+    ``{"kind": "finite_structure", "data": {...}}`` (see
+    ``unicode_logic_kit.atp.clingo_backend``/``minizinc_backend``) — a
+    ``"data"`` key, not the modelfinder's own ``"repr"``-carrying shape of
+    the same ``"kind"``. Deliberately does not attempt to parse or
+    pretty-print ``"data"``: that would risk a shape-specific, silently
+    incomplete duplication of what the backend already encodes, for a
+    one-line table cell that only needs to say a model exists.
+    """
+    kind = witness.get("kind") if isinstance(witness, dict) else None
+    label = kind if kind else "unlabelled"
+    return f'A "{label}" model was found; the definition is satisfied.'
+
+
+def _subsumption_explanation(result: "SubsumptionResult") -> Optional[str]:
+    """``result.explanation`` if set, else a best-effort fallback computed
+    from ``result.countermodel`` — never raising, and never glossing a
+    countermodel as a refutation outside ``status="refuted"``.
+
+    Unlike a :class:`SatisfiabilityResult` witness (see :func:`_witness_gloss`),
+    a :class:`SubsumptionResult` countermodel genuinely IS an implication
+    countermodel when ``status == "refuted"`` (``check_subsumption`` proves
+    ``Def(sub) -> Def(sup)`` REFUTED, i.e. finds a model where ``sub`` holds
+    and ``sup`` does not), so :func:`~unicode_logic_kit.eval.explain.explain_countermodel`'s
+    wording is the right one there — this is not the satisfiability-witness
+    deviation. But ``SubsumptionResult.__post_init__`` only requires
+    ``countermodel is not None`` when ``status == "refuted"``; it never
+    forbids a countermodel from also being present alongside
+    ``status in ("unknown", "entailed", "cyclic")`` on a hand-built instance
+    (as this file's own tests build throughout), and this module's own
+    docstring promises ``"unknown"`` is NEVER reported as ``"refuted"`` — so
+    the countermodel-based fallback below is only ever computed for
+    ``status == "refuted"``, matching what ``check_subsumption`` itself ever
+    produces.
+
+    ``check_subsumption`` itself always sets ``explanation`` to a non-``None``
+    string (it wraps its own ``explain_countermodel`` call in
+    ``try/except Exception`` and falls back to a generic sentence — see that
+    function's body), so this fallback path is never hit by the module's own
+    top-level API. But ``SubsumptionResult`` is a public dataclass whose
+    ``__post_init__`` never requires ``explanation`` to be set. A caller
+    building one by hand can therefore reach a ``status="refuted"``,
+    ``explanation=None`` object carrying a countermodel shape
+    ``explain_countermodel`` cannot handle — a bare
+    ``cvc5_model``/``finite_structure``-without-``repr`` witness, for
+    instance — and a report renderer must never crash on that, so the same
+    guard ``check_subsumption`` uses internally is mirrored here.
+    """
+    if result.explanation is not None:
+        return result.explanation
+    if result.status != "refuted" or result.countermodel is None:
+        return None
+    try:
+        from .explain import explain_countermodel
+        return explain_countermodel(result.countermodel)
+    except Exception:
+        backend = None
+        if isinstance(result.verdict, dict):
+            backend = result.verdict.get("backend")
+        who = backend or "a backend"
+        return (f"{who} found a countermodel: {result.sub} holds "
+                f"but {result.sup} does not.")
+
+
+def _theory_markdown_lines(report: TheoryReport) -> List[str]:
+    lines: List[str] = ["# Theory report", ""]
+    lines.append(f"**{len(report.proved_problems)}** proved problem(s), "
+                 f"**{len(report.undecided)}** undecided.")
+    lines.append("")
+
+    lines.append("## Cycles")
+    lines.append("")
+    if report.cycles:
+        for cycle in report.cycles:
+            lines.append("- " + " -> ".join(_md_cell(name) for name in cycle))
+    else:
+        lines.append("No cycles.")
+    lines.append("")
+
+    lines.append("## Satisfiability")
+    lines.append("")
+    by_status: Dict[str, List[SatisfiabilityResult]] = {}
+    for _, result in sorted(report.satisfiability.items()):
+        by_status.setdefault(result.status, []).append(result)
+    if not by_status:
+        lines.append("No definitions.")
+    for status in _SATISFIABILITY_STATUSES:
+        results = by_status.get(status)
+        if not results:
+            continue
+        lines.append(f"### {status}")
+        lines.append("")
+        lines.append("| name | detail |")
+        lines.append("|---|---|")
+        for result in results:
+            detail = result.detail or ""
+            # Only "satisfiable" is documented to carry a witness (see
+            # SatisfiabilityResult's docstring); __post_init__ does not
+            # forbid a witness on another status on a hand-built instance,
+            # so gate on status here rather than on witness truthiness alone
+            # to avoid glossing e.g. an "unsatisfiable" result as if a model
+            # were found.
+            gloss = _witness_gloss(result.witness) if result.status == "satisfiable" else None
+            if gloss:
+                detail = f"{detail} {gloss}".strip()
+            lines.append(f"| {_md_cell(result.name)} | {_md_cell(detail)} |")
+        lines.append("")
+
+    lines.append("## Subsumptions")
+    lines.append("")
+    sub_by_status: Dict[str, List[SubsumptionResult]] = {}
+    for result in report.subsumptions:
+        sub_by_status.setdefault(result.status, []).append(result)
+    if not sub_by_status:
+        lines.append("No subsumption checks.")
+    for status in _SUBSUMPTION_STATUSES:
+        results = sub_by_status.get(status)
+        if not results:
+            continue
+        lines.append(f"### {status}")
+        lines.append("")
+        lines.append("| sub | sup | explanation |")
+        lines.append("|---|---|---|")
+        for result in results:
+            explanation = _subsumption_explanation(result)
+            lines.append(f"| {_md_cell(result.sub)} | {_md_cell(result.sup)} | "
+                         f"{_md_cell(explanation)} |")
+        lines.append("")
+
+    while lines and lines[-1] == "":
+        lines.pop()
+    lines.append("")
+    return lines
+
+
+_THEORY_HTML_CSS = """
+.rpt{max-width:900px;margin:0 auto;padding:26px 16px;
+  font-family:ui-sans-serif,system-ui,"Segoe UI",Arial,sans-serif;
+  font-size:14px;line-height:1.5}
+.rpt h1{font-size:20px;margin:0 0 8px}
+.rpt h2{font-size:16px;margin:22px 0 6px;border-bottom:1.3px solid var(--bar);padding-bottom:3px}
+.rpt h3{font-size:12.5px;margin:14px 0 4px;color:var(--muted);
+  text-transform:uppercase;letter-spacing:.03em}
+.rpt table{border-collapse:collapse;width:100%;margin:4px 0 14px}
+.rpt th,.rpt td{border:1px solid var(--bar);padding:4px 8px;text-align:left;
+  vertical-align:top}
+.rpt th{color:var(--muted);font-weight:600}
+.rpt ul{margin:6px 0 14px;padding-left:22px}
+.rpt .muted{color:var(--muted)}
+"""
+
+
+def _status_table(rows: List[Tuple[str, ...]], headers: Tuple[str, ...]) -> str:
+    head = "".join("<th>%s</th>" % esc_html(h) for h in headers)
+    body = "".join(
+        "<tr>%s</tr>" % "".join("<td>%s</td>" % esc_html(cell) for cell in row)
+        for row in rows
+    )
+    return "<table><tr>%s</tr>%s</table>" % (head, body)
+
+
+def _theory_html_body(report: TheoryReport) -> str:
+    parts: List[str] = ['<div class="rpt">', "<h1>Theory report</h1>",
+                        "<p>%d proved problem(s), %d undecided.</p>"
+                        % (len(report.proved_problems), len(report.undecided))]
+
+    parts.append("<h2>Cycles</h2>")
+    if report.cycles:
+        items = "".join("<li>%s</li>" % esc_html(" -> ".join(cycle))
+                        for cycle in report.cycles)
+        parts.append("<ul>%s</ul>" % items)
+    else:
+        parts.append('<p class="muted">No cycles.</p>')
+
+    parts.append("<h2>Satisfiability</h2>")
+    by_status: Dict[str, List[SatisfiabilityResult]] = {}
+    for _, result in sorted(report.satisfiability.items()):
+        by_status.setdefault(result.status, []).append(result)
+    if not by_status:
+        parts.append('<p class="muted">No definitions.</p>')
+    for status in _SATISFIABILITY_STATUSES:
+        results = by_status.get(status)
+        if not results:
+            continue
+        rows = []
+        for result in results:
+            detail = result.detail or ""
+            # See the matching comment in _theory_markdown_lines: gate on
+            # status, not witness truthiness, so only "satisfiable" ever
+            # gets model-found prose.
+            gloss = _witness_gloss(result.witness) if result.status == "satisfiable" else None
+            if gloss:
+                detail = f"{detail} {gloss}".strip()
+            rows.append((result.name, detail))
+        parts.append("<h3>%s</h3>" % esc_html(status))
+        parts.append(_status_table(rows, ("name", "detail")))
+
+    parts.append("<h2>Subsumptions</h2>")
+    sub_by_status: Dict[str, List[SubsumptionResult]] = {}
+    for result in report.subsumptions:
+        sub_by_status.setdefault(result.status, []).append(result)
+    if not sub_by_status:
+        parts.append('<p class="muted">No subsumption checks.</p>')
+    for status in _SUBSUMPTION_STATUSES:
+        results = sub_by_status.get(status)
+        if not results:
+            continue
+        rows = []
+        for result in results:
+            explanation = _subsumption_explanation(result)
+            rows.append((result.sub, result.sup, explanation or ""))
+        parts.append("<h3>%s</h3>" % esc_html(status))
+        parts.append(_status_table(rows, ("sub", "sup", "explanation")))
+
+    parts.append("</div>")
+    return "".join(parts)