gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/api.py

@@ -0,0 +1,1628 @@
+"""The world's API: the vendor's HTTP surface, served from the world itself.
+
+A provider's client speaks the vendor's REST paths, not tool calls. The world
+answers those paths from its store, so the same ``connector.toml`` that
+captured from the real service now describes how the world serves it —
+reads, writes, and whatever logic sits between them:
+
+    [api]
+    envelope = "results"        # rows land under this key with hits and cursor; "" = bare array
+    hits_key = "hits"           # the envelope's count and next-page keys, named the vendor's way
+    cursor_key = "cursor"
+    page = "cursor"             # none | offset | cursor: how list routes paginate
+    limit_param = "limit"       # the query parameters the vendor's client sends for a page
+    offset_param = "offset"
+    cursor_param = "cursor"
+    page_size = 100
+    unauthorized = '{"detail": "Authentication credentials were not provided."}'
+    not_found = '{"detail": "Not found."}'
+    invalid = '{"detail": "Invalid request."}'
+    error_content_type = "application/problem+json"   # what error bodies are labelled; the vendor's choice
+    unauthorized_status = 401   # some vendors answer 403 for a bad key; say what the vendor says
+    not_found_status = 404
+    invalid_status = 400
+    token_path = "/oauth/token" # oauth2 worlds mint bearer tokens here, the way the vendor does
+    handlers = "api/handlers.py"   # the world's own logic (default when the file exists)
+    before = "gate"                # optional: runs before every operation; returns None or an answer
+
+    [[operations]]
+    name = "get_records_by_email"
+    path = "/breach/data/emails/{email}"
+    entity = "spycloud_records"
+    [operations.api]
+    filter = { email = "attributes.email" }   # path argument or query parameter -> row field (dotted),
+                                              # matched case-insensitively; an absent parameter does not filter
+
+    [[operations]]
+    name = "create_search"
+    method = "POST"
+    path = "/searches"
+    entity = "torchlight_searches"
+    [operations.api]
+    action = "create"                # read | create | update | delete | handler
+    status = 201                     # what the vendor answers with
+    single = true                    # the row itself, not a list envelope
+    body = { name = "name", description = "description" }   # row field <- request body path
+    defaults = { status = "drafted" }
+    generate = { id = "uuid", createdAt = "now" }           # uuid | int | now
+
+    [[operations]]
+    name = "execute_search"
+    method = "POST"
+    path = "/searches/{id}/execute"
+    entity = "torchlight_searches"
+    [operations.api]
+    action = "handler"
+    handler = "execute_search"       # def execute_search(ctx, args, query, body) in api/handlers.py
+
+An ``action = "handler"`` operation runs the world's own Python: ``ctx`` reads
+and writes the store (``rows``, ``get``, ``insert``, ``update``, ``delete``),
+tells the time (``now``, ``elapsed``, ``ladder`` for status machines that
+advance on a clock), mints ids (``uuid``) and wraps answers (``envelope``,
+``not_found``). That is where computed results and workflow transitions live,
+in the customer's world, never in this package.
+
+``serve`` runs the world's API locally with the standard library alone.
+``build_api_bundle`` writes the api-kind bundle the platform hosts (``gateway-api-world.toml``,
+``openapi.json``, ``seed/``, ``scenarios/``, ``server/``): the compiled world
+and this package are copied into ``server/`` so the container needs nothing
+installed, and the bundle root stays legacy-shaped because the api runner
+refuses a schema bundle at its root. The runner's admin endpoints
+(``/healthz``, ``/__world/seed``, ``/__world/reset``, ``/__world/state``) are
+served beside the vendor routes.
+"""
+
+from __future__ import annotations
+
+import base64
+import importlib.util
+import json
+import os
+import re
+import secrets
+import shutil
+import sys
+import tempfile
+import threading
+import time
+import tomllib
+import urllib.parse
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Callable
+
+from . import snapshot as snapshots
+from .compiler import check_bundle, compile_bundle
+from .connector import DEFAULT_TOKEN_PATH, SPEC, Operation, Spec, load_spec
+from .store import SQLiteStore
+from .validation import ContractError, fail, read_json
+
+ADMIN = {"seed": "/__world/seed", "reset": "/__world/reset", "state": "/__world/state", "health": "/healthz"}
+PORT = 8080
+FILTER_KEY = "api"
+HANDLERS = "api/handlers.py"
+SCENARIOS = "scenarios"
+BEFORE = "__before__"
+ACTIONS = ("read", "create", "update", "delete", "handler")
+MATCHES = ("equals", "contains", "prefix")
+PAGING = ("none", "offset", "cursor")
+GENERATORS = ("uuid", "int", "now")
+#: Set to an epoch to freeze the world's clock (tests, reproducible workflows).
+CLOCK_ENV = "GATEWAY_WORLD_CLOCK"
+
+
+# ---------------------------------------------------------------- settings
+
+
+@dataclass(frozen=True)
+class Paging:
+    style: str = "none"
+    limit_param: str = "limit"
+    offset_param: str = "offset"
+    cursor_param: str = "cursor"
+    page_size: int = 100
+
+
+@dataclass(frozen=True)
+class OperationSettings:
+    filter: dict[str, str] = field(default_factory=dict)  # arg -> row field path
+    match: dict[str, str] = field(default_factory=dict)  # arg -> equals | contains | prefix
+    action: str = "read"
+    status: int = 200
+    envelope: str | None = None  # None inherits [api].envelope
+    single: bool = False
+    body: dict[str, str] = field(default_factory=dict)  # row field <- body path; empty = the body as-is
+    defaults: dict[str, Any] = field(default_factory=dict)
+    generate: dict[str, str] = field(default_factory=dict)
+    handler: str | None = None
+    paging: str | None = None  # None inherits [api].page
+    sample: dict[str, str] = field(default_factory=dict)  # arg -> a value the route accepts, for conformance runs
+
+
+@dataclass(frozen=True)
+class UiSettings:
+    """``[ui]`` in connector.toml: a prebuilt static single-page app shipped
+    with the world and served by the World Host on the session's ui origin."""
+
+    #: Directory in the world holding ``index.html`` and its assets.
+    static: str
+    #: The page an agent lands on first.
+    entry: str = "/"
+    #: Same-origin prefix the SPA calls the api at; the host rewrites it.
+    api_path: str = "/__world-api"
+
+
+@dataclass(frozen=True)
+class ApiSettings:
+    envelope: str
+    unauthorized: Any
+    not_found: Any
+    filters: dict[str, dict[str, str]]  # operation -> {arg: row field path}; kept for callers that read it
+    unauthorized_status: int = 401
+    not_found_status: int = 404
+    invalid: Any = None
+    invalid_status: int = 400
+    error_content_type: str = "application/json"
+    hits_key: str = "hits"
+    cursor_key: str = "cursor"
+    previous_key: str | None = None  # emit the previous page's cursor under this key (DRF's "previous")
+    page_headers: dict[str, str] = field(default_factory=dict)  # cursor | total | previous -> response header name
+    page_links: bool = False  # next/previous as absolute URLs of the served host, the way DRF answers
+    paging: Paging = field(default_factory=Paging)
+    token_path: str | None = None
+    handlers: Path | None = None
+    before: str | None = None  # a function in the handlers module run before every operation
+    operations: dict[str, OperationSettings] = field(default_factory=dict)
+    ui: UiSettings | None = None
+
+    def for_operation(self, name: str) -> OperationSettings:
+        return self.operations.get(name, OperationSettings())
+
+
+def _json_body(table: dict, key: str, default: Any, location: str) -> Any:
+    text = table.get(key)
+    if text is None:
+        return default
+    if not isinstance(text, str):
+        fail("spec", f"{key} must be a JSON string", f"{location}/{key}")
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        fail("spec", f"{key} is not valid JSON", f"{location}/{key}")
+
+
+def _status(table: dict, key: str, default: int, location: str, *, low: int, high: int) -> int:
+    value = table.get(key, default)
+    if isinstance(value, bool) or not isinstance(value, int) or not low <= value <= high:
+        fail("spec", f"{key} must be an HTTP status between {low} and {high}", f"{location}/{key}")
+    return value
+
+
+def _page_headers(api: dict) -> dict[str, str]:
+    """``page_headers = { cursor = "Cursor", total = "Total-Count" }``: vendors that page by
+    response header (Torchlight) get the same values there as in the envelope."""
+    mapping = api.get("page_headers", {})
+    if not isinstance(mapping, dict) or not all(
+        k in ("cursor", "total", "previous") and isinstance(v, str) and v.strip() for k, v in mapping.items()
+    ):
+        fail("spec", "api.page_headers maps cursor, total and previous to response header names", "/api/page_headers")
+    return dict(mapping)
+
+
+def _flag(table: dict, key: str, location: str) -> bool:
+    value = table.get(key, False)
+    if not isinstance(value, bool):
+        fail("spec", f"{key} must be true or false", f"{location}/{key}")
+    return value
+
+
+def _name(table: dict, key: str, default: str, location: str) -> str:
+    value = table.get(key, default)
+    if not isinstance(value, str) or not value.strip():
+        fail("spec", f"{key} must be a non-empty string", f"{location}/{key}")
+    return value
+
+
+def _str_map(table: dict, key: str, location: str) -> dict[str, str]:
+    mapping = table.get(key, {})
+    if not isinstance(mapping, dict) or not all(
+        isinstance(k, str) and isinstance(v, str) and k for k, v in mapping.items()
+    ):
+        fail("spec", f"{key} maps names to strings", f"{location}/{key}")
+    return dict(mapping)
+
+
+def _operation_settings(entry: dict, operation: Operation, location: str) -> OperationSettings:
+    table = entry.get(FILTER_KEY, {})
+    if not isinstance(table, dict):
+        fail("spec", "[operations.api] must be a table", location)
+    mapping = _str_map(table, "filter", location)
+    for arg in mapping:
+        if arg not in operation.placeholders and arg not in operation.params:
+            fail(
+                "spec",
+                f"api.filter names {arg}, which is neither a path argument nor a parameter",
+                f"{location}/filter",
+            )
+    match = _str_map(table, "match", location)
+    for arg, mode in match.items():
+        if arg not in mapping:
+            fail("spec", f"api.match names {arg}, which api.filter does not declare", f"{location}/match")
+        if mode not in MATCHES:
+            fail("spec", f"api.match.{arg} must be one of {', '.join(MATCHES)}", f"{location}/match")
+    action = _name(table, "action", "read", location)
+    if action not in ACTIONS:
+        fail("spec", f"api.action must be one of {', '.join(ACTIONS)}", f"{location}/action")
+    if action in ("create", "update", "delete") and not operation.entity:
+        fail("spec", f"api.action {action} needs an entity to write", f"{location}/action")
+    if action in ("update", "delete") and not mapping:
+        fail("spec", f"api.action {action} needs a filter to find the row", f"{location}/filter")
+    handler = table.get("handler")
+    if action == "handler":
+        if not isinstance(handler, str) or not re.match(r"^[a-z_][a-z0-9_]*$", handler):
+            fail("spec", "api.handler names a function in the world's handlers module", f"{location}/handler")
+    elif handler is not None:
+        fail("spec", 'api.handler belongs to action = "handler"', f"{location}/handler")
+    default_status = {"create": 201, "delete": 204}.get(action, 200)
+    status = _status(table, "status", default_status, location, low=200, high=299)
+    envelope = table.get("envelope")
+    if envelope is not None and not isinstance(envelope, str):
+        fail("spec", "api.envelope must be a string", f"{location}/envelope")
+    single = table.get("single", action in ("create", "update"))
+    if not isinstance(single, bool):
+        fail("spec", "api.single must be true or false", f"{location}/single")
+    body = _str_map(table, "body", location)
+    defaults = table.get("defaults", {})
+    if not isinstance(defaults, dict):
+        fail("spec", "api.defaults is a table of constant fields", f"{location}/defaults")
+    generate = _str_map(table, "generate", location)
+    for field_name, kind in generate.items():
+        if kind not in GENERATORS:
+            fail("spec", f"api.generate.{field_name} must be one of {', '.join(GENERATORS)}", f"{location}/generate")
+    if (body or defaults or generate) and action not in ("create", "update"):
+        fail("spec", "api.body, defaults and generate belong to create and update actions", location)
+    sample = table.get("sample", {})
+    if not isinstance(sample, dict) or not all(
+        isinstance(k, str) and isinstance(v, (str, int, float)) for k, v in sample.items()
+    ):
+        fail("spec", "api.sample maps path arguments or parameters to a value the route accepts", f"{location}/sample")
+    for arg in sample:
+        if arg not in operation.placeholders and arg not in operation.params:
+            fail(
+                "spec",
+                f"api.sample names {arg}, which is neither a path argument nor a parameter",
+                f"{location}/sample",
+            )
+    paging = table.get("page")
+    if paging is not None and paging not in PAGING:
+        fail("spec", f"api.page must be one of {', '.join(PAGING)}", f"{location}/page")
+    return OperationSettings(
+        filter=mapping,
+        match=match,
+        action=action,
+        status=status,
+        envelope=envelope,
+        single=single,
+        body=body,
+        defaults=dict(defaults),
+        generate=generate,
+        handler=handler if action == "handler" else None,
+        paging=paging,
+        sample={k: str(v) for k, v in sample.items()},
+    )
+
+
+# Directory names every pusher (``bench push`` in Python and TypeScript, the
+# web upload) drops from a bundle at any depth, as build artifacts. A built ui
+# under one of them never reaches the hub, so the manifest refuses it here
+# rather than the host refusing every open of the version.
+ARCHIVE_DROPPED_DIRS = frozenset({"dist", "build", "outputs", "__pycache__"})
+
+
+def _ui_settings(raw: dict, world: Path) -> UiSettings | None:
+    ui = raw.get("ui")
+    if ui is None:
+        return None
+    if not isinstance(ui, dict):
+        fail("spec", "[ui] must be a table", "/ui")
+    static = ui.get("static")
+    if not isinstance(static, str) or not static or static.startswith("/") or ".." in static.split("/"):
+        fail("spec", "ui.static is a directory inside the world holding the built ui", "/ui/static")
+    dropped = [part for part in static.split("/") if part in ARCHIVE_DROPPED_DIRS or part.startswith(".")]
+    if dropped:
+        fail(
+            "spec",
+            f"ui.static = {static!r} is under {dropped[0]!r}, which bench push drops from every bundle "
+            "as a build artifact; build the ui into a directory such as ui/static",
+            "/ui/static",
+        )
+    if not (world / static / "index.html").is_file():
+        fail("spec", f"ui.static = {static!r} has no index.html; build the ui first", "/ui/static")
+    entry = ui.get("entry", "/")
+    if not isinstance(entry, str) or not entry.startswith("/"):
+        fail("spec", "ui.entry is the path the agent lands on, starting with /", "/ui/entry")
+    api_path = ui.get("api_path", "/__world-api")
+    if not isinstance(api_path, str) or not api_path.startswith("/") or api_path == "/":
+        fail("spec", "ui.api_path is the same-origin prefix the ui calls the api at", "/ui/api_path")
+    return UiSettings(static=static.rstrip("/"), entry=entry, api_path=api_path.rstrip("/"))
+
+
+def load_api_settings(world: Path, spec: Spec) -> ApiSettings:
+    raw = tomllib.loads((world / SPEC).read_text(encoding="utf-8"))
+    api = raw.get(FILTER_KEY, {})
+    if not isinstance(api, dict):
+        fail("spec", "[api] must be a table", "/api")
+    envelope = api.get("envelope", "")
+    if not isinstance(envelope, str):
+        fail("spec", "api.envelope must be a string", "/api/envelope")
+    style = _name(api, "page", "none", "/api")
+    if style not in PAGING:
+        fail("spec", f"api.page must be one of {', '.join(PAGING)}", "/api/page")
+    page_size = api.get("page_size", 100)
+    if isinstance(page_size, bool) or not isinstance(page_size, int) or page_size < 1:
+        fail("spec", "api.page_size must be a positive integer", "/api/page_size")
+    paging = Paging(
+        style=style,
+        limit_param=_name(api, "limit_param", "limit", "/api"),
+        offset_param=_name(api, "offset_param", "offset", "/api"),
+        cursor_param=_name(api, "cursor_param", "cursor", "/api"),
+        page_size=page_size,
+    )
+    token_path = api.get("token_path")
+    if token_path is not None and (not isinstance(token_path, str) or not token_path.startswith("/")):
+        fail("spec", "api.token_path is the path the world mints tokens on", "/api/token_path")
+    if token_path is not None and spec.scheme != "oauth2":
+        fail("spec", "api.token_path belongs to auth.scheme oauth2", "/api/token_path")
+    if spec.scheme == "oauth2" and token_path is None:
+        token_path = spec.token_url if (spec.token_url or "").startswith("/") else DEFAULT_TOKEN_PATH
+    handlers_name = api.get("handlers")
+    if handlers_name is not None and not isinstance(handlers_name, str):
+        fail("spec", "api.handlers is the path of the world's handlers module", "/api/handlers")
+    handlers = world / (handlers_name or HANDLERS)
+    if handlers_name is not None and not handlers.is_file():
+        fail("spec", f"api.handlers names {handlers_name}, which is not a file in the world", "/api/handlers")
+    operations: dict[str, OperationSettings] = {}
+    for index, entry in enumerate(raw.get("operations", [])):
+        location = f"/operations/{index}/api"
+        operation = spec.operations[entry["name"]]
+        operations[operation.name] = _operation_settings(entry, operation, location)
+    before = api.get("before")
+    if before is not None and (not isinstance(before, str) or not re.match(r"^[a-z_][a-z0-9_]*$", before)):
+        fail("spec", "api.before names a function in the world's handlers module", "/api/before")
+    needs_handlers = [name for name, op in operations.items() if op.handler] + (
+        [f"[api].before={before}"] if before else []
+    )
+    if needs_handlers and not handlers.is_file():
+        fail(
+            "spec",
+            f"Operations {', '.join(needs_handlers)} name handlers but the world has no {handlers.name}",
+            "/api/handlers",
+        )
+    return ApiSettings(
+        envelope=envelope,
+        unauthorized=_json_body(api, "unauthorized", {"error": "unauthorized"}, "/api"),
+        not_found=_json_body(api, "not_found", {"error": "not_found"}, "/api"),
+        filters={name: dict(op.filter) for name, op in operations.items()},
+        unauthorized_status=_status(api, "unauthorized_status", 401, "/api", low=400, high=599),
+        not_found_status=_status(api, "not_found_status", 404, "/api", low=400, high=599),
+        invalid=_json_body(api, "invalid", {"error": "invalid"}, "/api"),
+        invalid_status=_status(api, "invalid_status", 400, "/api", low=400, high=599),
+        error_content_type=_name(api, "error_content_type", "application/json", "/api"),
+        hits_key=_name(api, "hits_key", "hits", "/api"),
+        cursor_key=_name(api, "cursor_key", "cursor", "/api"),
+        previous_key=_name(api, "previous_key", "", "/api") if api.get("previous_key") is not None else None,
+        page_headers=_page_headers(api),
+        page_links=_flag(api, "page_links", "/api"),
+        paging=paging,
+        token_path=token_path,
+        handlers=handlers if handlers.is_file() else None,
+        before=before,
+        operations=operations,
+        ui=_ui_settings(raw, world),
+    )
+
+
+# ---------------------------------------------------------------- state
+
+
+class WorldState:
+    """The store behind the served API.
+
+    With a compiled snapshot in the tree (``db/state.sqlite`` whose sidecar names
+    this contract) a reset is a file copy and an open; without one the world's
+    initial batch is replayed, as it always was. ``snapshot`` is the sidecar of the
+    snapshot in use, or None on the legacy path."""
+
+    def __init__(self, world: Path):
+        self.world = world
+        self.contract = check_bundle(world)
+        self._initial: dict | None = None
+        self._snapshot_path = snapshots.default_snapshot(world)
+        # Only a snapshot that IS the tree's data through this contract (or the
+        # platform's pin) is opened; one left behind by an earlier compile while the
+        # journals grew is stale, and the journals are replayed instead.
+        self.snapshot: dict | None = snapshots.current_default(world, self.contract)
+        self._dir = tempfile.TemporaryDirectory(prefix="gateway-world-api-")
+        self._lock = threading.Lock()
+        self.store: SQLiteStore | None = None
+        self.reset()
+
+    @property
+    def digest(self) -> str | None:
+        """The batch digest of the snapshot the world is on; None on the legacy path."""
+        return self.snapshot["batchDigest"] if self.snapshot else None
+
+    @property
+    def initial(self) -> dict:
+        """The world's initial batch, read when the legacy path needs it: a snapshot
+        start never parses the JSON at all."""
+        if self._initial is None:
+            self._initial = read_json(self.world / "data/initial.json")
+        return self._initial
+
+    def reset(self, *, initial: bool = True) -> None:
+        """A fresh store: the snapshot copied (or the world's initial batch applied),
+        or empty when a legacy seed is about to supply the whole state (the runner's
+        base + overlay seed carries the initial rows itself; applying both would
+        collide on every key)."""
+        with self._lock:
+            self._open(self._snapshot_path if initial and self.snapshot else None, initial=initial)
+
+    def _open(self, snapshot: Path | None, *, initial: bool = True) -> None:
+        if self.store is not None:
+            self.store.close()
+        database = Path(self._dir.name) / f"{uuid.uuid4().hex}.db"
+        if snapshot is not None:
+            self.store = snapshots.open_copy(snapshot, self.contract, database)
+            return
+        self.store = SQLiteStore.create(database, self.contract)
+        if initial:
+            self.store.apply_batch(self.initial)
+
+    def seed(self, body: Any) -> dict:
+        """The runner's seed. Two bodies: the legacy whole state ``{entity: [rows]}``
+        (inserted on top of an empty world) and the overlay ``{"base": digest, "rows":
+        {entity: [rows]}, "mode": append|replace}`` (the snapshot reset, then the rows
+        applied on top). An overlay whose base is not the snapshot this world is on is
+        refused with ``base_mismatch`` naming the expected digest: a version mismatch
+        is an error, never a silent full reseed."""
+        if not isinstance(body, dict):
+            fail("seed", "Seed must be an object of entity -> rows", "/seed")
+        if isinstance(body.get("base"), str) and isinstance(body.get("rows"), dict):
+            return self._seed_overlay(body)
+        mutations = []
+        for entity, rows in body.items():
+            if entity not in self.contract.entities:
+                fail("seed", f"Unknown entity {entity}", f"/seed/{entity}")
+            if not isinstance(rows, list):
+                fail("seed", "Rows must be an array", f"/seed/{entity}")
+            for row in rows:
+                mutations.append(
+                    {"op": "insert", "entity": entity, "value": row, "source": {"record": f"api-seed:{entity}"}}
+                )
+        self.reset(initial=False)
+        if not mutations:
+            return {"applied": 0}
+        with self._lock:
+            assert self.store is not None
+            return self.store.apply_batch(
+                {
+                    "id": f"api-seed-{uuid.uuid4().hex}",
+                    "target": self.contract.target,
+                    "mapping": {"id": "api-seed", "version": "1"},
+                    "coverage": "partial",
+                    "mutations": mutations,
+                }
+            )
+
+    def _seed_overlay(self, body: dict) -> dict:
+        from .data import MODES
+
+        mode = body.get("mode", "append")
+        if mode not in MODES:
+            fail("seed", f"mode must be one of {', '.join(MODES)}", "/seed/mode")
+        if body["base"] != self.digest:
+            fail("base_mismatch", "The overlay's base is not the snapshot this world is on", expected=self.digest)
+        self.reset()
+        return self.seed_live(body["rows"], mode)
+
+    def seed_live(self, rows: dict, mode: str = "append") -> dict:
+        """Rows onto the world as it stands, no reset: ``append`` upserts by primary
+        key, ``replace`` swaps the named entities. The session's seed, so tool calls
+        made so far and the scenario's own rows stay."""
+        from .data import MODES, seed_batch
+
+        if mode not in MODES:
+            fail("seed", f"mode must be one of {', '.join(MODES)}", "/seed/mode")
+        with self._lock:
+            assert self.store is not None
+            batch = seed_batch(self.store, self.contract, rows, mode, batch_id=f"api-seed-{uuid.uuid4().hex}")
+            return self.store.apply_batch(batch)
+
+    def scenarios(self) -> dict[str, Path]:
+        """The world's own ``scenarios/<name>/scenario.toml`` dirs: a starting state each."""
+        return _scenario_dirs(self.world)
+
+    def apply_scenario(self, name: str) -> None:
+        """Start the world in one of its scenarios: the base seed with the scenario's
+        ``seed/*.json`` overlays replacing whole entities, the way the platform's runner
+        does. A compiled scenario snapshot is opened as it is; otherwise the overlay is
+        applied on a fresh default."""
+        scenarios = self.scenarios()
+        if name not in scenarios:
+            fail(
+                "scenario",
+                f"No scenario {name}; the world has {', '.join(scenarios) or 'none'}",
+                f"/{SCENARIOS}/{name}",
+            )
+        built = snapshots.scenario_snapshot(self.world, name)
+        if self.snapshot and snapshots.current(
+            built,
+            snapshots.contract_hash(self.contract),
+            snapshots.scenario_batch_digest(scenarios[name], snapshots.expected_default_digest(self.world)),
+        ):
+            with self._lock:
+                self._open(built)
+            return
+        overlay = snapshots.scenario_overlay(scenarios[name])
+        if self.snapshot:
+            self.seed({"base": self.digest, "rows": overlay, "mode": "replace"})
+            return
+        base: dict[str, list] = {}
+        for mutation in self.initial.get("mutations", []):
+            if mutation.get("op") == "insert":
+                base.setdefault(mutation["entity"], []).append(mutation["value"])
+        base.update(overlay)
+        self.seed(base)
+
+    def rows(self, entity: str) -> list[dict]:
+        with self._lock:
+            assert self.store is not None
+            return list(self.store.list(entity))
+
+    def get(self, entity: str, key: dict) -> dict | None:
+        with self._lock:
+            assert self.store is not None
+            return self.store.get(entity, key)
+
+    def insert(self, entity: str, value: dict) -> dict:
+        """Persist a row the API created; the contract validates it like any ingest."""
+        with self._lock:
+            assert self.store is not None
+            return self.store.insert(entity, value, source={"record": "api.create"})
+
+    def update(self, entity: str, key: dict, patch: dict) -> dict:
+        with self._lock:
+            assert self.store is not None
+            return self.store.update(entity, key, patch, source={"record": "api.update"})
+
+    def delete(self, entity: str, key: dict) -> None:
+        with self._lock:
+            assert self.store is not None
+            self.store.delete(entity, key, source={"record": "api.delete"})
+
+    def key_of(self, entity: str, row: dict) -> dict:
+        return {name: row.get(name) for name in self.contract.entities[entity]["primary_key"]}
+
+    def dump(self) -> dict:
+        out: dict[str, dict[str, dict]] = {}
+        for entity, spec in self.contract.entities.items():
+            keyed = {}
+            for row in self.rows(entity):
+                key = ":".join(str(row.get(field)) for field in spec["primary_key"])
+                keyed[key] = row
+            out[entity] = keyed
+        return out
+
+    def describe_snapshot(self) -> dict | None:
+        """What ``/__world/state`` reports beside the rows: the snapshot in use, or null."""
+        if not self.snapshot:
+            return None
+        return {"batchDigest": self.snapshot["batchDigest"], "contractHash": self.snapshot["contractHash"]}
+
+    def close(self) -> None:
+        with self._lock:
+            if self.store is not None:
+                self.store.close()
+                self.store = None
+        self._dir.cleanup()
+
+
+# ---------------------------------------------------------------- routing
+
+
+def _dig(row: Any, path: str) -> Any:
+    for part in path.split("."):
+        if not isinstance(row, dict) or part not in row:
+            return None
+        row = row[part]
+    return row
+
+
+def _matches(row: dict, filters: dict[str, str], values: dict[str, str], modes: dict[str, str] | None = None) -> bool:
+    """Every filter whose argument was supplied must match; a parameter left out does not narrow.
+
+    ``modes`` picks how: ``equals`` (default), ``contains`` (case-insensitive substring,
+    the vendor's ``icontains``) or ``prefix``. A list field matches when any element does."""
+    for arg, path in filters.items():
+        if arg not in values:
+            continue
+        value = _dig(row, path)
+        if value is None:
+            return False
+        mode = (modes or {}).get(arg, "equals")
+        wanted = values[arg].lower()
+        candidates = value if isinstance(value, list) else [value]
+        if not any(_compare(str(candidate).lower(), wanted, mode) for candidate in candidates):
+            return False
+    return True
+
+
+def _compare(have: str, wanted: str, mode: str) -> bool:
+    if mode == "contains":
+        return wanted in have
+    if mode == "prefix":
+        return have.startswith(wanted)
+    return have == wanted
+
+
+class Router:
+    def __init__(self, spec: Spec, settings: ApiSettings):
+        self.spec = spec
+        self.settings = settings
+        self.routes = [(operation, self._pattern(operation)) for operation in spec.operations.values()]
+        self.tokens: set[str] = set()
+        #: refresh token -> the subject it was minted for (password / refresh grants)
+        self._refresh_tokens: dict[str, str] = {}
+        self._jwt_secret = secrets.token_bytes(32)
+        self._lock = threading.Lock()
+
+    @staticmethod
+    def _pattern(operation: Operation) -> re.Pattern:
+        escaped = re.escape(operation.path)
+        pattern = re.sub(r"\\\{([A-Za-z_][A-Za-z0-9_]*)\\\}", r"(?P<\1>[^/]+)", escaped)
+        return re.compile(f"^{pattern}$")
+
+    def match(self, method: str, path: str, query: dict[str, str]) -> tuple[Operation, dict[str, str]] | None:
+        """The operation for a request. Vendors reuse one path for several lookups that
+        differ only by query parameter, so among path matches the one whose declared
+        parameters the caller actually sent wins; ties keep declaration order."""
+        best: tuple[int, int, Operation, dict[str, str]] | None = None
+        for index, (operation, pattern) in enumerate(self.routes):
+            found = pattern.match(path)
+            if not found or operation.method != method:
+                continue
+            present = sum(1 for name in operation.params if name in query)
+            candidate = (present, -index, operation, {k: urllib.parse.unquote(v) for k, v in found.groupdict().items()})
+            if best is None or candidate[:2] > best[:2]:
+                best = candidate
+        return None if best is None else (best[2], best[3])
+
+    def issue_token(self, form: dict[str, str], key: str | None) -> dict | None:
+        """The vendor's token endpoint. Three grants, the way real vendors mint:
+
+        * ``client_credentials`` (the default): a bearer ``access_token``.
+        * ``password``: ``email`` + ``password`` in, an ``id_token`` (an HS256 JWT
+          carrying ``sub``/``iat``/``exp``, so a client that reads expiry from the
+          token itself sees a real one) plus a ``refresh_token``. This is how
+          Torchlight's clients authenticate.
+        * ``refresh_token``: a refresh token this world minted in, a fresh
+          ``id_token`` + ``refresh_token`` out; an unknown refresh token is refused.
+
+        With ``WORLD_API_KEY`` pinned the client secret (or the password) must be that
+        key, the way a real vendor knows its clients; unpinned, any grant is served.
+        Every bearer this world minted — access or id token — authorizes calls."""
+        grant = form.get("grant_type", "client_credentials")
+        if grant == "client_credentials":
+            if key is not None and form.get("client_secret") != key:
+                return None
+            token = secrets.token_urlsafe(32)
+            with self._lock:
+                self.tokens.add(token)
+            answer = {"access_token": token, "token_type": "Bearer", "expires_in": 3600}
+            if form.get("scope"):
+                answer["scope"] = form["scope"]
+            elif self.spec.scope:
+                answer["scope"] = self.spec.scope
+            return answer
+        if grant == "password":
+            subject = form.get("email") or form.get("username") or ""
+            if not subject or not form.get("password"):
+                return None
+            if key is not None and form.get("password") != key:
+                return None
+            return self._issue_identity(subject)
+        if grant == "refresh_token":
+            presented = form.get("refresh_token") or ""
+            with self._lock:
+                subject = self._refresh_tokens.pop(presented, None)
+            if subject is None:
+                return None
+            return self._issue_identity(subject)
+        return None
+
+    def _issue_identity(self, subject: str) -> dict:
+        """An ``id_token`` (HS256 JWT, one hour) and a ``refresh_token``, both
+        remembered so later calls and refreshes are honoured."""
+        import hmac
+        import hashlib
+
+        now = int(time.time())
+        header = base64.urlsafe_b64encode(b'{"alg":"HS256","typ":"JWT"}').rstrip(b"=").decode()
+        payload = base64.urlsafe_b64encode(
+            json.dumps(
+                {"sub": subject, "iat": now, "exp": now + 3600, "iss": self.spec.slug, "jti": secrets.token_urlsafe(9)},
+                separators=(",", ":"),
+            ).encode()
+        ).rstrip(b"=").decode()
+        signature = base64.urlsafe_b64encode(
+            hmac.new(self._jwt_secret, f"{header}.{payload}".encode(), hashlib.sha256).digest()
+        ).rstrip(b"=").decode()
+        id_token = f"{header}.{payload}.{signature}"
+        refresh = secrets.token_urlsafe(32)
+        with self._lock:
+            self.tokens.add(id_token)
+            self._refresh_tokens[refresh] = subject
+        return {
+            "id_token": id_token,
+            "access_token": id_token,
+            "refresh_token": refresh,
+            "token_type": "Bearer",
+            "expires_in": 3600,
+        }
+
+    def authorized(self, headers: dict[str, str], query: dict[str, str], key: str | None) -> bool:
+        spec = self.spec
+        if spec.scheme == "none":
+            return True
+        presented: str | None = None
+        if spec.scheme == "header":
+            presented = headers.get((spec.auth_name or "").lower())
+        elif spec.scheme in ("bearer", "oauth2"):
+            value = headers.get("authorization", "")
+            presented = value[7:] if value.lower().startswith("bearer ") else None
+        elif spec.scheme == "basic":
+            value = headers.get("authorization", "")
+            try:
+                presented = base64.b64decode(value[6:]).decode() if value.lower().startswith("basic ") else None
+            except (ValueError, UnicodeDecodeError):
+                presented = None
+        elif spec.scheme == "query":
+            presented = query.get(spec.auth_name or "")
+        if not presented:
+            return False
+        if spec.scheme == "oauth2":
+            # A bearer is good only if this world minted it: the client did the grant first.
+            with self._lock:
+                return presented in self.tokens
+        return key is None or presented == key
+
+
+# ---------------------------------------------------------------- handlers
+
+
+class ApiContext:
+    """What a world's handler gets: the store, the clock, and the vendor's shapes."""
+
+    def __init__(
+        self, state: WorldState, router: Router, operation: Operation, link: tuple[str, dict[str, str]] | None = None
+    ):
+        self.state = state
+        self.router = router
+        self.settings = router.settings
+        self.operation = operation
+        self.spec = router.spec
+        #: (absolute URL without query, query) of the request being answered, for page links.
+        self.link = link
+        #: The request's headers, lower-cased — a gate reads the credential from here.
+        self.headers: dict[str, str] = {}
+
+    # -- the store
+    def rows(self, entity: str) -> list[dict]:
+        return self.state.rows(entity)
+
+    def get(self, entity: str, key: dict) -> dict | None:
+        return self.state.get(entity, key)
+
+    def find(self, entity: str, **fields: Any) -> list[dict]:
+        wanted = {k: str(v) for k, v in fields.items()}
+        return [row for row in self.state.rows(entity) if _matches(row, {k: k for k in wanted}, wanted)]
+
+    def insert(self, entity: str, value: dict) -> dict:
+        return self.state.insert(entity, value)
+
+    def update(self, entity: str, key: dict, patch: dict) -> dict:
+        return self.state.update(entity, key, patch)
+
+    def delete(self, entity: str, key: dict) -> None:
+        self.state.delete(entity, key)
+
+    def key_of(self, entity: str, row: dict) -> dict:
+        return self.state.key_of(entity, row)
+
+    # -- time and identity
+    @staticmethod
+    def clock() -> float:
+        frozen = os.environ.get(CLOCK_ENV)
+        return float(frozen) if frozen else time.time()
+
+    def now(self) -> str:
+        return datetime.fromtimestamp(self.clock(), timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+    def elapsed(self, since: str | None) -> float:
+        """Seconds since an ISO timestamp the world recorded; infinite when it never happened."""
+        if not since:
+            return float("inf")
+        started = datetime.fromisoformat(since.replace("Z", "+00:00"))
+        return self.clock() - started.timestamp()
+
+    def ladder(self, since: str | None, steps: list[tuple[float, Any]], before: Any = None) -> Any:
+        """A status machine on a clock: the last step whose delay has passed.
+
+        ``ladder(executed_at, [(0, "queued"), (5, "started"), (20, "completed")])``
+        reads ``queued`` right after execute, ``started`` five seconds later, and
+        ``completed`` from twenty seconds on. ``before`` is the answer when nothing
+        has started yet."""
+        if not since:
+            return before
+        passed = self.elapsed(since)
+        current = before
+        for delay, value in steps:
+            if passed >= delay:
+                current = value
+        return current
+
+    @staticmethod
+    def uuid() -> str:
+        return str(uuid.uuid4())
+
+    # -- the vendor's shapes
+    def envelope(self, rows: list[dict], query: dict[str, str] | None = None, *, envelope: str | None = None) -> Any:
+        page = paginate(rows, query or {}, self.settings.paging)
+        return wrap(page, self.settings, envelope, link=self.link)
+
+    def paged(
+        self, rows: list[dict], query: dict[str, str] | None = None, *, envelope: str | None = None, status: int = 200
+    ) -> Any:
+        """``envelope`` plus the vendor's paging headers, as a handler's full answer."""
+        page = paginate(rows, query or {}, self.settings.paging)
+        return status, wrap(page, self.settings, envelope, link=self.link), page_headers(page, self.settings)
+
+    def not_found(self) -> tuple[int, Any]:
+        return self.settings.not_found_status, self.settings.not_found
+
+    def invalid(self, detail: str | None = None) -> tuple[int, Any]:
+        body = self.settings.invalid
+        if detail and isinstance(body, dict):
+            body = {**body, "detail": detail}
+        return self.settings.invalid_status, body
+
+
+Handler = Callable[[ApiContext, dict[str, str], dict[str, str], Any], Any]
+
+
+def load_handlers(settings: ApiSettings) -> dict[str, Handler]:
+    """Import the world's handlers module once; every ``action = "handler"`` name must exist."""
+    if settings.handlers is None:
+        return {}
+    module_name = f"gateway_world_api_handlers_{uuid.uuid4().hex}"
+    spec = importlib.util.spec_from_file_location(module_name, settings.handlers)
+    if spec is None or spec.loader is None:
+        fail("handlers", f"Could not load {settings.handlers}", "/api/handlers")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    try:
+        spec.loader.exec_module(module)
+    finally:
+        sys.modules.pop(module_name, None)
+    handlers: dict[str, Handler] = {}
+    if settings.before:
+        gate = getattr(module, settings.before, None)
+        if not callable(gate):
+            fail(
+                "handlers",
+                f"{settings.handlers.name} has no function {settings.before} for [api].before",
+                "/api/before",
+            )
+        handlers[BEFORE] = gate
+    for name, op in settings.operations.items():
+        if not op.handler:
+            continue
+        function = getattr(module, op.handler, None)
+        if not callable(function):
+            fail(
+                "handlers",
+                f"{settings.handlers.name} has no function {op.handler} for operation {name}",
+                "/api/handlers",
+            )
+        handlers[name] = function
+    return handlers
+
+
+# ---------------------------------------------------------------- pages and envelopes
+
+
+@dataclass(frozen=True)
+class Page:
+    rows: list[dict]
+    total: int
+    offset: int
+    limit: int
+    style: str
+
+    @property
+    def next_offset(self) -> int | None:
+        following = self.offset + self.limit
+        return following if self.style != "none" and following < self.total else None
+
+    @property
+    def previous_offset(self) -> int | None:
+        return max(self.offset - self.limit, 0) if self.style != "none" and self.offset > 0 else None
+
+
+def _encode_cursor(offset: int) -> str:
+    return base64.urlsafe_b64encode(str(offset).encode()).decode().rstrip("=")
+
+
+def paginate(rows: list[dict], query: dict[str, str], paging: Paging) -> Page:
+    """One page of rows with the offsets the next and previous pages start at."""
+    total = len(rows)
+    if paging.style == "none":
+        return Page(rows, total, 0, total, "none")
+    limit = _int_param(query.get(paging.limit_param), paging.page_size)
+    offset = 0
+    if paging.style == "offset":
+        offset = _int_param(query.get(paging.offset_param), 0)
+    else:
+        raw = query.get(paging.cursor_param)
+        if raw:
+            try:
+                offset = int(base64.urlsafe_b64decode(raw + "=" * (-len(raw) % 4)).decode())
+            except (ValueError, UnicodeDecodeError):
+                offset = 0
+    return Page(rows[offset : offset + limit], total, offset, limit, paging.style)
+
+
+def _int_param(value: str | None, default: int) -> int:
+    try:
+        parsed = int(value) if value is not None else default
+    except ValueError:
+        return default
+    return parsed if parsed >= 0 else default
+
+
+def _page_ref(page: Page, offset: int | None, paging: Paging, link: tuple[str, dict[str, str]] | None) -> Any:
+    """What the vendor's client is handed for a neighbouring page: '' or None when there is
+    none, a cursor token, or — with ``page_links`` — the absolute URL DRF-style vendors answer."""
+    if offset is None:
+        return None if link is not None else ""
+    if link is None:
+        return _encode_cursor(offset)
+    base, query = link
+    following = dict(query)
+    if page.style == "offset":
+        following[paging.offset_param] = str(offset)
+    else:
+        following[paging.cursor_param] = _encode_cursor(offset)
+    following[paging.limit_param] = str(page.limit)
+    return f"{base}?{urllib.parse.urlencode(following)}"
+
+
+def page_headers(page: Page, settings: ApiSettings, paging: Paging | None = None) -> dict[str, str] | None:
+    """The page's cursor/total/previous as response headers, when the vendor sends them that way."""
+    if not settings.page_headers:
+        return None
+    paging = paging or settings.paging
+    values = {
+        "cursor": _page_ref(page, page.next_offset, paging, None),
+        "total": str(page.total),
+        "previous": _page_ref(page, page.previous_offset, paging, None),
+    }
+    return {header: str(values[key]) for key, header in settings.page_headers.items() if values[key] not in ("", None)}
+
+
+def wrap(
+    page: Page | list[dict],
+    settings: ApiSettings,
+    envelope: str | None = None,
+    *,
+    paging: Paging | None = None,
+    link: tuple[str, dict[str, str]] | None = None,
+) -> Any:
+    """Rows in the vendor's envelope: ``{<envelope>: rows, <hits_key>: total, <cursor_key>: next
+    [, <previous_key>: previous]}``; an empty envelope key means the bare array."""
+    if not isinstance(page, Page):
+        page = Page(page, len(page), 0, len(page), "none")
+    key = settings.envelope if envelope is None else envelope
+    if not key:
+        return page.rows
+    paging = paging or settings.paging
+    link = link if settings.page_links else None
+    out = {
+        key: page.rows,
+        settings.hits_key: page.total,
+        settings.cursor_key: _page_ref(page, page.next_offset, paging, link),
+    }
+    if settings.previous_key:
+        out[settings.previous_key] = _page_ref(page, page.previous_offset, paging, link)
+    return out
+
+
+def _normalize(result: Any, default_status: int | None) -> Any:
+    """What a handler (or the gate) hands back, as ``(status, body, headers)``.
+
+    A handler returns a body, ``(status, body)`` or ``(status, body, headers)``;
+    the gate returns ``None`` to let the request through or one of those to stop it."""
+    if result is None and default_status is None:
+        return None
+    if (
+        isinstance(result, tuple)
+        and len(result) in (2, 3)
+        and isinstance(result[0], int)
+        and not isinstance(result[0], bool)
+    ):
+        status, body = result[0], result[1]
+        extra = result[2] if len(result) == 3 else None
+        if extra is not None and not (
+            isinstance(extra, dict) and all(isinstance(k, str) and isinstance(v, str) for k, v in extra.items())
+        ):
+            fail("handlers", "A handler's headers are a mapping of header names to strings", "/api/handlers")
+        return status, body, extra
+    return default_status, result, None
+
+
+# ---------------------------------------------------------------- writes
+
+
+def _set(row: dict, target: str, value: Any, current: dict | None) -> None:
+    """Assign a dotted target (``attributes.note``), keeping the rest of a nested
+    object an update leaves alone."""
+    parts = target.split(".")
+    if len(parts) == 1:
+        row[target] = value
+        return
+    head = parts[0]
+    if head not in row:
+        base = current.get(head) if current else None
+        row[head] = json.loads(json.dumps(base)) if isinstance(base, dict) else {}
+    node = row[head]
+    for part in parts[1:-1]:
+        if not isinstance(node.get(part), dict):
+            node[part] = {}
+        node = node[part]
+    node[parts[-1]] = value
+
+
+def _bind(op: OperationSettings, ctx: ApiContext, body: Any, current: dict | None = None) -> dict:
+    """The row a create or update writes: defaults, then the body (mapped or as-is), then generated fields."""
+    if body is None or not isinstance(body, dict):
+        body = {}
+    row: dict = json.loads(json.dumps(op.defaults)) if current is None else {}
+    if op.body:
+        for field_name, path in op.body.items():
+            value = _dig(body, path)
+            if value is not None:
+                _set(row, field_name, value, current)
+    else:
+        row.update(body)
+    if current is None:
+        for field_name, kind in op.generate.items():
+            if row.get(field_name) is not None:
+                continue
+            if kind == "uuid":
+                row[field_name] = ctx.uuid()
+            elif kind == "now":
+                row[field_name] = ctx.now()
+            else:
+                existing = [r.get(field_name) for r in ctx.rows(ctx.operation.entity or "")]
+                row[field_name] = max([v for v in existing if isinstance(v, int)] + [0]) + 1
+    return row
+
+
+# ---------------------------------------------------------------- the server
+
+
+Response = tuple[int, Any, dict[str, str] | None]
+
+
+class WorldApp:
+    """One world's HTTP behaviour as a function of the request.
+
+    ``handle`` takes what a server read off the wire (method, request target,
+    headers, raw body) and answers ``(status, body, extra headers)``; nothing in
+    it touches a socket. ``make_handler`` wraps it for ``serve()``, and the
+    World Host calls it for whichever session a request names, so one process
+    can answer for many worlds without the handler knowing.
+    """
+
+    def __init__(
+        self,
+        state: WorldState,
+        router: Router,
+        key: str | None,
+        handlers: dict[str, Handler] | None = None,
+        allowed: frozenset[str] | None = None,
+    ):
+        self.state = state
+        self.router = router
+        self.key = key
+        self.settings = router.settings
+        self.prefix = urllib.parse.urlsplit(router.spec.base_url).path.rstrip("/")
+        self.handlers = load_handlers(self.settings) if handlers is None else handlers
+        #: The operations this session's task allows, or None for all of them.
+        #: A route outside the list answers 403 before any handler runs, so the
+        #: list holds against a client that talks to the vendor API directly.
+        self.allowed = allowed
+
+    # ------------------------------------------------------------ helpers
+
+    @staticmethod
+    def _json(raw: bytes) -> Any:
+        if not raw:
+            return {}
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return None
+
+    @staticmethod
+    def _form(raw: bytes, headers: dict[str, str]) -> dict[str, str]:
+        content_type = (headers.get("content-type") or "").split(";")[0].strip().lower()
+        if content_type == "application/json":
+            try:
+                parsed = json.loads(raw.decode("utf-8"))
+            except (UnicodeDecodeError, json.JSONDecodeError):
+                return {}
+            return {k: str(v) for k, v in parsed.items()} if isinstance(parsed, dict) else {}
+        form = {k: v[0] for k, v in urllib.parse.parse_qs(raw.decode("utf-8", "replace")).items()}
+        basic = headers.get("authorization", "")
+        if basic.lower().startswith("basic "):
+            try:
+                client_id, _, client_secret = base64.b64decode(basic[6:]).decode().partition(":")
+                form.setdefault("client_id", client_id)
+                form.setdefault("client_secret", client_secret)
+            except (ValueError, UnicodeDecodeError):
+                pass
+        return form
+
+    def _strip(self, path: str) -> str:
+        if self.prefix and path.startswith(self.prefix):
+            return path[len(self.prefix) :] or "/"
+        return path
+
+    # ------------------------------------------------------------ the request
+
+    def handle(self, method: str, target: str, headers: dict[str, str], raw: bytes, default_host: str) -> Response:
+        """Answer one request. ``headers`` are lower-cased; ``default_host`` is what
+        a link uses when the request carries no Host header."""
+        url = urllib.parse.urlsplit(target)
+        settings, router, state = self.settings, self.router, self.state
+        if method == "GET":
+            if url.path == ADMIN["health"]:
+                return 200, {"ok": True, "world": router.spec.slug}, None
+            if url.path == ADMIN["state"]:
+                return 200, {**state.dump(), "snapshot": state.describe_snapshot()}, None
+        if method == "POST":
+            if url.path == ADMIN["reset"]:
+                state.reset()
+                return 200, {"ok": True}, None
+            if url.path == ADMIN["seed"]:
+                body = self._json(raw)
+                if body is None:
+                    return 400, {"error": "seed must be JSON"}, None
+                try:
+                    state.seed(body)
+                except ContractError as error:
+                    if error.detail.get("code") == "base_mismatch":
+                        return 409, {"error": "base_mismatch", "expected": error.detail.get("expected")}, None
+                    return 400, {"error": "seed_rejected", "detail": str(error)}, None
+                except Exception as error:  # a rejected seed is the caller's problem, reported plainly
+                    return 400, {"error": "seed_rejected", "detail": str(error)}, None
+                return 200, {"ok": True}, None
+            if settings.token_path and self._strip(url.path) == settings.token_path:
+                issued = router.issue_token(self._form(raw, headers), self.key)
+                if issued is None:
+                    return 400, {"error": "invalid_client"}, None
+                return 200, issued, None
+        if method not in ("GET", "POST", "PUT", "PATCH", "DELETE"):
+            return 405, {"error": "method_not_allowed"}, None
+        return self._route(method, url, headers, raw, default_host)
+
+    def _route(self, method: str, url, headers: dict[str, str], raw: bytes, default_host: str) -> Response:
+        settings, router, state, handlers = self.settings, self.router, self.state, self.handlers
+        path = self._strip(url.path)
+        query = {k: v[0] for k, v in urllib.parse.parse_qs(url.query).items()}
+        if not router.authorized(headers, query, self.key):
+            return settings.unauthorized_status, settings.unauthorized, None
+        matched = router.match(method, path, query)
+        if matched is None:
+            return settings.not_found_status, settings.not_found, None
+        operation, args = matched
+        if self.allowed is not None and operation.name not in self.allowed:
+            return 403, {"error": "tool_not_allowed", "tool": operation.name}, None
+        op = settings.for_operation(operation.name)
+        body = self._json(raw) if method in ("POST", "PUT", "PATCH") else {}
+        if body is None:
+            return settings.invalid_status, settings.invalid, None
+        host = headers.get("host") or default_host
+        forwarded = (headers.get("x-forwarded-proto") or "http").split(",")[0].strip()
+        ctx = ApiContext(state, router, operation, link=(f"{forwarded}://{host}{url.path}", query))
+        ctx.headers = headers
+        try:
+            if BEFORE in handlers:
+                # The world's gate: quotas, allow-lists, key states — whatever the vendor
+                # checks before any route, declarative ones included.
+                verdict = _normalize(handlers[BEFORE](ctx, args, query, body), None)
+                if verdict is not None:
+                    return verdict
+            status, answer, extra = _normalize(self._answer(op, operation, ctx, args, query, body, handlers), op.status)
+        except ContractError as error:
+            detail = getattr(error, "detail", None) or {"message": str(error)}
+            invalid = settings.invalid
+            if isinstance(invalid, dict):
+                invalid = {**invalid, "detail": detail}
+            return settings.invalid_status, invalid, None
+        return status, answer, extra
+
+    @staticmethod
+    def _answer(
+        op: OperationSettings,
+        operation: Operation,
+        ctx: ApiContext,
+        args: dict[str, str],
+        query: dict[str, str],
+        body: Any,
+        handlers: dict[str, Handler],
+    ) -> Any:
+        if op.action == "handler":
+            return handlers[operation.name](ctx, args, query, body)
+        if not operation.entity:
+            return 501, {"error": "not_modelled", "operation": operation.name}
+        entity = operation.entity
+        values = {**{k: v for k, v in query.items() if k in operation.params}, **args}
+        if op.action == "create":
+            row = ctx.insert(entity, _bind(op, ctx, body))
+            return op.status, row if op.single else wrap([row], ctx.settings, op.envelope)
+        rows = [row for row in ctx.rows(entity) if _matches(row, op.filter, values, op.match)]
+        if op.action in ("update", "delete"):
+            if len(rows) != 1:
+                return ctx.not_found()
+            key = ctx.key_of(entity, rows[0])
+            if op.action == "delete":
+                ctx.delete(entity, key)
+                return op.status, None
+            row = ctx.update(entity, key, _bind(op, ctx, body, current=rows[0]))
+            return op.status, row if op.single else wrap([row], ctx.settings, op.envelope)
+        if op.single:
+            if not rows:
+                return ctx.not_found()
+            return op.status, rows[0]
+        paging = (
+            ctx.settings.paging
+            if op.paging is None
+            else Paging(
+                op.paging,
+                ctx.settings.paging.limit_param,
+                ctx.settings.paging.offset_param,
+                ctx.settings.paging.cursor_param,
+                ctx.settings.paging.page_size,
+            )
+        )
+        page = paginate(rows, query, paging)
+        return (
+            op.status,
+            wrap(page, ctx.settings, op.envelope, paging=paging, link=ctx.link),
+            page_headers(page, ctx.settings, paging),
+        )
+
+
+def send_response(
+    handler: BaseHTTPRequestHandler, status: int, body: Any, extra: dict[str, str] | None, error_content_type: str
+) -> None:
+    """Write one ``WorldApp`` answer to a request handler's socket."""
+    if status == 204 or body is None:
+        handler.send_response(status)
+        for name, value in (extra or {}).items():
+            handler.send_header(name, value)
+        handler.send_header("Content-Length", "0")
+        handler.end_headers()
+        return
+    payload = json.dumps(body, ensure_ascii=False).encode("utf-8")
+    handler.send_response(status)
+    handler.send_header("Content-Type", error_content_type if status >= 400 else "application/json")
+    for name, value in (extra or {}).items():
+        handler.send_header(name, value)
+    handler.send_header("Content-Length", str(len(payload)))
+    handler.end_headers()
+    handler.wfile.write(payload)
+
+
+def make_handler(state: WorldState, router: Router, key: str | None):
+    app = WorldApp(state, router, key)
+
+    class Handler(BaseHTTPRequestHandler):
+        server_version = f"gateway-world-api/{router.spec.slug}"
+
+        def log_message(self, *_):
+            pass
+
+        def _serve(self, method: str) -> None:
+            length = int(self.headers.get("Content-Length") or 0)
+            raw = self.rfile.read(length) if length else b""
+            headers = {k.lower(): v for k, v in self.headers.items()}
+            status, body, extra = app.handle(method, self.path, headers, raw, f"127.0.0.1:{self.server.server_port}")
+            send_response(self, status, body, extra, app.settings.error_content_type)
+
+        def do_GET(self):
+            self._serve("GET")
+
+        def do_POST(self):
+            self._serve("POST")
+
+        def do_PUT(self):
+            self._serve("PUT")
+
+        def do_PATCH(self):
+            self._serve("PATCH")
+
+        def do_DELETE(self):
+            self._serve("DELETE")
+
+    return Handler
+
+
+def serve(
+    world: str | Path,
+    *,
+    port: int = PORT,
+    host: str = "0.0.0.0",
+    api_key: str | None = None,
+    scenario: str | None = None,
+) -> ThreadingHTTPServer:
+    """Start the world's API and return the server; the caller decides how long it runs."""
+    root = Path(world)
+    spec = load_spec(root)
+    settings = load_api_settings(root, spec)
+    state = WorldState(root)
+    if scenario:
+        state.apply_scenario(scenario)
+    server = ThreadingHTTPServer((host, port), make_handler(state, Router(spec, settings), api_key))
+    server.world_state = state  # type: ignore[attr-defined]
+    return server
+
+
+def fetch_hosted_snapshot(world: str | Path, environ: dict[str, str] | None = None) -> dict | None:
+    """The hosted pod's snapshot, when ``WORLD_SNAPSHOT_URL`` / ``_SHA256`` / ``_DIGEST``
+    are set: downloaded to ``db/state.sqlite``, verified, sidecar written. All three
+    are required together; a digest mismatch is fatal and names the digest."""
+    env = os.environ if environ is None else environ
+    values = {name: env.get(name) for name in (snapshots.ENV_URL, snapshots.ENV_SHA256, snapshots.ENV_DIGEST)}
+    if not any(values.values()):
+        return None
+    missing = [name for name, value in values.items() if not value]
+    if missing:
+        fail("snapshot", f"{', '.join(missing)} must be set together with the snapshot URL")
+    root = Path(world)
+    return snapshots.fetch(
+        root,
+        check_bundle(root),
+        values[snapshots.ENV_URL],
+        values[snapshots.ENV_SHA256],
+        values[snapshots.ENV_DIGEST],
+    )
+
+
+def serve_forever(
+    world: str | Path, *, port: int = PORT, api_key: str | None = None, scenario: str | None = None
+) -> None:
+    try:
+        fetched = fetch_hosted_snapshot(world)
+    except ContractError as error:
+        print(f"world snapshot refused: {error}", file=sys.stderr)
+        raise SystemExit(2)
+    if fetched:
+        print(f"world snapshot {fetched['batchDigest']} opened", file=sys.stderr)
+    server = serve(world, port=port, api_key=api_key, scenario=scenario)
+    try:
+        print(f"world api listening on http://0.0.0.0:{port}", file=sys.stderr)
+        server.serve_forever()
+    finally:
+        server.server_close()
+        server.world_state.close()  # type: ignore[attr-defined]
+
+
+# ---------------------------------------------------------------- bundle
+
+
+def openapi_document(spec: Spec, contract_id: str, settings: ApiSettings | None = None) -> dict:
+    parameters = {"header": "header", "query": "query"}
+    security_scheme: dict[str, Any] = {}
+    if spec.scheme in ("header", "query"):
+        security_scheme = {"type": "apiKey", "in": parameters[spec.scheme], "name": spec.auth_name}
+    elif spec.scheme == "bearer":
+        security_scheme = {"type": "http", "scheme": "bearer"}
+    elif spec.scheme == "basic":
+        security_scheme = {"type": "http", "scheme": "basic"}
+    elif spec.scheme == "oauth2":
+        token_url = (settings.token_path if settings else None) or DEFAULT_TOKEN_PATH
+        security_scheme = {
+            "type": "oauth2",
+            "flows": {"clientCredentials": {"tokenUrl": token_url, "scopes": {spec.scope or "api": "API access"}}},
+        }
+    paths: dict[str, dict] = {}
+    for operation in spec.operations.values():
+        op = settings.for_operation(operation.name) if settings else OperationSettings()
+        params = [
+            {"name": name, "in": "path", "required": True, "schema": {"type": "string"}}
+            for name in operation.placeholders
+        ] + [
+            {"name": name, "in": "query", "required": False, "schema": {"type": "string"}} for name in operation.params
+        ]
+        entry: dict[str, Any] = {
+            "operationId": operation.name,
+            "parameters": params,
+            **({"x-gateway-entity": operation.entity} if operation.entity else {}),
+            "x-gateway-action": op.action,
+            "responses": {
+                str(op.status): {"description": "OK"},
+                "401": {"description": "Unauthorized"},
+                "404": {"description": "Not found"},
+            },
+            **({"security": [{"vendor": []}]} if security_scheme else {}),
+        }
+        if op.action in ("create", "update") or (
+            op.action == "handler" and operation.method in ("POST", "PUT", "PATCH")
+        ):
+            entry["requestBody"] = {"content": {"application/json": {"schema": {"type": "object"}}}}
+        methods = paths.setdefault(operation.path, {})
+        method = operation.method.lower()
+        if method in methods:
+            # OpenAPI keys one operation per path+method; a vendor that tells lookups apart
+            # by query parameter keeps every one of them here rather than losing all but the first.
+            methods[method].setdefault("x-gateway-variants", []).append(
+                {
+                    k: v
+                    for k, v in entry.items()
+                    if k in ("operationId", "parameters", "x-gateway-entity", "x-gateway-action")
+                }
+            )
+        else:
+            methods[method] = entry
+    document: dict[str, Any] = {
+        "openapi": "3.1.0",
+        "info": {"title": spec.slug, "version": "1.0.0", "x-gateway-domain": contract_id},
+        "servers": [{"url": spec.base_url}],
+        "paths": paths,
+    }
+    if security_scheme:
+        document["components"] = {"securitySchemes": {"vendor": security_scheme}}
+    return document
+
+
+def _scenario_dirs(root: Path) -> dict[str, Path]:
+    """A world's authored scenarios: each a starting state (seed overlays replacing whole
+    entities) plus an instruction, so a session can open the world mid-investigation,
+    quota-exhausted, or whatever else the vendor's client should be tested against."""
+    return snapshots.scenario_dirs(root)
+
+
+def base_seed(initial: dict) -> dict[str, list]:
+    """``seed/base.json``: the initial batch's inserted rows by entity, what older
+    runners post as the base of a session's seed."""
+    seed: dict[str, list] = {}
+    for mutation in initial.get("mutations", []):
+        if mutation.get("op") == "insert":
+            seed.setdefault(mutation["entity"], []).append(mutation["value"])
+    return seed
+
+
+def write_base_seed(world: Path, bundle: Path) -> Path:
+    """Regenerate the bundle's ``seed/base.json`` from the world's ``data/initial.json``."""
+    target = bundle / "seed/base.json"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(base_seed(read_json(world / "data/initial.json")), indent=1) + "\n")
+    return target
+
+
+def build_api_bundle(world: str | Path, out: str | Path) -> Path:
+    """Write the api-kind bundle that hosts this world's API under ``out``.
+
+    The world stays the authority; this is packaging. `gateway bench push` calls it
+    for any schema world carrying connector.toml, so users push the world, not a
+    second artifact."""
+    root = Path(world)
+    out_dir = Path(out)
+    if out_dir.exists() and any(out_dir.iterdir()):
+        fail("api", "Output directory must be empty or absent", "/api/out")
+    spec = load_spec(root)
+    settings = load_api_settings(root, spec)
+    load_handlers(settings)  # a handler the module lacks fails here, not in the container
+    contract = compile_bundle(root)
+    check_bundle(root)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    manifest = [
+        "# Generated from the world under server/world, which is the authority.",
+        "[service]",
+        f'name = "{contract.metadata["package"]["id"]}"',
+        f'emulates = "{spec.slug}"',
+        "",
+        "[server]",
+        f"port = {PORT}",
+        f'healthcheck = "{ADMIN["health"]}"',
+        "",
+        "[admin]",
+        f'reset = "{ADMIN["reset"]}"',
+        f'seed = "{ADMIN["seed"]}"',
+        f'state = "{ADMIN["state"]}"',
+        "",
+    ]
+    if settings.ui is not None:
+        # The built ui travels inside the copied world; the host serves it from
+        # there, so no ui image is ever built for a schema world.
+        manifest += [
+            "[ui]",
+            f'static = "server/world/{settings.ui.static}"',
+            f'entry = "{settings.ui.entry}"',
+            f'api_path = "{settings.ui.api_path}"',
+            "",
+        ]
+    (out_dir / "gateway-api-world.toml").write_text("\n".join(manifest))
+    (out_dir / "openapi.json").write_text(
+        json.dumps(openapi_document(spec, contract.target["id"], settings), indent=1) + "\n"
+    )
+    (out_dir / "seed").mkdir()
+    write_base_seed(root, out_dir)
+    authored = _scenario_dirs(root)
+    for name, path in authored.items():
+        shutil.copytree(path, out_dir / "scenarios" / name)
+    if "default" not in authored:
+        scenario = out_dir / "scenarios/default"
+        scenario.mkdir(parents=True)
+        (scenario / "scenario.toml").write_text('name = "default"\nseed = "seed"\n')
+        (scenario / "instruction.md").write_text(
+            f"The {spec.slug} world serving the vendor's API, seeded with its captured state. Point the provider client here.\n"
+        )
+    server = out_dir / "server"
+    package = server / "gatewaysdk" / "environment" / "schema"
+    package.mkdir(parents=True)
+    (server / "gatewaysdk" / "__init__.py").write_text("")
+    (server / "gatewaysdk" / "environment" / "__init__.py").write_text("")
+    for module in sorted(Path(__file__).parent.glob("*.py")):
+        shutil.copy(module, package / module.name)
+    shutil.copytree(root, server / "world", ignore=shutil.ignore_patterns("captures", "__pycache__", ".git"))
+    (server / "main.py").write_text(
+        "\n".join(
+            [
+                '"""Serve the world\'s API; everything it needs sits beside this file."""',
+                "import os",
+                "import sys",
+                "from pathlib import Path",
+                "",
+                "sys.path.insert(0, str(Path(__file__).resolve().parent))",
+                "from gatewaysdk.environment.schema.api import serve_forever  # noqa: E402",
+                "",
+                "serve_forever(",
+                '    Path(__file__).resolve().parent / "world",',
+                f'    port=int(os.environ.get("PORT") or {PORT}),',
+                '    api_key=os.environ.get("WORLD_API_KEY") or None,',
+                ")",
+                "",
+            ]
+        )
+    )
+    (server / "Dockerfile").write_text(
+        "\n".join(
+            [
+                "FROM python:3.12-slim",
+                "WORKDIR /app",
+                "COPY server /app",
+                f"EXPOSE {PORT}",
+                'CMD ["python", "/app/main.py"]',
+                "",
+            ]
+        )
+    )
+    return out_dir