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

unicode_logic_kit/_deadline.py

@@ -0,0 +1,219 @@
+"""A wall-clock limit shared by the kit's in-house searches.
+
+Every in-house search (the classical and the labelled tableaux, resolution, the finite model
+finder, the Kripke enumerator, the LTL tableau) takes its limit in milliseconds and turns it into
+one instant on the ``time.perf_counter()`` clock when the call starts. This module holds the two
+things they share.
+
+* :class:`DeadlineReached` is what a search raises from deep inside its own loops to unwind to its
+  entry point, which answers "no answer within the limit". It is raised by the search itself, at
+  a place the search chose.
+
+* :func:`run_until` runs a function that has no loop of its own to put a check in: it is the
+  normal-form conversion that precedes a resolution search, or a routine of another module that
+  the search only calls. It ends the call at the deadline by raising an exception in the calling
+  thread (``PyThreadState_SetAsyncExc``), which Python delivers at the next bytecode, so a
+  conversion that blows up exponentially is cut off within a few milliseconds of the deadline
+  and costs nothing before it. A call into C code (a long ``itertools`` step, a solver) is not
+  interrupted until it returns, and a function must be safe to abandon half-way: it may build
+  data of its own but must not leave a shared structure half-written.
+
+**When the interruption can arrive.** An asynchronous exception is delivered at whatever
+bytecode the thread executes next, so the helper decides, for every instant of a call, whether
+the timer may post one and where it would land.
+
+* Before the call arms the timer nothing can be posted: the timer thread is started in a state
+  in which it only notes that it ran out, and a call whose timer ran out first gives up without
+  running the function.
+* From the moment the call arms the timer until its own clean-up has withdrawn what the timer
+  may have left, every bytecode of the thread lies inside the one ``try`` statement that catches
+  this call's own exception class: the function, the instants between its return and the
+  clean-up, and the clean-up itself.
+* The clean-up is one critical section: it ends the timer's right to post and takes back an
+  exception that was posted but not yet delivered. After it, nothing of this call is pending,
+  and what runs next (the handler, the caller's code) is never interrupted by this call.
+* The clean-up is repeated by an outer ``finally``, so another exception that cuts the first
+  one short (a ``KeyboardInterrupt``, the cut-off of an enclosing call) cannot leave the timer
+  armed.
+* Calls in different threads do not meet: each call has its own timer, its own lock and its own
+  exception class, and the exception is posted to the thread that made the call.
+
+Two things the helper cannot do. A thread has room for ONE pending asynchronous exception, so
+of two nested limits that expire within the same few microseconds only one is delivered, and
+the enclosing call may miss its own limit and run on to its end; it is never interrupted at a
+place where nothing is waiting for it. And Python prints and drops an exception that is raised
+inside a ``__del__`` or a weak-reference callback, so a function that happens to run one at the
+very instant the exception lands is not cut off (the call then ends late, with its own answer).
+"""
+
+import threading
+import time
+from typing import Any, Callable, Optional, Tuple, Type, TypeVar
+
+try:
+    import ctypes
+    _SET_ASYNC_EXC: Optional[Any] = ctypes.pythonapi.PyThreadState_SetAsyncExc
+except Exception:                       # an interpreter without ctypes, or without the C API through it
+    ctypes = None                       # type: ignore[assignment]
+    _SET_ASYNC_EXC = None
+
+__all__ = ["DeadlineReached", "instant", "passed", "remaining_ms", "run_until"]
+
+T = TypeVar("T")
+
+
+class DeadlineReached(Exception):
+    """A search ran past its deadline (raised by the search, caught at its entry point)."""
+
+
+def instant(timeout_ms: Optional[float]) -> Optional[float]:
+    """The ``perf_counter`` instant ``timeout_ms`` milliseconds from now; ``None`` for no limit."""
+    return None if timeout_ms is None else time.perf_counter() + timeout_ms / 1000.0
+
+
+def passed(deadline: Optional[float]) -> bool:
+    """True iff ``deadline`` (an instant from :func:`instant`) is in the past; never for ``None``."""
+    return deadline is not None and time.perf_counter() > deadline
+
+
+def remaining_ms(deadline: Optional[float]) -> Optional[float]:
+    """The milliseconds left until ``deadline`` (not below 0), or ``None`` for no limit."""
+    if deadline is None:
+        return None
+    return max(0.0, (deadline - time.perf_counter()) * 1000.0)
+
+
+class _Interrupted(BaseException):
+    """Delivered into the calling thread at the deadline by :func:`run_until`.
+
+    A ``BaseException``, so that a broad ``except Exception`` somewhere in the interrupted code
+    cannot swallow it; :func:`run_until` is the only place that catches it.
+    """
+
+
+#: Whether this interpreter can raise an exception in a running thread (CPython can).
+_CAN_INTERRUPT = _SET_ASYNC_EXC is not None
+
+
+def _set_async_exception(thread_id: int, exception: Optional[type]) -> int:
+    """Ask the interpreter to raise ``exception`` in thread ``thread_id`` (``None`` clears a pending one)."""
+    assert _SET_ASYNC_EXC is not None
+    return _SET_ASYNC_EXC(ctypes.c_ulong(thread_id), ctypes.py_object(exception) if exception else None)
+
+
+#: The states of a :class:`_Cutoff`.
+_IDLE = 0       # the function has not begun: a timer that runs out now only notes it
+_ARMED = 1      # the function runs under the limit: a timer that runs out now posts
+_POSTED = 2     # the interruption was posted: delivered by now, or still pending
+_EXPIRED = 3    # the timer ran out before the function began: the function must not run
+_DONE = 4       # the call is over: the timer has no right left
+
+
+class _Cutoff:
+    """What the calling thread and the timer thread of one :func:`run_until` call share.
+
+    A state that only changes under one lock, so that the two never disagree about whether an
+    interruption has been posted:
+
+    * ``_IDLE`` → ``_ARMED`` when the calling thread is about to run the function (:meth:`arm`);
+    * ``_ARMED`` → ``_POSTED`` when the timer runs out and posts the interruption to the thread
+      (:meth:`fire`);
+    * ``_IDLE`` → ``_EXPIRED`` when the timer runs out first, which tells :meth:`arm` that the
+      limit is over already (nothing is posted: the thread is not inside the guarded region);
+    * any state → ``_DONE`` on :meth:`disarm`, which withdraws a posted interruption that was not
+      delivered yet.
+
+    Every call has its own exception class, so a nested call is cut off by its own timer and by
+    no other.
+
+    The timer itself is NOT a field. A timer that this object also pointed back to would make a
+    reference cycle, and a cycle's garbage is collected whenever the collector next runs: its
+    clean-up (a weak-reference callback of the ``threading`` module that drops the finished timer
+    thread) would then run in the middle of some later call's function, and an exception
+    delivered into such a callback is printed and dropped, which loses that call's cut-off.
+    Without the cycle the timer thread's object dies, by its reference count, when
+    :func:`run_until` returns.
+    """
+
+    __slots__ = ("thread_id", "interrupt", "_lock", "_state")
+
+    def __init__(self) -> None:
+        self.thread_id = threading.get_ident()
+        self.interrupt: Type[BaseException] = type("_Interrupted", (_Interrupted,), {})
+        self._lock = threading.Lock()
+        self._state = _IDLE
+
+    def fire(self) -> None:
+        """Run on the timer thread when the limit is over."""
+        with self._lock:
+            if self._state == _ARMED:
+                self._state = _POSTED
+                _set_async_exception(self.thread_id, self.interrupt)
+            elif self._state == _IDLE:
+                self._state = _EXPIRED
+
+    def arm(self) -> bool:
+        """Let the timer post from now on; False if its limit is over already (run nothing)."""
+        with self._lock:
+            if self._state != _IDLE:
+                return False
+            self._state = _ARMED
+            return True
+
+    def disarm(self) -> None:
+        """End the timer's right to post, and take back an interruption it posted and left pending.
+
+        Idempotent, so that a second call can complete a first one that another exception cut
+        short: a state that is not ``_DONE`` yet says what is left to do.
+        """
+        with self._lock:                                # a timer that is posting has finished by now
+            if self._state == _POSTED:
+                _set_async_exception(self.thread_id, None)
+            self._state = _DONE
+
+
+def run_until(deadline: Optional[float], function: Callable[[], T]) -> Tuple[bool, Optional[T]]:
+    """Run ``function()``; return ``(True, value)``, or ``(False, None)`` if it was cut off at ``deadline``.
+
+    ``deadline`` is an instant from :func:`instant`; ``None`` means no limit, and then this is a
+    plain call. A deadline that has passed already runs nothing, and so does one that passes
+    while the call is being set up (the answer is ``(False, None)`` either way). When the
+    deadline passes while ``function`` is still running, an exception is raised in this thread
+    at the next bytecode and ends it: the result is ``(False, None)`` and nothing the function
+    built is returned. An interruption that arrives after the function returned, or inside the
+    clean-up of this call, is absorbed: the result is then ``(False, None)`` if it cut the
+    return short and ``(True, value)`` if the function had finished. Nothing of this call is
+    ever raised into the caller, whatever the limit and however many threads call at once. A
+    function that finishes first costs one timer thread and nothing else. Nested calls are
+    independent: each cuts off only its own function (see the module docstring for the one
+    case in which an enclosing call can be late). On an interpreter that cannot raise an
+    exception in a running thread the function simply runs to its end.
+
+    ``function`` must be safe to abandon half-way (see the module docstring), and must not catch
+    ``BaseException``. An exception that ``function`` raises on its own propagates unchanged.
+    """
+    if deadline is None or not _CAN_INTERRUPT:
+        return True, function()
+    if passed(deadline):
+        return False, None
+    cutoff = _Cutoff()
+    timer = threading.Timer(max(0.0, deadline - time.perf_counter()), cutoff.fire)
+    timer.daemon = True
+    value: Optional[T] = None
+    finished = False
+    try:
+        try:
+            try:
+                timer.start()                           # cannot post yet: the call is not armed
+                if cutoff.arm():
+                    value = function()
+                    finished = True
+            finally:
+                cutoff.disarm()
+                timer.cancel()
+        except cutoff.interrupt:
+            pass
+    finally:
+        cutoff.disarm()                                 # again: finishes a clean-up that was cut short
+        timer.cancel()
+    return finished, (value if finished else None)

