stelling 0.1.0__py3-none-any.whl

stelling/__init__.py

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: 2026 Nicholas Ehsan Roy
+# SPDX-License-Identifier: Apache-2.0
+
+"""Harness-driven verification for JAX scientific computing.
+
+``stelling`` traces verification harnesses to jaxprs and discharges them with
+SMT solvers, abstract interpretation, and a region-aware fuzzer. See
+``design/founding.md`` in the repository for the roadmap.
+
+Everything heavier than the standard library — ``jax`` and the SMT backends —
+is an optional extra, imported on first use:
+
+* ``pip install "stelling[jax]"`` — tracing harnesses
+* ``pip install "stelling[z3]"`` — Z3 backend
+* ``pip install "stelling[cvc5]"`` — cvc5 backend
+* ``pip install "stelling[all]"`` — everything
+
+``python -m stelling`` reports which of these are importable and runs a
+one-formula smoke test against each installed solver.
+
+The jax-free IR lives in :mod:`stelling.ir`; jax itself is touched only
+inside :mod:`stelling._jax_compat`, the designated churn boundary.
+"""
+
+from __future__ import annotations
+
+from stelling._optional import OptionalDependencyError, available, require
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OptionalDependencyError",
+    "__version__",
+    "available",
+    "require",
+]

stelling/__main__.py

@@ -0,0 +1,120 @@
+# SPDX-FileCopyrightText: 2026 Nicholas Ehsan Roy
+# SPDX-License-Identifier: Apache-2.0
+
+"""``python -m stelling`` — report optional dependencies, smoke-test solvers.
+
+Exit status is nonzero only if an *installed* solver fails its smoke test
+(i.e. a broken wheel or binary); missing optional dependencies are
+informational.
+"""
+
+from __future__ import annotations
+
+import platform
+import re
+import subprocess
+import sys
+
+import stelling
+from stelling._optional import (
+    _OPTIONAL,
+    TESTED_JAX_SERIES,
+    cvc5_binary,
+    jax_series_tested,
+    require,
+    version,
+)
+
+
+def _selfcheck_z3() -> None:
+    z3 = require("z3")
+    x = z3.Real("x")
+    solver = z3.Solver()
+    solver.add(x != x)
+    if solver.check() != z3.unsat:
+        raise RuntimeError("z3 failed to refute `x != x`")
+
+
+def _selfcheck_cvc5() -> None:
+    cvc5 = require("cvc5")
+    tm = cvc5.TermManager()
+    solver = cvc5.Solver(tm)
+    x = tm.mkConst(tm.getRealSort(), "x")
+    solver.assertFormula(tm.mkTerm(cvc5.Kind.DISTINCT, x, x))
+    if not solver.checkSat().isUnsat():
+        raise RuntimeError("cvc5 failed to refute `x != x`")
+
+
+_SELFCHECKS = {"z3": _selfcheck_z3, "cvc5": _selfcheck_cvc5}
+
+_SMTLIB_PROBE = "(set-logic QF_LRA)(declare-const x Real)(assert (distinct x x))(check-sat)\n"
+
+
+def _run(argv: list[str], **kw) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(argv, capture_output=True, text=True, timeout=60, **kw)
+
+
+def _selfcheck_cvc5_binary(path: str) -> None:
+    proc = _run([path, "--lang", "smt2", "-"], input=_SMTLIB_PROBE)
+    verdict = proc.stdout.strip()
+    if verdict != "unsat":
+        raise RuntimeError(
+            f"expected `unsat` for `x != x`, got {verdict!r} (stderr: {proc.stderr.strip()!r})"
+        )
+
+
+def _cvc5_binary_version(path: str) -> str:
+    # first line is `cvc5 1.3.4 [git ...]` (older builds: `This is cvc5 version 1.3.4`)
+    match = re.search(r"^(?:This is )?cvc5(?: version)? (\S+)", _run([path, "--version"]).stdout, re.MULTILINE)
+    return match.group(1) if match else "unknown"
+
+
+def _cvc5_binary_features(path: str) -> list[str]:
+    """Optional components compiled into the binary, per --show-config."""
+    config = _run([path, "--show-config"]).stdout
+    interesting = ("cln", "cocoa", "glpk", "poly", "cryptominisat", "kissat")
+    return [f for f in interesting if re.search(rf"^{f}\s*:\s*yes", config, re.IGNORECASE | re.MULTILINE)]
+
+
+def main() -> int:
+    print(f"stelling {stelling.__version__} on Python {platform.python_version()}")
+    failures = 0
+    for name, spec in _OPTIONAL.items():
+        installed = version(name)
+        if installed is None:
+            line = f'  {name:<9} not installed — pip install "stelling[{spec.extra}]"'
+        else:
+            line = f"  {name:<9} {installed}"
+            if name == "jax" and not jax_series_tested(installed):
+                line += f"  [untested series — stelling is tested against jax {', '.join(TESTED_JAX_SERIES)}.x]"
+            selfcheck = _SELFCHECKS.get(name)
+            if selfcheck is not None:
+                try:
+                    selfcheck()
+                    line += "  [selfcheck: ok]"
+                except Exception as e:  # noqa: BLE001 — report broken wheels, don't crash
+                    failures += 1
+                    line += f"  [selfcheck FAILED: {e}]"
+        print(line)
+
+    # External cvc5 binary: the transport for full-featured (e.g. GPL) builds.
+    path = cvc5_binary()
+    if path is None:
+        print(f"  {'cvc5-bin':<9} none — optional; set STELLING_CVC5 or put `cvc5` on PATH")
+    else:
+        try:
+            line = f"  {'cvc5-bin':<9} {_cvc5_binary_version(path)} ({path})"
+            _selfcheck_cvc5_binary(path)
+            line += "  [selfcheck: ok]"
+            features = _cvc5_binary_features(path)
+            if features:
+                line += f"  [built with: {', '.join(features)}]"
+        except Exception as e:  # noqa: BLE001
+            failures += 1
+            line = f"  {'cvc5-bin':<9} {path}  [selfcheck FAILED: {e}]"
+        print(line)
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

