gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/_bundle.py

@@ -0,0 +1,281 @@
+"""Bundle inspection: kind detection, manifest parsing, handler loading.
+
+Two structurally-detected environment kinds (spec §3.1 + addendum):
+
+- **mock-tools** — ``gateway-env.toml`` at the bundle root, ``tools/*.py``
+  handlers, ``db/schema.sql`` (+ ``db/seed.sql``), ``verifiers/*.sql``.
+- **harbor** — a tree of Harbor task dirs (``tasks/*/task.toml`` or
+  ``*/task.toml``), mirroring ``benchmark_hub.harbor_adapter.detect_env_kind``.
+
+Handler loading executes each ``tools/*.py`` with this SDK's
+:mod:`gatewaysdk.environment.runtime` injected into ``sys.modules`` as
+``gateway_env`` for the duration of the load — the module the generated
+handlers import — and restores ``sys.modules`` afterwards.
+"""
+
+from __future__ import annotations
+
+import functools
+import importlib.util
+import inspect
+import sys
+import tomllib
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from . import runtime
+from .errors import EnvironmentNotReady, WorldStartError
+
+KIND_MOCK_TOOLS = "mock-tools"
+KIND_API = "api"
+KIND_HARBOR = "harbor"
+
+
+def detect_kind(bundle_path: Path) -> str:
+    """"api" iff ``gateway-api-world.toml`` sits at the root; else "mock-tools"
+    iff ``gateway-env.toml`` does; else "harbor" iff the tree holds Harbor task
+    dirs (same glob heuristics as the runner's ``detect_env_kind``); else the
+    bundle is not runnable here."""
+    from .schema import bundle_mode
+
+    bundle_mode(bundle_path)  # Orphan/invalid schema declarations never downgrade.
+    if (bundle_path / "gateway-api-world.toml").is_file():
+        return KIND_API
+    if (bundle_path / "gateway-env.toml").is_file():
+        return KIND_MOCK_TOOLS
+    if list(bundle_path.glob("tasks/*/task.toml")) or list(bundle_path.glob("*/task.toml")):
+        return KIND_HARBOR
+    raise EnvironmentNotReady(
+        f"{bundle_path} is neither a mock-tools bundle (no gateway-env.toml) nor "
+        "a harbor task tree (no */task.toml) — nothing gwenv can run locally."
+    )
+
+
+# ---------------------------------------------------------------------------
+# mock-tools: manifest + handlers
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class EnvManifest:
+    """Parsed ``gateway-env.toml``."""
+
+    name: str
+    serve: List[str]
+    db_engine: str = "sqlite"
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+
+def parse_manifest(bundle_path: Path) -> EnvManifest:
+    manifest_path = bundle_path / "gateway-env.toml"
+    try:
+        data = tomllib.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as error:
+        raise EnvironmentNotReady(f"cannot parse {manifest_path}: {error}") from error
+
+    # Builder-generated manifests use an [environment] table; hand-written
+    # ones may use [env] or a top-level name.
+    env_table: Dict[str, Any] = {}
+    for key in ("environment", "env"):
+        if isinstance(data.get(key), dict):
+            env_table = data[key]
+            break
+    name = env_table.get("name") or data.get("name") or bundle_path.name
+
+    tools_table = data.get("tools") if isinstance(data.get("tools"), dict) else {}
+    serve = tools_table.get("serve") or []
+    if not isinstance(serve, list):
+        raise EnvironmentNotReady(f"{manifest_path}: [tools] serve must be a list of tool names")
+
+    db_value = data.get("db")
+    if isinstance(db_value, dict):
+        engine = db_value.get("engine") or env_table.get("db") or "sqlite"
+    elif isinstance(db_value, str):
+        engine = db_value
+    else:
+        engine = env_table.get("db") or "sqlite"
+    if engine != "sqlite":
+        raise WorldStartError(
+            f"db engine {engine!r} is not supported in local mode — P1 runs "
+            "sqlite in-process (Postgres arrives with hosted worlds, spec §4.9)."
+        )
+    return EnvManifest(name=str(name), serve=[str(s) for s in serve], db_engine=engine, raw=data)
+
+
+def _wrap_run_handler(fn: Callable[..., Any], tool_name: str) -> Callable[..., Any]:
+    """Adapt the generated-bundle handler contract to the SDK's call shapes.
+
+    Builder-generated bundles expose ``run(input: dict, conn=None)`` in
+    ``tools/<tool_name>.py`` — the whole tool input arrives as one dict, and
+    the runtime injects an open sqlite connection so writes land in the
+    active world (not the bundle's on-disk default db).
+    """
+    takes_conn = "conn" in inspect.signature(fn).parameters
+
+    @functools.wraps(fn)
+    def handler(*args: Any, **kwargs: Any) -> Any:
+        tool_input = args[0] if args else (kwargs if runtime._active_store.get() is not None else (kwargs or None))
+        if takes_conn:
+            return fn(tool_input, conn=runtime._active_connection.get())
+        return fn(tool_input)
+
+    handler.__name__ = tool_name
+    return handler
+
+
+def load_handlers(bundle_path: Path, manifest: EnvManifest) -> Dict[str, Callable[..., Any]]:
+    """Execute ``tools/*.py`` and return the tool-name → handler map.
+
+    Registration paths, in priority order:
+      1. ``@tool(name=...)`` / bare ``@tool`` decorations (captured via the
+         runtime's load-registry contextvar during module exec);
+      2. fallback discovery — a plain module-level ``def <tool_name>`` whose
+         name matches a served tool that no decorator claimed;
+      3. the generated-bundle contract — ``run(input, conn=None)`` in the
+         module whose FILE STEM is the served tool name (wrapped so the
+         active world's connection is injected).
+
+    ``gateway_env`` is importable only inside this function's dynamic extent.
+    """
+    from .schema import bundle_mode, check_bundle
+
+    contract = check_bundle(bundle_path) if bundle_mode(bundle_path) is not None else None
+    tools_dir = bundle_path / "tools"
+    registry: Dict[str, Callable[..., Any]] = {}
+    modules = []
+    modules_by_stem: Dict[str, Any] = {}
+
+    handler_files = sorted(tools_dir.glob("*.py")) if tools_dir.is_dir() else []
+    load_token = runtime._load_registry.set(registry)
+    strict_token = runtime._strict_registration.set(contract is not None)
+    saved = sys.modules.get("gateway_env")
+    sys.modules["gateway_env"] = runtime
+    # Generated bundles use intra-bundle imports ("from tools._db import …"),
+    # so the bundle root must be importable for the load's dynamic extent.
+    bundle_root = str(bundle_path)
+    path_added = bundle_root not in sys.path
+    if path_added:
+        sys.path.insert(0, bundle_root)
+    saved_pkgs = {
+        name: sys.modules.get(name)
+        for name in list(sys.modules)
+        if name == "tools" or name.startswith("tools.")
+    }
+    for name in saved_pkgs:
+        sys.modules.pop(name, None)
+    try:
+        for handler_file in handler_files:
+            if handler_file.name.startswith("_"):
+                continue
+            module_name = f"_gateway_env_bundle_{uuid.uuid4().hex[:8]}_{handler_file.stem}"
+            spec = importlib.util.spec_from_file_location(module_name, handler_file)
+            if spec is None or spec.loader is None:  # pragma: no cover — importlib edge
+                raise WorldStartError(f"cannot load handler module {handler_file}")
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[module_name] = module
+            try:
+                spec.loader.exec_module(module)
+            except Exception as error:
+                raise WorldStartError(
+                    f"handler module {handler_file.name} failed to import: {error}"
+                ) from error
+            modules.append(module)
+            modules_by_stem[handler_file.stem] = module
+    finally:
+        if saved is not None:
+            sys.modules["gateway_env"] = saved
+        else:
+            sys.modules.pop("gateway_env", None)
+        if path_added:
+            try:
+                sys.path.remove(bundle_root)
+            except ValueError:
+                pass
+        # Drop bundle-local "tools" modules and restore anything shadowed.
+        for name in [
+            n for n in sys.modules if n == "tools" or n.startswith("tools.")
+        ]:
+            sys.modules.pop(name, None)
+        for name, module in saved_pkgs.items():
+            if module is not None:
+                sys.modules[name] = module
+        runtime._load_registry.reset(load_token)
+        runtime._strict_registration.reset(strict_token)
+
+    # Fallbacks for undecorated bundles.
+    for tool_name in manifest.serve:
+        if tool_name in registry:
+            continue
+        # (2) a plain module-level function named exactly like the tool.
+        for module in modules:
+            candidate = getattr(module, tool_name, None)
+            if callable(candidate) and getattr(candidate, "__module__", None) == module.__name__:
+                registry[tool_name] = candidate
+                break
+        else:
+            # (3) run(input, conn=None) in tools/<tool_name>.py.
+            stem_module = modules_by_stem.get(tool_name)
+            run_fn = getattr(stem_module, "run", None) if stem_module else None
+            if callable(run_fn):
+                registry[tool_name] = _wrap_run_handler(run_fn, tool_name)
+    if contract is not None and set(registry) != set(contract.tools):
+        from .schema import ContractError
+
+        raise ContractError("tool", "Authored handlers must exactly cover the declared tools")
+    return registry
+
+
+# ---------------------------------------------------------------------------
+# harbor: task enumeration
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class HarborTask:
+    """One Harbor task dir (``task.toml`` + ``instruction.md`` + ``tests/``)."""
+
+    name: str
+    path: Path
+    instruction: Optional[str]
+    docker_image: Optional[str]
+    has_tests: bool
+    config: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def prompt(self) -> Optional[str]:
+        """Alias — the task's instruction is its prompt."""
+        return self.instruction
+
+
+def harbor_tasks_root(bundle_path: Path) -> Path:
+    """The dir whose CHILDREN are task dirs: ``<src>/tasks`` if present, else
+    ``<src>`` (mirrors ``harbor_adapter.tasks_root``)."""
+    tasks = bundle_path / "tasks"
+    return tasks if list(tasks.glob("*/task.toml")) else bundle_path
+
+
+def load_harbor_tasks(bundle_path: Path) -> List[HarborTask]:
+    tasks: List[HarborTask] = []
+    for task_toml in sorted(harbor_tasks_root(bundle_path).glob("*/task.toml")):
+        task_dir = task_toml.parent
+        try:
+            config = tomllib.loads(task_toml.read_text(encoding="utf-8"))
+        except (OSError, tomllib.TOMLDecodeError) as error:
+            raise EnvironmentNotReady(f"cannot parse {task_toml}: {error}") from error
+        environment = config.get("environment") if isinstance(config.get("environment"), dict) else {}
+        instruction_path = task_dir / "instruction.md"
+        tasks.append(
+            HarborTask(
+                name=task_dir.name,
+                path=task_dir,
+                instruction=(
+                    instruction_path.read_text(encoding="utf-8") if instruction_path.is_file() else None
+                ),
+                docker_image=environment.get("docker_image"),
+                has_tests=(task_dir / "tests").is_dir(),
+                config=config,
+            )
+        )
+    return tasks

