puremethod 0.1.0__py3-none-any.whl

app/launcher.py

@@ -0,0 +1,389 @@
+"""The `puremethod` command (08-app.md §3 CLI, §5 steps 9 and 11, KB-025).
+
+`puremethod` starts self-hosted mode in the foreground (the API and the supervisor in one
+process, §5 step 8), then opens the browser signed in with a one-time code. While it runs it
+holds an exclusive lock on `<data dir>/server.lock` and records its port in `server.json`,
+so `open`, `stop` and a second `puremethod` find it. `stop` asks it to exit by creating
+`stop.request`, which the server polls; it then shuts down as on Ctrl+C."""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import logging
+import os
+import platform
+import shutil
+import socket
+import subprocess
+import sys
+import threading
+import time
+import webbrowser
+from collections.abc import Callable, Iterator, Mapping
+from pathlib import Path
+from typing import IO
+
+from app import paths
+from app.accounts import SigninCodes, bootstrap, issue_token, tenants
+from app.db import Database
+from app.settings import DEFAULT_WEB_DIR, Settings, SettingsError, data_dir_from, key_file
+
+log = logging.getLogger("app.launcher")
+
+READY_TIMEOUT_S = 60.0
+STOP_TIMEOUT_S = 30.0
+POLL_S = 0.5
+
+
+# ---- files that describe a running server ----------------------------------------------------
+
+def _lock_path(s: Settings) -> Path:
+    return s.data_dir / "server.lock"
+
+
+def _state_path(s: Settings) -> Path:
+    return s.data_dir / "server.json"
+
+
+def _stop_path(s: Settings) -> Path:
+    return s.data_dir / "stop.request"
+
+
+def _try_lock(fh: IO[bytes]) -> bool:
+    try:
+        fh.seek(0)
+        if sys.platform == "win32":
+            import msvcrt
+            msvcrt.locking(fh.fileno(), msvcrt.LK_NBLCK, 1)
+        else:
+            import fcntl
+            fcntl.flock(fh.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except OSError:
+        return False
+    return True
+
+
+def _unlock(fh: IO[bytes]) -> None:
+    # Explicitly: Windows releases a lock left on a closed handle only after a delay.
+    with contextlib.suppress(OSError):
+        fh.seek(0)
+        if sys.platform == "win32":
+            import msvcrt
+            msvcrt.locking(fh.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+            fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
+
+
+@contextlib.contextmanager
+def server_lock(s: Settings, wait_s: float = 0.0) -> Iterator[bool]:
+    """Yields True while this process holds the lock; False when another server holds it.
+    `wait_s` retries briefly, so a start does not lose to another command's quick probe."""
+    s.data_dir.mkdir(parents=True, exist_ok=True)
+    with open(_lock_path(s), "a+b") as fh:
+        end = time.monotonic() + wait_s
+        mine = _try_lock(fh)
+        while not mine and time.monotonic() < end:
+            time.sleep(0.1)
+            mine = _try_lock(fh)
+        try:
+            yield mine
+        finally:
+            if mine:
+                _unlock(fh)
+
+
+def running_port(s: Settings) -> int | None:
+    """The port of the server running on this data directory, or None."""
+    with server_lock(s) as mine:
+        if mine:
+            return None
+    try:
+        return int(json.loads(_state_path(s).read_text(encoding="utf-8"))["port"])
+    except (OSError, ValueError, KeyError):
+        return None
+
+
+def _port_answers(host: str, port: int) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=1):
+            return True
+    except OSError:
+        return False
+
+
+# ---- sign-in links -------------------------------------------------------------------------
+
+def signin_url(s: Settings, port: int) -> str:
+    """A link with a fresh one-time code in the URL fragment, which browsers never send in a
+    request line, so it is never in a server log (08 §5 step 9)."""
+    db = Database(s.app_db)
+    found = tenants(db)
+    if len(found) != 1:
+        raise SettingsError("self-hosted mode has exactly one user; start it with `puremethod`")
+    host = "127.0.0.1" if s.host in ("0.0.0.0", "::") else s.host  # noqa: S104
+    return f"http://{host}:{port}/signin/#code={SigninCodes(db).issue(found[0])}"
+
+
+def open_browser(url: str, opener: Callable[[str], bool] | None = None) -> None:
+    """Hands the link to the browser. It is never printed: output may go to a log file, and
+    the code must never be logged (INV-9). Without a browser, sign in with an API token."""
+    base = url.split("#", 1)[0]
+    if (opener or webbrowser.open)(url):
+        print(f"puremethod is open in your browser ({base})", flush=True)
+    else:
+        print(f"no browser could be opened. Sign in at {base} with an API token from "
+              "`puremethod token rotate`", flush=True)
+
+
+# ---- serving -------------------------------------------------------------------------------
+
+def serve(settings: Settings, *, on_ready: Callable[[int], None] | None = None,
+          stop_file: Path | None = None) -> int:
+    """Self-hosted mode in this process until Ctrl+C or a stop request. The API token from
+    the first start is not printed (KB-025)."""
+    import uvicorn
+
+    from app import bundled
+    from app.api import create_app
+    from app.server import build_ctx
+    from app.supervisor import Supervisor
+
+    if settings.mode != "self-hosted":
+        print("hosted mode is not available in v0.1", file=sys.stderr)
+        return 1
+    ctx = build_ctx(settings)
+    bootstrap(ctx.db)
+    if settings.web_dir is None or not (settings.web_dir / "index.html").is_file():
+        print("web UI not built: serving the API only (see implementation/web)", flush=True)
+    bundled.start_all(ctx.db)  # each local literature service starts with the server
+    app = create_app(ctx, settings.web_dir, local_status=bundled.status_for(settings))
+    server = uvicorn.Server(uvicorn.Config(app,
+                                           host=settings.host, port=settings.port,
+                                           log_level="info"))
+    done = threading.Event()
+
+    def watch() -> None:
+        announced = False
+        while not done.wait(POLL_S):
+            if not announced and server.started:
+                announced = True
+                if on_ready is not None:
+                    threading.Thread(target=_safe, args=(on_ready, settings.port),
+                                     daemon=True).start()
+            if stop_file is not None and stop_file.exists():
+                with contextlib.suppress(OSError):
+                    stop_file.unlink()
+                server.should_exit = True
+
+    supervisor = Supervisor(ctx.db, lambda lid: ctx.status.status(lid).status)
+    supervisor.start()
+    watcher = threading.Thread(target=watch, name="launcher", daemon=True)
+    watcher.start()
+    try:
+        server.run()
+    finally:
+        done.set()
+        supervisor.stop()
+        bundled.stop_all(ctx.db)
+    return 0
+
+
+def _safe(fn: Callable[[int], None], port: int) -> None:
+    try:
+        fn(port)
+    except Exception as exc:  # the server keeps running; `puremethod open` retries
+        print(f"could not open a sign-in link: {exc}", file=sys.stderr, flush=True)
+
+
+# ---- commands ------------------------------------------------------------------------------
+
+def ensure_key(env: Mapping[str, str]) -> bool:
+    """The launcher, not `serve`, creates the master key file on first start (08 §5 step 3).
+    Returns True when it created one."""
+    if env.get("PM_MASTER_KEY"):
+        return False
+    path = key_file(env)
+    if path.is_file():
+        return False
+    if path.is_relative_to(data_dir_from(env)):
+        raise SettingsError("the master key file must be outside the data directory")
+    paths.create_key_file(path)
+    return True
+
+
+def cmd_start(env: Mapping[str, str]) -> int:
+    created = ensure_key(env)
+    settings = Settings.from_env(env)
+    port = running_port(settings)
+    if port is not None:
+        print("puremethod is already running", flush=True)
+        open_browser(signin_url(settings, port))
+        return 0
+    if _port_answers("127.0.0.1", settings.port):
+        print(f"port {settings.port} is in use by another program; set PM_PORT to a free port",
+              file=sys.stderr)
+        return 1
+    if created:
+        print(f"created the master key file {key_file(env)}\n"
+              "  back it up: without it, stored keys cannot be read (it is not in the data "
+              "directory)", flush=True)
+    with server_lock(settings, wait_s=3.0) as mine:
+        if not mine:
+            print("puremethod is starting in another window", file=sys.stderr)
+            return 1
+        with contextlib.suppress(OSError):
+            _stop_path(settings).unlink()
+        _state_path(settings).write_text(json.dumps({"pid": os.getpid(),
+                                                     "port": settings.port}), encoding="utf-8")
+        try:
+            print("puremethod is starting; press Ctrl+C to stop", flush=True)
+            return serve(settings, stop_file=_stop_path(settings),
+                         on_ready=lambda port: open_browser(signin_url(settings, port)))
+        finally:
+            with contextlib.suppress(OSError):
+                _state_path(settings).unlink()
+
+
+def cmd_open(env: Mapping[str, str]) -> int:
+    settings = Settings.from_env(env)
+    port = running_port(settings)
+    if port is None:
+        print("puremethod is not running; start it with `puremethod`", file=sys.stderr)
+        return 1
+    open_browser(signin_url(settings, port))
+    return 0
+
+
+def cmd_stop(env: Mapping[str, str], timeout: float = STOP_TIMEOUT_S) -> int:
+    settings = Settings.from_env(env)
+    if running_port(settings) is None:
+        print("puremethod is not running", flush=True)
+        return 0
+    _stop_path(settings).touch()
+    end = time.monotonic() + timeout
+    while time.monotonic() < end:
+        if running_port(settings) is None:
+            print("puremethod stopped", flush=True)
+            return 0
+        time.sleep(POLL_S)
+    print("puremethod did not stop in time; press Ctrl+C in its window", file=sys.stderr)
+    return 1
+
+
+def cmd_token_rotate(env: Mapping[str, str]) -> int:
+    settings = Settings.from_env(env)
+    db = Database(settings.app_db)
+    found = tenants(db)
+    if len(found) != 1:
+        print("token rotate needs exactly one user (self-hosted); start `puremethod` first",
+              file=sys.stderr)
+        return 1
+    print(f"new API token (shown once; all sessions ended): {issue_token(db, found[0])}",
+          flush=True)
+    return 0
+
+
+def doctor(env: Mapping[str, str]) -> list[tuple[str, bool, str]]:
+    """Checks for `puremethod doctor`: (what, ok, detail). Never reads key material."""
+    out: list[tuple[str, bool, str]] = []
+    out.append(("Python", sys.version_info >= (3, 11),
+                f"{platform.python_version()} (3.11 or newer needed)"))
+    docker = shutil.which("docker")
+    if docker is None:
+        out.append(("Docker", False, "not found; needed for local-docker runs, the LaTeX build "
+                                     "and the bundled PureScholar"))
+    else:
+        try:
+            # Fixed arguments, no shell.
+            proc = subprocess.run([docker, "version", "--format",  # noqa: S603
+                                   "{{.Server.Version}}"], capture_output=True, text=True,
+                                  timeout=20, check=False)
+            ok = proc.returncode == 0 and bool(proc.stdout.strip())
+            out.append(("Docker", ok, f"engine {proc.stdout.strip()}" if ok
+                        else "installed but the engine is not running"))
+        except (OSError, subprocess.TimeoutExpired):
+            out.append(("Docker", False, "installed but not answering"))
+    path = key_file(env)
+    if env.get("PM_MASTER_KEY"):
+        out.append(("Master key", True, "from PM_MASTER_KEY"))
+    elif not path.is_file():
+        out.append(("Master key", False, f"{path} (created on first `puremethod`)"))
+    else:
+        private = paths.is_restricted(path)
+        out.append(("Master key", private, str(path) if private
+                    else f"{path} is readable by other users; restrict it to yours"))
+    # Built without the key, so doctor works before the first start.
+    data = data_dir_from(env)
+    probe = Settings(mode="self-hosted", data_dir=data, master_key=b"",
+                     port=int(env.get("PM_PORT", "8400")))
+    out.append(("Data directory", _writable(data), str(data)))
+    port = running_port(probe)
+    if port is not None:
+        out.append(("Server", True, f"running on port {port}"))
+    else:
+        free = not _port_answers("127.0.0.1", probe.port)
+        out.append(("Port", free, f"{probe.port} {'free' if free else 'in use'}"))
+    web = Path(env["PM_WEB_DIR"]).resolve() if env.get("PM_WEB_DIR") else DEFAULT_WEB_DIR
+    out.append(("Web UI", (web / "index.html").is_file(), str(web)))
+    return out
+
+
+def _writable(d: Path) -> bool:
+    try:
+        d.mkdir(parents=True, exist_ok=True)
+        probe = d / ".write-test"
+        probe.write_text("", encoding="utf-8")
+        probe.unlink()
+    except OSError:
+        return False
+    return True
+
+
+def cmd_doctor(env: Mapping[str, str]) -> int:
+    checks = doctor(env)
+    for what, ok, detail in checks:
+        print(f"{'ok  ' if ok else 'FAIL'} {what}: {detail}", flush=True)
+    return 0 if all(ok for _, ok, _ in checks) else 1
+
+
+COMMANDS: dict[str, Callable[[Mapping[str, str]], int]] = {
+    "start": cmd_start, "open": cmd_open, "stop": cmd_stop, "doctor": cmd_doctor}
+
+
+def main(argv: list[str] | None = None) -> int:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(message)s")
+    parser = argparse.ArgumentParser(
+        prog="puremethod", description="puremethod: an idea in, a paper and a run bundle out.")
+    sub = parser.add_subparsers(dest="cmd")
+    sub.add_parser("start", help="start, then open the browser signed in (the default)")
+    sub.add_parser("open", help="a new sign-in link for a running server")
+    sub.add_parser("stop", help="stop the running server")
+    sub.add_parser("doctor", help="check Python, Docker, ports and directories")
+    token = sub.add_parser("token", help="API tokens for scripts")
+    token.add_argument("action", choices=["rotate"],
+                       help="print a new API token and end all sessions")
+    args = parser.parse_args(sys.argv[1:] if argv is None else argv)
+    env = os.environ
+    try:
+        if args.cmd == "token":
+            return cmd_token_rotate(env)
+        return COMMANDS[args.cmd or "start"](env)
+    except SettingsError as exc:
+        print(f"cannot start: {exc}", file=sys.stderr)
+        return 1
+    except paths.KeyFileExists:
+        print("another puremethod created the master key just now; run it again",
+              file=sys.stderr)
+        return 1
+    except (OSError, subprocess.CalledProcessError) as exc:
+        print(f"cannot create the master key file: {type(exc).__name__}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

app/leases.py

@@ -0,0 +1,40 @@
+"""Leases: one worker per run, one per preflight check (08-app.md §5 step 2, KB-021).
+
+A lease is taken only if it is absent or expired, in one write transaction, so two workers
+never hold the same key. Worker side only."""
+
+from __future__ import annotations
+
+from app.db import Database
+
+LEASE_TTL_S = 60.0
+RENEW_S = 15.0
+
+
+def acquire(db: Database, key: str, holder: str, now: float, ttl: float = LEASE_TTL_S) -> bool:
+    with db.tx(write=True) as c:
+        rows = c.execute("SELECT holder, expires_at FROM leases WHERE key = ?", (key,))
+        if rows and float(rows[0][1]) >= now and rows[0][0] != holder:
+            return False
+        c.execute("INSERT INTO leases VALUES (?, ?, ?) ON CONFLICT (key) DO UPDATE SET "
+                  "holder = excluded.holder, expires_at = excluded.expires_at",
+                  (key, holder, now + ttl))
+    return True
+
+
+def renew(db: Database, key: str, holder: str, now: float, ttl: float = LEASE_TTL_S) -> bool:
+    """False when the lease is no longer this holder's, or has expired: the worker must stop."""
+    with db.tx(write=True) as c:
+        return c.rowcount("UPDATE leases SET expires_at = ? WHERE key = ? AND holder = ? "
+                          "AND expires_at >= ?", (now + ttl, key, holder, now)) == 1
+
+
+def release(db: Database, key: str, holder: str) -> None:
+    with db.tx(write=True) as c:
+        c.execute("DELETE FROM leases WHERE key = ? AND holder = ?", (key, holder))
+
+
+def held(db: Database, key: str, now: float) -> bool:
+    with db.tx() as c:
+        rows = c.execute("SELECT expires_at FROM leases WHERE key = ?", (key,))
+    return bool(rows) and float(rows[0][0]) >= now

app/literature_sources.py

@@ -0,0 +1,131 @@
+"""The scholarly sources the bundled PureScholar searches (08-app.md §3 Onboarding step 2, §4,
+§5 step 12; KB-039).
+
+OpenAlex, Crossref and Semantic Scholar work without a key and are on by default. The
+publisher sources do nothing without their key, so they can only be on with one. Elsevier's
+one key serves both ScienceDirect and Scopus. `env` is what the literature-service task passes
+the container; `check` is one search request with a key, for its credential check. Keys go to
+the source only, never into a returned message."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Iterable
+from typing import Any
+
+import httpx
+
+SOURCES = ("openalex", "crossref", "semanticscholar", "ieee", "sciencedirect", "scopus",
+           "springer")
+DEFAULT_SOURCES = ("openalex", "crossref", "semanticscholar")
+# The key each source uses: (key group). A source not listed takes no key.
+KEY_GROUP = {"semanticscholar": "semanticscholar", "ieee": "ieee", "sciencedirect": "elsevier",
+             "scopus": "elsevier", "springer": "springer"}
+KEY_GROUPS = ("semanticscholar", "ieee", "elsevier", "springer")
+NEEDS_KEY = frozenset({"ieee", "sciencedirect", "scopus", "springer"})
+ENV_NAME = {"semanticscholar": "SEMANTIC_SCHOLAR_API_KEY", "ieee": "IEEE_API_KEY",
+            "elsevier": "ELSEVIER_API_KEY", "springer": "SPRINGER_API_KEY"}
+CREDENTIAL_TYPE = "literature-key"
+CHECK_TIMEOUT_S = 20.0
+_EMAIL = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+
+
+class SourcesRefused(ValueError):
+    """A sources setting the bundled PureScholar cannot use; the message says why."""
+
+
+def sources_of(setting: dict[str, Any]) -> list[str]:
+    """The enabled sources; a setting saved before KB-039 has the defaults."""
+    return list(setting.get("sources") or DEFAULT_SOURCES)
+
+
+def keys_needed(setting: dict[str, Any]) -> dict[str, str]:
+    """{key group: credential name} for the enabled sources that have a key (INV-2: only
+    these are decrypted by the literature-service task)."""
+    names = setting.get("source_keys") or {}
+    out: dict[str, str] = {}
+    for source in sources_of(setting):
+        group = KEY_GROUP.get(source)
+        if group and names.get(group):
+            out[group] = str(names[group])
+    return out
+
+
+def validate(sources: Iterable[str], source_keys: dict[str, str], email: str | None,
+             credential_types: dict[str, str]) -> None:
+    """Raises SourcesRefused for: no source on, an unknown source or key group, a publisher
+    source on without its key, a key that is not a stored literature-source key, or an email
+    that is not an address."""
+    chosen = list(sources)
+    if not chosen:
+        raise SourcesRefused("turn at least one literature source on")
+    unknown = sorted(set(chosen) - set(SOURCES))
+    if unknown:
+        raise SourcesRefused(f"unknown literature sources: {', '.join(unknown)}")
+    if len(set(chosen)) != len(chosen):
+        raise SourcesRefused("a literature source is listed twice")
+    for group, name in source_keys.items():
+        if group not in KEY_GROUPS:
+            raise SourcesRefused(f"{group!r} takes no key")
+        if credential_types.get(name) != CREDENTIAL_TYPE:
+            raise SourcesRefused(f"no {CREDENTIAL_TYPE} credential named {name!r}")
+    for source in chosen:
+        if source in NEEDS_KEY and not source_keys.get(KEY_GROUP[source]):
+            raise SourcesRefused(f"{source} needs its key before it can be turned on")
+    if email and (len(email) > 254 or not _EMAIL.match(email)):
+        raise SourcesRefused("the OpenAlex contact email is not an email address")
+
+
+def env(setting: dict[str, Any], lookup: Callable[[str], str]) -> dict[str, str]:
+    """The container environment for the sources (08 §5 step 12)."""
+    out = {"EXTERNAL_SOURCES": ",".join(sources_of(setting))}
+    email = str(setting.get("openalex_email") or "")
+    if email:
+        out["OPENALEX_MAILTO"] = email
+    for group, name in keys_needed(setting).items():
+        out[ENV_NAME[group]] = lookup(name)
+    return out
+
+
+# ---- the key check (08 §5 step 3) ---------------------------------------------------------------
+
+def _request(group: str, key: str) -> tuple[str, dict[str, str], dict[str, str]]:
+    """(url, params, headers) for one small search with the key, as PureScholar sends it."""
+    if group == "semanticscholar":
+        return ("https://api.semanticscholar.org/graph/v1/paper/search",
+                {"query": "reproducibility", "limit": "1", "fields": "title"},
+                {"x-api-key": key})
+    if group == "ieee":
+        return ("https://ieeexploreapi.ieee.org/api/v1/search/articles",
+                {"querytext": "reproducibility", "max_records": "1", "apikey": key}, {})
+    if group == "elsevier":
+        return ("https://api.elsevier.com/content/search/scopus",
+                {"query": "reproducibility", "count": "1"},
+                {"X-ELS-APIKey": key, "Accept": "application/json"})
+    if group == "springer":
+        return ("https://api.springernature.com/meta/v2/json",
+                {"q": "reproducibility", "p": "1", "api_key": key}, {})
+    raise ValueError(f"unknown key group {group!r}")
+
+
+def check(group: str, key: str, client: httpx.Client | None = None) -> list[str]:
+    """One search request with the key. Returns the problems; empty means passed. Messages
+    never include the request URL, which carries some keys."""
+    url, params, headers = _request(group, key)
+    own = client is None
+    http = client or httpx.Client(timeout=CHECK_TIMEOUT_S)
+    try:
+        resp = http.get(url, params=params, headers=headers)
+    except httpx.HTTPError as exc:
+        return [f"{group} did not answer ({type(exc).__name__})"]
+    finally:
+        if own:
+            http.close()
+    if resp.status_code in (401, 403):
+        return [f"{group} refused the key (HTTP {resp.status_code})"]
+    if resp.status_code == 429:
+        return [f"{group} is rate limiting this machine (HTTP 429); try the check again in a "
+                "minute"]
+    if resp.status_code >= 400:
+        return [f"{group} answered HTTP {resp.status_code}"]
+    return []

app/model_endpoints.py

@@ -0,0 +1,104 @@
+"""Where a profile role's model is reached (07-llm.md §4 Endpoint; 08-app.md INV-11, INV-12;
+KB-036).
+
+A stored role names its endpoint as one of:
+- `base_url`: an http(s) URL;
+- `local_port`: a server on the engine's machine (self-hosted only);
+- `machine` and `remote_port`: a server on an SSH machine, reached through a tunnel.
+
+When a run is created, `expand` turns the role into what the worker needs: a `base_url`, or
+an `ssh` block with the machine's resolved connection (the run's snapshot, like its
+executor's), and `public_only` in hosted mode."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import urlsplit
+
+from app.addresses import private_address
+from app.settings import Mode
+
+ENDPOINT_KEYS = ("base_url", "local_port", "machine")
+
+
+class EndpointRefused(ValueError):
+    """The role's endpoint breaks a rule; the message says which and how to fix it."""
+
+
+def _port(value: Any, what: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or not 1 <= value <= 65535:
+        raise EndpointRefused(f"{what} must be a port number")
+    return value
+
+
+def check(spec: dict[str, Any], mode: Mode, machine_ids: set[str]) -> None:
+    """Refuses a role endpoint that breaks KB-036's rules. Hosted providers keep their
+    optional `base_url`, under the same address rules."""
+    given = [k for k in ENDPOINT_KEYS if spec.get(k) is not None]
+    if len(given) > 1:
+        raise EndpointRefused(f"give one of {', '.join(ENDPOINT_KEYS)}, not several")
+    if given and given[0] != "base_url" and spec.get("provider") != "openai_compatible":
+        raise EndpointRefused("a local or SSH endpoint needs provider openai_compatible")
+    if spec.get("provider") == "openai_compatible" and not given:
+        raise EndpointRefused("an openai_compatible model needs base_url, local_port or "
+                              "machine")
+    if "local_port" in given:
+        if mode == "hosted":  # INV-11: "this computer" is the platform's server
+            raise EndpointRefused("hosted puremethod has no local models; use an SSH machine "
+                                  "or a public URL")
+        _port(spec["local_port"], "local_port")
+    if "machine" in given:
+        if str(spec["machine"]) not in machine_ids:
+            raise EndpointRefused(f"no SSH machine {spec['machine']!r}")
+        _port(spec.get("remote_port"), "remote_port")
+    if "base_url" in given:
+        url = str(spec["base_url"])
+        parts = urlsplit(url)
+        if parts.scheme not in ("http", "https") or not parts.hostname:
+            raise EndpointRefused("base_url must be an http or https URL")
+        private = private_address(parts.hostname)
+        if mode == "hosted" and private:  # INV-11
+            raise EndpointRefused(f"{parts.hostname} is not a public address; hosted "
+                                  "puremethod does not call it. Use an SSH machine instead")
+        if parts.scheme == "http" and not private and spec.get("allow_unencrypted") is not True:
+            # INV-12: prompts and code would cross the network unencrypted.
+            raise EndpointRefused(f"{url} is plain http to a public address: prompts and code "
+                                  "would cross the network unencrypted. Use https or an SSH "
+                                  "machine, or confirm with allow_unencrypted")
+
+
+def expand(spec: dict[str, Any], mode: Mode,
+           resolve_machine: Callable[[str], dict[str, Any]]) -> dict[str, Any]:
+    """The role as a run uses it (see the module docstring)."""
+    out = {k: v for k, v in spec.items()
+           if k not in ("local_port", "machine", "remote_port", "allow_unencrypted")}
+    if spec.get("local_port") is not None:
+        out["base_url"] = f"http://127.0.0.1:{int(spec['local_port'])}/v1"
+    if spec.get("machine") is not None:
+        conn = resolve_machine(str(spec["machine"]))
+        target = {k: conn[k] for k in ("host", "user", "port", "key_credential", "host_key")}
+        out["ssh"] = {"machine": spec["machine"], "remote_port": int(spec["remote_port"]),
+                      "hops": [*conn.get("jumps", []), target]}
+    if mode == "hosted" and out.get("base_url"):
+        out["public_only"] = True  # INV-11, checked again at every call
+    if isinstance(spec.get("fallback"), dict):
+        out["fallback"] = expand(spec["fallback"], mode, resolve_machine)
+    return out
+
+
+def ssh_credentials(llm: dict[str, dict[str, Any]]) -> list[str]:
+    """The SSH key credentials an expanded profile's tunnels use (08 §5 step 3)."""
+    names: list[str] = []
+    for spec in llm.values():
+        for s in (spec, spec.get("fallback") or {}):
+            ssh = s.get("ssh") if isinstance(s, dict) else None
+            if isinstance(ssh, dict):
+                names += [str(h["key_credential"]) for h in ssh.get("hops", [])]
+    return sorted(set(names))
+
+
+def machines_used(spec: dict[str, Any]) -> list[str]:
+    out = [str(spec["machine"])] if spec.get("machine") else []
+    fb = spec.get("fallback")
+    return out + (machines_used(fb) if isinstance(fb, dict) else [])