codecalc 0.1.0__py3-none-win_amd64.whl

codecalc/doctor.py

@@ -0,0 +1,428 @@
+"""What this install actually resolved, as data (THE-780).
+
+`codecalc doctor` existed and printed prose. Prose is right for the operator
+reading it and useless to the installer script, the CI job or the agent that
+wants to branch on whether the native executor is present — all of which had to
+either parse English or make a tool call and read a field out of the result.
+
+So the report is built here as a dict and rendered by the caller. Two
+consequences worth having: the text and the JSON cannot disagree, because there
+is one source; and the report is testable without spawning a CLI, which is what
+made the degraded-environment cases (no binary, no runtimes, unwritable
+workspace) reachable at all.
+
+THE FOUR-STATE RUNTIME VOCABULARY, AND WHY IT IS NOT FOUR STATES BY DEFAULT
+
+THE-780 asks doctor to distinguish `supported`, `installed`, `available` and
+`unhealthy`. The honest version of that distinction costs something:
+
+    supported   codecalc knows this language; nothing for it resolves here
+    installed   its command resolves on the sandbox PATH and is executable
+    unhealthy   its command resolves and is NOT executable, or was run and failed
+    available   it was actually RUN here and answered
+
+`available` is the only one that requires executing the runtime, and there are
+31 of them. Doing that on every `doctor` invocation would turn a diagnostic
+into a minute-long build step, so the default reports resolution only —
+`installed`, never `available` — and `--deep` is what promotes a resolved
+runtime to `available` or demotes it to `unhealthy` by running it.
+
+That split is the point rather than a shortcut. Reporting `available` for a
+binary this process only found on PATH would be the exact defect this project
+keeps correcting: a field that claims a stronger measurement than was taken.
+`status_basis` says which of the two ran, per report, so a reader never has to
+infer it.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from . import __version__, contract, executor, landlock, optional, providers, registry
+
+#: The four states, ordered weakest to strongest claim. Defined in registry.py
+#: and re-exported here: `list_languages` reports the same vocabulary now
+#: (THE-817), and registry is the module all three readers already import.
+#: contract.py's schema still imports it from this name.
+RUNTIME_STATES = registry.RUNTIME_STATES
+
+#: Extras, and the modules whose presence defines them. Mirrors what the text
+#: renderer used to hardcode.
+EXTRAS: dict[str, tuple[str, ...]] = {
+    "symbolic": ("sympy", "z3"),
+    "parsing": ("tree_sitter_language_pack",),
+}
+
+#: Registry entries that are a second spelling of a language already counted.
+#: Mirrors `_ALIAS_ENTRIES` in server.py and `ALIAS_ENTRIES` in
+#: scripts/check_claims.py — the count this reports has to agree with the
+#: README's and the gate's, or it is a fourth opinion on a number this repo
+#: already has a gate for.
+ALIAS_ENTRIES = frozenset({"c++"})
+
+
+def primary_command(entry: dict, name: str | None = None) -> str:
+    """The command whose presence decides whether a language resolves.
+
+    Mirrors the fallback in `executor.probe()` deliberately, and
+    `tests/test_doctor.py` asserts the two agree on every language. Two copies
+    of this rule that drift would make `doctor` and the executor disagree about
+    which runtimes exist, which is worse than either being wrong on its own.
+
+    For a shell-wrapped language the deciding command is the REAL tool, not
+    `bash` (THE-835): `bash` resolving says nothing about whether gleam is
+    installed, and probing it advertised wrapper languages on machines that
+    had never seen them. `name` is optional only for callers that predate the
+    wrapper distinction; passing it is what makes the answer honest.
+    """
+    if name is not None and name in registry.SHELL_WRAPPED:
+        return registry.WRAPPED_TOOL[name]
+    cmd = entry["run"][0] if entry["run"] else ""
+    if cmd.startswith("{"):
+        cmd = (entry["compile"] or ["bash"])[0] if entry["compile"] else "bash"
+    if cmd.startswith(("bash", "sh")):
+        cmd = "bash"
+    return cmd
+
+
+def _runtime_status(cmd: str) -> tuple[str, str | None]:
+    """`(status, resolved_path)` from resolution alone — no execution."""
+    if not cmd:
+        return "supported", None
+    runtime_path = registry.runtime_path()
+    path = shutil.which(cmd, path=runtime_path)
+    if path is not None:
+        return "installed", path
+
+    # `shutil.which` already filters by the execute bit, so a present-but-not-
+    # executable command comes back as None and would report `supported` —
+    # "codecalc knows this language, nothing for it here" — when the file is
+    # sitting right there unable to run. That is the most confusing answer
+    # available: the operator can see the binary and doctor says it is absent.
+    #
+    # The first version of this function had exactly that bug. It called
+    # os.access(X_OK) on which()'s result, which can only ever be True, so
+    # `unhealthy` was unreachable without --deep and the four-state vocabulary
+    # was three states wearing four names. Caught by the test written for it.
+    #
+    # So the fallback scan is a SECOND pass, deliberately after which(): which()
+    # handles PATHEXT on Windows and this does not, and getting that wrong would
+    # trade a rare state for a common platform.
+    for directory in runtime_path.split(os.pathsep):
+        if not directory:
+            continue
+        candidate = Path(directory) / cmd
+        if candidate.is_file():
+            return "unhealthy", str(candidate)
+    return "supported", None
+
+
+def _grammar_cache() -> dict:
+    """Is the tree-sitter grammar cache warm? (THE-821)
+
+    `analyze_complexity` parses with tree-sitter, and the grammars are NOT in
+    the wheel — `tree-sitter-language-pack` ships a ~5 MB extension and fetches
+    each grammar on first use, in-process, into a local cache (28 grammars,
+    89 MB, ~15s cold).
+
+    That is a socket opened from inside the server, which is a surprise on a
+    host chosen for being offline. Reported here so it is discoverable BEFORE a
+    tool call degrades to `regex-fallback`, rather than after — an operator
+    planning an air-gapped install otherwise has no way to find out.
+
+    `cached: false` is not an error. It means the first analysis of each
+    language will reach the network; `scripts/prefetch_grammars.py` warms it.
+    """
+    if not optional.have("tree_sitter_language_pack"):
+        return {"extra_installed": False, "cached": False, "path": None,
+                "grammars": 0,
+                "detail": "the 'parsing' extra is not installed; "
+                          "analyze_complexity uses the regex fallback"}
+    try:
+        from tree_sitter_language_pack import cache_dir as _cache_dir
+
+        path = str(_cache_dir())
+    except Exception as exc:
+        return {"extra_installed": True, "cached": False, "path": None,
+                "grammars": 0,
+                "detail": f"cannot resolve the grammar cache: "
+                          f"{type(exc).__name__}: {exc}"}
+
+    # COUNTED, not just existence-checked: an empty cache directory is created
+    # by the pack before anything is downloaded, so `path.is_dir()` is true on a
+    # completely cold host and would report a warm cache that is not there.
+    count = 0
+    p = Path(path)
+    if p.is_dir():
+        count = sum(1 for f in p.iterdir()
+                    if f.is_file() and f.suffix in (".so", ".dylib", ".dll", ".pyd"))
+    return {
+        "extra_installed": True,
+        "cached": count > 0,
+        "path": path,
+        "grammars": count,
+        "detail": None if count else (
+            "no grammars cached — the first analyze_complexity call per "
+            "language will DOWNLOAD one. Run scripts/prefetch_grammars.py to "
+            "warm it, which is what an offline install needs"),
+    }
+
+
+def _workspace_check() -> dict:
+    """Can we actually create a workdir? Written, not assumed.
+
+    `tempfile.gettempdir()` returning a path says nothing about whether this
+    process may write there — a read-only TMPDIR, a full disk and a correct
+    setup all return the same string. Every execution needs a writable workdir,
+    so this is the one check whose failure means nothing will work.
+    """
+    root = tempfile.gettempdir()
+    try:
+        with tempfile.TemporaryDirectory(prefix="codecalc-doctor-") as d:
+            probe = Path(d) / "w"
+            probe.write_text("ok", encoding="utf-8")
+            probe.read_text(encoding="utf-8")
+        return {"path": root, "writable": True, "error": None}
+    except OSError as exc:
+        return {"path": root, "writable": False,
+                "error": f"{type(exc).__name__}: {exc}"}
+
+
+def report(deep: bool = False) -> dict:
+    """Everything `doctor` knows, as data.
+
+    `deep=True` executes each resolved runtime to promote it to `available` or
+    demote it to `unhealthy`. Off by default: 31 runtimes is not a diagnostic,
+    it is a build.
+    """
+    backend = executor.backend()
+    abi = landlock.abi_version()
+
+    extras = []
+    for name, modules in EXTRAS.items():
+        missing = [m for m in modules if not optional.have(m)]
+        extras.append({
+            "name": name,
+            "installed": not missing,
+            "missing": missing,
+            # The exact command, because "install the extra" is not actionable
+            # and this is the one place that knows the distribution name.
+            "remedy": None if not missing else f"pip install 'codecalc[{name}]'",
+        })
+
+    langs = [name for name in sorted(registry.LANGUAGES) if name not in ALIAS_ENTRIES]
+    runtimes = []
+    for name in langs:
+        cmd = primary_command(registry.LANGUAGES[name], name)
+        # A plan the platform cannot run reports `supported` — "codecalc knows
+        # this language, nothing FOR IT here" — with the reason in `detail`,
+        # BEFORE any resolution happens. Resolving the tool first and then
+        # deciding would report gleam `installed` on a Windows box where the
+        # plan is structurally unable to run (THE-835): a stronger claim than
+        # was measured, which is the defect this file's docstring is about.
+        if not registry.plan_supported(name, windows=os.name == "nt"):
+            runtimes.append({
+                "name": name, "command": cmd, "status": "supported",
+                "path": None, "version": None,
+                "detail": "the canonical plan needs a POSIX shell to scaffold "
+                          "a project; unsupported on Windows",
+            })
+            continue
+        status, path = _runtime_status(cmd)
+        # A wrapped plan needs its shell AS WELL as its tool. The tool
+        # resolving while bash is absent (minimal containers) is still a plan
+        # that cannot run, and `installed` would overstate it.
+        if (name in registry.SHELL_WRAPPED and status == "installed"
+                and shutil.which("bash", path=registry.runtime_path()) is None):
+            status, path = "supported", None
+        # `version` is present on every row so a caller never has to branch on
+        # the key's existence, and is None unless it was actually read. Under
+        # --deep only, for the same reason `available` is: asking 31 runtimes
+        # their version is a build, not a diagnostic.
+        row = {"name": name, "command": cmd, "status": status, "path": path,
+               "version": _runtime_version(cmd, path) if deep else None}
+        # Only languages with a hello program are promoted. Running the others
+        # with an EMPTY source would execute a no-op, find no "codecalc" in its
+        # stdout, and demote a perfectly good runtime to `unhealthy` — a --deep
+        # run reporting failures it manufactured itself. They stay `installed`,
+        # which is what was actually measured about them.
+        if deep and status == "installed" and name in _HELLO:
+            probe = executor.execute(name, _HELLO[name], timeout=20)
+            ran = probe.get("ok") is True and "codecalc" in (probe.get("stdout") or "")
+            row["status"] = "available" if ran else "unhealthy"
+            if not ran:
+                row["detail"] = (probe.get("error")
+                                 or (probe.get("stderr") or "")[:200]
+                                 or f"verdict={probe.get('verdict')}")
+        runtimes.append(row)
+
+    summary = {state: sum(1 for r in runtimes if r["status"] == state)
+               for state in RUNTIME_STATES}
+    workspace = _workspace_check()
+    provider_registry = providers.configured_registry()
+    execution_providers = []
+    for descriptor in provider_registry.descriptors():
+        row = dict(descriptor)
+        if descriptor["host_class"] in {"local", providers.strict_host_platform()}:
+            health = provider_registry.select(descriptor["provider_id"]).health()
+            row["ready"] = health["ready"]
+            row["technology"] = health.get("technology")
+            row["detail"] = health.get("error")
+        else:
+            # Doctor must not turn into an unsolicited remote network probe.
+            row["ready"] = None
+            row["technology"] = None
+            row["detail"] = "remote readiness not probed by doctor"
+        execution_providers.append(row)
+
+    # `healthy` is deliberately NARROW. A missing optional extra and an
+    # uninstalled Haskell are ordinary facts about a host, not faults, and
+    # exiting non-zero for them would make `doctor` useless as an install check
+    # — the thing THE-780 wants it to be. What makes an install unhealthy is
+    # that it cannot execute anything: no workspace to run in, or no backend.
+    healthy = bool(workspace["writable"]) and backend in ("rust", "python")
+
+    return {
+        # Under the result contract's version and policy rather than a third
+        # number of its own. This is machine-readable output a client programs
+        # against, which is what that policy is for; a separate doctor version
+        # would mean two documents to keep in step and two policies to read.
+        "contract_version": contract.CONTRACT_VERSION,
+        "codecalc_version": __version__,
+        "healthy": healthy,
+        "python": {"version": sys.version.split()[0], "platform": sys.platform},
+        "backend": {
+            "kind": backend,
+            "binary": executor._rust,
+            # Named rather than left as an absence: "no binary" and "a binary
+            # that would not run" are different problems with different fixes.
+            "detail": None if backend == "rust" else (
+                "native executor not found — running the pure-Python fallback, "
+                "which cannot enforce no_net. Set CODECALC_REQUIRE_NATIVE=1 to "
+                "make this a startup failure instead of a weaker sandbox."),
+        },
+        "execution_providers": execution_providers,
+        "install_sandbox": {
+            "landlock_abi": abi,
+            "confined": bool(abi),
+            "detail": None if abi else "installs are not confined on this host",
+        },
+        "extras": extras,
+        # Where analyze_complexity's grammars come from, and whether they are
+        # here yet. Not an extra and not a runtime: it is a network dependency
+        # of a tool, which neither of those blocks describes.
+        "grammar_cache": _grammar_cache(),
+        # Which measurement produced the statuses above. Without this a reader
+        # cannot tell `installed` ("found on PATH") from a --deep run that
+        # simply found nothing runnable.
+        "status_basis": "executed" if deep else "resolved",
+        "runtimes": runtimes,
+        "runtime_summary": summary,
+        "workspace": workspace,
+        "skill_file": _skill_path(),
+        "remedies": _remedies(backend, extras, runtimes, workspace),
+    }
+
+
+#: A one-line program per language would be 31 more things to keep correct, and
+#: `--deep` only needs to prove the runtime answers at all. Languages absent
+#: here are still resolved and reported; they are simply not promoted.
+_HELLO = {
+    "python3": 'print("codecalc")',
+    "node": 'console.log("codecalc")',
+    "ruby": 'puts "codecalc"',
+    "perl": 'print "codecalc\\n";',
+    "php": '<?php echo "codecalc\\n";',
+    "lua": 'print("codecalc")',
+    "bash": 'echo codecalc',
+}
+
+
+#: How to ask a runtime its version. Keyed by COMMAND rather than by language,
+#: because `primary_command` collapses several languages onto one binary and
+#: asking `bash` its version four times would be three wasted spawns.
+#:
+#: `--version` is the default and the map holds only the exceptions, so a
+#: runtime added later works without an entry. An exception is not a special
+#: case for its own sake: `java -version` predates the GNU convention and
+#: prints to STDERR, which is why both streams are read below.
+_VERSION_FLAG: dict[str, str] = {
+    "java": "-version",
+    "kotlinc": "-version",
+}
+
+#: Commands with no version flag worth calling. `escript` and `tclsh` have no
+#: non-interactive `--version`, and invoking them without one starts a REPL that
+#: would hang until the timeout. Listed rather than discovered, because "it hung
+#: for 10 seconds" is a bad way to learn this.
+_NO_VERSION = frozenset({"escript", "tclsh"})
+
+
+def _runtime_version(command: str, path: str | None) -> str | None:
+    """The runtime's own version string, or None when it could not be read.
+
+    NONE MEANS NOT MEASURED, NEVER "no version". THE-780 asks doctor to report
+    versions; it does not ask it to invent them. A runtime that has no version
+    flag, times out, crashes, or answers with something unparsable all produce
+    `None` here and leave `status` untouched — a version that could not be read
+    says nothing about whether the runtime works, and demoting it would report a
+    failure this function manufactured.
+
+    Runs under the executor's 23-entry env allowlist rather than the doctor
+    process's own environment. This is a diagnostic, but it is still spawning
+    host binaries, and there is no reason for `gcc --version` to see an API key.
+    """
+    if not path or command in _NO_VERSION:
+        return None
+    flag = _VERSION_FLAG.get(command, "--version")
+    try:
+        proc = subprocess.run(
+            [path, flag],
+            capture_output=True, timeout=10, env=executor._env(), check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    # stdout OR stderr: `java -version` uses stderr, and a runtime that answers
+    # on the stream we did not read is indistinguishable from one that did not
+    # answer at all.
+    for stream in (proc.stdout, proc.stderr):
+        text = (stream or b"").decode("utf-8", "replace").strip()
+        for line in text.splitlines():
+            line = line.strip()
+            if line:
+                # First non-empty line, capped. Some runtimes print a paragraph
+                # (gcc prints its licence), and the report is a diagnostic, not
+                # a transcript.
+                return line[:120]
+    return None
+
+
+def _skill_path() -> str | None:
+    p = Path(__file__).resolve().parent / "SKILL.md"
+    return str(p) if p.is_file() else None
+
+
+def _remedies(backend: str, extras: list, runtimes: list, workspace: dict) -> list[str]:
+    """What to do about it, in the order it matters."""
+    out = []
+    if not workspace["writable"]:
+        out.append(f"workspace {workspace['path']} is not writable "
+                   f"({workspace['error']}) — nothing can execute until it is; "
+                   f"set TMPDIR to a writable directory")
+    if backend != "rust":
+        out.append("build the native executor (`cargo build --release` in "
+                   "executor/, then copy it to bin/) or install a platform "
+                   "wheel — the fallback cannot enforce no_net")
+    for e in extras:
+        if e["remedy"]:
+            out.append(e["remedy"])
+    unhealthy = [r["name"] for r in runtimes if r["status"] == "unhealthy"]
+    if unhealthy:
+        out.append(f"resolved but not runnable: {', '.join(unhealthy)} — "
+                   f"check the file mode and the runtime PATH")
+    return out

codecalc/errors.py

@@ -0,0 +1,214 @@
+"""Stable error codes for the result contract (THE-781).
+
+Every failing tool result carried a free-form English sentence and nothing
+else — 121 distinct `"error":` strings across the package. A caller could show
+them to a human and could do nothing else with them: "unknown language 'foo'",
+"expression too long", "uv not found" and "session worker died" are four
+different situations that a program has to tell apart by matching prose that
+nobody promised to keep stable.
+
+So this adds a `code` beside the message rather than replacing it. The message
+stays human-facing and free to improve; the code is the part a caller may
+branch on, and the part this module promises not to churn.
+
+TWO MECHANISMS, AND THE SECOND IS TRANSITIONAL
+`classify()` maps an EXCEPTION to a code and is the mechanism worth having: it
+keys on the exception type, which the code that raised it chose deliberately.
+
+That was going to be enough. It is not. The first draft attached it only to
+`guarded_call`, on the assumption that symbolic tools raise and it catches
+them. Measured against the eight most reachable failures — a bad expression,
+an unknown language, an unknown session, a blown recursion ceiling — it
+reached ZERO of them, because those paths `return {"ok": False, ...}` directly
+and never raise. An assumption about control flow, disproved by running it.
+
+So `ensure_code()` is the second mechanism: it fills in a code for a failing
+result that has none, by matching the message. Message matching is fragile —
+improve a sentence and the classification changes with it — so a code derived
+that way is marked `code_inferred: true` and is NOT the same claim as one
+attached at the raise site.
+
+The distinction is the point. `scripts/check_claims.py` counts inferred codes
+and floors the total, so the transitional half is visible and shrinking rather
+than quietly permanent.
+"""
+
+from __future__ import annotations
+
+#: The taxonomy. Values are the wire format and are API: renaming one is a
+#: breaking change to the result contract, which is the whole point of having
+#: them. Deliberately coarse — eight buckets a caller can act on differently,
+#: not a catalogue of every way a call can fail.
+VALIDATION = "validation"                    # the request was malformed or out of range
+RUNTIME_UNAVAILABLE = "runtime_unavailable"  # a language/compiler is not installed here
+TIMEOUT = "timeout"                          # a wall clock or CPU deadline expired
+RESOURCE_EXHAUSTED = "resource_exhausted"    # memory, output or process ceiling hit
+PERMISSION_DENIED = "permission_denied"      # refused by a jail, ACL or elevation gate
+DEPENDENCY_MISSING = "dependency_missing"    # an optional extra is not installed
+WORKER_FAILURE = "worker_failure"            # a session worker died or desynced
+INTERNAL = "internal"                        # a defect here, not in the request
+
+#: Every code, for the gate and for callers that want to validate.
+ALL_CODES = frozenset({
+    VALIDATION, RUNTIME_UNAVAILABLE, TIMEOUT, RESOURCE_EXHAUSTED,
+    PERMISSION_DENIED, DEPENDENCY_MISSING, WORKER_FAILURE, INTERNAL,
+})
+
+#: What a caller can do about each, in one line. Returned by the MCP surface so
+#: the remedy travels with the code instead of living only in documentation
+#: somebody has to find.
+REMEDIES = {
+    VALIDATION: "fix the arguments and retry; the message names the field",
+    RUNTIME_UNAVAILABLE: "install the runtime, or call list_languages to see what this host has",
+    TIMEOUT: "raise `timeout`, or reduce the work; a partial result is not returned",
+    RESOURCE_EXHAUSTED: "raise the relevant ceiling (max_memory_mb, max_output_kb) or reduce the work",
+    PERMISSION_DENIED: "the path or operation is outside what this server permits; it will not succeed on retry",
+    DEPENDENCY_MISSING: "install the named extra; the message gives the exact pip command",
+    WORKER_FAILURE: "the session is unusable — call session_stop and start a new one",
+    INTERNAL: "a defect in codecalc; the message is worth reporting verbatim",
+}
+
+
+def classify(exc: BaseException) -> str:
+    """Map an exception to a code. Pure, and exception-type first.
+
+    Ordering matters. `MissingExtra` subclasses `ImportError` on purpose (see
+    optional.py), so it has to be tested BEFORE the ImportError branch or every
+    absent extra reports as an internal defect — which is the opposite of
+    actionable, since the caller can fix a missing extra and cannot fix a bug.
+
+    Type before message, always. Matching on message text is how a classifier
+    becomes wrong silently when someone improves a sentence, so `_from_message`
+    below is the last resort and is only consulted for exception types that
+    carry no useful class.
+    """
+    from .optional import MissingExtra
+
+    if isinstance(exc, MissingExtra):
+        return DEPENDENCY_MISSING
+    if isinstance(exc, TimeoutError):
+        return TIMEOUT
+    if isinstance(exc, MemoryError):
+        return RESOURCE_EXHAUSTED
+    if isinstance(exc, RecursionError):
+        # Depth is a resource here: the guard exists so a deeply nested
+        # expression cannot take the process down, and the caller's remedy is
+        # to simplify the input, same as any other ceiling.
+        return RESOURCE_EXHAUSTED
+    if isinstance(exc, PermissionError):
+        return PERMISSION_DENIED
+    if isinstance(exc, FileNotFoundError):
+        # A missing executable is the common case on this path — a language
+        # whose runtime is not installed. A missing FILE is validation, but the
+        # executor reports that through its own result shape rather than here.
+        return RUNTIME_UNAVAILABLE
+    if isinstance(exc, ImportError):
+        return DEPENDENCY_MISSING
+    if isinstance(exc, (ValueError, TypeError, KeyError, IndexError, ArithmeticError)):
+        return VALIDATION
+    if isinstance(exc, OSError):
+        return INTERNAL
+    return _from_message(str(exc))
+
+
+#: Message fragments consulted ONLY for exceptions with no informative type.
+#: Ordered, first match wins, lowercase comparison.
+#: The first version of this list had ten entries and classified four of the
+#: seven most reachable failures as INTERNAL — including a bad expression and
+#: an unknown session id. INTERNAL's remedy is "a defect in codecalc; the
+#: message is worth reporting verbatim", so that told a caller who mistyped an
+#: expression to go and file a bug. A wrong code is worse than a missing one,
+#: because it is actionable in the wrong direction.
+#:
+#: INTERNAL is the fallback and should be RARE. If a common failure lands there,
+#: the list is wrong, not the failure.
+_MESSAGE_HINTS = (
+    # resource ceilings — before the parse hints, because "expression too long"
+    # is a ceiling and contains no parse vocabulary but sits near it
+    ("timed out", TIMEOUT),
+    ("timeout", TIMEOUT),
+    ("memory ceiling", RESOURCE_EXHAUSTED),
+    ("memory", RESOURCE_EXHAUSTED),
+    ("too long", RESOURCE_EXHAUSTED),
+    ("too deeply nested", RESOURCE_EXHAUSTED),
+    ("too many", RESOURCE_EXHAUSTED),
+    ("resource limit", RESOURCE_EXHAUSTED),
+    ("exceeded", RESOURCE_EXHAUSTED),
+    # dependency
+    ("not installed", DEPENDENCY_MISSING),
+    ("ships in the", DEPENDENCY_MISSING),
+    # permission / jail
+    ("permission", PERMISSION_DENIED),
+    ("escapes", PERMISSION_DENIED),
+    ("outside", PERMISSION_DENIED),
+    ("refus", PERMISSION_DENIED),
+    # worker / session lifecycle
+    ("worker", WORKER_FAILURE),
+    ("session is", WORKER_FAILURE),
+    ("desync", WORKER_FAILURE),
+    # runtime availability
+    ("runtime unavailable", RUNTIME_UNAVAILABLE),
+    ("not found in path", RUNTIME_UNAVAILABLE),
+    # validation — the largest bucket, and the one INTERNAL was stealing
+    ("unknown language", VALIDATION),
+    ("unknown session", VALIDATION),
+    ("no such file", VALIDATION),
+    ("no such directory", VALIDATION),
+    ("parse error", VALIDATION),
+    ("could not parse", VALIDATION),
+    ("could not be tokenised", VALIDATION),
+    ("sympify", VALIDATION),
+    ("unexpected character", VALIDATION),
+    ("invalid", VALIDATION),
+    ("must be", VALIDATION),
+    ("empty", VALIDATION),
+)
+
+
+def _from_message(message: str) -> str:
+    low = message.lower()
+    for needle, code in _MESSAGE_HINTS:
+        if needle in low:
+            return code
+    return INTERNAL
+
+
+def error_result(code: str, message: str, **extra) -> dict:
+    """The failing half of the result contract.
+
+    `code` is validated rather than trusted: a typo'd code is worse than no
+    code, because a caller branching on it silently takes the wrong branch and
+    nothing raises. An unknown code becomes INTERNAL and says so in the
+    message, which is a loud failure at the point of the mistake.
+    """
+    if code not in ALL_CODES:
+        message = f"[unclassified code {code!r}] {message}"
+        code = INTERNAL
+    return {"ok": False, "code": code, "error": message,
+            "remedy": REMEDIES[code], **extra}
+
+
+def ensure_code(result: dict) -> dict:
+    """Give a failing result a code if it has none. Mutates and returns it.
+
+    The transitional half. Applied where every tool result passes on its way
+    out, so the model-facing surface is covered without editing 121 return
+    sites — but the code comes from the MESSAGE, which is a weaker claim than
+    one chosen at the raise site, so it is labelled `code_inferred: true`.
+
+    A caller can therefore tell the two apart, and so can the gate: the goal is
+    for this function to have less to do over time, not to be the answer.
+
+    Only touches results that are failing and codeless. A successful result
+    gets nothing — a `code` on an `ok: True` payload would read as a warning
+    and there is no such thing here.
+    """
+    if not isinstance(result, dict) or result.get("ok") is not False:
+        return result
+    if result.get("code"):
+        return result
+    code = _from_message(str(result.get("error") or ""))
+    result["code"] = code
+    result["remedy"] = REMEDIES[code]
+    result["code_inferred"] = True
+    return result