gatewaysdk/environment/_harbor.py

@@ -0,0 +1,276 @@
+"""Harbor worlds — per-task docker sandboxes for harbor-kind environments.
+
+A harbor env is a tree of task dirs (``task.toml`` + ``instruction.md`` +
+``tests/``). ``env.task(name)`` boots one task's declared ``docker_image`` as
+a local container, copies the task dir in, and hands back a
+:class:`HarborWorld`: ``exec`` commands inside the sandbox, then ``verify()``
+runs the task's own grader (``tests/test.sh``) and parses the harbor reward
+contract (``/logs/verifier/reward.json`` scalar ``reward`` + named numeric
+sub-rewards; ``reward.txt`` fallback; missing/unparseable → score ``None``,
+NEVER 0 — mirrors ``benchmark_hub.harbor_adapter`` / the runner's harvest).
+
+The docker layer is an injectable interface (:class:`DockerRuntime`) so tests
+run offline against a fake; the real implementation shells out to the docker
+CLI with timeouts on every call (never hangs).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Dict, List, Optional, Sequence, Tuple, Union
+
+from ._bundle import HarborTask
+from ._world import VerifierResult
+from .errors import VerifierError, WorldStartError
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .core import Environment
+
+Command = Union[str, Sequence[str]]
+
+REWARD_JSON_PATH = "/logs/verifier/reward.json"
+REWARD_TXT_PATH = "/logs/verifier/reward.txt"
+
+
+@dataclass
+class ExecResult:
+    """Outcome of one command inside the sandbox."""
+
+    exit_code: int
+    stdout: str
+    stderr: str
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0
+
+
+class DockerRuntime:
+    """The container operations a harbor world needs. Subclass (or duck-type)
+    to inject a fake for offline tests; :class:`CliDockerRuntime` is the real
+    thing."""
+
+    def available(self) -> Tuple[bool, str]:
+        """(usable, reason-if-not)."""
+        raise NotImplementedError
+
+    def run_container(self, image: str, *, name: str) -> str:
+        """Start a long-lived container from ``image``; return its id."""
+        raise NotImplementedError
+
+    def copy_in(self, container: str, source: Path, dest: str) -> None:
+        """Copy a local file/dir into the container at ``dest``."""
+        raise NotImplementedError
+
+    def exec(self, container: str, cmd: Command, *, timeout: float) -> ExecResult:
+        """Run a command in the container (str → via ``sh -c``)."""
+        raise NotImplementedError
+
+    def read_file(self, container: str, path: str) -> Optional[bytes]:
+        """The file's bytes, or ``None`` when it does not exist."""
+        raise NotImplementedError
+
+    def remove(self, container: str) -> None:
+        """Force-remove the container (best-effort)."""
+        raise NotImplementedError
+
+
+class CliDockerRuntime(DockerRuntime):
+    """Shells out to the ``docker`` CLI. Every call has a timeout."""
+
+    def __init__(self, binary: str = "docker", *, pull_timeout: float = 900.0) -> None:
+        self._binary = binary
+        self._pull_timeout = pull_timeout
+
+    def _run(self, args: List[str], *, timeout: float, binary_output: bool = False) -> subprocess.CompletedProcess:
+        return subprocess.run(
+            [self._binary, *args],
+            capture_output=True,
+            text=not binary_output,
+            timeout=timeout,
+        )
+
+    def available(self) -> Tuple[bool, str]:
+        if shutil.which(self._binary) is None:
+            return False, f"'{self._binary}' not found on PATH"
+        try:
+            proc = self._run(["version", "--format", "{{.Server.Version}}"], timeout=15)
+        except subprocess.TimeoutExpired:
+            return False, "docker daemon did not answer within 15s"
+        if proc.returncode != 0:
+            return False, (proc.stderr or proc.stdout or "docker daemon unreachable").strip()[:300]
+        return True, ""
+
+    def run_container(self, image: str, *, name: str) -> str:
+        try:
+            proc = self._run(
+                ["run", "-d", "--name", name, "--entrypoint", "sleep", image, "infinity"],
+                timeout=self._pull_timeout,
+            )
+        except subprocess.TimeoutExpired as error:
+            raise WorldStartError(
+                f"docker run {image} timed out after {self._pull_timeout}s (pull too slow?)"
+            ) from error
+        if proc.returncode != 0:
+            raise WorldStartError(
+                f"docker run {image} failed: {(proc.stderr or proc.stdout).strip()[:500]}"
+            )
+        return proc.stdout.strip()
+
+    def copy_in(self, container: str, source: Path, dest: str) -> None:
+        proc = self._run(["cp", str(source), f"{container}:{dest}"], timeout=300)
+        if proc.returncode != 0:
+            raise WorldStartError(f"docker cp {source} failed: {proc.stderr.strip()[:500]}")
+
+    def exec(self, container: str, cmd: Command, *, timeout: float) -> ExecResult:
+        args = ["exec", container]
+        args += ["sh", "-c", cmd] if isinstance(cmd, str) else list(cmd)
+        try:
+            proc = self._run(args, timeout=timeout)
+        except subprocess.TimeoutExpired:
+            return ExecResult(exit_code=124, stdout="", stderr=f"timed out after {timeout}s")
+        return ExecResult(exit_code=proc.returncode, stdout=proc.stdout, stderr=proc.stderr)
+
+    def read_file(self, container: str, path: str) -> Optional[bytes]:
+        try:
+            proc = self._run(["exec", container, "cat", path], timeout=60, binary_output=True)
+        except subprocess.TimeoutExpired:
+            return None
+        return proc.stdout if proc.returncode == 0 else None
+
+    def remove(self, container: str) -> None:
+        try:
+            self._run(["rm", "-f", container], timeout=60)
+        except subprocess.TimeoutExpired:  # pragma: no cover — best-effort cleanup
+            pass
+
+
+def parse_rewards(
+    reward_json: Optional[bytes], reward_txt: Optional[bytes]
+) -> Tuple[Optional[float], Dict[str, float], str]:
+    """(scalar score, named sub-rewards, note) from the harbor reward files.
+
+    ``reward.json``: scalar = the ``reward`` key (or the first numeric value);
+    every OTHER numeric key is a named sub-reward. ``reward.txt``: bare float
+    fallback. Missing/unparseable → ``(None, {}, why)`` — never 0.
+    """
+    if reward_json is not None:
+        try:
+            data = json.loads(reward_json.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            data = None
+        if isinstance(data, (int, float)) and not isinstance(data, bool):
+            return float(data), {}, "scalar reward.json"
+        if isinstance(data, dict):
+            numeric = {
+                key: float(value)
+                for key, value in data.items()
+                if isinstance(value, (int, float)) and not isinstance(value, bool)
+            }
+            if "reward" in numeric:
+                scalar = numeric.pop("reward")
+                return scalar, numeric, "reward.json"
+            if numeric:
+                first_key = next(iter(numeric))
+                scalar = numeric.pop(first_key)
+                return scalar, numeric, f"reward.json (no 'reward' key — used '{first_key}')"
+            return None, {}, "reward.json held no numeric metrics"
+        note = "reward.json unparseable"
+    else:
+        note = "reward.json missing"
+
+    if reward_txt is not None:
+        try:
+            return float(reward_txt.decode("utf-8").strip()), {}, f"{note}; reward.txt fallback"
+        except (ValueError, UnicodeDecodeError):
+            return None, {}, f"{note}; reward.txt unparseable"
+    return None, {}, f"{note}; no reward.txt"
+
+
+class HarborWorld:
+    """One task's live docker sandbox."""
+
+    def __init__(self, env: "Environment", task: HarborTask, docker: DockerRuntime) -> None:
+        self.env = env
+        self.task = task
+        self._docker = docker
+        self.id = uuid.uuid4().hex[:8]
+
+        usable, reason = docker.available()
+        if not usable:
+            raise WorldStartError(
+                f"docker unavailable: {reason} — install/start Docker, or inject "
+                "a DockerRuntime (gwenv.init_from_path(..., docker=...))."
+            )
+        if not task.docker_image:
+            raise WorldStartError(
+                f"harbor task '{task.name}' declares no [environment].docker_image "
+                "(Dockerfile-only tasks have nothing pullable) — build and tag the "
+                "image, set docker_image in task.toml, or run it via the harbor "
+                "engine / platform Batch instead."
+            )
+        container_name = re.sub(r"[^a-zA-Z0-9_.-]", "-", f"gwenv-{env.slug}-{task.name}")[:52] + f"-{self.id}"
+        try:
+            self.container = docker.run_container(task.docker_image, name=container_name)
+        except WorldStartError:
+            raise
+        except Exception as error:  # pragma: no cover — runtime-impl specific
+            raise WorldStartError(f"failed to start {task.docker_image}: {error}") from error
+        try:
+            docker.copy_in(self.container, task.path, "/task")
+        except Exception:
+            self.close()
+            raise
+
+    def exec(self, cmd: Command, *, timeout: float = 120.0) -> ExecResult:
+        """Run a command inside the task sandbox."""
+        started = time.perf_counter()
+        result = self._docker.exec(self.container, cmd, timeout=timeout)
+        summary = cmd if isinstance(cmd, str) else " ".join(cmd)
+        self.env._record_route(
+            f"{self.task.name}:exec[{summary[:60]}]",
+            "env",
+            (time.perf_counter() - started) * 1000.0,
+            self.id,
+        )
+        return result
+
+    def verify(self, name: Optional[str] = None) -> VerifierResult:
+        """Run the task's own grader (``tests/test.sh``) and parse the reward
+        files. A missing/failed grader yields score ``None`` (never 0), with
+        the failure surfaced in ``detail``."""
+        if not self.task.has_tests:
+            raise VerifierError(f"harbor task '{self.task.name}' ships no tests/ dir — nothing to verify")
+
+        verifier_cfg = self.task.config.get("verifier") if isinstance(self.task.config.get("verifier"), dict) else {}
+        timeout = float(verifier_cfg.get("timeout_sec") or 600.0)
+
+        self._docker.copy_in(self.container, self.task.path / "tests", "/tests")
+        self._docker.exec(self.container, ["mkdir", "-p", "/logs/verifier"], timeout=30)
+        run = self._docker.exec(self.container, ["bash", "/tests/test.sh"], timeout=timeout)
+
+        score, rewards, note = parse_rewards(
+            self._docker.read_file(self.container, REWARD_JSON_PATH),
+            self._docker.read_file(self.container, REWARD_TXT_PATH),
+        )
+        detail = note
+        if not run.ok:
+            detail = f"test.sh exited {run.exit_code} ({(run.stderr or run.stdout).strip()[:300]}); {note}"
+        passed = None if score is None else score >= 1.0
+        return VerifierResult(
+            name=name or self.task.name, passed=passed, score=score, detail=detail, rewards=rewards
+        )
+
+    def state(self, path: str) -> Optional[bytes]:
+        """Read a file out of the sandbox (harbor worlds have no SQL surface)."""
+        return self._docker.read_file(self.container, path)
+
+    def close(self) -> None:
+        self._docker.remove(self.container)

gatewaysdk/environment/_materialize.py

@@ -0,0 +1,97 @@
+"""Shared SDK/hosted template materialization; schema mode never falls back."""
+
+from __future__ import annotations
+
+import shutil
+import sqlite3
+import sys
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from ._bundle import load_handlers, parse_manifest
+from .errors import WorldStartError
+from .schema import SQLiteStore, bundle_mode, check_bundle
+from .schema.validation import read_json
+
+
+def materialize_template(bundle: Path, destination: Path, *, require_sql: bool = False) -> None:
+    bundle, destination = Path(bundle), Path(destination)
+    if bundle_mode(bundle) is not None:
+        contract = check_bundle(bundle)
+        if destination.exists():
+            from .schema import ContractError
+
+            raise ContractError("state_exists", "Refusing to overwrite an existing template")
+        from .schema.snapshot import current_default, default_snapshot, pin_path
+
+        if current_default(bundle, contract) is not None:
+            # The compiled snapshot is this exact data through this exact contract,
+            # already audited: a copy is the materialized template.
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(default_snapshot(bundle), destination)
+            return
+        if pin_path(bundle).is_file():
+            # A pinned tree's data is the hosted snapshot; its data files cannot
+            # stand in for it, so a missing or stale snapshot is refused, not rebuilt.
+            from .schema import ContractError
+
+            raise ContractError(
+                "snapshot_pinned",
+                "db/snapshot.json pins a hosted snapshot that is not in the tree: fetch the world "
+                "with its snapshot (load_world_to_sandbox, gateway worlds pull) instead of "
+                "materializing from its data files",
+                schema_path="/db/state.sqlite",
+            )
+        initial = read_json(bundle / "data/initial.json")
+        try:
+            with SQLiteStore.create(destination, contract) as store:
+                store.apply_batch(initial)
+                # Immutable refresh journals retain each mapping/source contribution.
+                # Coverage never prunes: every change is an explicit store mutation.
+                batches = bundle / "data/batches"
+                if batches.is_symlink():
+                    from .schema import ContractError
+
+                    raise ContractError("path", "Refresh batches cannot be symlinks")
+                if batches.exists():
+                    for batch in sorted(batches.iterdir()):
+                        if batch.is_symlink() or not batch.is_file() or batch.suffix != ".json":
+                            from .schema import ContractError
+
+                            raise ContractError("path", "Refresh journals must be regular JSON files")
+                        store.apply_batch(read_json(batch))
+        except BaseException:
+            destination.unlink(missing_ok=True)
+            raise
+        return
+    schema, seed = bundle / "db/schema.sql", bundle / "db/seed.sql"
+    if require_sql and not schema.is_file():
+        raise WorldStartError("mock-tools bundle is missing db/schema.sql")
+    conn = sqlite3.connect(destination)
+    try:
+        if schema.is_file():
+            conn.executescript(schema.read_text(encoding="utf-8"))
+        if seed.is_file():
+            conn.executescript(seed.read_text(encoding="utf-8"))
+        conn.commit()
+    except sqlite3.Error as error:
+        raise WorldStartError("Failed to build seed database; check db/schema.sql and db/seed.sql") from error
+    finally:
+        conn.close()
+
+
+def validate_schema_materialization(bundle: Path) -> None:
+    """Validate compiled artifacts and initial state without retaining a database."""
+    bundle = Path(bundle)
+    write_bytecode = sys.dont_write_bytecode
+    sys.dont_write_bytecode = True
+    try:
+        load_handlers(bundle, parse_manifest(bundle))
+    finally:
+        sys.dont_write_bytecode = write_bytecode
+    with TemporaryDirectory(prefix="gateway-schema-validation-") as directory:
+        materialize_template(
+            bundle,
+            Path(directory) / "template.sqlite",
+            require_sql=True,
+        )

gatewaysdk/environment/_tar.py

@@ -0,0 +1,33 @@
+"""Guarded tar extraction.
+
+Shared by the benchmark-container ``pull`` path (untrusted-by-provenance), the
+verifiers runner's bundle extraction and the World Host's version cache. Rejects any
+member that would write outside the destination directory — via ``..`` traversal, an absolute path, or a
+sym/hard link — *before* extracting anything, so a malicious or malformed tarball
+cannot escape ``dest_path``.
+"""
+
+from __future__ import annotations
+
+import tarfile
+from pathlib import Path
+
+
+def safe_tar_extract(tar: tarfile.TarFile, dest_path: str | Path) -> None:
+    """Extract ``tar`` into ``dest_path``, refusing any member that escapes it.
+
+    Raises ``ValueError`` on the first unsafe member (absolute path, ``..``
+    component, or a symlink/hardlink). All members are validated up front, so
+    nothing is written when any member is unsafe.
+    """
+    dest = Path(dest_path).resolve()
+    for member in tar.getmembers():
+        if member.issym() or member.islnk():
+            raise ValueError(f"refusing link member in archive: {member.name}")
+        member_path = Path(member.name)
+        if member_path.is_absolute() or ".." in member_path.parts:
+            raise ValueError(f"unsafe path in archive: {member.name}")
+        resolved = (dest / member_path).resolve()
+        if not resolved.is_relative_to(dest):
+            raise ValueError(f"archive member escapes destination: {member.name}")
+    tar.extractall(dest)