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

unicode_logic_kit/eval/converses.py

@@ -0,0 +1,200 @@
+"""Declared converse / argument-permutation axioms — an opt-in equivalence bridge.
+
+Two predicates can denote the same relation with their arguments swapped —
+``LovedBy(x, y)`` and ``Loves(y, x)`` — or, more generally, permuted for any
+arity: ``Between(a, b, c)`` and ``BetweenRev(c, b, a)``. Neither
+:func:`~unicode_logic_kit.eval.canonical.exact_match` (which never renames a
+predicate) nor :func:`~unicode_logic_kit.eval.predicate_match.align_symbols`
+(which renames predicate *names* but never touches argument *order* — see
+that module's docstring) closes this gap, and deliberately so: automatically
+GUESSING that ``LovedBy``/``Loves`` are converses from lexical similarity
+alone is undecidable-from-the-AST and would just as happily "forgive" a
+genuine subject/object-swap translation ERROR (see roadmap item C32's
+rejection). This module takes the opposite approach: the CALLER declares the
+bridge explicitly, per comparison, and only the solver level of
+:func:`unicode_logic_kit.eval.equivalence.equivalent` ever consumes it — see
+that module for how ``converses=`` is threaded through and tagged with its
+own ``method_used`` value (``"solver_modulo_converses"``), never merged into
+plain equivalence.
+
+A declaration is a plain, JSON-friendly 3-tuple::
+
+    (a_key, b_key, permutation)
+
+where ``a_key`` / ``b_key`` are ``(name, arity)`` predicate keys — the same
+convention :mod:`~unicode_logic_kit.eval.predicate_match` uses for its own
+symbol inventories — and ``permutation`` is a tuple of ``arity`` distinct
+indices into ``range(arity)``. :func:`converse_axioms` turns a list of these
+into one closed biconditional sentence per declaration:
+
+    ∀v0 … v_{n-1} (A(v0, …, v_{n-1}) ↔ B(v_perm[0], …, v_perm[n-1]))
+
+so ``(("LovedBy", 2), ("Loves", 2), (1, 0))`` builds
+``∀v0 ∀v1 (LovedBy(v0, v1) ↔ Loves(v1, v0))``. :func:`validate_converses`
+runs the structural sanity checks (arity match, permutation validity,
+no self-pair, no built-in predicate, no duplicate/contradictory pair) that
+:func:`converse_axioms` also runs internally before building anything, so a
+malformed declaration is refused with :class:`ValueError` before any Z3 call
+is even attempted.
+
+On the Z3-domain-sort question a caller might reasonably worry about: this
+kit's whole classical export (:class:`~unicode_logic_kit.fol.nodes.Z3Env`) uses
+exactly ONE Z3 sort for every term, always (``_SORT = z3.DeclareSort("S")`` in
+``fol/_fol_nodes.py`` — confirmed by inspection, the only ``DeclareSort`` call
+in the codebase), and a predicate is interned purely by ``(name, arity)`` —
+its Z3 domain is always ``[_SORT] * arity``, regardless of whether the atom
+sits under a plain :class:`~unicode_logic_kit.fol.nodes.Quantifier` or under a
+:class:`~unicode_logic_kit.fol.nodes.SortedQuantifier` (which auto-relativises
+to plain FOL over the SAME single sort, guarded by a unary sort-membership
+predicate — see ``fol._msfl_nodes.to_fol``). So a plain, unsorted axiom built
+here for a predicate pair ``(name, arity)`` interns to the IDENTICAL Z3
+function declaration the compared formulas themselves use for that pair,
+many-sorted or not — there is no second Z3 domain-sort family for it to
+silently diverge into. See :mod:`unicode_logic_kit.eval.equivalence`'s
+docstring for the differential test that proves this bridges correctly under
+:class:`~unicode_logic_kit.fol.nodes.SortedQuantifier` input, not just for
+unsorted formulas.
+"""
+
+from typing import Sequence, Tuple
+
+from unicode_logic_kit.fol.nodes import Node, Atom, Iff, Quantifier, Variable
+from .validate import _BUILTIN_PREDS
+
+__all__ = ["ConverseDeclaration", "validate_converses", "converse_axioms"]
+
+#: A predicate symbol key: ``(name, arity)`` — the same convention
+#: :data:`unicode_logic_kit.eval.predicate_match._SymKey` uses.
+_SymKey = Tuple[str, int]
+
+#: One declared converse: ``A`` (natural argument order) is biconditional
+#: with ``B`` applied to ``A``'s arguments permuted by ``permutation`` — see
+#: the module docstring for the exact axiom shape.
+ConverseDeclaration = Tuple[_SymKey, _SymKey, Tuple[int, ...]]
+
+
+def validate_converses(declarations: Sequence[ConverseDeclaration]) -> None:
+    """Raise :class:`ValueError` for any structurally invalid declaration.
+
+    Checked per declaration, in this order:
+
+    * ``a_key`` and ``b_key`` have the same arity (a converse cannot relate
+      predicates of different arity — there is no argument permutation
+      between them);
+    * ``permutation`` has exactly ``arity`` entries;
+    * ``permutation`` is a bijection on ``range(arity)`` (every position
+      0..arity-1 appears exactly once — a real permutation, not a partial or
+      repeating map that would silently drop or duplicate an argument);
+    * ``a_key != b_key`` (a predicate cannot be declared its own converse);
+    * neither predicate name is a built-in (``=``, ``≠``, ``<``, ``>``, ``≤``,
+      ``≥`` — see :data:`unicode_logic_kit.eval.validate._BUILTIN_PREDS`), since
+      those already have fixed Z3 semantics an extra biconditional cannot
+      touch meaningfully and must not be allowed to appear to.
+
+    Checked across the whole list: the same UNORDERED pair ``{a_key, b_key}``
+    is never declared twice — this single check also catches two genuinely
+    CONTRADICTORY declarations for the same pair (e.g. two different
+    permutations for ``{LovedBy, Loves}``), since both shapes collide on the
+    same unordered-pair key. A chain of declarations over DISTINCT pairs
+    (``A~B``, ``B~C``) is explicitly allowed and composes correctly — each
+    axiom is independent, so the solver sees both biconditionals as separate
+    premises.
+
+    Never touches Z3 or any other backend — pure structural validation over
+    the declarations alone, so it is always safe (and cheap) to call before
+    committing to a solver run.
+    """
+    seen_pairs: set = set()
+    for a_key, b_key, permutation in declarations:
+        a_name, a_arity = a_key
+        b_name, b_arity = b_key
+
+        if a_arity != b_arity:
+            raise ValueError(
+                f"validate_converses: arity mismatch between {a_key!r} and "
+                f"{b_key!r} — a converse permutation needs equal arity")
+
+        if len(permutation) != a_arity:
+            raise ValueError(
+                f"validate_converses: permutation {permutation!r} has "
+                f"{len(permutation)} entries, expected {a_arity} for {a_key!r}")
+
+        if sorted(permutation) != list(range(a_arity)):
+            raise ValueError(
+                f"validate_converses: permutation {permutation!r} for "
+                f"{a_key!r} is not a bijection on range({a_arity})")
+
+        if a_key == b_key:
+            raise ValueError(
+                f"validate_converses: {a_key!r} cannot be declared its own "
+                "converse")
+
+        for name in (a_name, b_name):
+            if name in _BUILTIN_PREDS:
+                raise ValueError(
+                    f"validate_converses: {name!r} is a built-in predicate "
+                    "and cannot be declared a converse")
+
+        pair = frozenset((a_key, b_key))
+        if pair in seen_pairs:
+            raise ValueError(
+                f"validate_converses: the pair {{{a_key!r}, {b_key!r}}} is "
+                "already declared — a predicate pair may only be declared "
+                "converses once (this also rejects two contradictory "
+                "permutations for the same pair)")
+        seen_pairs.add(pair)
+
+
+def converse_axioms(declarations: Sequence[ConverseDeclaration]) -> Tuple[Node, ...]:
+    """Build one closed biconditional sentence per declared converse.
+
+    Validates first (:func:`validate_converses` — every declaration must be
+    structurally sound before anything is built) and then, for each
+    ``(a_key, b_key, permutation)`` with ``a_key = (a_name, arity)`` and
+    ``b_key = (b_name, _)``, builds fresh bound variables ``v0 .. v_{n-1}``
+    (fresh PER AXIOM — reused across axioms is fine, since each axiom is its
+    own independently-scoped closed sentence, but never shared with the
+    caller's own formulas) and the sentence::
+
+        ∀v0 … v_{n-1} (A(v0, …, v_{n-1}) ↔ B(v_perm[0], …, v_perm[n-1]))
+
+    i.e. ``A``'s arguments are the fresh variables in NATURAL order and
+    ``B``'s are the same variables reordered by ``permutation`` — so
+    ``permutation=(1, 0)`` for a binary pair yields
+    ``A(v0, v1) ↔ B(v1, v0)``, the plain converse reading.
+
+    Each returned sentence is a pure biconditional between two otherwise-
+    unconstrained (uninterpreted) predicates — a DEFINITIONAL extension: for
+    any valuation of one side there is always a valuation of the other that
+    satisfies the axiom, so asserting it can never make a previously
+    satisfiable axiom set unsatisfiable, and can never manufacture an
+    entailment between predicates it does not mention (see
+    :mod:`unicode_logic_kit.eval.equivalence`'s module docstring for the
+    worked-through soundness argument this relies on).
+
+    Returns:
+        A tuple of closed :class:`~unicode_logic_kit.fol.nodes.Node` sentences,
+        same length and order as ``declarations``, each ``.to_z3()``-able and
+        ``.to_unicode_str()``-able like any other formula node.
+
+    Raises:
+        ValueError: via :func:`validate_converses`, if any declaration is
+            structurally invalid.
+    """
+    validate_converses(declarations)
+
+    axioms = []
+    for a_key, b_key, permutation in declarations:
+        a_name, arity = a_key
+        b_name, _b_arity = b_key
+
+        variables = tuple(Variable(f"v{j}") for j in range(arity))
+        atom_a = Atom(a_name, variables)
+        atom_b = Atom(b_name, tuple(variables[p] for p in permutation))
+
+        axiom: Node = Iff(atom_a, atom_b)
+        for v in reversed(variables):
+            axiom = Quantifier("∀", v, axiom)
+        axioms.append(axiom)
+
+    return tuple(axioms)