stelling/_bound_spelling.py

@@ -0,0 +1,185 @@
+# SPDX-FileCopyrightText: 2026 Nicholas Ehsan Roy
+# SPDX-License-Identifier: Apache-2.0
+
+"""What a declared bound's VALUE is, decided exactly or not at all.
+
+The declaration layer records bounds as binary64 in the IR, and this
+layer's defect history (three "a case the author did not enumerate"
+escapes, ending in a measured false VERIFIED) is one pattern repeated:
+storability was judged by the bound's TYPE while its VALUE went through
+``float()``, a conversion that silently rounds exactly the values the
+judgment exists to protect.
+
+This module replaces the type question with a value question, asked in a
+single exact domain: every accepted spelling is mapped to the exact
+number it denotes — a :class:`fractions.Fraction` when finite, the
+binary64 ``±inf``/``nan`` when not — and every downstream judgment (is
+it storable? does rounding narrow or widen? does the declared interval
+hold a dtype value?) is made by exact rational comparison. Spelling
+independence is then structural rather than enumerated: two spellings of
+one value map to one rational, so no route and no guard can tell them
+apart.
+
+THE FAMILY IS CLOSED, AND EVERY SPELLING OUTSIDE IT IS COVERED BY
+REFUSAL. Accepted: python ``int``/``bool``/``float``; numpy integer,
+floating (every width, ``longdouble`` included), and bool scalars;
+``decimal.Decimal``; ``fractions.Fraction``; 0-d numpy arrays of those.
+Anything else — ``str``, ``complex``, a jax array, an ``ml_dtypes``
+scalar, any third-party number, any object with a ``__float__`` — makes
+:func:`declared_bound_value` return None, and the declaration layer
+refuses it loudly, naming this family. That is the whole coverage story
+for spellings nobody thought of: they are refused BY DEFAULT, before any
+conversion, so a new numeric type cannot ride in through ``float()`` and
+round on the way in. (A ``str`` like ``'0.1'`` denotes a decidable
+value, so its refusal is POLICY rather than necessity: accepting text
+would reopen the family this module exists to close. Respell it
+``Decimal('0.1')`` for the exact decimal, or ``0.1`` for the binary64.)
+
+jax-free and numpy-lazy, so :mod:`stelling.contracts` can validate at
+authoring time in a bare environment: numpy is recognized when it is
+importable and irrelevant when it is not — a numpy-spelled bound cannot
+exist in a process that has no numpy.
+"""
+
+from __future__ import annotations
+
+import math
+from decimal import Decimal
+from fractions import Fraction
+
+__all__ = ["ACCEPTED_SPELLINGS", "binary64_image", "declared_bound_value"]
+
+# The one sentence every unknown-spelling refusal quotes, so the family
+# is named identically at every route into the layer.
+ACCEPTED_SPELLINGS = (
+    "a python int, float, or bool; a numpy integer, floating, or bool "
+    "scalar; a decimal.Decimal; a fractions.Fraction; or a 0-d numpy "
+    "array of one of those (np.asarray(x) converts a concrete jax scalar)"
+)
+
+
+def _np():
+    try:
+        import numpy
+    except ImportError:  # pragma: no cover — every tested venv has numpy
+        return None
+    return numpy
+
+
+def declared_bound_value(raw):
+    """The exact value ``raw`` declares: a :class:`Fraction` for a
+    finite nonzero value; a FLOAT for the values binary64 holds exactly
+    but Fraction cannot represent faithfully — ``±inf``, ``nan``, and
+    the signed zeros (a Fraction has no ``-0``, and the recorded param
+    must keep the zero's sign the parent recorded); or **None** for a
+    spelling outside the accepted family — the caller refuses a None;
+    nothing here or downstream ever converts one."""
+    # bool before int (bool is an int subclass); both are exact already
+    if isinstance(raw, bool):
+        return Fraction(int(raw))
+    if isinstance(raw, int):
+        return Fraction(raw)
+    if isinstance(raw, float):
+        # np.float64 subclasses float and lands here; it IS a binary64,
+        # so this branch and the np.floating one below agree on it. Two
+        # value classes go through float() instead of Fraction: the
+        # non-finite ones (nothing to round about ±inf/nan, and float()
+        # NORMALIZES np.float64('inf') so the recorded param keeps the
+        # python-float type the parent recorded) and ZERO, whose IEEE
+        # sign a Fraction cannot carry — classifying -0.0 through
+        # Fraction recorded +0.0 where the parent recorded -0.0, moving
+        # recorded params and the query content hash for a spelling
+        # class disclosed as unmoved (measured; blinded lens, repair
+        # round 1). float() of a zero is exact and keeps the sign.
+        if math.isfinite(raw) and raw != 0.0:
+            return Fraction(raw)
+        return float(raw)
+    if isinstance(raw, Fraction):
+        return raw
+    if isinstance(raw, Decimal):
+        if raw.is_nan():
+            return math.nan
+        if raw.is_infinite():
+            return math.inf if raw > 0 else -math.inf
+        if raw.is_zero():
+            # Decimal('-0') is a signed zero too, and the parent's
+            # float() image recorded -0.0 for it (measured); keep that
+            return float(raw)
+        return Fraction(raw)
+    np = _np()
+    if np is not None:
+        if isinstance(raw, np.bool_):
+            return Fraction(int(raw))
+        if isinstance(raw, np.integer) and raw.dtype.kind in "iu":
+            # numpy's scalar lattice is not a number lattice:
+            # np.timedelta64 IS an np.integer subclass (measured; blinded
+            # lens, repair rounds 1-2), so the isinstance test alone let
+            # datetime arithmetic in as bounds: a tick count was silently
+            # ADMITTED with its unit discarded — recorded as a plain
+            # integer — for the generic form and every unit whose value
+            # int() cannot turn into a datetime.timedelta (as/fs/ps/ns
+            # and the calendar units M/Y; measured per unit), while the
+            # timedelta-representable units (us through W) and NaT
+            # crashed in int() with a bare TypeError, on every route. The
+            # dtype-kind conjunct asks
+            # numpy's VALUE system (kind 'i'/'u' means integer) rather
+            # than its class tree, so timedelta64 (kind 'm'),
+            # datetime64 (kind 'M') and anything else the lattice grafts
+            # onto an integer parent falls through to the default
+            # refusal. np.floating below needs no such conjunct: every
+            # np.floating subclass this numpy has is kind 'f', and an
+            # unexercisable guard would be an unpinnable half.
+            return Fraction(int(raw))
+        if isinstance(raw, np.floating):
+            # as_integer_ratio is exact at every numpy width, the
+            # longdouble 64-bit significand included; float(raw) is the
+            # rounding this module exists to avoid, and it is also
+            # WRONG here — float(np.longdouble('1e400')) silently
+            # returns inf for a finite declared value
+            if np.isnan(raw):
+                return math.nan
+            if np.isinf(raw):
+                return math.inf if raw > 0 else -math.inf
+            if raw == 0:
+                # ±0.0 at any width: float() is exact and keeps the
+                # sign the parent recorded; as_integer_ratio drops it
+                return float(raw)
+            return Fraction(*raw.as_integer_ratio())
+        if isinstance(raw, np.ndarray) and raw.ndim == 0:
+            inner = raw[()]
+            # a 0-d array unwraps to its numpy scalar; a dtype the
+            # family does not hold (complex, datetime, object) falls
+            # through to None exactly as the bare scalar would
+            if not isinstance(inner, np.ndarray):
+                return declared_bound_value(inner)
+    return None
+
+
+def binary64_image(v):
+    """The binary64 the IR would record for exact value ``v`` (an output
+    of :func:`declared_bound_value`): round-to-nearest, ties-to-even,
+    overflowing to the infinity of ``v``'s sign.
+
+    Agrees with ``float(raw)`` everywhere ``float(raw)`` returns a
+    finite answer (both are correct nearest-even rounding; measured over
+    the spelling grid in tests), but is TOTAL where ``float`` is not:
+    ``float(10**400)`` raises OverflowError while the longdouble
+    spelling of the same magnitude silently returned inf — one value,
+    two behaviours. Here the overflow that makes ``float`` raise is
+    caught and mapped to the signed infinity the rounding denotes, and
+    the caller judges that image (it is non-finite for a finite declared
+    value exactly when the value cannot be recorded at all).
+
+    CPython's int/int true division is correctly rounded, which is what
+    makes ``numerator / denominator`` the exact rounding rather than an
+    approximation of it.
+    """
+    if isinstance(v, float):
+        # ±inf, nan, and the signed zeros: binary64 holds each exactly,
+        # nothing to round (the zero's sign survives precisely because
+        # it never went through Fraction)
+        return v
+    try:
+        return v.numerator / v.denominator
+    except OverflowError:
+        return math.inf if v > 0 else -math.inf