unicode_logic_kit/ace/__init__.py

@@ -0,0 +1,126 @@
+"""The ``ace`` subpackage — Attempto Controlled English, via APE.
+
+ACE is a controlled natural language with exactly ONE reading per sentence,
+fixed by documented interpretation rules rather than by a statistical guesser
+— which makes it the natural English-shaped INPUT format for a kit whose other
+readers (TPTP, Prover9, SMT-LIB, SBN, CASL, …) already assume that a text
+means one thing. The reference parser APE is driven as an external subprocess
+(LGPL; never vendored, never reimplemented — see
+:mod:`unicode_logic_kit.ace.runner`'s module docstring for why a partial APE
+clone would be worse than none).
+
+What works today (milestone ACE-1) is the TPTP route: ACE text → APE → TPTP →
+:func:`unicode_logic_kit.fol.tptp_input.parse_tptp` → kit formulas, plus a
+mechanical per-sentence coverage report. Three outcomes, none silent:
+
+>>> from unicode_logic_kit.ace import ace_to_fol   # doctest: +SKIP
+>>> [f.to_unicode_str() for f in ace_to_fol("Every man waits.")]  # doctest: +SKIP
+['∀a (Man(a) → ∃b Predicate1(b, wait, a))']
+
+- a sentence that is not ACE raises :class:`~unicode_logic_kit.ace.runner.AceParseError`
+  with APE's own diagnosis (position, token, repair hint);
+- an ACE sentence whose DRS uses modality, negation as failure, a question or
+  a command raises :class:`~unicode_logic_kit.ace.runner.AceTptpUnsupportedError`
+  — Attempto's OWN TPTP translator refuses those, and the kit routes them
+  into its modal family in milestone ACE-3 instead of mistranslating today;
+- a plural cardinality ("at least 3 men") survives only REIFIED on THIS
+  route (Attempto's export kept verbatim) and is flagged by
+  :func:`~unicode_logic_kit.ace.runner.ace_coverage` (``reified_cardinality``)
+  — the DRS and formula routes below carry the counting force (ACE-4/5).
+
+Since milestone ACE-2/3 the DRS itself is first-class, and three routes share
+one vocabulary (pinned against each other by a Z3 differential over the whole
+corpus — see ``tests/test_ace_mapping.py``):
+
+- :func:`~unicode_logic_kit.ace.runner.ace_to_fol` — Attempto's own TPTP,
+  through the kit's reader (fast, but only what THEIR translator covers);
+- :func:`~unicode_logic_kit.ace.mapping.ace_to_drs` — APE's DRS read 1:1
+  (:func:`~unicode_logic_kit.ace.drs_reader.parse_ape_drs`) and mapped onto
+  :mod:`unicode_logic_kit.drt`'s core, every condition reported
+  (:class:`~unicode_logic_kit.ace.mapping.DrsMapping`), nothing dropped
+  silently — since ACE-5 including plurals and cardinalities, collectively,
+  on the ``Card``/``Part`` conditions;
+- :func:`~unicode_logic_kit.ace.translate.ace_to_formula` — straight to one
+  kit formula, INCLUDING what a DRS cannot hold: ACE's four modal boxes
+  become □/◇/Ⓞ/Ⓟ, a wh-question an open formula, a yes/no question a
+  closed one with its interrogative force kept on ``kind``, the
+  ``exactly``/``at most`` maximality a counting quantifier, and arithmetic
+  kit terms (decided by :func:`~unicode_logic_kit.atp.z3_arith.is_valid_arith`).
+
+Still refused everywhere, by name: commands and negation as failure (both
+honestly undecided — no milestone).
+
+Since ACE-6 the pipeline also runs BACKWARDS:
+:func:`~unicode_logic_kit.ace.verbalize.drs_to_ace` verbalizes a kit DRS as
+ACE text plus the user-lexicon entries that carry its content words, and
+:func:`~unicode_logic_kit.ace.verbalize.ace_round_trip` is the machine
+self-check — text through APE and back, judged by Z3 (the whole mappable
+corpus closes the loop). :func:`~unicode_logic_kit.ace.chem_lexicon.chem_ulex`
+renders the ChemLog signature as such a lexicon, so ACE sentences can talk
+about molecules in plain words ("a carbon", "bonds", "aromatic") while the
+DRS underneath carries the declared chemistry vocabulary.
+
+Since ACE-7 the backward direction also covers the modal/deontic fragment
+(question/command generation stays deferred):
+:func:`~unicode_logic_kit.ace.reverse_modal.fol_to_modal_drs` recognizes the
+two shapes ACE's modal surface can carry — a modality wrapping a whole
+formula ("John must wait.") and one nested in a duplex's consequent ("Every
+man must wait.", verbalized as "If there is a man X1 then X1 must wait.") —
+as :class:`~unicode_logic_kit.ace.reverse_modal.ModalBox` /
+:class:`~unicode_logic_kit.ace.reverse_modal.ModalImpl`, reusing
+:func:`~unicode_logic_kit.drt.reverse.fol_to_drs` for every classical piece
+and refusing every other placement by the same message that route already
+gives a bare modal node. :func:`~unicode_logic_kit.ace.verbalize.modal_formula_to_ace`
+is the ACE-6 entry point's modal counterpart, and
+:func:`~unicode_logic_kit.ace.verbalize.modal_ace_round_trip` closes the loop
+through APE, judged by :func:`~unicode_logic_kit.eval.equivalence.equivalent`
+(not raw Z3 — a modal ``Node`` has no direct Z3 export; ``equivalent``
+already routes a modal pair through the modal tableau / QML embedding).
+"""
+
+from .drs_reader import (
+    AceAtom, AceCommand, AceCondList, AceDrs, AceDrsUnreadError, AceExpr,
+    AceImpl, AceInt, AceModal, AceNaf, AceNamed, AceNeg, AceOr, AceQuestion,
+    AceReal, AceString, AceTermApp, AceVar, parse_ape_drs,
+)
+from .mapping import (
+    AceUnsupportedError, ConditionReport, DrsMapping, ace_to_drs,
+    condition_statistics, map_ace_drs,
+)
+from .runner import (
+    AceError, AceParseError, AceTptpUnreadError, AceTptpUnsupportedError,
+    ApeMessage, ApeResult, ApeUnavailableError, CoverageRow, ace_coverage,
+    ace_to_fol, ape_available, run_ape,
+)
+from .translate import AceFormula, ace_drs_to_formula, ace_to_formula
+from .reverse_modal import ModalBox, ModalImpl, fol_to_modal_drs
+from .verbalize import (
+    AceRoundTrip, AceText, AceVerbalizationError, ModalAceRoundTrip,
+    ace_round_trip, drs_to_ace, formula_to_ace, modal_ace_round_trip,
+    modal_drs_to_ace, modal_formula_to_ace,
+)
+from .chem_lexicon import ace_kit_name, chem_ulex
+
+__all__ = [
+    # the engine and the three routes
+    "ape_available", "run_ape", "ace_to_fol", "ace_to_drs", "ace_to_formula",
+    "ace_coverage", "map_ace_drs", "ace_drs_to_formula", "parse_ape_drs",
+    "condition_statistics",
+    # the reverse direction (ACE-6)
+    "drs_to_ace", "formula_to_ace", "ace_round_trip", "chem_ulex",
+    "ace_kit_name",
+    # the reverse direction, modal/deontic fragment (ACE-7)
+    "fol_to_modal_drs", "ModalBox", "ModalImpl", "modal_drs_to_ace",
+    "modal_formula_to_ace", "modal_ace_round_trip", "ModalAceRoundTrip",
+    # results and reports
+    "ApeResult", "ApeMessage", "CoverageRow", "DrsMapping",
+    "ConditionReport", "AceFormula", "AceText", "AceRoundTrip",
+    # the 1:1 DRS model
+    "AceDrs", "AceVar", "AceNamed", "AceInt", "AceReal", "AceString",
+    "AceExpr", "AceTermApp", "AceAtom", "AceNeg", "AceNaf", "AceImpl",
+    "AceOr", "AceModal", "AceQuestion", "AceCommand", "AceCondList",
+    # errors
+    "AceError", "ApeUnavailableError", "AceParseError",
+    "AceTptpUnsupportedError", "AceTptpUnreadError", "AceDrsUnreadError",
+    "AceUnsupportedError", "AceVerbalizationError",
+]

