rung-cli 0.1.2__py3-none-any.whl

rung/drafting/providers.py

@@ -0,0 +1,294 @@
+"""Model providers: the model that drafts specs, proofs and drive scripts.
+
+Every call is schema-constrained: the model must return one JSON object matching a JSON Schema,
+which the provider's own structured-output feature enforces. Claude Code gets the schema with
+`--json-schema`, Codex with `--output-schema`, OpenAI-compatible servers with `response_format`.
+Nothing is scraped out of free text.
+
+Rung never asks for or stores credentials. The CLI providers reuse the login of a tool the
+developer already has (`claude auth login`, `codex login`); the HTTP provider reads its key from
+an environment variable. The model only *proposes*: a checker (TLC, the Lean kernel, a
+differential test, the app itself) accepts or rejects what it drafts.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import tomllib
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from rung.core.config import LLMConfig
+from rung.core.errors import RungError, ToolMissing
+
+PROVIDERS = {
+    "claude-cli": "Claude Code CLI (uses your `claude auth login` session)",
+    "codex-cli": "Codex CLI (uses your `codex login` session)",
+    "openai-compatible": "Any OpenAI-compatible /v1/chat/completions endpoint (Ollama, vLLM, Kompact, ...)",
+    "none": "No model; Rung runs checks but drafts nothing",
+}
+
+
+class ProviderError(RungError):
+    """The model could not be reached, or did not return the requested JSON."""
+
+
+@dataclass
+class LoginState:
+    ok: bool
+    detail: str
+
+
+def check_shape(value: Any, schema: dict[str, Any], path: str = "$") -> None:
+    """Verify the parts of a JSON Schema Rung uses (object, array, string, required).
+
+    The providers enforce the schema already; this guards against a provider that
+    silently ignores it, so a malformed reply fails here instead of deep in a draft.
+    """
+    kind = schema.get("type")
+    if kind == "object":
+        if not isinstance(value, dict):
+            raise ProviderError(f"{path}: expected an object")
+        for key in schema.get("required", []):
+            if key not in value:
+                raise ProviderError(f"{path}: missing `{key}`")
+        for key, sub in schema.get("properties", {}).items():
+            if key in value:
+                check_shape(value[key], sub, f"{path}.{key}")
+    elif kind == "array":
+        if not isinstance(value, list):
+            raise ProviderError(f"{path}: expected an array")
+        for i, item in enumerate(value):
+            check_shape(item, schema.get("items", {}), f"{path}[{i}]")
+    elif kind == "string" and not isinstance(value, str):
+        raise ProviderError(f"{path}: expected a string")
+
+
+class Provider:
+    name = "none"
+
+    def __init__(self, config: LLMConfig) -> None:
+        self.config = config
+        self.models_used: set[str] = set()  # the models that actually answered, as each tool reports them
+
+    def models(self) -> str:
+        """The models that answered so far, else the configured one, else the CLI's own default."""
+        return ", ".join(sorted(self.models_used)) or self.config.model or "the CLI's default model"
+
+    def available(self) -> bool:
+        return False
+
+    def login_state(self) -> LoginState:
+        return LoginState(False, "no provider configured")
+
+    def login(self) -> int:
+        """Run the provider's own interactive login; returns its exit code."""
+        return 1
+
+    def complete_json(
+        self, prompt: str, *, schema: dict[str, Any], system: str = "", cwd: Path | None = None, timeout: int = 1200
+    ) -> dict[str, Any]:
+        """Ask the model for one JSON object matching `schema`."""
+        raise ToolMissing("no model provider is configured; run `rung init` or set [llm] in rung.toml")
+
+
+class ClaudeCLI(Provider):
+    name = "claude-cli"
+
+    def available(self) -> bool:
+        return shutil.which("claude") is not None
+
+    def login_state(self) -> LoginState:
+        if not self.available():
+            return LoginState(False, "`claude` is not installed")
+        proc = subprocess.run(["claude", "auth", "status"], capture_output=True, text=True, timeout=60)
+        try:
+            info = json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            lines = (proc.stdout or proc.stderr).strip().splitlines()
+            return LoginState(proc.returncode == 0, lines[0] if lines else "")
+        # Report only the login state, never account identifiers such as the email.
+        if info.get("loggedIn"):
+            return LoginState(True, f"logged in ({info.get('authMethod', 'unknown method')})")
+        return LoginState(False, "not logged in")
+
+    def login(self) -> int:
+        return subprocess.call(["claude", "auth", "login"])
+
+    def complete_json(
+        self, prompt: str, *, schema: dict[str, Any], system: str = "", cwd: Path | None = None, timeout: int = 1200
+    ) -> dict[str, Any]:
+        if not self.available():
+            raise ToolMissing("`claude` is not installed")
+        # Drafting only: with no tools the model reads nothing and runs nothing on its own.
+        cmd = ["claude", "-p", "--tools", "", "--output-format", "json", "--json-schema", json.dumps(schema)]
+        if self.config.model:
+            cmd += ["--model", self.config.model]
+        if system:
+            cmd += ["--append-system-prompt", system]
+        proc = subprocess.run(cmd, input=prompt, cwd=cwd, capture_output=True, text=True, timeout=timeout)
+        try:
+            envelope = json.loads(proc.stdout)
+        except json.JSONDecodeError as exc:
+            raise ProviderError(
+                f"claude exited {proc.returncode}: {(proc.stderr or proc.stdout).strip()[:500]}"
+            ) from exc
+        if envelope.get("is_error"):
+            raise ProviderError(f"claude reported an error: {str(envelope.get('result'))[:500]}")
+        self.models_used.update(envelope.get("modelUsage") or {})
+        result = envelope.get("structured_output")
+        if result is None:
+            raise ProviderError("claude returned no structured output")
+        check_shape(result, schema)
+        return result
+
+
+class CodexCLI(Provider):
+    name = "codex-cli"
+
+    def available(self) -> bool:
+        return shutil.which("codex") is not None
+
+    def login_state(self) -> LoginState:
+        if not self.available():
+            return LoginState(False, "`codex` is not installed")
+        proc = subprocess.run(["codex", "login", "status"], capture_output=True, text=True, timeout=60)
+        detail = (proc.stdout or proc.stderr).strip().splitlines()
+        return LoginState(proc.returncode == 0, detail[0] if detail else "")
+
+    def login(self) -> int:
+        return subprocess.call(["codex", "login"])
+
+    def complete_json(
+        self, prompt: str, *, schema: dict[str, Any], system: str = "", cwd: Path | None = None, timeout: int = 1200
+    ) -> dict[str, Any]:
+        if not self.available():
+            raise ToolMissing("`codex` is not installed")
+        full = f"{system}\n\n{prompt}" if system else prompt
+        with tempfile.TemporaryDirectory(prefix="rung-codex-") as tmp:
+            out, schema_file = Path(tmp) / "last.json", Path(tmp) / "schema.json"
+            schema_file.write_text(json.dumps(schema))
+            # Read-only sandbox: Codex may read the repository but cannot change or run anything in it.
+            cmd = ["codex", "exec", "--skip-git-repo-check", "--ephemeral", "-s", "read-only",
+                   "--output-schema", str(schema_file), "-o", str(out)]  # fmt: skip
+            if self.config.model:
+                cmd += ["-m", self.config.model]
+            cmd.append("-")
+            proc = subprocess.run(cmd, input=full, cwd=cwd or tmp, capture_output=True, text=True, timeout=timeout)
+            if proc.returncode != 0:
+                raise ProviderError(f"codex exited {proc.returncode}: {proc.stderr.strip()[-500:]}")
+            try:
+                result = json.loads(out.read_text())
+            except (OSError, json.JSONDecodeError) as exc:
+                raise ProviderError("codex did not return the requested JSON") from exc
+        # Codex does not report which model answered; record what was requested, and say so.
+        if model := self.config.model or _codex_default_model():
+            self.models_used.add(f"{model}, as configured")
+        check_shape(result, schema)
+        return result
+
+
+def _codex_default_model() -> str:
+    """The model `codex exec` uses without `-m`, from its config (with the reasoning effort, if set)."""
+    path = Path(os.environ.get("CODEX_HOME") or Path.home() / ".codex") / "config.toml"
+    try:
+        config = tomllib.loads(path.read_text())
+    except (OSError, tomllib.TOMLDecodeError):
+        return ""
+    model = str(config.get("model") or "")
+    effort = config.get("model_reasoning_effort")
+    return f"{model} ({effort} effort)" if model and effort else model
+
+
+class OpenAICompatible(Provider):
+    name = "openai-compatible"
+
+    def available(self) -> bool:
+        return bool(self.config.base_url)
+
+    def login_state(self) -> LoginState:
+        if not self.config.base_url:
+            return LoginState(False, "set [llm] base_url in rung.toml")
+        has_key = bool(os.environ.get(self.config.api_key_env))
+        return LoginState(True, f"{self.config.base_url} (key from ${self.config.api_key_env}: "
+                                f"{'set' if has_key else 'not set'})")  # fmt: skip
+
+    def login(self) -> int:
+        print(f"Export your key as ${self.config.api_key_env}; Rung never stores it.")
+        return 0
+
+    def _post(self, body: dict[str, Any], timeout: int) -> dict[str, Any]:
+        headers = {"Content-Type": "application/json"}
+        if key := os.environ.get(self.config.api_key_env):
+            headers["Authorization"] = f"Bearer {key}"
+        url = self.config.base_url.rstrip("/") + "/chat/completions"
+        request = urllib.request.Request(url, data=json.dumps(body).encode(), headers=headers, method="POST")
+        with urllib.request.urlopen(request, timeout=timeout) as resp:
+            return json.loads(resp.read())
+
+    def complete_json(
+        self, prompt: str, *, schema: dict[str, Any], system: str = "", cwd: Path | None = None, timeout: int = 1200
+    ) -> dict[str, Any]:
+        if not self.config.base_url:
+            raise ToolMissing("set [llm] base_url for the openai-compatible provider")
+        messages = ([{"role": "system", "content": system}] if system else []) + [{"role": "user", "content": prompt}]
+        body: dict[str, Any] = {
+            "model": self.config.model or "default",
+            "messages": messages,
+            "response_format": {
+                "type": "json_schema",
+                "json_schema": {"name": "rung", "schema": schema, "strict": True},
+            },
+        }
+        try:
+            payload = self._post(body, timeout)
+        except urllib.error.HTTPError as exc:
+            if exc.code not in (400, 422):
+                raise ProviderError(f"{self.config.base_url} returned HTTP {exc.code}") from exc
+            # The server does not support json_schema: ask in the prompt and extract the object.
+            body.pop("response_format")
+            messages[-1]["content"] += "\n\nReply with only one JSON object matching this schema:\n" + json.dumps(
+                schema
+            )
+            payload = self._post(body, timeout)
+        except urllib.error.URLError as exc:
+            raise ProviderError(f"cannot reach {self.config.base_url}: {exc.reason}") from exc
+        if payload.get("model"):
+            self.models_used.add(str(payload["model"]))
+        content = payload["choices"][0]["message"]["content"]
+        match = re.search(r"\{[\s\S]*\}", content)
+        try:
+            result = json.loads(match.group(0) if match else content)
+        except json.JSONDecodeError as exc:
+            raise ProviderError("the model did not return valid JSON") from exc
+        check_shape(result, schema)
+        return result
+
+
+_REGISTRY: dict[str, type[Provider]] = {
+    "claude-cli": ClaudeCLI,
+    "codex-cli": CodexCLI,
+    "openai-compatible": OpenAICompatible,
+    "none": Provider,
+}
+
+
+def get(config: LLMConfig) -> Provider:
+    cls = _REGISTRY.get(config.provider)
+    if cls is None:
+        raise ValueError(f"unknown provider {config.provider!r}; choose one of {', '.join(PROVIDERS)}")
+    return cls(config)
+
+
+def detect() -> list[str]:
+    """Providers usable on this machine right now, best first."""
+    found = [name for name, cls in (("claude-cli", ClaudeCLI), ("codex-cli", CodexCLI)) if cls(LLMConfig()).available()]
+    return [*found, "openai-compatible", "none"]

