gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/platform.py

@@ -0,0 +1,1272 @@
+"""Credential-free platform bridge for authored schema bundles.
+
+Validation parses Python syntax without importing it. Authored code executes only
+inside the hosted runner or an isolated workbench, never the publication server.
+The stdio protocol deliberately contains bundle bytes and mapping context only.
+"""
+
+from __future__ import annotations
+
+import ast
+import base64
+import binascii
+import gzip
+import io
+import json
+import shutil
+import sys
+import tarfile
+import tempfile
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from .._materialize import materialize_template
+from . import ContractError, SQLiteStore, bundle_mode, check_bundle, compile_bundle
+from . import snapshot as snapshots
+from .validation import (
+    digest,
+    encoded,
+    fail,
+    journal_paths,
+    members,
+    nonempty,
+    read_json,
+)
+
+MAX_BYTES = 64 * 1024 * 1024
+MAX_FILES = 2000
+COMMANDS = (
+    "validate",
+    "validate-archive",
+    "init-template",
+    "init-template-files",
+    "template-summary",
+    "describe",
+    "compile",
+    "apply-batch",
+    "build-slack",
+    "refresh-slack",
+    "capture",
+    "import-data",
+    "ingest",
+    "conform",
+    "counts",
+    "api-bundle",
+    "templates",
+    "validate-rows",
+    "snapshot-build",
+    "snapshot-default",
+    "run-tests",
+)
+PLATFORM_MAPPING = {"id": "platform-agent", "version": "1"}
+
+
+def compile_world(root: Path) -> dict:
+    """Authored files -> generated artifacts, on an arbitrary schema world.
+
+    The platform stores compiled trees, so a world whose authored inputs changed
+    (``schema/world.json``, ``gateway-env.toml``, handlers) is recompiled here
+    rather than rejected with ``lock_mismatch``. Only a journal that holds no
+    state (``mutations == []``) of the same domain ``$id`` follows the contract to
+    its new identity; a journal with rows is refused, never migrated silently —
+    state migration stays manual (re-import the rows against the new schema).
+    Journals from a different domain are refused outright. The snapshots are then
+    rebuilt loudly: data the contract refuses is a rejection, not a dropped snapshot.
+    """
+    from .snapshot import build_all
+
+    if bundle_mode(root) is None:
+        fail(
+            "mode",
+            "Expected a schema-backed mock-tools world (gateway-env.toml with [schema] language)",
+        )
+    added = []
+    base = root / "schema/base.json"
+    if not base.exists():
+        from .scaffold import TEMPLATES
+
+        base.parent.mkdir(parents=True, exist_ok=True)
+        base.write_bytes((TEMPLATES / "base.json").read_bytes())
+        added.append("schema/base.json")
+    contract = compile_bundle(root, snapshots=False)
+    initial = root / "data/initial.json"
+    if not initial.exists():
+        initial.parent.mkdir(parents=True, exist_ok=True)
+        initial.write_bytes(
+            encoded(
+                {
+                    "id": f"{contract.metadata['package']['id']}.initial.v1",
+                    "target": contract.target,
+                    "mapping": {"id": "empty", "version": "1"},
+                    "coverage": "partial",
+                    "mutations": [],
+                }
+            )
+        )
+        added.append("data/initial.json")
+    retargeted = []
+    for path in journal_paths(root):
+        journal = read_json(path)
+        location = str(path.relative_to(root))
+        if not isinstance(journal, dict) or not isinstance(journal.get("target"), dict):
+            fail("batch", "Journal must be a batch object with a target", location)
+        if journal["target"] == contract.target:
+            continue
+        if journal["target"].get("id") != contract.target["id"]:
+            fail(
+                "batch_target",
+                "Journal belongs to a different domain; remove it or restore the schema's $id",
+                location,
+            )
+        if journal.get("mutations") != []:
+            fail(
+                "batch_target",
+                "Batch targets a different domain identity/version/hash; a journal that holds "
+                "state is not migrated to an edited schema — re-import its rows against the new "
+                "contract (or restore the schema it was written against)",
+                location,
+            )
+        journal["target"] = contract.target
+        path.write_bytes(encoded(journal))
+        retargeted.append(location)
+    build_all(root, contract)
+    return {"added": added, "retargeted": retargeted}
+
+
+def append_batch(root: Path, batch: dict, *, source: str | None = None) -> dict:
+    """Validate then append one platform batch as an immutable refresh journal.
+
+    ``target`` is filled from the compiled contract (a caller-supplied one must
+    match); ``mapping`` and ``coverage`` default to the platform mapping and
+    ``partial``. Mutations without ``source`` take ``{"record": "<source>#<n>"}``
+    when a source prefix is given, otherwise provenance is required per mutation.
+    Replaying every prior journal first makes a repeated batch id idempotent and
+    a reused id with different content a conflict, exactly as in the store.
+    """
+    contract = check_bundle(root)
+    members(
+        batch,
+        {"id", "target", "mapping", "coverage", "mutations"},
+        {"id", "mutations"},
+        "/batch",
+    )
+    nonempty(batch["id"], "/batch/id")
+    if "target" in batch and batch["target"] != contract.target:
+        fail(
+            "batch_target",
+            "Batch targets a different domain identity/version/hash",
+            "/batch/target",
+        )
+    if not isinstance(batch["mutations"], list) or not batch["mutations"]:
+        fail("batch", "mutations must be a non-empty array", "/batch/mutations")
+    mutations = []
+    for index, mutation in enumerate(batch["mutations"]):
+        if not isinstance(mutation, dict):
+            fail(
+                "batch", "Each mutation must be an object", f"/batch/mutations/{index}"
+            )
+        if "source" not in mutation:
+            if source is None:
+                fail(
+                    "provenance",
+                    "Mutation has no source; pass a source prefix or a source.record per mutation",
+                    f"/batch/mutations/{index}/source",
+                )
+            mutation = {**mutation, "source": {"record": f"{source}#{index}"}}
+        mutations.append(mutation)
+    resolved = {
+        "id": batch["id"],
+        "target": contract.target,
+        "mapping": batch.get("mapping", PLATFORM_MAPPING),
+        "coverage": batch.get("coverage", "partial"),
+        "mutations": mutations,
+    }
+    journals = journal_paths(root)
+    with (
+        tempfile.TemporaryDirectory(prefix="gateway-apply-batch-") as temporary,
+        SQLiteStore.create(Path(temporary) / "state.sqlite", contract) as store,
+    ):
+        for path in journals:
+            store.apply_batch(read_json(path))
+        result = store.apply_batch(resolved)
+        store.audit()
+    if result["status"] == "already_applied":
+        return result
+    batches = root / "data/batches"
+    batches.mkdir(exist_ok=True)
+    existing = len(journals) - 1
+    target = batches / f"{existing + 1:06d}-{digest(batch['id'].encode())[:16]}.json"
+    target.write_bytes(encoded(resolved))
+    if snapshots.default_snapshot(root).is_file():
+        # The journals grew; a snapshot built before this batch would be served
+        # over them. Rebuild so the tree stays one thing (default + scenarios).
+        from .compiler import build
+        from .snapshot import build_all
+
+        build_all(root, build(root))
+    return {**result, "journal": str(target.relative_to(root))}
+
+
+def _pinned_state(bundle: Path, contract) -> dict[str, int] | None:
+    """The entity counts of a data-only version whose hosted snapshot is not in the
+    tree: ``db/snapshot.json`` alone. The platform audited that snapshot through
+    this contract when it built it, so the pin stands in for the state check —
+    provided it names this contract; a snapshot built through another contract
+    is refused, since the tree's data files cannot reproduce it either. A tree
+    that carries its snapshot, or no pin at all, materializes as usual."""
+    from .snapshot import contract_hash, current_default, pinned_default
+
+    pin = pinned_default(bundle)
+    if pin is None or current_default(bundle, contract) is not None:
+        return None
+    if pin.get("contractHash") != contract_hash(contract):
+        fail(
+            "snapshot_pinned",
+            "db/snapshot.json pins a hosted snapshot built through a different contract; "
+            "re-import its rows against the current schema (import_world_data, "
+            "gateway worlds data import) or restore the schema it was built against",
+            "/db/snapshot.json",
+        )
+    counts = pin.get("entityCounts")
+    if not isinstance(counts, dict) or any(
+        not isinstance(value, int) or isinstance(value, bool)
+        for value in counts.values()
+    ):
+        fail(
+            "snapshot_pin",
+            "db/snapshot.json must carry the hosted snapshot's entityCounts",
+            "/db/snapshot.json",
+        )
+    return {entity: int(counts.get(entity, 0)) for entity in contract.entities}
+
+
+def validate_bundle(bundle: str | Path) -> dict:
+    bundle = Path(bundle)
+    if bundle_mode(bundle) is None:
+        fail("mode", "Expected a schema-backed mock-tools world")
+    contract = check_bundle(bundle)
+    declared = set(contract.tools)
+    found: dict[str, str] = {}
+    for path in sorted((bundle / "tools").glob("*.py")):
+        if path.is_symlink():
+            fail("path", "Tool handlers must be regular files")
+        try:
+            tree = ast.parse(path.read_text(encoding="utf-8"), filename=path.name)
+        except (SyntaxError, UnicodeError):
+            fail("handler", f"Invalid Python handler syntax: {path.name}")
+        for node in tree.body:
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            names = []
+            for decorator in node.decorator_list:
+                target = (
+                    decorator.func if isinstance(decorator, ast.Call) else decorator
+                )
+                is_tool = (isinstance(target, ast.Name) and target.id == "tool") or (
+                    isinstance(target, ast.Attribute) and target.attr == "tool"
+                )
+                if not is_tool:
+                    continue
+                name = node.name
+                if isinstance(decorator, ast.Call):
+                    for keyword in decorator.keywords:
+                        if keyword.arg == "name":
+                            if not isinstance(
+                                keyword.value, ast.Constant
+                            ) or not isinstance(keyword.value.value, str):
+                                fail(
+                                    "handler", "Publication requires literal tool names"
+                                )
+                            name = keyword.value.value
+                names.append(name)
+            if not names and node.name in declared:
+                names.append(node.name)
+            if not names and node.name == "run" and path.stem in declared:
+                names.append(path.stem)
+            for name in names:
+                if name in found:
+                    fail("handler", f"Duplicate handler for {name}")
+                found[name] = path.name
+    if set(found) != declared:
+        fail("handler", "Declared tools and Python handlers must match exactly")
+    pinned = _pinned_state(bundle, contract)
+    if pinned is not None:
+        counts, initial_state = pinned, "pinned"
+    else:
+        initial_state = "validated"
+        with tempfile.TemporaryDirectory(prefix="gateway-state-check-") as staging:
+            database = Path(staging) / "world.db"
+            materialize_template(bundle, database)
+            with SQLiteStore.open(database, contract) as store:
+                store.audit()
+                counts = {
+                    entity: len(store.list(entity)) for entity in contract.entities
+                }
+    return {
+        "status": "ok",
+        "domain": contract.target,
+        "package": contract.metadata["package"],
+        "initial_state": initial_state,
+        "handler_execution": "skipped",
+        "entity_counts": counts,
+        "tools": sorted(declared),
+    }
+
+
+API_BUNDLE = "gateway-api-world.toml"
+BUNDLED_WORLD = "server/world"
+
+
+def world_root(root: Path) -> Path:
+    """The world inside the tree the platform holds. ``bench push`` uploads a schema
+    world as its api bundle, so a version's tree is ``gateway-api-world.toml`` +
+    ``seed/`` + ``scenarios/`` + ``server/world/<the authoring world>``: that nested
+    world is what data commands operate on. A plain tree is its own root."""
+    nested = root / BUNDLED_WORLD
+    if (root / API_BUNDLE).is_file() and (
+        (nested / "connector.toml").is_file()
+        or (nested / "schema/world.json").is_file()
+    ):
+        return nested
+    return root
+
+
+def _write_files(root: Path, entries: list) -> None:
+    if not isinstance(entries, list) or len(entries) > MAX_FILES:
+        fail("size", "Invalid bundle file count")
+    seen = set()
+    size = 0
+    for entry in entries:
+        if not isinstance(entry, dict) or set(entry) != {"path", "content"}:
+            fail("input", "Expected path and base64 content")
+        name = entry["path"]
+        if not isinstance(name, str) or not name or "\\" in name or "\x00" in name:
+            fail("path", "Invalid bundle path")
+        path = PurePosixPath(name)
+        if (
+            path.is_absolute()
+            or any(p in ("", ".", "..") for p in name.split("/"))
+            or name in seen
+        ):
+            fail("path", "Bundle paths must be unique relative file paths")
+        seen.add(name)
+        try:
+            data = base64.b64decode(entry["content"], validate=True)
+        except (ValueError, TypeError):
+            fail("input", "Invalid base64 bundle content")
+        size += len(data)
+        if size > MAX_BYTES:
+            fail("size", "Bundle exceeds 64 MiB")
+        target = root.joinpath(*path.parts)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(data)
+
+
+def _archive_files(encoded: str) -> list:
+    try:
+        archive = base64.b64decode(encoded, validate=True)
+        if len(archive) > MAX_BYTES:
+            fail("size", "Schema archive exceeds 64 MiB")
+        with gzip.GzipFile(fileobj=io.BytesIO(archive)) as stream:
+            data = stream.read(MAX_BYTES + 1)
+        if len(data) > MAX_BYTES:
+            fail("size", "Expanded schema archive exceeds 64 MiB")
+        files = {}
+        with tarfile.open(fileobj=io.BytesIO(data), mode="r:") as tar:
+            if tar.pax_headers:
+                fail("archive", "Global archive metadata is not supported")
+            for member in tar:
+                if len(files) > MAX_FILES:
+                    fail("size", "Too many archive files")
+                if (
+                    member.issym()
+                    or member.islnk()
+                    or not (member.isfile() or member.isdir())
+                ):
+                    fail(
+                        "archive",
+                        "Archive may contain only ordinary files and directories",
+                    )
+                if any(
+                    key
+                    not in (
+                        "path",
+                        "mtime",
+                        "atime",
+                        "ctime",
+                        "uid",
+                        "gid",
+                        "uname",
+                        "gname",
+                    )
+                    for key in member.pax_headers
+                ):
+                    fail("archive", "Unsupported archive metadata")
+                name = member.name
+                while name.startswith("./"):
+                    name = name[2:]
+                path = PurePosixPath(name)
+                if (
+                    path.is_absolute()
+                    or ".." in path.parts
+                    or not name
+                    or chr(92) in name
+                ):
+                    fail("path", "Archive path escapes the bundle")
+                if member.isdir():
+                    continue
+                stream = tar.extractfile(member)
+                if stream is None:
+                    fail("archive", "Unreadable archive member")
+                content = stream.read(MAX_BYTES + 1)
+                if len(content) != member.size:
+                    fail("archive", "Truncated archive member")
+                files[str(path)] = base64.b64encode(content).decode("ascii")
+        return [{"path": path, "content": content} for path, content in files.items()]
+    except (tarfile.TarError, EOFError, OSError, ValueError, TypeError):
+        fail("archive", "Invalid world archive")
+
+
+def _capture(request: dict) -> dict:
+    """``capture``: run one connection operation for the platform, from the pod whose
+    egress the vendor allow-listed. The spec arrives as text, the credential as the
+    environment variable it names (set by the caller, never in the request), and every
+    recorded page comes back redacted the way the CLI would have written it."""
+    from .connector import CAPTURES, MANIFEST, capture, parse_spec
+
+    spec_text = request.get("spec")
+    op = request.get("op")
+    args = request.get("args") or {}
+    params = request.get("params") or {}
+    max_pages = request.get("max_pages")
+    if not isinstance(spec_text, str) or not isinstance(op, str):
+        fail("input", "Expected the connector.toml text and an operation name")
+    if not all(
+        isinstance(m, dict)
+        and all(isinstance(k, str) and isinstance(v, str) for k, v in m.items())
+        for m in (args, params)
+    ):
+        fail("input", "args and params map names to strings")
+    if max_pages is not None and (
+        isinstance(max_pages, bool) or not isinstance(max_pages, int) or max_pages < 1
+    ):
+        fail("input", "max_pages must be a positive integer")
+    parse_spec(spec_text)
+    with tempfile.TemporaryDirectory(prefix="gateway-capture-") as directory:
+        root = Path(directory) / "world"
+        root.mkdir()
+        (root / "connector.toml").write_text(spec_text, encoding="utf-8")
+        written = capture(root, op, args, params, max_pages=max_pages)
+        manifest = json.loads((root / CAPTURES / MANIFEST).read_text(encoding="utf-8"))
+        return {
+            "status": "ok",
+            "files": [
+                {
+                    "path": path.relative_to(root).as_posix(),
+                    "content": base64.b64encode(path.read_bytes()).decode("ascii"),
+                }
+                for path in written
+            ],
+            "manifest": manifest,
+        }
+
+
+def _template_files(request: dict) -> dict[str, bytes]:
+    listed = request.get("files")
+    if not isinstance(listed, list) or not listed:
+        fail("input", "Expected the template's files as [{path, content}]")
+    files: dict[str, bytes] = {}
+    for entry in listed:
+        if (
+            not isinstance(entry, dict)
+            or not isinstance(entry.get("path"), str)
+            or not isinstance(entry.get("content"), str)
+        ):
+            fail("input", "Each template file is {path, content} with base64 content")
+        try:
+            files[entry["path"]] = base64.b64decode(entry["content"], validate=True)
+        except (ValueError, binascii.Error):
+            fail("input", "Template file content must be base64")
+    return files
+
+
+def _template_summary(files: dict[str, bytes]) -> dict:
+    """What a workspace connector is, read from its files: the vendor connection
+    (connector.toml) and the data model (world.json), plus the digest the platform
+    pins worlds to. Never runs the template's Python."""
+    from .connector import parse_spec
+    from .scaffold import template_digest
+
+    # A template keeps world.json at its root; an initialized world keeps it under schema/.
+    world_path = next(
+        (path for path in ("world.json", "schema/world.json") if path in files), None
+    )
+    if world_path is None:
+        fail(
+            "template",
+            "No world.json (template) or schema/world.json (world) among the files",
+        )
+    try:
+        world = json.loads(files[world_path].decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        fail("template", f"{world_path} is not valid JSON: {error}")
+    gateway = world.get("x-gateway") if isinstance(world, dict) else None
+    if not isinstance(gateway, dict):
+        fail("template", f"{world_path} is not a gateway-world document")
+    entities = []
+    for name, entity in sorted((gateway.get("entities") or {}).items()):
+        fields: list = []
+        schema = entity.get("schema") if isinstance(entity, dict) else None
+        ref = schema.get("$ref") if isinstance(schema, dict) else None
+        definition = None
+        if isinstance(ref, str) and ref.startswith("#/$defs/"):
+            definition = (world.get("$defs") or {}).get(ref[len("#/$defs/") :])
+        properties = (
+            (definition or {}).get("properties") or {}
+            if isinstance(definition, dict)
+            else {}
+        )
+        required = (
+            set((definition or {}).get("required") or [])
+            if isinstance(definition, dict)
+            else set()
+        )
+        for field_name, field_schema in properties.items():
+            kind = field_schema.get("type") if isinstance(field_schema, dict) else None
+            if isinstance(kind, list):
+                # A nullable field is `["string", "null"]` in JSON Schema; the page
+                # shows it as one readable type, not the list's concatenation.
+                kind = " | ".join(str(part) for part in kind)
+            if (
+                kind is None
+                and isinstance(field_schema, dict)
+                and isinstance(field_schema.get("$ref"), str)
+            ):
+                kind = field_schema["$ref"].rsplit("/", 1)[-1]
+            fields.append(
+                {"name": field_name, "type": kind, "required": field_name in required}
+            )
+        entities.append(
+            {
+                "name": name,
+                "primaryKey": list(entity.get("primary_key") or [])
+                if isinstance(entity, dict)
+                else [],
+                "unique": list(entity.get("unique") or [])
+                if isinstance(entity, dict)
+                else [],
+                "relationships": list(entity.get("relationships") or [])
+                if isinstance(entity, dict)
+                else [],
+                "fields": fields,
+            }
+        )
+    connection = None
+    if "connector.toml" in files:
+        spec = parse_spec(files["connector.toml"].decode("utf-8"))
+        connection = {
+            "slug": spec.slug,
+            "baseUrl": spec.base_url,
+            "auth": spec.scheme,
+            "operations": [
+                {
+                    "name": op.name,
+                    "method": op.method,
+                    "path": op.path,
+                    "params": list(op.params),
+                    "entity": op.entity,
+                    "results": op.results,
+                }
+                for op in spec.operations.values()
+            ],
+        }
+    package = gateway.get("package") or {}
+    return {
+        "status": "ok",
+        "summary": {
+            "packageVersion": package.get("version"),
+            "domainVersion": gateway.get("domain_version"),
+            "domainId": world.get("$id"),
+            "digest": template_digest(files),
+            "entities": entities,
+            "connection": connection,
+            "tools": sorted((gateway.get("tools") or {}).keys()),
+            "files": sorted(files),
+        },
+    }
+
+
+COMPILED_MARKERS = ("schema/world.json", "tool-schemas.json")
+# The compiled world's files a description is read from; the rest of a bundle
+# (seed data, verifiers, tool sources) says nothing about the contract.
+DESCRIBE_PATHS = (
+    "schema/world.json",
+    "tool-schemas.json",
+    "connector.toml",
+    "api/handlers.py",
+)
+
+
+def _describe(request: dict) -> dict:
+    """One description for the connector page and a world's Schema tab: the data
+    model, the tools with their schemas, and — when the connector declares a vendor
+    connection — the OpenAPI document the served world answers to.
+
+    The connector is compiled exactly as a world build compiles it (an installed
+    template by slug, or a template's files), so the page shows what a world gets;
+    a compiled world's own files (``schema/world.json`` + ``tool-schemas.json``) pass
+    straight through. Never runs the connector's Python."""
+    from .connector import parse_spec
+    from .scaffold import (
+        TEMPLATES,
+        init_bundle,
+        init_bundle_from_files,
+        template_digest,
+    )
+
+    connector = request.get("connector")
+    with tempfile.TemporaryDirectory(prefix="gateway-schema-") as directory:
+        root = Path(directory) / "bundle"
+        if connector is not None:
+            if not isinstance(connector, str):
+                fail("input", "Expected an installed connector template slug")
+            init_bundle(root, connector=connector)
+            template_dir = TEMPLATES / connector
+            authored = {
+                str(path.relative_to(template_dir)): path.read_bytes()
+                for path in sorted(template_dir.rglob("*"))
+                if path.is_file() and "__pycache__" not in path.parts
+            }
+        else:
+            authored = _template_files(request)
+            if all(marker in authored for marker in COMPILED_MARKERS):
+                root.mkdir()
+                for path, data in authored.items():
+                    if path in DESCRIBE_PATHS:
+                        target = root / path
+                        target.parent.mkdir(parents=True, exist_ok=True)
+                        target.write_bytes(data)
+            else:
+                slug = (
+                    request.get("slug")
+                    if isinstance(request.get("slug"), str)
+                    else None
+                )
+                if slug is None and "connector.toml" in authored:
+                    slug = parse_spec(authored["connector.toml"].decode("utf-8")).slug
+                init_bundle_from_files(root, authored, connector=slug or "custom")
+        summary = _template_summary(
+            {"world.json": (root / "schema/world.json").read_bytes()}
+        )["summary"]
+        summary["digest"] = template_digest(authored)
+        summary["files"] = sorted(authored)
+        tool_schemas = {}
+        if (root / "tool-schemas.json").is_file():
+            tool_schemas = (
+                json.loads(
+                    (root / "tool-schemas.json").read_text(encoding="utf-8")
+                ).get("tools")
+                or {}
+            )
+        summary["tools"] = [
+            {
+                "name": name,
+                "description": str(entry.get("description") or ""),
+                "inputSchema": entry.get("input_schema"),
+                "outputSchema": entry.get("output_schema"),
+            }
+            for name, entry in sorted(tool_schemas.items())
+        ]
+        summary["connection"] = None
+        summary["openapi"] = None
+        if (root / "connector.toml").is_file():
+            from .api import load_api_settings, openapi_document
+
+            spec = parse_spec((root / "connector.toml").read_text(encoding="utf-8"))
+            try:
+                settings = load_api_settings(root, spec)
+            except ContractError:
+                # A template without its handlers still has a shape worth showing;
+                # the routes render with the default action and status.
+                settings = None
+            summary["connection"] = {
+                "slug": spec.slug,
+                "baseUrl": spec.base_url,
+                "auth": spec.scheme,
+                "operations": [
+                    {
+                        "name": op.name,
+                        "method": op.method,
+                        "path": op.path,
+                        "params": list(op.params),
+                        "entity": op.entity,
+                        "results": op.results,
+                        "action": settings.for_operation(op.name).action
+                        if settings
+                        else None,
+                        "status": settings.for_operation(op.name).status
+                        if settings
+                        else None,
+                    }
+                    for op in spec.operations.values()
+                ],
+            }
+            summary["openapi"] = openapi_document(
+                spec, summary.get("domainId") or spec.slug, settings
+            )
+        return {"status": "ok", "description": summary}
+
+
+def _import_data(request: dict) -> dict:
+    """``import-data``: rows into a world the platform holds as files. The tree arrives
+    as ``[{path, content}]``, the rows as ``{entity: [row, …]}`` with a mode; the world is
+    rebuilt in a temporary directory, the rows go in through :func:`data.import_rows`
+    (the same gate the CLI uses, scratch copy first), and every file of the updated
+    tree comes back the way ``init-template`` returns one, so the platform commits a
+    version from it without knowing which file changed."""
+    from .data import KIND_SCHEMA, MODES, import_rows
+
+    rows = request.get("rows")
+    mode = request.get("mode", "append")
+    if not isinstance(rows, dict) or not all(
+        isinstance(v, list) for v in rows.values()
+    ):
+        fail("input", "Expected rows as {entity: [row, …]}")
+    if mode not in MODES:
+        fail("input", f"mode must be one of {', '.join(MODES)}")
+    with tempfile.TemporaryDirectory(prefix="gateway-import-") as directory:
+        root = Path(directory) / "bundle"
+        root.mkdir()
+        _write_files(root, request.get("files"))
+        world = world_root(root)
+        result = import_rows(world, rows, mode=mode)
+        if result["kind"] == KIND_SCHEMA and snapshots.default_snapshot(world).is_file():
+            # The journals grew; a snapshot built before this import would be
+            # served over them. Rebuild so the tree that travels back is one thing.
+            from .compiler import build
+            from .snapshot import build_all
+
+            build_all(world, build(world))  # build(): the contract, no snapshot audit
+        if world != root and result["kind"] == KIND_SCHEMA:
+            # The bundle's base seed is derived from the world's data; older runners post it.
+            from .api import write_base_seed
+
+            write_base_seed(world, root)
+        return {
+            "status": "ok",
+            "kind": result["kind"],
+            "entity_counts": result["entity_counts"],
+            "changed": result["changed"],
+            "files": _tree(root),
+        }
+
+
+# ---------------------------------------------------------------- batches
+
+
+def _workdir(request: dict) -> Path:
+    """The absolute directory the caller prepared; every path in the request is under it."""
+    workdir = request.get("workdir")
+    if (
+        not isinstance(workdir, str)
+        or not workdir
+        or not Path(workdir).is_absolute()
+        or not Path(workdir).is_dir()
+    ):
+        fail(
+            "input",
+            "Expected workdir: an absolute path to a directory the caller prepared",
+        )
+    return Path(workdir).resolve()
+
+
+def _under(workdir: Path, name: Any, what: str) -> Path:
+    if not isinstance(name, str) or not name or "\x00" in name:
+        fail("path", f"{what} must be a path under workdir")
+    candidate = (
+        (workdir / name).resolve()
+        if not Path(name).is_absolute()
+        else Path(name).resolve()
+    )
+    if not candidate.is_relative_to(workdir):
+        fail("path", f"{what} must stay under workdir")
+    return candidate
+
+
+def _chunk_specs(workdir: Path, request: dict) -> list:
+    from .batch import ChunkSpec
+
+    listed = request.get("chunks")
+    if not isinstance(listed, list) or not listed:
+        fail("input", "Expected chunks as [{ordinal, path, entity?}]")
+    specs = []
+    seen = set()
+    for entry in listed:
+        if (
+            not isinstance(entry, dict)
+            or not isinstance(entry.get("ordinal"), int)
+            or isinstance(entry.get("ordinal"), bool)
+        ):
+            fail("input", "Each chunk is {ordinal, path, entity?}")
+        entity = entry.get("entity")
+        if entity is not None and not isinstance(entity, str):
+            fail("input", "chunk entity must be a string")
+        if entry["ordinal"] in seen:
+            fail("input", f"chunk ordinal {entry['ordinal']} is listed twice")
+        seen.add(entry["ordinal"])
+        path = _under(workdir, entry.get("path"), "chunk path")
+        if not path.is_file():
+            fail("input", f"chunk {entry['ordinal']} is missing under workdir")
+        specs.append(ChunkSpec(entry["ordinal"], path, entity))
+    return sorted(specs, key=lambda spec: spec.ordinal)
+
+
+def _tree(root: Path) -> list:
+    """Every file under ``root`` as ``[{path, content}]``, the encoding ``init-template``
+    returns, so the platform commits a version without knowing which file changed."""
+    return [
+        {
+            "path": path.relative_to(root).as_posix(),
+            "content": base64.b64encode(path.read_bytes()).decode("ascii"),
+        }
+        for path in sorted(root.rglob("*"))
+        if path.is_file() and "__pycache__" not in path.parts
+    ]
+
+
+def _write_tree(workdir: Path, request: dict) -> Path:
+    """The world tree from ``files``, written under ``workdir/tree`` and compiled (the
+    contract alone is enough: generated artifacts are regenerated, snapshots are not)."""
+    from .compiler import compile_bundle
+
+    root = workdir / "tree"
+    if root.exists():
+        shutil.rmtree(root)
+    root.mkdir()
+    _write_files(root, request.get("files"))
+    world = world_root(root)
+    compile_bundle(world, snapshots=False)
+    return world
+
+
+def _flag(request: dict, name: str, default: bool) -> bool:
+    value = request.get(name, default)
+    if not isinstance(value, bool):
+        fail("input", f"{name} must be true or false")
+    return value
+
+
+def _validate_rows(request: dict) -> dict:
+    """``validate-rows``: shape-only validation of every row in the chunks (type, bounds,
+    required, unknown property, primary key present); no reference checks."""
+    from .batch import validate_chunks
+    from .compiler import check_bundle
+    from .data import MODES
+
+    workdir = _workdir(request)
+    if request.get("mode", "append") not in MODES:
+        fail("input", f"mode must be one of {', '.join(MODES)}")
+    root = _write_tree(workdir, request)
+    report = validate_chunks(check_bundle(root), _chunk_specs(workdir, request))
+    return {"status": "ok", **report}
+
+
+def _snapshot_build(request: dict) -> dict:
+    """``snapshot-build``: the parent snapshot (or the tree's default) with the chunks
+    applied in dependency order, one transaction (atomic) or one per chunk; the new
+    snapshot saved under workdir with its sidecar, or nothing on dryRun or an atomic
+    refusal."""
+    from .batch import build_batch
+    from .compiler import check_bundle
+    from .data import MERGES, MODES
+    from .snapshot import EMPTY_DIGEST, build_default, default_snapshot
+
+    workdir = _workdir(request)
+    mode = request.get("mode", "append")
+    merge = request.get("merge", "upsert")
+    if mode not in MODES:
+        fail("input", f"mode must be one of {', '.join(MODES)}")
+    if merge not in MERGES:
+        fail("input", f"merge must be one of {', '.join(MERGES)}")
+    batch_id = request.get("batchId")
+    parent_digest = request.get("parentBatchDigest", EMPTY_DIGEST)
+    if (
+        not isinstance(batch_id, str)
+        or not batch_id
+        or "/" in batch_id
+        or batch_id in (".", "..")
+    ):
+        fail("input", "batchId must be a non-empty string without slashes")
+    if not isinstance(parent_digest, str) or len(parent_digest) != 64:
+        fail("input", "parentBatchDigest must be a 64-hex batch digest")
+    atomic = _flag(request, "atomic", True)
+    dry_run = _flag(request, "dryRun", False)
+    root = _write_tree(workdir, request)
+    contract = check_bundle(root)
+    chunks = _chunk_specs(workdir, request)
+    # One directory per batch, so a parent built by an earlier call in the same
+    # workdir is never the file being written.
+    out_dir = workdir / "snapshot" / batch_id
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out = out_dir / "state.sqlite"
+    out.unlink(missing_ok=True)
+    out.with_name("state.json").unlink(missing_ok=True)
+    if request.get("parentSnapshot") is not None:
+        parent = _under(workdir, request["parentSnapshot"], "parentSnapshot")
+        if not parent.is_file():
+            fail("input", "parentSnapshot is missing under workdir")
+        shutil.copyfile(parent, out)
+    else:
+        build_default(root, contract)
+        shutil.copyfile(default_snapshot(root), out)
+    result = build_batch(
+        contract,
+        out,
+        chunks,
+        mode=mode,
+        merge=merge,
+        atomic=atomic,
+        batch_id=batch_id,
+        parent_digest=parent_digest,
+        dry_run=dry_run,
+    )
+    if "snapshot" in result:
+        # Absolute, under workdir: the caller opens it as it is.
+        result["snapshot"] = str(result["snapshot"])
+    return {"status": "ok", **result}
+
+
+def _snapshot_default(request: dict) -> dict:
+    """``snapshot-default``: the tree's default snapshot and every scenario snapshot,
+    built under ``workdir/tree``; the sidecars come back with absolute paths."""
+    from .compiler import check_bundle
+    from .snapshot import build_all, default_snapshot, scenario_snapshot
+
+    workdir = _workdir(request)
+    root = _write_tree(workdir, request)
+    built = build_all(root, check_bundle(root))
+    # Paths are absolute, under workdir; the sidecar sits both at the top level and
+    # keyed by its tree path, so a reader may take either.
+    return {
+        "status": "ok",
+        "snapshot": str(default_snapshot(root)),
+        "sidecar": built["default"],
+        "sidecars": {"db/state.json": built["default"]},
+        "scenarios": {
+            name: {"snapshot": str(scenario_snapshot(root, name)), "sidecar": sidecar}
+            for name, sidecar in built["scenarios"].items()
+        },
+    }
+
+
+def _api_bundle(request: dict) -> dict:
+    """The api-kind bundle that hosts a world's API, built from the world's files:
+    what `gateway worlds schema api-bundle` writes locally, for a CLI with no Python."""
+    from .api import build_api_bundle
+
+    files = _template_files(request)
+    with tempfile.TemporaryDirectory(prefix="gateway-schema-") as directory:
+        root = Path(directory) / "world"
+        root.mkdir()
+        for path, data in files.items():
+            target = root / path
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(data)
+        out = Path(directory) / "api"
+        build_api_bundle(root, out)
+        return {"status": "ok", "files": _tree(out)}
+
+
+def _ingest(request: dict) -> dict:
+    """``ingest``: the world's authored tree, its ``captures/`` and manifest included,
+    seeded from those captures through the contract exactly as the CLI does, and the
+    whole updated tree handed back. Runs no Python of the world's own."""
+    from .connector import ingest
+
+    batch_id = request.get("batch_id")
+    if batch_id is not None and not isinstance(batch_id, str):
+        fail("input", "batch_id must be a string")
+    with tempfile.TemporaryDirectory(prefix="gateway-ingest-") as directory:
+        root = Path(directory) / "world"
+        root.mkdir()
+        _write_files(root, request.get("files"))
+        result = ingest(world_root(root), batch_id=batch_id)
+        return {"status": "ok", "result": result, "files": _tree(root)}
+
+
+def _conform(request: dict) -> dict:
+    """``conform``: serve the world in the bridge and check every operation's answer
+    against the vendor's OpenAPI documents. The report is the one ``connector conform
+    --out`` writes; ``world`` names the bundle, never the bridge's scratch path."""
+    from .conform import conform
+
+    documents = request.get("openapi")
+    if not isinstance(documents, list) or not documents:
+        fail("input", "Expected one or more OpenAPI documents as [{path, content}]")
+    max_operations = request.get("max_operations")
+    if max_operations is not None and (
+        isinstance(max_operations, bool)
+        or not isinstance(max_operations, int)
+        or max_operations < 1
+    ):
+        fail("input", "max_operations must be a positive integer")
+    with tempfile.TemporaryDirectory(prefix="gateway-conform-") as directory:
+        root = Path(directory) / "world"
+        root.mkdir()
+        _write_files(root, request.get("files"))
+        openapi = Path(directory) / "openapi"
+        openapi.mkdir()
+        _write_files(openapi, documents)
+        paths = [
+            openapi.joinpath(*PurePosixPath(entry["path"]).parts) for entry in documents
+        ]
+        report = conform(
+            world_root(root), paths, max_operations=max_operations
+        ).to_json()
+        report["world"] = root.name
+        return {"status": "ok", "report": report}
+
+
+def _run_tests(request: dict) -> dict:
+    """``run-tests``: serve the world at these files in the bridge and run the tests it
+    ships under ``tests/`` (see :mod:`world_tests`). ``scenario`` starts the world in one
+    of its scenarios; ``snapshot`` ({url, sha256, digest}) lays a pinned data snapshot
+    into the tree first, so a data-only version is tested with its rows."""
+    from .snapshot import fetch as fetch_snapshot
+    from .world_tests import run
+
+    scenario = request.get("scenario")
+    if scenario is not None and not isinstance(scenario, str):
+        fail("input", "scenario must be a string")
+    snapshot = request.get("snapshot")
+    if snapshot is not None and not (
+        isinstance(snapshot, dict) and all(isinstance(snapshot.get(k), str) for k in ("url", "sha256", "digest"))
+    ):
+        fail("input", "snapshot must be {url, sha256, digest}")
+    with tempfile.TemporaryDirectory(prefix="gateway-tests-") as directory:
+        root = Path(directory) / "world"
+        root.mkdir()
+        _write_files(root, request.get("files"))
+        root = world_root(root)
+        if snapshot is not None:
+            fetch_snapshot(root, check_bundle(root), snapshot["url"], snapshot["sha256"], snapshot["digest"])
+        report = run(root, scenario=scenario).to_json()
+        report["world"] = root.name
+        return {"status": "ok", "report": report}
+
+
+def _counts(request: dict) -> dict:
+    """``counts``: what the world at these files seeds with. A kind whose seed lives
+    elsewhere (a harbor tree, an unknown layout) answers with the reason instead of
+    a rejection, so the caller can show it."""
+    from .data import entity_counts, entity_rows, world_kind
+
+    entity = request.get("entity")
+    if entity is not None and not isinstance(entity, str):
+        fail("input", "entity must be a string")
+    with tempfile.TemporaryDirectory(prefix="gateway-counts-") as directory:
+        root = Path(directory) / "world"
+        root.mkdir()
+        _write_files(root, request.get("files"))
+        root = world_root(root)
+        kind = world_kind(root)
+        try:
+            counts = entity_counts(root)
+        except ContractError as error:
+            if error.detail.get("code") != "kind":
+                raise
+            return {
+                "status": "ok",
+                "kind": kind,
+                "entity_counts": None,
+                "reason": error.detail["message"],
+            }
+        report = {"status": "ok", "kind": kind, "entity_counts": counts}
+        if entity is not None:
+            report["rows"] = entity_rows(root, entity)
+        return report
+
+
+def _templates(request: dict) -> dict:
+    """``templates``: every installed connector template, read from its ``world.json``
+    (name and description when the document carries them) and whether it declares a
+    vendor connection. Never runs a template's Python."""
+    from .scaffold import TEMPLATES, list_templates
+
+    templates = []
+    for slug in list_templates():
+        world = json.loads(
+            (TEMPLATES / slug / "world.json").read_text(encoding="utf-8")
+        )
+        gateway = world.get("x-gateway") if isinstance(world, dict) else None
+        if not isinstance(gateway, dict):
+            fail("template", f"{slug}/world.json is not a gateway-world document")
+        templates.append(
+            {
+                "slug": slug,
+                "name": world.get("title")
+                if isinstance(world.get("title"), str)
+                else None,
+                "description": world.get("description")
+                if isinstance(world.get("description"), str)
+                else None,
+                "entities": sorted(gateway.get("entities") or {}),
+                "tools": sorted(gateway.get("tools") or {}),
+                "hasConnection": (TEMPLATES / slug / "connector.toml").is_file(),
+            }
+        )
+    return {"status": "ok", "templates": templates}
+
+
+def execute(request: dict) -> dict:
+    if not isinstance(request, dict) or request.get("command") not in COMMANDS:
+        fail(
+            "command",
+            "Expected one of " + ", ".join(COMMANDS[:-1]) + " or " + COMMANDS[-1],
+        )
+    if request["command"] == "validate-rows":
+        return _validate_rows(request)
+    if request["command"] == "snapshot-build":
+        return _snapshot_build(request)
+    if request["command"] == "snapshot-default":
+        return _snapshot_default(request)
+    if request["command"] == "capture":
+        return _capture(request)
+    if request["command"] == "import-data":
+        return _import_data(request)
+    if request["command"] == "ingest":
+        return _ingest(request)
+    if request["command"] == "conform":
+        return _conform(request)
+    if request["command"] == "run-tests":
+        return _run_tests(request)
+    if request["command"] == "counts":
+        return _counts(request)
+    if request["command"] == "templates":
+        return _templates(request)
+    if request["command"] == "api-bundle":
+        return _api_bundle(request)
+    if request["command"] == "template-summary":
+        return _template_summary(_template_files(request))
+    if request["command"] == "describe":
+        return _describe(request)
+    extra: dict = {}
+    with tempfile.TemporaryDirectory(prefix="gateway-schema-") as directory:
+        root = Path(directory) / "bundle"
+        root.mkdir()
+        if request["command"] == "validate-archive":
+            _write_files(root, _archive_files(request.get("archive")))
+            # A stored version may be the api bundle of a schema world: the
+            # world lives under server/world, and that is what gets validated.
+            root = world_root(root)
+            if bundle_mode(root) is None:
+                return {"status": "ok", "mode": "legacy"}
+        if request["command"] in (
+            "validate",
+            "compile",
+            "apply-batch",
+            "refresh-slack",
+        ):
+            _write_files(root, request.get("files"))
+        # The tree the platform sent may be a schema world's api bundle; the
+        # world itself sits under server/world and is what compiles, takes a
+        # batch and validates. The whole tree still travels back.
+        world = world_root(root)
+        if request["command"] == "compile":
+            # Arbitrary custom worlds: the agent authors schema/world.json (+ manifest,
+            # handlers, journals); the trusted compiler owns every generated artifact.
+            extra["compile"] = compile_world(world)
+            if world != root and (world / "data/initial.json").is_file():
+                from .api import write_base_seed
+
+                write_base_seed(world, root)
+        if request["command"] == "apply-batch":
+            batch, source = request.get("batch"), request.get("source")
+            if not isinstance(batch, dict) or (
+                source is not None and not isinstance(source, str)
+            ):
+                fail(
+                    "input",
+                    "Expected a batch object and an optional source prefix string",
+                )
+            extra["batch"] = append_batch(world, batch, source=source)
+        if request["command"] == "init-template":
+            # The platform's "create world" for every connector template: the same
+            # init + compile the CLI runs, on a fresh empty tree, with nothing seeded.
+            from .scaffold import init_bundle
+
+            connector = request.get("connector")
+            name = request.get("name")
+            if not isinstance(connector, str) or (
+                name is not None and not isinstance(name, str)
+            ):
+                fail("input", "Expected a connector template slug and an optional name")
+            init_bundle(root, connector=connector, name=name)
+        if request["command"] == "init-template-files":
+            # A workspace connector: the template arrives as files, never as a path
+            # the request chose, and the world is built exactly as from an installed one.
+            from .scaffold import init_bundle_from_files
+
+            connector = request.get("connector")
+            name = request.get("name")
+            if not isinstance(connector, str) or (
+                name is not None and not isinstance(name, str)
+            ):
+                fail("input", "Expected the connector slug and an optional name")
+            init_bundle_from_files(
+                root, _template_files(request), connector=connector, name=name
+            )
+        if request["command"] == "build-slack":
+            from .slack import build_slack_bundle
+
+            build_slack_bundle(
+                root, evidence=request.get("evidence"), name=request.get("name")
+            )
+        if request["command"] == "refresh-slack":
+            from .slack import refresh_slack_bundle
+
+            refresh_slack_bundle(
+                root, request.get("evidence"), batch_id=request.get("batch_id")
+            )
+        report = {**validate_bundle(world_root(root)), **extra}
+        if request["command"] not in ("validate", "validate-archive"):
+            report["files"] = [
+                {
+                    "path": str(path.relative_to(root)),
+                    "content": base64.b64encode(path.read_bytes()).decode("ascii"),
+                }
+                for path in sorted(root.rglob("*"))
+                if path.is_file()
+            ]
+        return report
+
+
+def main():
+    try:
+        raw = sys.stdin.buffer.read(2 * MAX_BYTES + 1)
+        if len(raw) > 2 * MAX_BYTES:
+            fail("size", "Bridge request is too large")
+        result = execute(json.loads(raw))
+        print(json.dumps(result, sort_keys=True))
+    except ContractError as error:
+        print(json.dumps({"status": "rejected", "error": error.detail}, sort_keys=True))
+        return 1
+    except (OSError, ValueError, TypeError):
+        # Never dump request content or provider records in process diagnostics.
+        print(
+            json.dumps(
+                {
+                    "status": "rejected",
+                    "error": {
+                        "code": "input",
+                        "message": "Invalid schema bridge input",
+                    },
+                }
+            )
+        )
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())