peye 0.1.0__tar.gz

peye-0.1.0/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+### Copyright 2021-2026 Jos De Roo, KNoWS office of IDLab, Ghent University - imec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

peye-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: peye
+Version: 0.1.0
+Summary: peye — reasoning you can see. A dependency-free Python rule language with forward and backward reasoning and checkable proofs.
+Author: Jos De Roo
+License: # MIT License
+        
+        ### Copyright 2021-2026 Jos De Roo, KNoWS office of IDLab, Ghent University - imec
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/eyereasoner/peye
+Project-URL: Documentation, https://eyereasoner.github.io/peye/
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Dynamic: license-file
+
+# peye
+
+![EYE](https://josd.github.io/images/eye.png)
+
+*peye — reasoning you can see.*
+
+A standalone, dependency-free **Python rule language** with forward and backward
+reasoning and checkable proofs.
+
+peye turns explicit facts and rules into conclusions whose derivations can be
+inspected and checked. An answer can arrive together with a certificate, and
+that certificate can be verified against the program that produced it.
+
+Facts and rules are Python:
+
+```python
+from peye import *
+
+fact(human('socrates'))
+forward(mortal(X), human(X))
+```
+
+There is nothing to declare: a name the program uses without defining it is a
+variable when it starts with a capital or an underscore, like `X`, and a
+predicate otherwise, like `human`. Atoms are strings.
+
+`forward(Head, *Body)` materializes conclusions until a fixpoint.
+`backward(Head, *Body)` defines a predicate evaluated when called. The two
+compose: a forward body may call backward definitions, and a backward goal may
+use facts that forward reasoning established.
+
+## The thread
+
+peye is built around one idea: **reasoning you can see**. You write facts and
+rules; peye draws conclusions, forward until nothing new follows and backward
+on request, and every answer can come with a proof. A separate checker verifies
+that proof against the program, independently of the reasoner, and does more
+than a classic proof checker:
+
+- **The derivation:** every step is an instance of a program clause (C1),
+  nothing is circular (C2), and every claim and every use is justified (C4).
+- **The form (C3):** every step has exactly one justification of an allowed
+  kind, in the right shape, so the report shows at once whether a proof fails
+  on form or on content.
+- **Recomputation (C5):** built-in calculations are redone rather than trusted.
+- **Honesty about absence:** "there is nothing that …" and "these are *all* the
+  answers" cannot be proved; they become explicit obligations, which the
+  checker tries to refute with the evidence at hand (C6).
+- **The right question (C7):** the proof answers the question asked and
+  contains nothing beside it.
+
+The report is itself Python data, and every generated proof is checked before it
+is returned. Proofs are read with Python's `ast` module and never executed, so
+checking a proof from someone else runs none of their code. Around that core, [59 examples](https://eyereasoner.github.io/peye/examples/)
+grew, from Socrates and the zebra puzzle to a hospital research portal decided
+under today's EU rules and under the Commission's Digital Omnibus proposal, and
+package holiday cancellations under the 2015 and the revised Package Travel
+Directive. Each has a [deck](https://eyereasoner.github.io/peye/examples/deck/)
+for a wide audience and can be run in the [playground](https://eyereasoner.github.io/peye/playground/).
+
+A proof guarantees that the conclusions follow from the rules, not that the
+rules say what the law or the policy says. So `peye --unused` shows which
+parts of a translation make no difference to the conclusions, and an expert
+knows [where to look](https://eyereasoner.github.io/peye/GUIDE#checking-the-translation-not-just-the-reasoning).
+
+## Run it
+
+Python 3.9 or newer. No dependencies, no build step. From the root of a
+checkout:
+
+```sh
+python -m peye examples/socrates.py
+python -m peye --proof examples/socrates.py
+python -m peye --proof examples/socrates.py | python -m peye --check-proof - examples/socrates.py
+python -m unittest discover -s tests
+```
+
+To use peye from anywhere, install it; an editable install keeps using the
+checkout, so your edits take effect at once:
+
+```sh
+pip install -e .
+peye --proof examples/socrates.py
+python examples/socrates.py --proof
+```
+
+Once peye is installed, a program is also a script: `python program.py`
+runs it with the same options as `peye program.py`. Run `peye --help` for the
+full command line.
+
+Or in the browser: the [playground](https://eyereasoner.github.io/peye/playground/) edits, runs and checks any
+example, with peye running in the page through Pyodide. To run it from a
+checkout, serve it (`python -m http.server`) and open `/playground/`.
+
+## From Python
+
+```python
+from peye import check_proof, load_text, run
+
+socrates = load_text("""
+from peye import *
+fact(human('socrates'))
+forward(mortal(X), human(X))
+""")
+result = run(socrates, goal='mortal(X)', proof=True)
+print(result.answers)                                  # ["mortal('socrates')"]
+print(check_proof(socrates, result.proof)['valid'])    # True
+```
+
+`load('program.py')` reads a program file the same way.
+
+## Read on
+
+- **[Make reasoning something you can see](https://eyereasoner.github.io/peye/GUIDE)** —
+  what the language is for, how to write it, what a checked proof does and does
+  not establish, and how the engine works.
+- **[Examples](https://eyereasoner.github.io/peye/examples/)** — 59 complete programs, each with its saved
+  conclusions, proof and C1-C7 check report.
+- **[Example decks](https://eyereasoner.github.io/peye/examples/deck/)** — a short card deck for every
+  example, explaining it for a wide audience: the question, what peye
+  concludes, why, and what the proof checker confirms.
+- **[Playground](https://eyereasoner.github.io/peye/playground/)** — write a program in the browser, run it, check
+  its proof, and share a link to exactly what you see.
+
+## License
+
+[MIT](https://eyereasoner.github.io/peye/LICENSE.md)

peye-0.1.0/README.md

@@ -0,0 +1,127 @@
+# peye
+
+![EYE](https://josd.github.io/images/eye.png)
+
+*peye — reasoning you can see.*
+
+A standalone, dependency-free **Python rule language** with forward and backward
+reasoning and checkable proofs.
+
+peye turns explicit facts and rules into conclusions whose derivations can be
+inspected and checked. An answer can arrive together with a certificate, and
+that certificate can be verified against the program that produced it.
+
+Facts and rules are Python:
+
+```python
+from peye import *
+
+fact(human('socrates'))
+forward(mortal(X), human(X))
+```
+
+There is nothing to declare: a name the program uses without defining it is a
+variable when it starts with a capital or an underscore, like `X`, and a
+predicate otherwise, like `human`. Atoms are strings.
+
+`forward(Head, *Body)` materializes conclusions until a fixpoint.
+`backward(Head, *Body)` defines a predicate evaluated when called. The two
+compose: a forward body may call backward definitions, and a backward goal may
+use facts that forward reasoning established.
+
+## The thread
+
+peye is built around one idea: **reasoning you can see**. You write facts and
+rules; peye draws conclusions, forward until nothing new follows and backward
+on request, and every answer can come with a proof. A separate checker verifies
+that proof against the program, independently of the reasoner, and does more
+than a classic proof checker:
+
+- **The derivation:** every step is an instance of a program clause (C1),
+  nothing is circular (C2), and every claim and every use is justified (C4).
+- **The form (C3):** every step has exactly one justification of an allowed
+  kind, in the right shape, so the report shows at once whether a proof fails
+  on form or on content.
+- **Recomputation (C5):** built-in calculations are redone rather than trusted.
+- **Honesty about absence:** "there is nothing that …" and "these are *all* the
+  answers" cannot be proved; they become explicit obligations, which the
+  checker tries to refute with the evidence at hand (C6).
+- **The right question (C7):** the proof answers the question asked and
+  contains nothing beside it.
+
+The report is itself Python data, and every generated proof is checked before it
+is returned. Proofs are read with Python's `ast` module and never executed, so
+checking a proof from someone else runs none of their code. Around that core, [59 examples](https://eyereasoner.github.io/peye/examples/)
+grew, from Socrates and the zebra puzzle to a hospital research portal decided
+under today's EU rules and under the Commission's Digital Omnibus proposal, and
+package holiday cancellations under the 2015 and the revised Package Travel
+Directive. Each has a [deck](https://eyereasoner.github.io/peye/examples/deck/)
+for a wide audience and can be run in the [playground](https://eyereasoner.github.io/peye/playground/).
+
+A proof guarantees that the conclusions follow from the rules, not that the
+rules say what the law or the policy says. So `peye --unused` shows which
+parts of a translation make no difference to the conclusions, and an expert
+knows [where to look](https://eyereasoner.github.io/peye/GUIDE#checking-the-translation-not-just-the-reasoning).
+
+## Run it
+
+Python 3.9 or newer. No dependencies, no build step. From the root of a
+checkout:
+
+```sh
+python -m peye examples/socrates.py
+python -m peye --proof examples/socrates.py
+python -m peye --proof examples/socrates.py | python -m peye --check-proof - examples/socrates.py
+python -m unittest discover -s tests
+```
+
+To use peye from anywhere, install it; an editable install keeps using the
+checkout, so your edits take effect at once:
+
+```sh
+pip install -e .
+peye --proof examples/socrates.py
+python examples/socrates.py --proof
+```
+
+Once peye is installed, a program is also a script: `python program.py`
+runs it with the same options as `peye program.py`. Run `peye --help` for the
+full command line.
+
+Or in the browser: the [playground](https://eyereasoner.github.io/peye/playground/) edits, runs and checks any
+example, with peye running in the page through Pyodide. To run it from a
+checkout, serve it (`python -m http.server`) and open `/playground/`.
+
+## From Python
+
+```python
+from peye import check_proof, load_text, run
+
+socrates = load_text("""
+from peye import *
+fact(human('socrates'))
+forward(mortal(X), human(X))
+""")
+result = run(socrates, goal='mortal(X)', proof=True)
+print(result.answers)                                  # ["mortal('socrates')"]
+print(check_proof(socrates, result.proof)['valid'])    # True
+```
+
+`load('program.py')` reads a program file the same way.
+
+## Read on
+
+- **[Make reasoning something you can see](https://eyereasoner.github.io/peye/GUIDE)** —
+  what the language is for, how to write it, what a checked proof does and does
+  not establish, and how the engine works.
+- **[Examples](https://eyereasoner.github.io/peye/examples/)** — 59 complete programs, each with its saved
+  conclusions, proof and C1-C7 check report.
+- **[Example decks](https://eyereasoner.github.io/peye/examples/deck/)** — a short card deck for every
+  example, explaining it for a wide audience: the question, what peye
+  concludes, why, and what the proof checker confirms.
+- **[Playground](https://eyereasoner.github.io/peye/playground/)** — write a program in the browser, run it, check
+  its proof, and share a link to exactly what you see.
+
+## License
+
+[MIT](https://eyereasoner.github.io/peye/LICENSE.md)

peye-0.1.0/peye/__init__.py

@@ -0,0 +1,47 @@
+"""peye: reasoning you can see, in Python.
+
+Facts and rules are Python. Forward rules materialize conclusions until a
+fixpoint, backward rules are decided when a goal asks for them, and every
+answer can come with a proof that a separate checker verifies against the
+program, condition by condition (C1-C7).
+"""
+import sys
+
+from .dsl import (
+    _, arg, atom_chars, atom_codes, atom_concat, atom_length, backward, call, compare,
+    contradiction, eq, fact, facts_from, fail, false, findall, forward, functor, identical, is_,
+    is_atom, is_compound, is_float, is_ground, is_int, is_nonvar, is_number, is_var, load,
+    load_text, ne, not_, not_identical, not_unify, once, preds, build, query, struct, true,
+    unify, univ, vars,
+)
+from .engine import Result, run, unused_clauses
+from .program import Program
+from .proof import check_proof, check_report, public_report, verdict_text
+from .reader import read_term, read_terms
+from .terms import PeyeError, Struct, Var
+from .writer import write
+
+# Exact integers can be far longer than Python prints by default.
+if hasattr(sys, 'set_int_max_str_digits'):
+    sys.set_int_max_str_digits(0)
+
+__version__ = '0.1.0'
+
+# What `from peye import *` gives a program: the names it states clauses
+# with. The library API (load, run, check_proof, ...) is imported by name.
+__all__ = [
+    # Stating a program.
+    'preds', 'vars', '_', 'fact', 'facts_from', 'forward', 'backward', 'query', 'contradiction',
+    'struct',
+    # Controls.
+    'call', 'once', 'not_', 'findall',
+    # Primitives.
+    'true', 'fail', 'false', 'unify', 'not_unify', 'identical', 'not_identical', 'compare',
+    'is_', 'eq', 'ne', 'is_var', 'is_nonvar', 'is_ground', 'is_atom', 'is_number', 'is_int',
+    'is_float', 'is_compound', 'functor', 'arg', 'univ', 'atom_chars', 'atom_codes',
+    'atom_length', 'atom_concat',
+]
+
+from .dsl import run_as_script  # noqa: E402
+
+run_as_script()

peye-0.1.0/peye/__main__.py

@@ -0,0 +1,3 @@
+from .cli import entry
+
+entry()

peye-0.1.0/peye/arith.py

@@ -0,0 +1,118 @@
+"""Arithmetic evaluation with Python semantics.
+
+An expression term means what the same expression means in Python: integers
+are unbounded and exact, floats are IEEE-754 doubles, ``/`` is true division,
+``//`` and ``%`` are floor division and modulo, ``**`` is exact on integers
+with a nonnegative exponent, and ``&``, ``|``, ``^``, ``~``, ``<<`` and ``>>``
+are the bitwise operators. The functions are Python's builtins ``abs``,
+``min``, ``max``, ``round``, ``int`` and ``float``, and from ``math`` the
+functions listed in FUNCTIONS. A result that is not a finite real number is an
+error, never a value.
+"""
+import math
+
+from .terms import PeyeError, Var, deref
+
+# A power whose result would need more bits than this is refused rather than
+# allowed to exhaust memory.
+MAX_POWER_BITS = 1 << 26
+
+
+def _power(a, b):
+    if type(a) is int and type(b) is int and b > 0 and abs(a) > 1:
+        if b * a.bit_length() > MAX_POWER_BITS:
+            raise PeyeError(f'arithmetic resource: {a} ** {b} is too large')
+    return a ** b
+
+
+def _shift(a, b):
+    if type(a) is int and type(b) is int and b > MAX_POWER_BITS:
+        raise PeyeError(f'arithmetic resource: {a} << {b} is too large')
+    return a << b
+
+
+BINARY = {
+    '+': lambda a, b: a + b,
+    '-': lambda a, b: a - b,
+    '*': lambda a, b: a * b,
+    '/': lambda a, b: a / b,
+    '//': lambda a, b: a // b,
+    '%': lambda a, b: a % b,
+    '**': _power,
+    '<<': _shift,
+    '>>': lambda a, b: a >> b,
+    '^': lambda a, b: a ^ b,
+    ',': lambda a, b: a & b,
+    ';': lambda a, b: a | b,
+}
+UNARY = {
+    '-': lambda a: -a,
+    '+': lambda a: +a,
+    '~': lambda a: ~a,
+}
+FUNCTIONS = {
+    'abs': abs, 'min': min, 'max': max, 'round': round, 'int': int, 'float': float,
+    'pow': _power, 'gcd': math.gcd, 'lcm': getattr(math, 'lcm', None),
+    'floor': math.floor, 'ceil': math.ceil, 'trunc': math.trunc,
+    'sqrt': math.sqrt, 'isqrt': math.isqrt, 'exp': math.exp, 'log': math.log,
+    'log2': math.log2, 'log10': math.log10,
+    'sin': math.sin, 'cos': math.cos, 'tan': math.tan,
+    'asin': math.asin, 'acos': math.acos, 'atan': math.atan, 'atan2': math.atan2,
+    'sinh': math.sinh, 'cosh': math.cosh, 'tanh': math.tanh,
+    'hypot': math.hypot, 'degrees': math.degrees, 'radians': math.radians,
+    'fmod': math.fmod, 'copysign': math.copysign,
+}
+FUNCTIONS = {name: fn for name, fn in FUNCTIONS.items() if fn is not None}
+CONSTANTS = {'pi': math.pi, 'e': math.e, 'tau': math.tau}
+
+
+def evaluate(term, env):
+    term = deref(term, env)
+    kind = type(term)
+    if kind is int or kind is float:
+        return term
+    if kind is Var:
+        raise PeyeError('arithmetic needs a bound expression, found an unbound variable')
+    if kind is str:
+        if term in CONSTANTS:
+            return CONSTANTS[term]
+        raise PeyeError(f'{term!r} is not an arithmetic value')
+    values = [evaluate(arg, env) for arg in term.args]
+    return apply(term.name, values)
+
+
+def apply(name, values):
+    arity = len(values)
+    if arity == 2 and name in BINARY:
+        fn = BINARY[name]
+    elif arity == 1 and name in UNARY:
+        fn = UNARY[name]
+    elif name in FUNCTIONS:
+        fn = FUNCTIONS[name]
+    else:
+        raise PeyeError(f'{name}/{arity} is not an arithmetic function')
+    try:
+        result = fn(*values)
+    except ZeroDivisionError:
+        raise PeyeError(f'arithmetic: division by zero in {name}') from None
+    except OverflowError:
+        raise PeyeError(f'arithmetic: overflow in {name}') from None
+    except (ValueError, TypeError) as error:
+        raise PeyeError(f'arithmetic: {name} {error}') from None
+    kind = type(result)
+    if kind is int:
+        return result
+    if kind is float:
+        if not math.isfinite(result):
+            raise PeyeError(f'arithmetic: {name} has no finite result')
+        return result
+    if kind is bool:
+        return int(result)
+    raise PeyeError(f'arithmetic: {name} has no real result')
+
+
+def compare(left, right, env):
+    """-1, 0 or 1. Python compares integers and floats exactly."""
+    a = evaluate(left, env)
+    b = evaluate(right, env)
+    return -1 if a < b else (1 if a > b else 0)

peye-0.1.0/peye/builtins.py

@@ -0,0 +1,193 @@
+"""The pure primitives.
+
+Only pure primitives belong here. Collections, call and negation are controls
+handled by the solver and explicitly distinguished in proof documents.
+
+A test decides a goal at most once: it is handed the goal's arguments, the
+same arguments dereferenced, the substitution and a bind function, and says
+whether the goal holds. Any bindings it made on the way to failing are undone
+for it. A relation can hold several times: it is a generator that yields once
+per solution, and the solver undoes the bindings of one solution before asking
+for the next.
+"""
+import itertools
+
+from . import arith
+from .terms import (
+    PeyeError, Struct, Var, compare_terms, copy_resolved, deref, is_ground,
+    key, list_from_items, proper_list_items, unify,
+)
+
+
+def _comparison(holds):
+    return lambda args, resolved, env, bind: holds(arith.compare(args[0], args[1], env))
+
+
+def _same(args, env):
+    return compare_terms(copy_resolved(args[0], env), copy_resolved(args[1], env)) == 0
+
+
+def _not_unify(args, resolved, env, bind):
+    mark = env.mark()
+    unifies = unify(args[0], args[1], env)
+    env.undo(mark)
+    return not unifies
+
+
+def _bounded_integer(term, low, high):
+    if type(term) is not int or term < 0:
+        raise PeyeError('expected a nonnegative integer')
+    if term < low or term > high:
+        raise PeyeError(f'integer outside {low}..{high}')
+    return term
+
+
+_functor_serial = itertools.count(1)
+
+
+def _functor(args, resolved, env, bind):
+    term, name, arity = resolved
+    if type(term) is not Var:
+        if type(term) is Struct:
+            return bind(args[1], term.name) and bind(args[2], len(term.args))
+        return bind(args[1], term) and bind(args[2], 0)
+    count = _bounded_integer(arity, 0, 1024)
+    if type(name) is Var:
+        raise PeyeError('functor/3 needs a bound name')
+    if count > 0 and type(name) is not str:
+        raise PeyeError('functor/3 needs an atom name')
+    # Unique names across primitive invocations preserve variable isolation.
+    serial = next(_functor_serial)
+    if count == 0:
+        return bind(args[0], name)
+    return bind(args[0], Struct(name, tuple(Var(f'_functor{serial}_{i}') for i in range(count))))
+
+
+def _arg(args, resolved, env, bind):
+    position, term = resolved[0], resolved[1]
+    index = _bounded_integer(position, 1, 1024)
+    return type(term) is Struct and index <= len(term.args) and bind(args[2], term.args[index - 1])
+
+
+def _univ(args, resolved, env, bind):
+    term = resolved[0]
+    if type(term) is not Var:
+        if type(term) is Struct:
+            return bind(args[1], list_from_items([term.name, *term.args]))
+        return bind(args[1], list_from_items([term]))
+    items = proper_list_items(args[1], env)
+    items = None if items is None else [deref(item, env) for item in items]
+    if not items or type(items[0]) is Var or (len(items) > 1 and type(items[0]) is not str):
+        raise PeyeError('univ/2 needs a nonempty bound term list')
+    return bind(args[0], items[0] if len(items) == 1 else Struct(items[0], tuple(items[1:])))
+
+
+def _atom_text(name, codes):
+    def test(args, resolved, env, bind):
+        term = resolved[0]
+        if type(term) is str:
+            items = [ord(ch) for ch in term] if codes else list(term)
+            return bind(args[1], list_from_items(items))
+        items = proper_list_items(args[1], env)
+        if items is None:
+            raise PeyeError(f'{name} needs a proper list')
+        chars = []
+        for item in items:
+            item = deref(item, env)
+            if codes:
+                chars.append(chr(_bounded_integer(item, 0, 0x10FFFF)))
+            else:
+                if type(item) is not str or len(item) != 1:
+                    raise PeyeError('atom_chars/2 needs characters')
+                chars.append(item)
+        return bind(args[0], ''.join(chars))
+    return test
+
+
+def _atom_length(args, resolved, env, bind):
+    if type(resolved[0]) is not str:
+        raise PeyeError('atom_length/2 needs a bound atom')
+    return bind(args[1], len(resolved[0]))
+
+
+def _compare(args, resolved, env, bind):
+    order = compare_terms(copy_resolved(args[1], env), copy_resolved(args[2], env))
+    return bind(args[0], '<' if order < 0 else ('>' if order > 0 else '='))
+
+
+def _is(args, resolved, env, bind):
+    return bind(args[0], arith.evaluate(args[1], env))
+
+
+TESTS = {
+    ('true', 0): lambda args, resolved, env, bind: True,
+    ('fail', 0): lambda args, resolved, env, bind: False,
+    ('false', 0): lambda args, resolved, env, bind: False,
+    ('unify', 2): lambda args, resolved, env, bind: bind(args[0], args[1]),
+    ('not_unify', 2): _not_unify,
+    ('identical', 2): lambda args, resolved, env, bind: _same(args, env),
+    ('not_identical', 2): lambda args, resolved, env, bind: not _same(args, env),
+    ('is_', 2): _is,
+    ('eq', 2): _comparison(lambda n: n == 0),
+    ('ne', 2): _comparison(lambda n: n != 0),
+    ('<', 2): _comparison(lambda n: n < 0),
+    ('<=', 2): _comparison(lambda n: n <= 0),
+    ('>', 2): _comparison(lambda n: n > 0),
+    ('>=', 2): _comparison(lambda n: n >= 0),
+    ('is_var', 1): lambda args, resolved, env, bind: type(resolved[0]) is Var,
+    ('is_nonvar', 1): lambda args, resolved, env, bind: type(resolved[0]) is not Var,
+    ('is_ground', 1): lambda args, resolved, env, bind: is_ground(args[0], env),
+    ('is_atom', 1): lambda args, resolved, env, bind: type(resolved[0]) is str,
+    ('is_number', 1): lambda args, resolved, env, bind: type(resolved[0]) in (int, float),
+    ('is_int', 1): lambda args, resolved, env, bind: type(resolved[0]) is int,
+    ('is_float', 1): lambda args, resolved, env, bind: type(resolved[0]) is float,
+    ('is_compound', 1): lambda args, resolved, env, bind: type(resolved[0]) is Struct,
+    ('functor', 3): _functor,
+    ('arg', 3): _arg,
+    ('univ', 2): _univ,
+    ('atom_chars', 2): _atom_text('atom_chars/2', False),
+    ('atom_codes', 2): _atom_text('atom_codes/2', True),
+    ('atom_length', 2): _atom_length,
+    ('compare', 3): _compare,
+}
+
+
+def _atom_concat(args, resolved, env, mark):
+    left, right, whole = resolved
+    if type(left) is str and type(right) is str:
+        if unify(args[2], left + right, env):
+            yield env
+        else:
+            env.undo(mark)
+        return
+    if type(whole) is not str:
+        raise PeyeError('atom_concat/3 needs the result or both operands bound')
+    for i in range(len(whole) + 1):
+        if unify(args[0], whole[:i], env) and unify(args[1], whole[i:], env):
+            yield env
+        env.undo(mark)
+
+
+RELATIONS = {
+    ('atom_concat', 3): _atom_concat,
+}
+PRIMITIVE_KEYS = frozenset(TESTS) | frozenset(RELATIONS)
+
+
+def primitive(goal, env):
+    """Solve a primitive goal: a generator yielding env once per solution."""
+    goal_key = key(goal)
+    args = goal.args if type(goal) is Struct else ()
+    resolved = [deref(arg, env) for arg in args]
+    mark = env.mark()
+    test = TESTS.get(goal_key)
+    if test is None:
+        relation = RELATIONS.get(goal_key)
+        if relation is None:
+            raise PeyeError(f'unsupported primitive {goal_key[0]}/{goal_key[1]}')
+        yield from relation(args, resolved, env, mark)
+        return
+    if test(args, resolved, env, lambda a, b: unify(a, b, env)):
+        yield env
+    else:
+        env.undo(mark)