rung/drafting/runtime.py

@@ -0,0 +1,186 @@
+"""`rung draft runtime`: generate a repo-specific verification script, and make it prove itself.
+
+The idea comes from Lauren Tan's pstack (`/create-verification-skill`): every
+project needs a scripted way to drive the real app the way a user does and
+capture evidence, plus a feature map saying how each feature is reached and what
+observable state proves it works. pstack states the key rule in prose: a
+generated skill that was never executed is a draft, not a deliverable.
+
+Rung enforces that rule mechanically. The model writes the drive script and the
+feature map; Rung runs the script as an `evidence` check and feeds failures back
+for repair. Nothing is registered until a run has passed and left evidence. The
+feature map's sources are covered by the check, so when the app changes the
+verdict goes stale and the script must be re-proven.
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+import shutil
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+from rung import guides
+from rung.analysis.survey import Inspection
+from rung.checks import deps
+from rung.checks.base import Context
+from rung.checks.command import EvidenceChecker
+from rung.core import git
+from rung.core.config import Check
+from rung.core.errors import ToolMissing
+from rung.drafting.common import FILES, STRINGS, files_of, safe_write, schema
+from rung.drafting.providers import Provider
+
+VERIFY_DIR = Path(".rung") / "verify"
+CONTEXT_FILES = (
+    "README.md", "README.rst", "package.json", "pyproject.toml", "Makefile", "justfile", "Procfile",
+    "docker-compose.yml", "compose.yaml", "manage.py", "main.py", "app.py", "go.mod", "Cargo.toml",
+)  # fmt: skip
+MAX_CONTEXT_BYTES = 60_000
+SCHEMA = schema(files=FILES, sources=STRINGS, requirements=STRINGS, notes={"type": "string"})
+
+FORMAT = """
+
+Return `files` with `drive.py` and `FEATURES.md`, `sources` with globs of the source files the driven
+feature depends on, `requirements` with the Python packages the script imports beyond the standard
+library (e.g. `playwright`; empty if none), and `notes` with anything the developer should know."""
+
+
+MIN_PACKAGE_AGE_DAYS = 30
+
+
+def vet_requirements(requirements: list[str]) -> list[str]:
+    """Problems with packages a model wants to install: missing from PyPI, or too new to trust.
+
+    The same rule the `deps` check applies to a project's own dependencies: a model can invent a
+    package name, and an attacker can register it.
+    """
+    problems = []
+    for spec in requirements:
+        name = deps.requirement_name(spec)
+        if not name:
+            problems.append(f"{spec!r} is not a package requirement")
+            continue
+        published = deps.first_published(deps.Package("pypi", name))
+        if published is None:
+            problems.append(f"{name} does not exist on PyPI")
+        elif (age := (datetime.now(UTC) - published).days) < MIN_PACKAGE_AGE_DAYS:
+            problems.append(f"{name} was first published {age} day(s) ago")
+    return problems
+
+
+def run_command(requirements: list[str]) -> str:
+    """How Rung runs the drive script: plain Python, or an isolated uv environment with its packages."""
+    script = (VERIFY_DIR / "drive.py").as_posix()
+    if not requirements:
+        return f"python3 {script}"
+    if not shutil.which("uv"):
+        raise ToolMissing(f"the drive script needs {', '.join(requirements)}; install uv (https://docs.astral.sh/uv/)")
+    withs = " ".join(f"--with {shlex.quote(r)}" for r in requirements)
+    return f"uv run --no-project {withs} python {script}"
+
+
+@dataclass
+class RuntimeDraft:
+    ok: bool
+    message: str
+    files: list[Path] = field(default_factory=list)
+    rounds: int = 0
+    covers: list[str] = field(default_factory=list)
+    evidence: list[str] = field(default_factory=list)
+    notes: str = ""
+    run: str = ""
+
+
+# Files that usually show how an app starts and what a user sees first, per project directory.
+ENTRY_GLOBS = (
+    "README.md", "package.json", "pyproject.toml", "app/page.*", "src/app/page.*", "app/layout.*",
+    "src/app/layout.*", "pages/index.*", "src/pages/index.*", "src/main.*", "src/index.*", "main.py", "app.py",
+    "manage.py", "cmd/*/main.go", "src/main.rs",
+)  # fmt: skip
+MAX_LISTED_FILES = 400
+SURVEY_KEYS = ("languages", "surfaces", "test_commands", "ci", "projects")
+
+
+def _context_files(root: Path, info: Inspection, focus: list[str], files: list[str]) -> list[str]:
+    """Focus files first, then each project's docs, manifests and entry points, then root build files."""
+    chosen: list[str] = list(focus)
+    for project in info.projects:
+        prefix = "" if project.path == "." else f"{project.path}/"
+        for pattern in ENTRY_GLOBS:
+            chosen += [f for f in files if git.glob_match(prefix + pattern, f)]
+    chosen += list(CONTEXT_FILES)
+    return list(dict.fromkeys(chosen))
+
+
+def gather_context(root: Path, info: Inspection, focus: list[str]) -> str:
+    """What the model sees: the survey, a file list, and the project's own docs and entry points.
+
+    Files near the focus come first in the listing, so a sub-project (`frontend/`) is never hidden
+    behind hundreds of unrelated files that sort earlier.
+    """
+    files = git.list_files(root)
+    focus_dirs = {str(Path(f).parent) for f in focus} - {"."}
+    near = [f for f in files if any(f.startswith(d + "/") for d in focus_dirs)]
+    listing = list(dict.fromkeys(near + files))[:MAX_LISTED_FILES]
+    parts = [
+        "Survey:",
+        json.dumps({k: info.to_dict()[k] for k in SURVEY_KEYS}, indent=1),
+        "",
+        f"Files ({len(listing)} of {len(files)}, those near the focus first):",
+        "\n".join(listing),
+    ]
+    budget = MAX_CONTEXT_BYTES
+    for rel in _context_files(root, info, focus, files):
+        path = root / rel
+        if not path.is_file() or budget <= 0:
+            continue
+        text = path.read_text(errors="ignore")[: min(budget, 12_000)]
+        budget -= len(text)
+        parts += ["", f"--- {rel} ---", text]
+    return "\n".join(parts)
+
+
+def draft_runtime(
+    provider: Provider, root: Path, info: Inspection, *, focus: list[str], check_id: str = "runtime",
+    intent: str = "", max_rounds: int = 4, require: tuple[str, ...] = (),
+) -> RuntimeDraft:  # fmt: skip
+    out_dir = root / VERIFY_DIR
+    prompt = (
+        "Write the verification script and feature map for this project.\n"
+        + (f"Drive this feature: {intent}\n" if intent else "")
+        + (f"The evidence must include: {', '.join(require)} (e.g. `.webm` means a video).\n" if require else "")
+        + "\n"
+        + gather_context(root, info, focus)
+    )
+    files: list[Path] = []
+    for round_no in range(1, max_rounds + 1):
+        reply = provider.complete_json(prompt, schema=SCHEMA, system=guides.load("runtime") + FORMAT, cwd=root)
+        produced = files_of(reply)
+        if "drive.py" not in produced or "FEATURES.md" not in produced:
+            prompt += "\n\nYour reply must contain both `drive.py` and `FEATURES.md` in `files`."
+            continue
+        files = safe_write(out_dir, produced)
+        covers = [g.strip() for g in reply["sources"] if g.strip()]
+        requirements = [p.strip() for p in reply["requirements"] if p.strip()]
+        if problems := vet_requirements(requirements):
+            prompt += (
+                "\n\nRung will not install these requirements: "
+                + "; ".join(problems)
+                + ". Use only established packages (or none). Return the same fields."
+            )
+            continue
+        run = run_command(requirements)
+        check = Check(check_id, "evidence", covers, {"run": run, "timeout": 900, "require": list(require)})
+        outcome = EvidenceChecker().run(Context(root=root), check)
+        if outcome.verdict == "pass":
+            return RuntimeDraft(True, outcome.summary, files, round_no, covers, list(outcome.evidence),
+                                reply["notes"].strip(), run)  # fmt: skip
+        prompt += (
+            f"\n\nRung ran your script and it did not prove the feature ({outcome.summary}):\n"
+            + "\n".join(outcome.lines[-30:])
+            + "\nFix the script. Do not weaken what it checks. Return the same fields."
+        )
+    return RuntimeDraft(False, f"no passing verification script after {max_rounds} rounds", files, max_rounds)

