puremethod 0.1.0__py3-none-any.whl

executor/ssh.py

@@ -0,0 +1,481 @@
+"""`ssh` backend (05-executor.md §6): a machine the user owns, reached over SSH.
+
+Isolation is declared from the host configuration: `container` when jobs run in Docker on
+the host, otherwise `none` (§6). The deadline is enforced on the host by `timeout`, so it
+holds if the engine or the connection goes away (INV-2, §9). Credentials reach the job as
+`export` lines on the remote shell's stdin: never on a command line, never on disk (INV-7).
+Host requirements (§9, KB-015): a POSIX shell, `tar`, `timeout`; Docker for containers.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import shlex
+import stat
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import paramiko
+
+from .base import CredentialLookup, Executor
+from .common import TAG_FILE, cap, check_tag, cost, process_text, redact, sanitized_tar
+from .common import classify as classify_status
+from .local_process import _tar
+from .types import (
+    DEFAULT_IMAGE,
+    METRICS_FILE,
+    EnvRef,
+    EnvSpec,
+    ExecutorInfo,
+    JobResult,
+    JobSpec,
+    Network,
+    PreflightReport,
+    Resources,
+)
+
+LOST_AFTER = 3  # consecutive failed polls before a job is `lost` (§4)
+
+# Kills every process in a session: `pkill -s` where available, else a /proc scan (Linux).
+KILL_SESSION = (
+    '_pm_kill_session() { [ -n "$1" ] || return 0; '
+    'if command -v pkill >/dev/null 2>&1; then pkill -KILL -s "$1" 2>/dev/null; '
+    'else for s in /proc/[0-9]*/stat; do set -- "$1" $(cat "$s" 2>/dev/null); '
+    '[ "$7" = "$1" ] && kill -KILL "$2" 2>/dev/null; done; fi; return 0; }; '
+)
+
+
+@dataclass
+class _Remote:
+    job_id: str
+    dir: str
+    deadline_s: float
+    killed: bool = False
+    failures: int = 0
+    lost: bool = False
+
+
+def _load_key(text: str) -> paramiko.PKey:
+    last: Exception | None = None
+    for cls in (paramiko.Ed25519Key, paramiko.ECDSAKey, paramiko.RSAKey):
+        try:
+            return cls.from_private_key(io.StringIO(text))
+        except (paramiko.SSHException, ValueError) as exc:
+            last = exc
+    raise ValueError(f"unsupported or invalid private key ({type(last).__name__})")
+
+
+class _JumpFailed(OSError):
+    """A jump host failed (§5 step 10). The message names the hop, never server text."""
+
+    def __init__(self, host: str, port: int, user: str, cause: Exception,
+                 onward: str | None = None) -> None:
+        if onward is not None:
+            reason = f"jump host {host} cannot reach {onward} ({type(cause).__name__})"
+        else:
+            reason = "jump host " + _connect_problem(cause, host, port, user, None)
+        super().__init__(reason)
+        self.reason = reason
+
+
+def _connect_problem(exc: Exception, host: str, port: int, user: str,
+                     known_hosts: str | None) -> str:
+    """Why the connection failed, in words the user can act on. Built from the exception's
+    type and our own settings, never its text beyond a fixed marker: server messages are
+    not shown."""
+    if isinstance(exc, _JumpFailed):
+        return exc.reason
+    if isinstance(exc, paramiko.BadHostKeyException):
+        return (f"{host}'s host key does not match the trusted one; the server may have been "
+                "replaced or impersonated")
+    if isinstance(exc, paramiko.AuthenticationException):
+        return f"{host} refused the SSH key for user {user!r}"
+    if isinstance(exc, FileNotFoundError) and known_hosts:
+        return f"the trusted host keys file {known_hosts!r} does not exist"
+    if isinstance(exc, paramiko.SSHException) and "not found in known_hosts" in str(exc):
+        where = f"in {known_hosts!r}" if known_hosts else "(no trusted host keys file is set)"
+        return (f"{host}'s host key is not trusted {where}; connect once with "
+                f"`ssh -p {port} {user}@{host}` to verify and trust it")
+    if isinstance(exc, ValueError):
+        return "the SSH key credential is missing or is not a supported private key"
+    if isinstance(exc, OSError):
+        return f"cannot reach {host}:{port} ({type(exc).__name__})"
+    return type(exc).__name__
+
+
+class SSHExecutor(Executor):
+    def __init__(self, credentials: CredentialLookup, *, executor_id: str = "ssh", host: str,
+                 user: str, key_credential: str, port: int = 22, remote_root: str = "puremethod",
+                 use_docker: bool = False, network: Network = "on", concurrency: int = 1,
+                 rate_usd_per_hour: float | None = None, grace_s: float = 30.0,
+                 known_hosts: str | None = None, accept_unknown_host: bool = False,
+                 host_key: str | None = None, jumps: list[dict[str, Any]] | None = None,
+                 connect_timeout_s: float = 15.0, resources: Resources | None = None) -> None:
+        super().__init__(credentials)
+        self._info = ExecutorInfo(id=executor_id, kind="ssh",
+                                  isolation="container" if use_docker else "none",
+                                  network=network, concurrency=concurrency,
+                                  resources=resources or Resources(),
+                                  rate_usd_per_hour=rate_usd_per_hour)
+        self._host, self._port, self._user = host, port, user
+        self._key_credential = key_credential
+        self._root = remote_root.strip("/")
+        self._docker = use_docker
+        self._grace = grace_s
+        self._known_hosts = known_hosts
+        self._accept_unknown = accept_unknown_host
+        self._host_key = host_key  # "<type> <base64>": the one key this host may present
+        self._timeout = connect_timeout_s
+        # §5 step 10 (KB-036): hops before the host, each {host, user, port, key_credential,
+        # host_key}; every hop trusts exactly its confirmed key.
+        self._jumps = list(jumps or [])
+        self._client: paramiko.SSHClient | None = None
+        self._hop_clients: list[paramiko.SSHClient] = []
+
+    def describe(self) -> ExecutorInfo:
+        return self._info
+
+    # ---- connection --------------------------------------------------------------------
+
+    def _connect(self) -> paramiko.SSHClient:
+        if self._client is not None:
+            transport = self._client.get_transport()
+            if transport is not None and transport.is_active():
+                return self._client
+        self.close()
+        sock: Any = None
+        for hop in self._jumps:
+            hop_client = self._trusting(str(hop["host"]), int(hop.get("port", 22)),
+                                        str(hop["host_key"]))
+            self._hop_clients.append(hop_client)
+            try:
+                hop_client.connect(str(hop["host"]), port=int(hop.get("port", 22)),
+                                   username=str(hop["user"]), sock=sock,
+                                   pkey=_load_key(self._credentials(str(hop["key_credential"]))),
+                                   timeout=self._timeout, banner_timeout=self._timeout,
+                                   auth_timeout=self._timeout, allow_agent=False,
+                                   look_for_keys=False)
+            except Exception as exc:
+                self.close()
+                raise _JumpFailed(str(hop["host"]), int(hop.get("port", 22)),
+                                  str(hop["user"]), exc) from exc
+            nxt = [*self._jumps, {"host": self._host, "port": self._port}][
+                len(self._hop_clients)]
+            transport = hop_client.get_transport()
+            try:
+                if transport is None:
+                    raise paramiko.SSHException("no transport")
+                sock = transport.open_channel("direct-tcpip",
+                                              (str(nxt["host"]), int(nxt.get("port", 22))),
+                                              ("127.0.0.1", 0), timeout=self._timeout)
+            except Exception as exc:
+                self.close()
+                raise _JumpFailed(str(hop["host"]), int(hop.get("port", 22)),
+                                  str(hop["user"]), exc, onward=str(nxt["host"])) from exc
+        client = self._trusting(self._host, self._port, self._host_key)
+        # Unknown host keys are refused unless the configuration explicitly accepts them.
+        client.set_missing_host_key_policy(paramiko.AutoAddPolicy() if self._accept_unknown
+                                           else paramiko.RejectPolicy())
+        try:
+            pkey = _load_key(self._credentials(self._key_credential))
+            client.connect(self._host, port=self._port, username=self._user, pkey=pkey,
+                           sock=sock, timeout=self._timeout, banner_timeout=self._timeout,
+                           auth_timeout=self._timeout, allow_agent=False, look_for_keys=False)
+        except Exception:
+            client.close()
+            self.close()
+            raise
+        self._client = client
+        return client
+
+    def _trusting(self, host: str, port: int, host_key: str | None) -> paramiko.SSHClient:
+        """A client that trusts this host's confirmed key (and, for the target only, a
+        known_hosts file from before KB-035), and refuses any other."""
+        client = paramiko.SSHClient()
+        if self._known_hosts and host == self._host:
+            client.load_host_keys(self._known_hosts)
+        if host_key:
+            kind, b64 = host_key.split(None, 1)
+            name = host if port == 22 else f"[{host}]:{port}"
+            client.get_host_keys().add(name, kind, paramiko.PKey.from_type_string(
+                kind, base64.b64decode(b64.strip())))
+        client.set_missing_host_key_policy(paramiko.RejectPolicy())
+        return client
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+        for c in reversed(self._hop_clients):
+            c.close()
+        self._hop_clients = []
+
+    def _exec(self, command: str, stdin: str | None = None,
+              timeout: float = 120) -> tuple[int, str, str]:
+        client = self._connect()
+        chan_in, out, err = client.exec_command(command, timeout=timeout)
+        if stdin is not None:
+            chan_in.write(stdin)
+            chan_in.channel.shutdown_write()
+        rc = out.channel.recv_exit_status()
+        return rc, out.read().decode(errors="replace"), err.read().decode(errors="replace")
+
+    # ---- interface ---------------------------------------------------------------------
+
+    def preflight(self) -> PreflightReport:
+        problems: list[str] = []
+        try:
+            for tool in ("sh", "tar", "timeout") + (("docker",) if self._docker else ()):
+                rc, _, _ = self._exec(f"command -v {tool}")
+                if rc != 0:
+                    problems.append(f"host lacks `{tool}`")
+            if self._docker and not problems:
+                rc, _, err = self._exec("docker version --format '{{.Server.Version}}'")
+                if rc != 0:
+                    problems.append(f"docker on the host does not answer: {err.strip()[:200]}")
+        except (OSError, paramiko.SSHException, ValueError) as exc:
+            problem = _connect_problem(exc, self._host, self._port, self._user,
+                                       self._known_hosts)
+            return PreflightReport(False, [f"ssh connection failed: {problem}"])
+        if problems:
+            return PreflightReport(False, problems)
+        env = self.build_env(EnvSpec(base_image=DEFAULT_IMAGE if self._docker else None))
+        if env.status != "ok":
+            return PreflightReport(False, [f"environment: {env.log[-500:]}"])
+        handle = self.submit(JobSpec(code=_tar({"ok.sh": b"echo ok\n"}), entrypoint="sh ok.sh",
+                                     env=env, seed=0, deadline_s=60))
+        deadline = time.monotonic() + 120
+        while self.poll(handle) != "done" and time.monotonic() < deadline:
+            time.sleep(0.5)
+        if self.poll(handle) != "done" or self.result(handle).status != "ok":
+            problems.append("a trivial job did not run")
+        return PreflightReport(not problems, problems)
+
+    def build_env(self, spec: EnvSpec) -> EnvRef:
+        digest = spec.digest()
+        short = digest.removeprefix("sha256:")[:24]
+        t0 = time.monotonic()
+        try:
+            if self._docker:
+                tag = f"pm-env:{short}"
+                rc, _, _ = self._exec(f"docker image inspect {tag} >/dev/null 2>&1")
+                if rc == 0:
+                    return EnvRef(digest=digest, status="ok", ref=tag)
+                ctx = f"{self._root}/envs/{short}"
+                lines = [f"FROM {spec.base_image or DEFAULT_IMAGE}"]
+                if spec.requirements_lock.strip():
+                    lines += ["COPY requirements.lock /tmp/requirements.lock",
+                              "RUN pip install --no-cache-dir -r /tmp/requirements.lock"]
+                self._put_files(ctx, {"Dockerfile": "\n".join(lines) + "\n",
+                                      "requirements.lock": spec.requirements_lock})
+                rc, out, err = self._exec(f"docker build -t {tag} {shlex.quote(ctx)}",
+                                          timeout=3600)
+                ok = rc == 0
+                return EnvRef(digest=digest, status="ok" if ok else "failed",
+                              ref=tag if ok else "", log=(out + err)[-20000:],
+                              build_seconds=time.monotonic() - t0, built=ok)
+            if not spec.requirements_lock.strip() and spec.python_version is None:
+                return EnvRef(digest=digest, status="ok", ref="")
+            venv = f"{self._root}/envs/{short}"
+            self._put_files(venv, {"requirements.lock": spec.requirements_lock})
+            python = (spec.python_version and f"python{spec.python_version}") or "python3"
+            cmd = (f"test -f {venv}/.pm-ready || ({python} -m venv {venv}/venv && "
+                   f"{venv}/venv/bin/pip install -r {venv}/requirements.lock && "
+                   f"touch {venv}/.pm-ready)")
+            rc, out, err = self._exec(cmd, timeout=3600)
+            ok = rc == 0
+            return EnvRef(digest=digest, status="ok" if ok else "failed",
+                          ref=f"{venv}/venv/bin" if ok else "", log=(out + err)[-20000:],
+                          build_seconds=time.monotonic() - t0, built=ok)
+        except (OSError, paramiko.SSHException, ValueError) as exc:
+            return EnvRef(digest=digest, status="failed", ref="",
+                          log=f"ssh error: {type(exc).__name__}",
+                          build_seconds=time.monotonic() - t0)
+
+    def _put_files(self, remote_dir: str, files: dict[str, str]) -> None:
+        self._exec(f"mkdir -p {shlex.quote(remote_dir)}")
+        sftp = self._connect().open_sftp()
+        try:
+            for name, text in files.items():
+                with sftp.open(f"{remote_dir}/{name}", "w") as f:
+                    f.write(text.encode())
+        finally:
+            sftp.close()
+
+    # ---- backend hooks -----------------------------------------------------------------
+
+    def _start(self, job_id: str, spec: JobSpec, secrets: dict[str, str]) -> _Remote:
+        d = f"{self._root}/jobs/{job_id}"
+        self._exec(f"mkdir -p {d}/ws/outputs")
+        if spec.tag is not None:  # validated by `submit`: safe in a shell word
+            self._exec(f"printf %s {shlex.quote(spec.tag)} > {d}/{TAG_FILE}")
+        sftp = self._connect().open_sftp()
+        try:
+            with sftp.open(f"{d}/code.tar", "wb") as f:
+                f.write(sanitized_tar(spec.code))
+        finally:
+            sftp.close()
+        rc, _, err = self._exec(f"tar -xf {d}/code.tar -C {d}/ws && mkdir -p {d}/ws/outputs")
+        if rc != 0:
+            raise RuntimeError(f"unpacking the code bundle failed: {err.strip()[:200]}")
+        grace = str(int(max(self._grace, 1)))
+        deadline = str(max(int(spec.deadline_s), 1))
+        exports = [f"export {name}={shlex.quote(value)}" for name, value in secrets.items()]
+        exports += [f"export PM_SEED={spec.seed}",
+                    f"export PM_ENTRY={shlex.quote(spec.entrypoint)}"]
+        if self._docker:
+            flags = " ".join(f"-e {name}" for name in secrets)
+            net = "--network none" if self._info.network == "off" else ""
+            inner = (f'docker run --name pm-job-{job_id} -v "$PWD":/work -w /work '
+                     f'-e PM_SEED {flags} {net} {spec.env.ref} '
+                     f'timeout -s TERM -k {grace} {deadline} sh -c "$PM_ENTRY"')
+        else:
+            path = f'export PATH="$HOME/{spec.env.ref}:$PATH"; ' if spec.env.ref else ""
+            inner = f'{path}timeout -s TERM -k {grace} {deadline} sh -c "$PM_ENTRY"'
+        # The job's session is the handle for the whole tree: `timeout` moves the job into a
+        # process group of its own, but never out of the session. After the exit code is
+        # written, anything the job left behind in its session is killed (INV-3).
+        wrapper = (f"{KILL_SESSION}"
+                   "sid=$(cut -d' ' -f6 /proc/$$/stat 2>/dev/null); [ -n \"$sid\" ] || sid=$$; "
+                   "echo \"$sid\" > ../sid; "
+                   f"{inner} > ../stdout 2> ../stderr; echo $? > ../exit_code.tmp; "
+                   "mv ../exit_code.tmp ../exit_code; _pm_kill_session \"$sid\"")
+        script = "\n".join([
+            *exports,
+            f'cd "$HOME/{d}/ws"',
+            "date +%s > ../started",
+            "if command -v setsid >/dev/null 2>&1; then",
+            f"  setsid sh -c {shlex.quote(wrapper)} </dev/null >/dev/null 2>&1 &",
+            "else",
+            f"  nohup sh -c {shlex.quote(wrapper)} </dev/null >/dev/null 2>&1 &",
+            "fi",
+            "echo $! > ../pid",
+        ]) + "\n"
+        rc, _, err = self._exec("sh -s", stdin=script)
+        if rc != 0:
+            raise RuntimeError(f"starting the job failed: {err.strip()[:200]}")
+        return _Remote(job_id=job_id, dir=d, deadline_s=spec.deadline_s)
+
+    def _done(self, backend: Any) -> bool:
+        r: _Remote = backend
+        try:
+            rc, _, _ = self._exec(f"test -f {r.dir}/exit_code", timeout=30)
+            r.failures = 0
+            return rc == 0
+        except (OSError, paramiko.SSHException, EOFError):
+            self.close()
+            r.failures += 1
+            if r.failures >= LOST_AFTER:
+                r.lost = True
+                return True
+            return False
+
+    def _read(self, sftp: paramiko.SFTPClient, path: str, limit: int | None = None) -> bytes:
+        try:
+            with sftp.open(path, "rb") as f:
+                return bytes(f.read(limit + 1 if limit else -1))
+        except OSError:
+            return b""
+
+    def _collect(self, backend: Any, spec: JobSpec, secrets: dict[str, str], *,
+                 killed: bool) -> JobResult:
+        r: _Remote = backend
+        if r.lost:
+            return JobResult(status="lost", exit_code=None, stdout=b"", stderr=b"", outputs={},
+                             metrics=None, started_at=None, ended_at=None, duration_s=None,
+                             cost_usd=None, metered=False, env_digest=spec.env.digest,
+                             code_digest=spec.code_digest, redactions=[],
+                             output_cap_bytes=2 * 1024 * 1024)
+        limit = 2 * 1024 * 1024
+        sftp = self._connect().open_sftp()
+        try:
+            stdout, n1 = redact(self._read(sftp, f"{r.dir}/stdout", limit), secrets)
+            stderr, n2 = redact(self._read(sftp, f"{r.dir}/stderr", limit), secrets)
+            code_text = self._read(sftp, f"{r.dir}/exit_code").decode().strip()
+            started_text = self._read(sftp, f"{r.dir}/started").decode().strip()
+            ended_mtime = sftp.stat(f"{r.dir}/exit_code").st_mtime
+            outputs, n3, truncated = self._outputs(sftp, f"{r.dir}/ws/outputs", secrets)
+        finally:
+            sftp.close()
+        stdout, t1 = cap(stdout)
+        stderr, t2 = cap(stderr)
+        truncated += [n for n, t in (("stdout", t1), ("stderr", t2)) if t]
+        exit_code = int(code_text) if code_text.lstrip("-").isdigit() else None
+        duration = None
+        if started_text.isdigit() and ended_mtime:
+            duration = max(float(ended_mtime) - float(started_text), 0.0)
+        timed_out = duration is not None and duration >= r.deadline_s and exit_code != 0
+        status = classify_status(exit_code, killed=killed or r.killed, timed_out=timed_out,
+                                 crashed=False)
+        if self._docker:
+            self._exec(f"docker rm -f pm-job-{r.job_id} >/dev/null 2>&1", timeout=60)
+        # The remote workspace may hold what the job wrote, credentials included.
+        self._exec(f"rm -rf {shlex.quote(r.dir)}", timeout=120)
+        usd, metered = cost(self._info.rate_usd_per_hour, duration)
+        return JobResult(status=status, exit_code=exit_code, stdout=stdout, stderr=stderr,
+                         outputs=outputs, metrics=outputs.get(METRICS_FILE), started_at=None,
+                         ended_at=None, duration_s=duration, cost_usd=usd, metered=metered,
+                         env_digest=spec.env.digest, code_digest=spec.code_digest,
+                         redactions=sorted(set(n1 + n2 + n3)), output_cap_bytes=limit,
+                         truncated=truncated)
+
+    def _outputs(self, sftp: paramiko.SFTPClient, root: str, secrets: dict[str, str]
+                 ) -> tuple[dict[str, bytes], list[str], list[str]]:
+        files: dict[str, bytes] = {}
+        names: list[str] = []
+        truncated: list[str] = []
+        stack = [""]
+        while stack:
+            rel = stack.pop()
+            try:
+                entries = sftp.listdir_attr(f"{root}/{rel}" if rel else root)
+            except OSError:
+                continue
+            for e in entries:
+                sub = f"{rel}/{e.filename}" if rel else e.filename
+                mode = e.st_mode or 0
+                if stat.S_ISDIR(mode):
+                    stack.append(sub)
+                elif stat.S_ISREG(mode):
+                    data, hit, cut = process_text(self._read(sftp, f"{root}/{sub}"), secrets)
+                    files[f"outputs/{sub}"] = data
+                    names += hit
+                    if cut:
+                        truncated.append(f"outputs/{sub}")
+        return files, names, truncated
+
+    def _kill(self, backend: Any) -> None:
+        r: _Remote = backend
+        r.killed = True
+        docker = f"docker kill pm-job-{r.job_id} >/dev/null 2>&1; " if self._docker else ""
+        script = (KILL_SESSION + docker
+                  + f"sid=$(cat {r.dir}/sid 2>/dev/null); pid=$(cat {r.dir}/pid 2>/dev/null); "
+                  + f"test -f {r.dir}/exit_code || echo 137 > {r.dir}/exit_code; "
+                  + '_pm_kill_session "$sid"; '
+                  + 'if [ -n "$pid" ]; then kill -KILL -- -"$pid" 2>/dev/null '
+                  + '|| kill -KILL "$pid" 2>/dev/null; fi; true')
+        self._exec(script, timeout=60)
+
+    def reap(self, tags: list[str]) -> list[str]:
+        """Jobs on the host from any engine process, found by their tag file (INV-9): kill
+        the session and the process group, remove the container and the job directory."""
+        wanted = [check_tag(t) for t in tags]
+        if not wanted:
+            return []
+        docker = ('docker rm -f "pm-job-$(basename "$d")" >/dev/null 2>&1; '
+                  if self._docker else "")
+        listed = " ".join(wanted)  # check_tag: no spaces, quotes or shell characters
+        script = (KILL_SESSION
+                  + f"for d in {self._root}/jobs/*; do "
+                  + f'[ -f "$d/{TAG_FILE}" ] || continue; t=$(cat "$d/{TAG_FILE}"); '
+                  + f'case " {listed} " in *" $t "*) ;; *) continue;; esac; '
+                  + docker
+                  + 'sid=$(cat "$d/sid" 2>/dev/null); pid=$(cat "$d/pid" 2>/dev/null); '
+                  + '_pm_kill_session "$sid"; '
+                  + 'if [ -n "$pid" ]; then kill -KILL -- -"$pid" 2>/dev/null '
+                  + '|| kill -KILL "$pid" 2>/dev/null; fi; '
+                  + 'rm -rf "$d"; echo "$t"; done; true')
+        _, out, _ = self._exec(script, timeout=120)
+        return sorted({line.strip() for line in out.splitlines() if line.strip() in wanted})

executor/types.py

@@ -0,0 +1,128 @@
+"""Executor types (05-executor.md §3, §4)."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Literal
+
+Isolation = Literal["container", "vm", "none"]
+Network = Literal["on", "off"]
+JobState = Literal["queued", "running", "done"]
+Status = Literal["ok", "failed", "crashed", "timeout", "killed", "lost"]
+
+DEFAULT_IMAGE = "python:3.11-slim"
+METRICS_FILE = "outputs/pm_metrics.json"
+
+
+@dataclass(frozen=True)
+class Resources:
+    cpus: float | None = None
+    memory_mb: int | None = None
+    gpus: int = 0
+    gpu_model: str | None = None
+
+
+@dataclass(frozen=True)
+class ExecutorInfo:
+    id: str
+    kind: str
+    isolation: Isolation
+    network: Network
+    concurrency: int
+    resources: Resources
+    rate_usd_per_hour: float | None  # None: unmetered
+
+    @property
+    def metered(self) -> bool:
+        return self.rate_usd_per_hour is not None
+
+
+@dataclass(frozen=True)
+class EnvSpec:
+    base_image: str | None = DEFAULT_IMAGE  # container kinds
+    python_version: str | None = None       # local-process and ssh without Docker
+    requirements_lock: str = ""
+    system_packages: tuple[str, ...] = ()
+
+    def digest(self) -> str:
+        canonical = json.dumps(asdict(self), sort_keys=True, separators=(",", ":"))
+        return "sha256:" + hashlib.sha256(canonical.encode()).hexdigest()
+
+
+@dataclass(frozen=True)
+class EnvRef:
+    digest: str
+    status: Literal["ok", "failed"]
+    ref: str            # image tag, or interpreter path
+    log: str = ""
+    build_seconds: float = 0.0
+    built: bool = False  # built by this call (not reused)
+
+
+@dataclass(frozen=True)
+class DataMount:
+    name: str
+    source: str  # host path the user configured; mounted read-only at /data/<name>
+
+
+@dataclass(frozen=True)
+class JobSpec:
+    code: bytes  # a tar archive
+    entrypoint: str
+    env: EnvRef
+    seed: int
+    deadline_s: float
+    resources: Resources = field(default_factory=Resources)
+    credentials: tuple[str, ...] = ()
+    data_mounts: tuple[DataMount, ...] = ()
+    tag: str | None = None  # the caller's id for the job, for `reap` (KB-020)
+
+    @property
+    def code_digest(self) -> str:
+        return "sha256:" + hashlib.sha256(self.code).hexdigest()
+
+
+@dataclass(frozen=True)
+class JobHandle:
+    job_id: str
+    executor_id: str
+
+
+@dataclass
+class JobResult:
+    status: Status
+    exit_code: int | None
+    stdout: bytes
+    stderr: bytes
+    outputs: dict[str, bytes]
+    metrics: bytes | None
+    started_at: str | None
+    ended_at: str | None
+    duration_s: float | None
+    cost_usd: float | None
+    metered: bool
+    env_digest: str
+    code_digest: str
+    redactions: list[str]
+    output_cap_bytes: int
+    truncated: list[str] = field(default_factory=list)
+
+
+@dataclass
+class PreflightReport:
+    ok: bool
+    problems: list[str] = field(default_factory=list)
+
+
+class ExecutorError(Exception):
+    """Base error."""
+
+
+class UnknownJob(ExecutorError):
+    """No job with this handle on this executor."""
+
+
+class NotDone(ExecutorError):
+    """`result` called before `poll` reported `done`."""