unicode_logic_kit/eval/datasets/__init__.py

@@ -0,0 +1,136 @@
+"""NL→logic benchmark adapters, plus a known_bad / self-audit mechanic for
+finding defective gold FOL annotations.
+
+Every adapter normalises its source rows into the SAME
+:class:`DatasetExample` shape (see its docstring for the field mapping each
+one uses), so downstream evaluation code can iterate a mixed pipeline without
+caring which dataset an example came from:
+
+    from unicode_logic_kit.eval.datasets import load_folio, load_groves, audit_examples
+
+    examples = list(load_folio("folio-validation.jsonl", known_bad_ids={"folio:17"}))
+    report = audit_examples(examples)          # finds parse/well-formedness defects
+    broken = [r for r in report if not r["ok"]]
+
+The adapters (each module's docstring names its VERIFIED upstream source,
+field schema, license, and every honest limitation; provenance is also
+collected machine-readably in :data:`DATASET_INFO`):
+
+- :mod:`~unicode_logic_kit.eval.datasets.folio` — FOLIO: premises/conclusion
+  with entailment labels AND gold FOL.
+- :mod:`~unicode_logic_kit.eval.datasets.malls` — MALLS: NL→FOL translation
+  pairs (GPT-4-generated).
+- :mod:`~unicode_logic_kit.eval.datasets.groves` — GROVES (this repo's author's
+  dataset): NL→FOL translation pairs in this kit's own Unicode notation.
+- :mod:`~unicode_logic_kit.eval.datasets.willow` — WillowNLtoFOL: NL→FOL
+  translation pairs (one of GROVES's NL sources).
+- :mod:`~unicode_logic_kit.eval.datasets.prontoqa` — ProntoQA (Logic-LM
+  rendering): NL QA plus a Logic-LM DSL program per example, with
+  :func:`~unicode_logic_kit.eval.datasets.prontoqa.parse_logic_program` (DSL →
+  kit AST) and :func:`~unicode_logic_kit.eval.datasets.prontoqa.solve_example`
+  (end-to-end deciding via ``api.prove``).
+- :mod:`~unicode_logic_kit.eval.datasets.proofwriter` — ProofWriter, two
+  routes: :func:`load_proofwriter` reads the flat tasksource mirror (NL text
+  only, NO FOL gold; CWA/OWA label caveat in the module docstring), and
+  :func:`load_proofwriter_structured` reads the structured OWA distribution
+  and GENERATES FOL deterministically from the dataset's own triple/rule
+  representations (marked ``meta["fol_generated"]``;
+  :func:`~unicode_logic_kit.eval.datasets.proofwriter.solve_structured_example`
+  decides each question against its OWA label).
+- :mod:`~unicode_logic_kit.eval.datasets.logicnli` — LogicNLI: NLI-style FOL
+  reasoning; the upstream structured logic annotation is preserved in
+  ``meta``, not presented as gold FOL formula strings (it is not).
+- :mod:`~unicode_logic_kit.eval.datasets.proverqa` — ProverQA: FOL-annotated QA
+  whose gold formulas use the OPPOSITE naming convention from this kit's
+  grammar (snake_case predicates, capitalised constants). The loader parses
+  them with a dedicated import-time dialect grammar and re-emits kit
+  notation (originals + injective name mapping in ``meta``;
+  ``convert_fol=False`` restores the verbatim 0%-parse pass-through);
+  :func:`~unicode_logic_kit.eval.datasets.proverqa.solve_example` decides each
+  example end-to-end. Willow gets the same treatment for its ~1.2% tail via
+  :func:`~unicode_logic_kit.eval.datasets.willow.repair_willow_formula`
+  (NLTK-precedence reading, minimal renaming).
+
+- :mod:`~unicode_logic_kit.eval.datasets.fracas` — FraCaS: the one PURE-NLI
+  adapter, premises/hypothesis/three-valued answer with no logic annotation
+  anywhere (its gold ``yes``/``no``/``unknown`` maps onto ``⊨ h`` / ``⊨ ¬h``
+  / neither exactly, so it is a reference target for a translation step that
+  lives outside this library —
+  :func:`~unicode_logic_kit.eval.datasets.fracas.solve_example` takes that
+  translation as an injected callable). ``fol_premises`` is always empty, so
+  :func:`audit_examples` is vacuous on it;
+  :func:`~unicode_logic_kit.eval.datasets.fracas.ace_census` reports, per
+  sentence, what APE accepts as controlled English.
+- :mod:`~unicode_logic_kit.eval.datasets.pmb` — PMB (Parallel Meaning Bank): the
+  only adapter with no ready-made NL/FOL pair file — gold FOL is produced by
+  reading each document's own DRS (in SBN notation) through
+  :mod:`unicode_logic_kit.drt`, and a document this subset's grammar cannot
+  parse still yields an example, with the refusal recorded in
+  ``meta["parse_error"]`` rather than dropped.
+- :mod:`~unicode_logic_kit.eval.datasets.pfolio` — P-FOLIO: FOLIO's own
+  entailment labels, joined against a bundled, human-written step-by-step
+  derivation per conclusion (``meta["proof_steps"]``); every join is
+  cross-checked against ``FOLIO.csv``'s own truth value, never merged
+  silently, and a disagreement is refused rather than guessed
+  (:func:`~unicode_logic_kit.eval.datasets.pfolio.pfolio_refusals`).
+- :mod:`~unicode_logic_kit.eval.datasets.logicbench` — LogicBench: 25
+  single-inference-rule reasoning patterns split by logic type
+  (propositional, first-order, non-monotonic), another no-gold-FOL adapter in
+  FraCaS's shape;
+  :func:`~unicode_logic_kit.eval.datasets.logicbench.solve_example` routes a
+  non-monotonic-logic row through :mod:`unicode_logic_kit.semantics.nonmonotonic`
+  instead of a second classical cascade.
+
+Per-dataset helper functions (converters, solvers) deliberately live on
+their OWN modules rather than being re-exported here — two adapters
+legitimately name their solver ``solve_example``, and a package-level
+re-export would force one to shadow the other.
+
+Deliberately NOT adapted (verified 2026-08-12, so the omission is a decision,
+not an oversight): **AR-LSAT** (no logic annotation of any kind — Logic-LM
+generates a Z3-style DSL at inference time, which is neither gold data nor
+FOL; and the underlying LSAT passages are copyright-encumbered),
+and **LogicalDeduction** (BIG-bench; pure NL ordering puzzles, no formal
+annotation — Logic-LM uses a runtime CSP DSL). FraCaS was listed here for
+the same reason until it got the pure-NLI adapter above; its source file
+carries no explicit licence statement, so this repository ships a synthetic
+fixture and reads the real file from a caller-supplied path.
+
+No loader downloads anything — every one reads a LOCAL file the caller
+already obtained (some upstreams distribute JSON arrays; each adapter's
+docstring gives the one-line conversion recipe).
+
+``known_bad`` (set by the loader from a caller-supplied ``known_bad_ids``) is
+a CURATED flag; :func:`audit_examples` is an AUTOMATED, independent check
+(does every gold FOL string parse, and is it well-formed?) — the two are
+meant to be cross-checked against each other, not conflated as the same
+signal.
+"""
+
+from ._base import DatasetExample, DATASET_INFO, audit_examples
+from .folio import load_folio
+from .malls import load_malls
+from .groves import load_groves
+from .willow import load_willow
+from .prontoqa import load_prontoqa
+from .proofwriter import load_proofwriter, load_proofwriter_structured
+from .logicnli import load_logicnli
+from .proverqa import load_proverqa
+from .fracas import load_fracas
+# C3PO is the first adapter whose gold is not a formula but an EXECUTABLE
+# membership decision: a definition is scored by model-checking it against
+# real molecule structures, so score_definition lives here beside the loader.
+from .c3po import load_c3po, score_definition, DefinitionScore
+from .pmb import load_pmb
+from .pfolio import load_pfolio
+from .logicbench import load_logicbench
+
+__all__ = [
+    "DatasetExample", "DATASET_INFO", "audit_examples",
+    "load_folio", "load_malls", "load_groves", "load_willow",
+    "load_prontoqa",
+    "load_proofwriter", "load_proofwriter_structured",
+    "load_logicnli", "load_proverqa", "load_fracas",
+    "load_c3po", "score_definition", "DefinitionScore",
+    "load_pmb", "load_pfolio", "load_logicbench",
+]