rung/drafting/sandbox.py

@@ -0,0 +1,63 @@
+"""A disposable copy of a project, for running model-written tests and deliberate bugs.
+
+Model-written test code runs before any person has read it, and mutation testing edits source files.
+Neither should touch the developer's working tree, so both happen in a copy:
+
+- every file git would show (tracked, plus untracked files that are not ignored) is copied, so
+  ignored local files such as `.env` are not there;
+- dependency directories (`node_modules`, `.venv`) are linked rather than copied, since they are
+  large and only read;
+- environment variables that look like credentials are removed for the run.
+
+This is damage control, not a security sandbox: a test can still reach the network and any path it
+names explicitly. Read a drafted test before you trust it.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from rung.core import git
+
+DEPENDENCY_DIRS = ("node_modules", ".venv", "venv", ".lake")
+SECRET_NAME = re.compile(r"KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|PRIVATE|SESSION|COOKIE|AUTH", re.I)
+KEEP = {"PATH", "HOME", "USER", "LANG", "LC_ALL", "TERM", "TMPDIR", "SHELL", "UV_CACHE_DIR", "XDG_CACHE_HOME"}
+
+
+@contextmanager
+def copy_of(root: Path) -> Iterator[Path]:
+    """Yield a temporary copy of the project at `root`; it is deleted afterwards."""
+    tmp = Path(tempfile.mkdtemp(prefix="rung-sandbox-"))
+    copy = tmp / root.name
+    try:
+        dirs: set[Path] = {Path(".")}
+        for rel in git.list_files(root):
+            if git.is_rung_output(rel):
+                continue
+            source, target = root / rel, copy / rel
+            target.parent.mkdir(parents=True, exist_ok=True)
+            if source.is_symlink():
+                target.symlink_to(os.readlink(source))
+            else:
+                shutil.copy2(source, target)
+            dirs.update(Path(rel).parents)
+        for d in dirs:
+            for name in DEPENDENCY_DIRS:
+                if (root / d / name).is_dir() and not (copy / d / name).exists():
+                    (copy / d).mkdir(parents=True, exist_ok=True)
+                    (copy / d / name).symlink_to(root / d / name, target_is_directory=True)
+        yield copy
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def scrubbed_env(extra: dict[str, str] | None = None) -> dict[str, str]:
+    """The current environment without variables whose names look like credentials."""
+    env = {k: v for k, v in os.environ.items() if k in KEEP or not SECRET_NAME.search(k)}
+    return env | (extra or {})

rung/drafting/tla.py

@@ -0,0 +1,97 @@
+"""`rung draft tla`: a model writes a TLA+ spec that mirrors the code; TLC decides."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from rung import guides
+from rung.drafting.common import FILES, LAWS, LAWS_FORMAT, DraftResult, files_of, safe_write, schema, source_block
+from rung.drafting.providers import Provider
+from rung.engines import tla
+
+FORMAT = (
+    """
+
+Return `files` with exactly two entries: `<Module>.tla` (starting `---- MODULE <Module> ----` and ending
+`====`) and `<Module>.cfg`. Put anything you want the developer to know in `notes`."""
+    + LAWS_FORMAT
+)
+SCHEMA = schema(files=FILES, laws=LAWS, notes={"type": "string"})
+
+# Slips language models make in TLA+ that are safe to correct mechanically before SANY sees the spec.
+UNICODE_OPERATORS = {
+    "\u2227": "/\\",  # ∧
+    "\u2228": "\\/",  # ∨
+    "\u00ac": "~",  # ¬
+    "\u2208": "\\in",  # ∈
+    "\u2209": "\\notin",  # ∉
+    "\u21d2": "=>",  # ⇒
+    "\u2192": "->",  # →
+    "\u21d4": "<=>",  # ⇔
+    "\u2260": "#",  # ≠
+    "\u2264": "<=",  # ≤
+    "\u2265": ">=",  # ≥
+    "\u222a": "\\cup",  # ∪
+    "\u2229": "\\cap",  # ∩
+    "\u2286": "\\subseteq",  # ⊆
+    "\u2200": "\\A",  # ∀
+    "\u2203": "\\E",  # ∃
+    "\u225c": "==",  # ≜
+    "\u25a1": "[]",  # □
+    "\u25c7": "<>",  # ◇
+    "\u27e8": "<<",  # ⟨
+    "\u27e9": ">>",  # ⟩
+    "\u2032": "'",  # ′
+}
+
+
+def normalize(spec: str) -> str:
+    """Replace Unicode operators with ASCII and drop stray Markdown fences."""
+    for uni, ascii_op in UNICODE_OPERATORS.items():
+        spec = spec.replace(uni, ascii_op)
+    return re.sub(r"^```.*$\n?", "", spec, flags=re.M)
+
+
+def draft(
+    provider: Provider, root: Path, sources: list[Path], out_dir: Path, *, intent: str = "", max_rounds: int = 4
+) -> DraftResult:
+    system = guides.load("tla") + FORMAT
+    prompt = (
+        "Write a TLA+ model of this code.\n"
+        + (f"What it must guarantee (from the developer): {intent}\n" if intent else "")
+        + "\n"
+        + source_block(root, sources)
+    )
+    files: list[Path] = []
+    for round_no in range(1, max_rounds + 1):
+        reply = provider.complete_json(prompt, schema=SCHEMA, system=system, cwd=root)
+        produced, notes, laws = files_of(reply), reply["notes"].strip(), reply["laws"]
+        spec_name = next((n for n in produced if n.endswith(".tla")), None)
+        cfg_name = next((n for n in produced if n.endswith(".cfg")), None)
+        if not spec_name or not cfg_name:
+            prompt += "\n\nYour reply must contain one `.tla` file and one `.cfg` file."
+            continue
+        produced[spec_name] = normalize(produced[spec_name])
+        files = safe_write(out_dir, produced)
+        result = tla.run(out_dir / spec_name, out_dir / cfg_name)
+        if result.verdict == "fail":
+            return DraftResult(
+                True,
+                f"TLC found a counterexample: {result.reason}. Decide: real bug, or wrong spec?",
+                files,
+                round_no,
+                tla.render_trace(result.trace),
+                notes=notes,
+                laws=laws,
+            )
+        if result.verdict == "pass" and result.distinct_states > 1:
+            return DraftResult(True, f"model-checked {result.distinct_states} distinct states, no violation",
+                               files, round_no, notes=notes, laws=laws)  # fmt: skip
+        problem = (
+            (result.reason + "\n" + result.output[-2000:])
+            if result.verdict == "error"
+            else "TLC explored at most one state, so the invariants are vacuous. Make Init and Next reachable."
+        )
+        prompt += f"\n\nTLC rejected your previous spec:\n{problem}\nFix the spec (not the invariants)."
+    return DraftResult(False, f"no checkable spec after {max_rounds} rounds", files, max_rounds)

rung/engines/__init__.py

@@ -0,0 +1 @@
+"""Engines: thin wrappers around TLC, Lean, differential testing and SARIF; they know nothing of rung.toml."""