unicode_logic_kit/ace/_align.py

@@ -0,0 +1,135 @@
+"""Align APE's reified TPTP vocabulary onto the mapping's — differential glue.
+
+The ACE-2 correctness argument is a differential: for every corpus sentence
+that BOTH routes cover, the kit-DRS route's FOL
+(:func:`unicode_logic_kit.drt.export.drs_to_fol` over
+:func:`unicode_logic_kit.ace.mapping.map_ace_drs`) must be Z3-equivalent to
+Attempto's own reference translation (the TPTP output, read by
+:func:`unicode_logic_kit.fol.tptp_input.parse_tptp`). The two sides speak
+different dialects of the same signature — APE reifies what the mapping
+names::
+
+    Predicate2(e, see, s, o)        vs.   See(e, s, o)
+    Property1(a, rich, pos)         vs.   Rich(a)
+    Property2(a, tall, comp_than, m) vs.  Tall_comp_than(a, m)
+    Relation(a, of, b)              vs.   Of(a, b)
+    Modifier_adv(e, loudly, pos)    vs.   Loudly(e)
+    Object(a, water, mass, na, na, na) vs. Water(a)
+    'John', 30, string('Johnny')    vs.   john, c_30, c_Johnny
+
+This module rewrites the APE side into the mapping side, atom by atom, with
+the SAME name rules the mapping uses (imported from it, not re-implemented),
+so the differential compares semantics rather than spelling. It is private
+test machinery in package form: the rewrite rules are themselves a claim
+about the correspondence, and the differential is what checks that claim —
+a wrong rule here makes sentences INequivalent and the test loud, never the
+other way around. Anything outside the measured inventory raises.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from ..fol.nodes import (
+    And, Atom, Constant, Function, Implies, Node, Not, Number, Or, Quantifier,
+    Variable,
+)
+from .mapping import _degree_name, _kit_predicate, _named_constant
+
+__all__ = ["align_ape_tptp_formula", "conjoin"]
+
+
+def conjoin(formulas: List[Node]) -> Node:
+    """One formula per sentence → one formula per text (∧-fold)."""
+    if not formulas:
+        raise ValueError("conjoin: no formulas")
+    result = formulas[0]
+    for f in formulas[1:]:
+        result = And(result, f)
+    return result
+
+
+def align_ape_tptp_formula(formula: Node) -> Node:
+    """Rewrite one parsed APE-TPTP formula into the mapping vocabulary."""
+    return _align(formula)
+
+
+def _align(node: Node) -> Node:
+    if isinstance(node, Quantifier):
+        return Quantifier(node.type, node.variable, _align(node.formula))
+    if isinstance(node, And):
+        return And(_align(node.left), _align(node.right))
+    if isinstance(node, Or):
+        return Or(_align(node.left), _align(node.right))
+    if isinstance(node, Implies):
+        return Implies(_align(node.left), _align(node.right))
+    if isinstance(node, Not):
+        return Not(_align(node.formula))
+    if isinstance(node, Atom):
+        return _align_atom(node)
+    raise NotImplementedError(
+        f"APE TPTP alignment: {type(node).__name__} is not in the measured "
+        "inventory of APE outputs")
+
+
+def _atom_name(term: Node, what: str) -> str:
+    if isinstance(term, Constant):
+        return term.name
+    raise NotImplementedError(
+        f"APE TPTP alignment: expected a constant {what}, got "
+        f"{type(term).__name__}")
+
+
+def _align_atom(atom: Atom) -> Atom:
+    p, args = atom.predicate, atom.args
+    if p in ("Predicate1", "Predicate2", "Predicate3") and len(args) >= 3:
+        verb = _atom_name(args[1], "verb")
+        participants = tuple(_align_term(a) for a in (args[0],) + args[2:])
+        return Atom(_kit_predicate(verb), participants)
+    if p in ("Property1", "Property2") and len(args) >= 3:
+        adjective = _atom_name(args[1], "adjective")
+        degree = _atom_name(args[2], "degree")
+        rest = tuple(_align_term(a) for a in (args[0],) + args[3:])
+        return Atom(_degree_name(adjective, degree), rest)
+    if p == "Relation" and len(args) == 3:
+        middle = _atom_name(args[1], "relation kind")
+        if middle != "of":
+            raise NotImplementedError(
+                f"APE TPTP alignment: relation kind {middle!r} not measured")
+        return Atom("Of", (_align_term(args[0]), _align_term(args[2])))
+    if p == "Modifier_adv" and len(args) == 3:
+        adverb = _atom_name(args[1], "adverb")
+        degree = _atom_name(args[2], "degree")
+        return Atom(_degree_name(adverb, degree), (_align_term(args[0]),))
+    if p == "Modifier_pp" and len(args) == 3:
+        preposition = _atom_name(args[1], "preposition")
+        return Atom(_kit_predicate(preposition),
+                    (_align_term(args[0]), _align_term(args[2])))
+    if p == "Object" and len(args) == 6:
+        noun = _atom_name(args[1], "noun")
+        return Atom(_kit_predicate(noun), (_align_term(args[0]),))
+    # Everything else — the prettified unary nouns (Man, Dog), equality —
+    # already speaks the mapping vocabulary up to its TERMS.
+    return Atom(p, tuple(_align_term(a) for a in args))
+
+
+def _align_term(term: Node) -> Node:
+    if isinstance(term, Variable):
+        return term
+    if isinstance(term, Constant):
+        return Constant(_named_constant(term.name))
+    if isinstance(term, Number):
+        value = term.value
+        if isinstance(value, int) or value == int(value):
+            text = str(int(value)) if value >= 0 else "m" + str(-int(value))
+        else:
+            text = ("m" if value < 0 else "") + str(abs(value)).replace(".", "p")
+        return Constant("c_" + text)
+    if isinstance(term, Function) and term.name == "string" and len(term.args) == 1:
+        inner = term.args[0]
+        if isinstance(inner, Constant):
+            cleaned = "".join(ch for ch in inner.name if ch.isalnum())
+            return Constant("c_" + (cleaned if cleaned else "str"))
+    raise NotImplementedError(
+        f"APE TPTP alignment: term {type(term).__name__} is not in the "
+        "measured inventory")

unicode_logic_kit/ace/chem_lexicon.py

@@ -0,0 +1,128 @@
+"""The ChemLog vocabulary as an APE user lexicon — ACE about molecules.
+
+:func:`chem_ulex` renders every speakable predicate of
+:data:`unicode_logic_kit.chem.signature.CHEMLOG_SIGNATURE` as APE
+``-ulextext`` entries, so ACE sentences can talk about molecules in plain
+words while the DRS underneath carries the ChemLog symbols::
+
+    from unicode_logic_kit.ace import ace_to_drs, chem_ulex
+    drs = ace_to_drs("There is a carbon X1. There is an oxygen X2. "
+                     "X1 bonds X2. X1 is aromatic.", ulex=chem_ulex())
+
+The surface/symbol split is the whole point: the ENGLISH side says
+"carbon", "bonds", "aromatic"; the LOGICAL side of each lexicon entry is
+the ChemLog predicate itself (``c``, ``bond``, ``aromatic``), so what
+arrives in the DRS is the declared chemistry vocabulary, not a parallel
+spelling. Two shape differences against the raw signature are inherent to
+ACE and documented rather than papered over:
+
+- **Capitalization**: the kit's DRS/formula routes spell predicates in the
+  kit convention (``c`` → ``C``, ``bond`` → ``Bond``, ``bSINGLE`` →
+  ``BSINGLE``) — :func:`ace_kit_name` computes the arriving spelling for
+  any ChemLog predicate.
+- **Events**: an ACE verb always carries a Davidsonian event, so the
+  binary ChemLog relations arrive with arity THREE (``Bond(e1, x1, x2)``).
+  Projecting the event away (``∃e Bond(e, x, y)`` → ``bond(x, y)``) is a
+  deliberate, separate step for the caller — this module does not do it
+  silently.
+
+The three NULLARY predicates (``net_charge_neutral``,
+``NetChargePositive``, ``NetChargeNegative``) are unspeakable in ACE —
+a sentence needs a subject — and are excluded by name
+(:data:`CHEM_UNSPEAKABLE`); the coverage test pins that the three tables
+plus this exclusion list tile the signature exactly, so a signature change
+lands here loudly.
+
+Category choices: elements and ``atom`` are NOUNS ("a carbon"), atom
+properties are ADJECTIVES ("X1 is aromatic"), binary relations are
+TRANSITIVE VERBS ("X1 bonds X2"). Hyphenated surfaces are ordinary ACE
+words (probed: quoted-atom lexicon entries parse fine).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Tuple
+
+from .mapping import _kit_predicate
+from .verbalize import _atom, _s_form
+
+__all__ = ["chem_ulex", "ace_kit_name", "CHEM_NOUNS", "CHEM_ADJECTIVES",
+           "CHEM_VERBS", "CHEM_UNSPEAKABLE"]
+
+
+#: ChemLog predicate → ACE noun (singular surface; the plural adds ``s``).
+CHEM_NOUNS: Dict[str, str] = {
+    "at": "astatine",
+    "atom": "atom",
+    "br": "bromine",
+    "c": "carbon",
+    "cl": "chlorine",
+    "f": "fluorine",
+    "h": "hydrogen",
+    "i": "iodine",
+    "n": "nitrogen",
+    "o": "oxygen",
+    "p": "phosphorus",
+    "s": "sulfur",
+}
+
+#: ChemLog predicate → ACE adjective ("X1 is aromatic.").
+CHEM_ADJECTIVES: Dict[str, str] = {
+    "ChiralR": "r-chiral",
+    "ChiralS": "s-chiral",
+    "aromatic": "aromatic",
+    "charge0": "uncharged",
+    "charge_m1": "negatively-charged",
+    "charge_p1": "positively-charged",
+    "has_0_hs": "zero-hydrogen",
+    "has_1_hs": "one-hydrogen",
+    "has_2_hs": "two-hydrogen",
+    "has_3_hs": "three-hydrogen",
+    "in_ring": "cyclic",
+    "in_ring_of_size_3": "three-membered",
+    "in_ring_of_size_4": "four-membered",
+    "in_ring_of_size_5": "five-membered",
+    "in_ring_of_size_6": "six-membered",
+    "in_ring_of_size_7": "seven-membered",
+    "in_ring_of_size_8": "eight-membered",
+}
+
+#: ChemLog predicate → (finite-singular, infinitive/plural) verb surfaces.
+CHEM_VERBS: Dict[str, Tuple[str, str]] = {
+    "bAROMATIC": ("aromatically-bonds", "aromatically-bond"),
+    "bDOUBLE": ("double-bonds", "double-bond"),
+    "bSINGLE": ("single-bonds", "single-bond"),
+    "bTRIPLE": ("triple-bonds", "triple-bond"),
+    "bond": ("bonds", "bond"),
+    "carbon_connected": ("carbon-connects-to", "carbon-connect-to"),
+    "has_bond_to": ("has-a-bond-to", "have-a-bond-to"),
+    "same_fragment": ("shares-a-fragment-with", "share-a-fragment-with"),
+}
+
+#: The nullary ChemLog predicates — no ACE sentence can state a
+#: subject-less proposition, so these have no surface, by name.
+CHEM_UNSPEAKABLE = frozenset({
+    "NetChargeNegative", "NetChargePositive", "net_charge_neutral",
+})
+
+
+def chem_ulex() -> str:
+    """The whole speakable ChemLog vocabulary as ``-ulextext`` clauses."""
+    lines = []
+    for logical, noun in CHEM_NOUNS.items():
+        lines.append(f"noun_sg({_atom(noun)}, {_atom(logical)}, neutr).")
+        lines.append(
+            f"noun_pl({_atom(_s_form(noun))}, {_atom(logical)}, neutr).")
+    for logical, adj in CHEM_ADJECTIVES.items():
+        lines.append(f"adj_itr({_atom(adj)}, {_atom(logical)}).")
+    for logical, (finsg, infpl) in CHEM_VERBS.items():
+        lines.append(f"tv_finsg({_atom(finsg)}, {_atom(logical)}).")
+        lines.append(f"tv_infpl({_atom(infpl)}, {_atom(logical)}).")
+    return "\n".join(sorted(lines))
+
+
+def ace_kit_name(chemlog_name: str) -> str:
+    """The kit-convention spelling a ChemLog predicate arrives under when
+    an ACE sentence travels the DRS or formula route (``c`` → ``C``,
+    ``bond`` → ``Bond``, ``bSINGLE`` → ``BSINGLE``)."""
+    return _kit_predicate(chemlog_name)