unicode_logic_kit/eval/datasets/_base.py

@@ -0,0 +1,263 @@
+"""Shared infrastructure for NL/FOL dataset adapters (:mod:`folio`, :mod:`malls`).
+
+This module defines the one example shape every dataset adapter normalises
+into (:class:`DatasetExample`), a small provenance registry
+(:data:`DATASET_INFO`), and the self-audit mechanic (:func:`audit_examples`)
+that a caller uses to find defective *gold* formulas in a dataset BEFORE
+trusting them as an evaluation reference — an LLM-authored or crowd-annotated
+FOL string can itself be unparseable or ill-formed, and treating it as ground
+truth without checking would silently corrupt every metric computed against
+it.
+
+Design notes:
+
+* :class:`DatasetExample` is deliberately dataset-agnostic: FOLIO's
+  premises/conclusion/label entailment shape and MALLS's single
+  NL-statement/FOL-formula translation pairs both fit the same fields (see
+  each adapter module's docstring for its exact field mapping).
+* Parsing is LAZY and never raises: :meth:`DatasetExample.parse_premises` /
+  :meth:`DatasetExample.parse_conclusion` call
+  :func:`unicode_logic_kit.api.parse_any` only when invoked (loading a dataset
+  of thousands of examples must not eagerly parse every one), and return
+  :class:`~unicode_logic_kit.api.ParseResult` objects — a parse failure is
+  reported, never swallowed or turned into an exception.
+* ``known_bad`` is a CURATED flag an adapter sets from a caller-supplied
+  ``known_bad_ids`` set (e.g. IDs a human or a prior audit run identified as
+  having a broken gold annotation). It is independent of
+  :func:`audit_examples`, which is the AUTOMATED detector: the two are meant
+  to be cross-checked against each other, not conflated.
+"""
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Dict, Iterable, List, Optional, Tuple
+
+if TYPE_CHECKING:                                   # pragma: no cover - typing only
+    from ...api import CheckResult, ParseResult
+
+__all__ = ["DatasetExample", "DATASET_INFO", "audit_examples"]
+
+
+# ---------------------------------------------------------------------------
+# DatasetExample
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class DatasetExample:
+    """One normalised NL/FOL example from any adapter in this subpackage.
+
+    Fields:
+        id: a stable identifier. Adapters use the dataset's own ID field when
+            the source data provides one, otherwise a positional fallback
+            (documented per adapter) — never ``None``, so examples are always
+            addressable (e.g. for ``known_bad_ids``).
+        nl_premises: natural-language premise sentences, in source order.
+            Empty for datasets with no premise/conclusion structure (e.g.
+            MALLS — see its adapter module for the field-mapping rationale).
+        fol_premises: the gold FOL premise strings, in the SAME order as
+            ``nl_premises`` (index ``i`` of one corresponds to index ``i`` of
+            the other). Left as raw strings, not parsed, until
+            :meth:`parse_premises` is called.
+        nl_conclusion / fol_conclusion: the natural-language / FOL conclusion
+            (entailment datasets), or the single NL statement / FOL formula
+            being translated (translation-pair datasets). ``None`` when the
+            dataset has no conclusion slot at all.
+        label: the gold entailment label (dataset-specific vocabulary, e.g.
+            FOLIO's ``"True"``/``"False"``/``"Uncertain"``), or ``None`` for
+            datasets without one (e.g. MALLS).
+        known_bad: True iff this example's ``id`` was passed in the loader's
+            ``known_bad_ids`` — a caller-curated "do not trust this gold
+            annotation" flag, set at load time and never inferred here.
+        meta: adapter-specific leftover fields from the source record (e.g.
+            FOLIO's ``source``/``story-id``, or a synthetic-fixture marker),
+            kept as a plain JSON-compatible dict so nothing from the original
+            record is silently discarded.
+    """
+
+    id: str
+    nl_premises: Tuple[str, ...]
+    fol_premises: Tuple[str, ...]
+    nl_conclusion: Optional[str]
+    fol_conclusion: Optional[str]
+    label: Optional[str]
+    known_bad: bool
+    meta: dict = field(default_factory=dict)
+
+    def parse_premises(self) -> Tuple["ParseResult", ...]:
+        """Parse every ``fol_premises`` string, lazily, in order.
+
+        Uses :func:`unicode_logic_kit.api.parse_any` (dialect auto-detection);
+        each element of the returned tuple is that call's
+        :class:`~unicode_logic_kit.api.ParseResult` UNCHANGED — a parse failure
+        shows up as ``ok=False`` with its ``errors``, never as an exception
+        and never silently dropped.
+        """
+        from ... import api           # lazy: avoid import-time cost/cycles
+
+        return tuple(api.parse_any(p) for p in self.fol_premises)
+
+    def parse_conclusion(self) -> Optional["ParseResult"]:
+        """Parse ``fol_conclusion``, lazily — ``None`` iff there is none.
+
+        Returns the raw :class:`~unicode_logic_kit.api.ParseResult` (so a parse
+        failure is visible via ``ok=False``/``errors``), or ``None`` when this
+        example carries no conclusion/target formula at all (a different
+        thing from a formula that failed to parse).
+        """
+        if self.fol_conclusion is None:
+            return None
+        from ... import api           # lazy: avoid import-time cost/cycles
+
+        return api.parse_any(self.fol_conclusion)
+
+    def to_dict(self) -> dict:
+        """Serialise to a JSON-compatible dict (all fields, names as keys)."""
+        return {
+            "id": self.id,
+            "nl_premises": list(self.nl_premises),
+            "fol_premises": list(self.fol_premises),
+            "nl_conclusion": self.nl_conclusion,
+            "fol_conclusion": self.fol_conclusion,
+            "label": self.label,
+            "known_bad": self.known_bad,
+            "meta": self.meta,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Provenance registry
+# ---------------------------------------------------------------------------
+
+#: Dataset name -> provenance dict (``license``, ``source_url``,
+#: ``citation_hint``). Populated by each adapter module at import time via
+#: :func:`_register_dataset_info` so this dict never drifts from the loader
+#: that actually claims to implement it. Verified against the primary sources
+#: named in each adapter's module docstring — nothing here is guessed.
+DATASET_INFO: Dict[str, dict] = {}
+
+
+def _register_dataset_info(name: str, *, license: str, source_url: str,
+                           citation_hint: str) -> None:
+    """Record ``name``'s provenance in :data:`DATASET_INFO` (adapter-internal)."""
+    DATASET_INFO[name] = {
+        "license": license,
+        "source_url": source_url,
+        "citation_hint": citation_hint,
+    }
+
+
+# ---------------------------------------------------------------------------
+# audit_examples — the self-audit mechanic
+# ---------------------------------------------------------------------------
+
+def _check_result_defects(check_result: "CheckResult", field_name: str,
+                          index: Optional[int]) -> List[dict]:
+    """Expand one failing :class:`~unicode_logic_kit.api.CheckResult` into
+    per-aspect defect dicts (a formula can fail more than one aspect at once,
+    e.g. an unbound variable AND an arity conflict, so this can return more
+    than one entry for a single formula).
+    """
+    defects: List[dict] = []
+    if not check_result.is_closed:
+        defects.append({
+            "kind": "free_variables", "field": field_name, "index": index,
+            "detail": list(check_result.free_variables),
+        })
+    if not check_result.arity_consistent:
+        defects.append({
+            "kind": "arity_conflict", "field": field_name, "index": index,
+            "detail": list(check_result.arity_conflicts),
+        })
+    if check_result.has_lambdas:
+        defects.append({
+            "kind": "residual_lambda", "field": field_name, "index": index,
+            "detail": None,
+        })
+    return defects
+
+
+def audit_examples(examples: Iterable[DatasetExample], *,
+                   max_examples: Optional[int] = None) -> List[dict]:
+    """Self-audit a batch of examples: which gold FOL strings are broken?
+
+    This is the mechanic for finding defective gold annotations WITHOUT any
+    external reference — it only requires that a gold formula (a) parses and
+    (b) is well-formed (closed, arity-consistent, lambda-free), both of which
+    :func:`unicode_logic_kit.api.parse_any` / :func:`unicode_logic_kit.api.check`
+    can decide on their own. It does NOT check the entailment ``label``
+    itself (that would need a prover run over the whole premise set, a
+    heavier and separately-scoped operation).
+
+    Args:
+        examples: any iterable of :class:`DatasetExample` (a generator from a
+            loader is fine — nothing here requires a materialised list).
+        max_examples: stop after auditing this many examples (``None`` audits
+            everything). Useful for a quick pass over a large dataset.
+
+    Returns:
+        A ``list[dict]``, one entry per audited example, in input order, each
+        JSON-compatible:
+
+        * ``id`` / ``known_bad``: copied from the example, for cross-checking
+          the automated finding against any curated flag.
+        * ``all_parsed``: True iff every ``fol_premises`` string and (if
+          present) ``fol_conclusion`` parsed successfully — answers "parsen
+          alle FOL-Strings?".
+        * ``all_checked``: True iff every formula that DID parse also passed
+          :func:`~unicode_logic_kit.api.check` (``check().ok``); vacuously True
+          if nothing parsed. Independent of ``all_parsed`` — a formula that
+          fails to parse contributes nothing here, only to ``all_parsed``.
+        * ``ok``: ``all_parsed and all_checked`` — no defect of any kind.
+        * ``defects``: the collected defect classes, each
+          ``{"kind": ..., "field": "premises"|"conclusion", "index": int|None,
+          "detail": ...}``. ``kind`` is one of ``"unparseable"``,
+          ``"free_variables"``, ``"arity_conflict"``, ``"residual_lambda"``.
+          ``index`` is the position within ``fol_premises`` for that field, or
+          ``None`` for the (singular) conclusion.
+    """
+    from ... import api           # lazy: avoid import-time cost/cycles
+
+    reports: List[dict] = []
+    for i, example in enumerate(examples):
+        if max_examples is not None and i >= max_examples:
+            break
+
+        defects: List[dict] = []
+        all_parsed = True
+        all_checked = True
+
+        premise_results = example.parse_premises()
+        for idx, pr in enumerate(premise_results):
+            if not pr.ok:
+                all_parsed = False
+                message = pr.errors[-1]["message"] if pr.errors else "unparseable"
+                defects.append({"kind": "unparseable", "field": "premises",
+                                "index": idx, "detail": message})
+                continue
+            cr = api.check(pr.formula)
+            if not cr.ok:
+                all_checked = False
+                defects.extend(_check_result_defects(cr, "premises", idx))
+
+        conclusion_result = example.parse_conclusion()
+        if conclusion_result is not None:
+            if not conclusion_result.ok:
+                all_parsed = False
+                message = (conclusion_result.errors[-1]["message"]
+                          if conclusion_result.errors else "unparseable")
+                defects.append({"kind": "unparseable", "field": "conclusion",
+                                "index": None, "detail": message})
+            else:
+                cr = api.check(conclusion_result.formula)
+                if not cr.ok:
+                    all_checked = False
+                    defects.extend(_check_result_defects(cr, "conclusion", None))
+
+        reports.append({
+            "id": example.id,
+            "known_bad": example.known_bad,
+            "all_parsed": all_parsed,
+            "all_checked": all_checked,
+            "ok": all_parsed and all_checked,
+            "defects": defects,
+        })
+    return reports