stelling/_cvc5_driver.py

@@ -0,0 +1,160 @@
+# SPDX-FileCopyrightText: 2026 Nicholas Ehsan Roy
+# SPDX-License-Identifier: Apache-2.0
+
+"""Child-process driver for the cvc5 wheel transport.
+
+``stelling.solvers`` runs this module as ``python -m stelling._cvc5_driver``
+with an SMT-LIB2 script on stdin. It feeds the script through the wheel's
+own SMT-LIB2 parser (``cvc5.InputParser``, SMT_LIB_2_6 string input) —
+the ``get-model`` command is realized through the model API
+(``getValue``), everything else is invoked as parsed — and reports on
+stdout in a line protocol::
+
+    version <backend version>
+    answer <sat|unsat|unknown>
+    value <name> <exact rational p/q>        (sat only, one per declared const)
+    opaque <name> <raw term text>            (sat, non-rational model value)
+    end <count of value+opaque lines written>
+
+``end <count>`` is the terminator, and the parent requires it to be the
+**last line** of stdout and to state the number of model lines the parent
+actually parsed. A bare token would only say "the driver reached its last
+statement"; the count says "and it wrote exactly this much model", which is
+what *complete* has to mean if a crashed or truncated run is to be refused
+(``solvers._run_cvc5_wheel``). Driver and parent ship in the same package
+and are read together — change one and you must change the other; a
+mismatch degrades every run to UNKNOWN with the terminator quoted, which
+is the safe direction but is still a break. **That is a claim about the
+PAIR, and its two halves are not equal.** A stale DRIVER writing past this
+whitelist is caught by the parent for nine of the ten separators and not
+for the tenth, which is ``\\n``, the protocol's own record boundary
+(measured, real children, real bytes: ``scratchpad/probe_cvc5_backstop.py``
+part A, and
+``tests/test_solver_audit_findings.py::test_f4wheel3_the_reader_now_refuses_nine_of_the_ten_separators``).
+A stale PARENT is not caught here at all. The whitelist is what makes the
+sentence true for all ten in the direction this file controls.
+
+THE PROTOCOL'S ALPHABET, and why it is a whitelist. Every field below is
+written through :func:`_token` / :func:`_tail`, which pass **printable
+ASCII and nothing else**; the only ``\\n`` on this stdout is the one
+``print`` puts at the end of a record. This used to be a blacklist —
+``str.replace("\\n", " ")`` on the model text only — and it was too narrow
+twice over:
+
+* ``str.splitlines()``, which the parent used to read with, breaks on ten
+  characters, not one (measured: U+000A U+000B U+000C U+000D U+001C U+001D
+  U+001E U+0085 U+2028 U+2029). A model value carrying one of those was
+  ONE line to this writer and TWO to that reader, which let the payload
+  forge the terminator.
+* ``\\r`` used to be worse than the rest and unfixable downstream: the
+  parent captured with ``text=True``, so Python's universal-newline
+  decoding turned a ``\\r`` into a real ``\\n`` **before the parent got to
+  split anything** (measured), and no reader-side rule could see it.
+  **THAT SENTENCE DESCRIBED A PARENT THIS PACKAGE NO LONGER HAS**
+  (2026-08-09): the parent reads bytes and applies the one translation
+  itself (``solvers._decode_child_stream``), so a bare ``\\r`` now reaches
+  its alphabet check and is refused there — eight of the ten backstopped
+  became nine. **This whitelist is still the load-bearing half and is not
+  weakened by that.** The reader's share is what a STALE parent-and-driver
+  pair degrades to; the boundary for a matched pair is created here, and
+  ``\\n`` and ``\\r\\n`` are created here or nowhere at all, because both
+  are real record boundaries that no reader can tell from two records.
+
+A whitelist rather than a wider blacklist because the blacklist's contents
+are not ours: ``str.splitlines()`` may learn a new separator, and the io
+layer may learn a new translation. Printable ASCII cannot become a line
+boundary under either.
+
+:func:`_token` additionally escapes the space, because ``value`` and
+``opaque`` lines are read with ``split(maxsplit=2)`` — a space inside a
+NAME would shift the value into the name's field, which is the same
+writer/reader disagreement one delimiter down.
+
+Why a child process at all, measured on cvc5 1.3.4: the wheel's
+``checkSat`` holds the GIL for the entire check, so an in-process thread
+guard can never fire, and the script-level ``:tlimit`` does not reliably
+preempt the coverings solver — the parent's subprocess timeout is the
+wall-clock guard that actually binds. Any internal failure prints
+``error <reason>`` and exits 0; the parent degrades it to UNKNOWN (the
+guard rule: solver failures are quoted reasons, never crashes).
+
+Stdlib-only at import time; cvc5 is imported inside :func:`main` via
+``stelling._optional``.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from stelling._optional import require
+
+
+def _esc(text: str, keep_space: bool) -> str:
+    lo = 0x20 if keep_space else 0x21
+    return "".join(
+        c if lo <= ord(c) <= 0x7E else f"\\u{{{ord(c):x}}}" for c in text
+    )
+
+
+def _token(text: str) -> str:
+    """One whitespace-free field: no line boundary AND no field boundary."""
+    return _esc(text, keep_space=False)
+
+
+def _tail(text: str) -> str:
+    """A record's free-text last field: spaces are content, everything
+    outside printable ASCII is escaped."""
+    return _esc(text, keep_space=True)
+
+
+def main() -> int:
+    out = sys.stdout
+    try:
+        cvc5 = require("cvc5")
+        script = sys.stdin.read()
+        tm = cvc5.TermManager()
+        solver = cvc5.Solver(tm)
+        version = solver.getVersion()
+        if isinstance(version, bytes):
+            version = version.decode("utf-8", "replace")
+        print(f"version {_token(str(version))}", file=out)
+        parser = cvc5.InputParser(solver)
+        parser.setStringInput(
+            cvc5.InputLanguage.SMT_LIB_2_6, script, "stelling-escalation"
+        )
+        sm = parser.getSymbolManager()
+        answer = ""
+        while True:
+            cmd = parser.nextCommand()
+            if cmd.isNull():
+                break
+            if str(cmd).strip().startswith("(get-model"):
+                continue  # realized via the model API below
+            result = cmd.invoke(solver, sm)
+            if result:
+                token = result.strip()
+                if token in ("sat", "unsat", "unknown"):
+                    answer = token
+        if not answer:
+            print("error script produced no check-sat answer", file=out)
+            return 0
+        print(f"answer {answer}", file=out)
+        written = 0
+        if answer == "sat":
+            for term in sm.getDeclaredTerms():
+                value = solver.getValue(term)
+                name = _token(str(term))
+                if value.isRealValue():
+                    print(f"value {name} {_tail(str(value.getRealValue()))}", file=out)
+                else:
+                    print(f"opaque {name} {_tail(str(value))}", file=out)
+                written += 1
+        print(f"end {written}", file=out)
+        return 0
+    except Exception as e:  # noqa: BLE001 — the parent quotes this, never crashes
+        print(f"error {_tail(f'{type(e).__name__}: {e}')}", file=out)
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())