@withgateway/sdk 0.2.6 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/README.md +24 -8
  2. package/dist/cli.js +15468 -11263
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +15233 -11028
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +291 -40
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +284 -37
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +203 -47
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +198 -42
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-BaKu5ZSU.d.mts → index-C3UzD0G3.d.mts} +75 -1
  19. package/dist/{index-BaKu5ZSU.d.ts → index-C3UzD0G3.d.ts} +75 -1
  20. package/dist/{index-CLkMr6VG.d.ts → index-D-_4Ibcn.d.ts} +36 -4
  21. package/dist/{index-CdbmO4aX.d.mts → index-FfK4Nump.d.mts} +36 -4
  22. package/dist/index.d.mts +3 -3
  23. package/dist/index.d.ts +3 -3
  24. package/dist/index.js +2149 -615
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2053 -566
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/traces/index.js +268 -31
  29. package/dist/traces/index.js.map +1 -1
  30. package/dist/traces/index.mjs +262 -28
  31. package/dist/traces/index.mjs.map +1 -1
  32. package/dist/tracing/index.js +19 -11
  33. package/dist/tracing/index.js.map +1 -1
  34. package/dist/tracing/index.mjs +19 -11
  35. package/dist/tracing/index.mjs.map +1 -1
  36. package/dist/worlds/index.d.mts +886 -117
  37. package/dist/worlds/index.d.ts +886 -117
  38. package/dist/worlds/index.js +1770 -452
  39. package/dist/worlds/index.js.map +1 -1
  40. package/dist/worlds/index.mjs +1752 -434
  41. package/dist/worlds/index.mjs.map +1 -1
  42. package/package.json +14 -10
  43. package/runtime/gatewaysdk/environment/_toml.py +3 -10
  44. package/runtime/gatewaysdk/environment/_world.py +95 -28
  45. package/runtime/gatewaysdk/environment/runtime.py +10 -6
  46. package/runtime/gatewaysdk/environment/schema/__main__.py +35 -0
  47. package/runtime/gatewaysdk/environment/schema/api.py +19 -23
  48. package/runtime/gatewaysdk/environment/schema/batch.py +68 -14
  49. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +4 -2
  50. package/runtime/gatewaysdk/environment/schema/cast.py +264 -0
  51. package/runtime/gatewaysdk/environment/schema/compiler.py +35 -1
  52. package/runtime/gatewaysdk/environment/schema/conform.py +28 -10
  53. package/runtime/gatewaysdk/environment/schema/connector.py +59 -14
  54. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +38 -1
  55. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +3 -1
  56. package/runtime/gatewaysdk/environment/schema/credentials.py +20 -0
  57. package/runtime/gatewaysdk/environment/schema/csv_rows.py +117 -0
  58. package/runtime/gatewaysdk/environment/schema/cycles.py +121 -0
  59. package/runtime/gatewaysdk/environment/schema/data.py +21 -5
  60. package/runtime/gatewaysdk/environment/schema/grading.py +95 -13
  61. package/runtime/gatewaysdk/environment/schema/handler_errors.py +44 -0
  62. package/runtime/gatewaysdk/environment/schema/handler_scan.py +175 -0
  63. package/runtime/gatewaysdk/environment/schema/host.py +68 -115
  64. package/runtime/gatewaysdk/environment/schema/host_requests.py +78 -0
  65. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +12 -0
  66. package/runtime/gatewaysdk/environment/schema/ingest.py +5 -18
  67. package/runtime/gatewaysdk/environment/schema/local.py +7 -10
  68. package/runtime/gatewaysdk/environment/schema/openapi_document.py +322 -0
  69. package/runtime/gatewaysdk/environment/schema/openapi_import.py +382 -0
  70. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +441 -0
  71. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +629 -0
  72. package/runtime/gatewaysdk/environment/schema/openapi_source.py +210 -0
  73. package/runtime/gatewaysdk/environment/schema/platform.py +110 -299
  74. package/runtime/gatewaysdk/environment/schema/platform_import.py +182 -0
  75. package/runtime/gatewaysdk/environment/schema/platform_query.py +95 -0
  76. package/runtime/gatewaysdk/environment/schema/route_bindings.py +176 -0
  77. package/runtime/gatewaysdk/environment/schema/runtime.py +56 -7
  78. package/runtime/gatewaysdk/environment/schema/scaffold.py +64 -5
  79. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +70 -22
  80. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +54 -4
  81. package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +27 -2
  82. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +62 -0
  83. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +91 -54
  84. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +146 -146
  85. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
  86. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +30 -0
  87. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
  88. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +90 -0
  89. package/runtime/gatewaysdk/environment/schema/store.py +15 -6
  90. package/runtime/gatewaysdk/environment/schema/store_contract.py +119 -0
  91. package/runtime/gatewaysdk/environment/schema/tasks.py +121 -32
  92. package/runtime/gatewaysdk/environment/schema/tools_world.py +32 -10
  93. package/runtime/gatewaysdk/environment/schema/tree_import.py +228 -0
  94. package/runtime/gatewaysdk/environment/schema/ui.py +18 -2
  95. package/runtime/gatewaysdk/environment/schema/validation.py +35 -0
  96. package/runtime/gatewaysdk/environment/schema/verbs.py +8 -2
  97. package/runtime/gatewaysdk/environment/world.py +42 -3
  98. package/runtime/gatewaysdk/environment/world_session_contract.py +57 -0
  99. package/skills/benchmarks-getting-started/SKILL.md +70 -22
  100. package/skills/connector-schema-authoring/SKILL.md +54 -4
  101. package/skills/connector-schema-authoring/connector-worlds.md +21 -7
  102. package/skills/connector-schema-authoring/world-schema.md +144 -83
  103. package/skills/hooks-getting-started/SKILL.md +27 -2
  104. package/skills/world-data-ingestion/ROWS.md +62 -0
  105. package/skills/world-data-ingestion/SKILL.md +91 -54
  106. package/skills/worlds-getting-started/SKILL.md +146 -146
  107. package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
  108. package/skills/worlds-getting-started/references/gotchas.md +30 -0
  109. package/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
  110. package/skills/worlds-getting-started/references/openapi-import.md +90 -0
@@ -0,0 +1,182 @@
1
+ """The bridge's import commands: rows into a world's data files.
2
+
3
+ ``import-data`` takes the world as ``files`` and the rows inline, and answers with
4
+ the updated tree — the platform's lane (the MCP ``import_world_data`` over a small
5
+ tree, ``worlds create --rows``), bounded by what one request carries.
6
+
7
+ ``import-files`` is the tree door of the CLI on this machine (:class:`.tree_import.TreeImport`):
8
+ the world is a directory here (``world``), the rows files are paths here (``sources``),
9
+ opened in place and streamed — nothing travels through the request, and the answer is
10
+ the report, not the tree. Only where this runtime may run authored code
11
+ (:func:`platform.may_execute`); the platform's runtime refuses it, as it refuses ``world``.
12
+
13
+ ``chunk-files`` is the same door's other exit: the same paths, typed by the same tree,
14
+ cut into the gzipped JSONL chunks a platform data batch takes, written under ``out``
15
+ (:meth:`.tree_import.TreeImport.chunks`). It is what ``gateway worlds data chunks``
16
+ runs in the TypeScript CLI — the ``gateway`` the platform stages into a sandbox — and
17
+ so the sandbox-side half of ``gateway worlds sandbox import``. Same gate: local
18
+ runtime only.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import tempfile
24
+ from collections.abc import Callable
25
+ from pathlib import Path
26
+
27
+ from .validation import fail
28
+
29
+ WorldOpener = Callable[[dict, Path], Path]
30
+
31
+
32
+ def import_data(request: dict) -> dict:
33
+ """``import-data``: rows into a world the platform holds as files. The tree arrives
34
+ as ``[{path, content}]``, the rows as ``{entity: [row, …]}`` with a mode; the world is
35
+ rebuilt in a temporary directory, the rows go in through :func:`data.import_rows`
36
+ (the same gate the CLI uses, scratch copy first), and every file of the updated
37
+ tree comes back the way ``init-template`` returns one, so the platform commits a
38
+ version from it without knowing which file changed."""
39
+ from . import snapshot as snapshots
40
+ from .data import KIND_SCHEMA, MERGES, MODES, import_rows
41
+ from .platform import _flag, _tree, _write_files, world_root
42
+ from .redaction import parse_mode
43
+
44
+ rows = request.get("rows")
45
+ mode = request.get("mode", "append")
46
+ merge = request.get("merge", "upsert")
47
+ if not isinstance(rows, dict) or not all(isinstance(v, list) for v in rows.values()):
48
+ fail("input", "Expected rows as {entity: [row, …]}")
49
+ if mode not in MODES:
50
+ fail("input", f"mode must be one of {', '.join(MODES)}")
51
+ if merge not in MERGES:
52
+ fail("input", f"merge must be one of {', '.join(MERGES)}")
53
+ redact = parse_mode(request.get("redact"))
54
+ dry_run = _flag(request, "dry_run", False)
55
+ with tempfile.TemporaryDirectory(prefix="gateway-import-") as directory:
56
+ root = Path(directory) / "bundle"
57
+ root.mkdir()
58
+ _write_files(root, request.get("files"))
59
+ world = world_root(root)
60
+ result = import_rows(world, rows, mode=mode, merge=merge, redact=redact, dry_run=dry_run)
61
+ keys = ("kind", "entity_counts", "changed")
62
+ report = {"status": "ok", **{key: result[key] for key in keys}}
63
+ if dry_run:
64
+ return {
65
+ **report,
66
+ **{key: result[key] for key in ("proof", "deferred") if key in result},
67
+ }
68
+ if result["kind"] == KIND_SCHEMA and snapshots.default_snapshot(world).is_file():
69
+ # The journals grew; a snapshot built before this import would be
70
+ # served over them. Rebuild so the tree that travels back is one thing.
71
+ from .compiler import build
72
+ from .snapshot import build_all
73
+
74
+ build_all(world, build(world)) # build(): the contract, no snapshot audit
75
+ if world != root and result["kind"] == KIND_SCHEMA:
76
+ # The bundle's base seed is derived from the world's data; older runners post it.
77
+ from .api import write_base_seed
78
+
79
+ write_base_seed(world, root)
80
+ return {**report, "files": _tree(root)}
81
+
82
+
83
+ def _sources(request: dict, command: str) -> tuple[list[Path], str | None, str | None]:
84
+ """The rows files a local-runtime command reads: ``sources`` (absolute paths on this
85
+ machine), ``entity`` and ``delimiter``, checked; refused outright where this runtime
86
+ may not read this machine's files."""
87
+ from .platform import may_execute
88
+
89
+ if not may_execute():
90
+ fail(
91
+ "input",
92
+ f"{command} reads files on this machine; it runs through the CLI's bundled runtime, "
93
+ "never the platform (send files and rows to import-data instead)",
94
+ )
95
+ if not isinstance(request.get("world"), str):
96
+ fail(
97
+ "input",
98
+ "world must be an absolute path to a world directory on this machine",
99
+ )
100
+ sources = request.get("sources")
101
+ if (
102
+ not isinstance(sources, list)
103
+ or not sources
104
+ or not all(isinstance(s, str) and Path(s).is_absolute() for s in sources)
105
+ ):
106
+ fail("input", "sources must be absolute paths to rows files on this machine")
107
+ entity = request.get("entity")
108
+ if entity is not None and not isinstance(entity, str):
109
+ fail("input", "entity must be a string")
110
+ delimiter = request.get("delimiter")
111
+ if delimiter is not None and not isinstance(delimiter, str):
112
+ fail("input", "delimiter must be a string")
113
+ return [Path(s) for s in sources], entity, delimiter
114
+
115
+
116
+ def _count(request: dict, name: str) -> int | None:
117
+ value = request.get(name)
118
+ if value is None:
119
+ return None
120
+ if isinstance(value, bool) or not isinstance(value, int) or value < 1:
121
+ fail("input", f"{name} must be a positive integer")
122
+ return value
123
+
124
+
125
+ def import_files(request: dict, open_world: WorldOpener) -> dict:
126
+ """``import-files``: the rows files at ``sources`` (absolute paths on this machine)
127
+ into the world directory at ``world``, through :class:`.tree_import.TreeImport`:
128
+ streamed, typed by the tree's contract, capped by what a source tree carries.
129
+ ``entity``, ``delimiter``, ``mode``, ``merge``, ``redact`` and ``dry_run`` as the
130
+ CLI's flags. The answer is the import's report (``kind``, ``entity_counts``,
131
+ ``changed``, ``rows``; the proof when ``dry_run``) — the tree changed in place."""
132
+ from .data import MERGES, MODES
133
+ from .platform import _flag
134
+ from .redaction import parse_mode
135
+ from .tree_import import TreeImport
136
+
137
+ sources, entity, delimiter = _sources(request, "import-files")
138
+ mode = request.get("mode", "append")
139
+ merge = request.get("merge", "upsert")
140
+ if mode not in MODES:
141
+ fail("input", f"mode must be one of {', '.join(MODES)}")
142
+ if merge not in MERGES:
143
+ fail("input", f"merge must be one of {', '.join(MERGES)}")
144
+ redact = parse_mode(request.get("redact"))
145
+ dry_run = _flag(request, "dry_run", False)
146
+ with tempfile.TemporaryDirectory(prefix="gateway-import-files-") as directory:
147
+ root = open_world(request, Path(directory))
148
+ tree = TreeImport(root, sources, entity=entity, delimiter=delimiter)
149
+ result = tree.run(mode=mode, merge=merge, redact=redact, dry_run=dry_run)
150
+ keys = (
151
+ "kind",
152
+ "entity_counts",
153
+ "changed",
154
+ "rows",
155
+ "proof",
156
+ "deferred",
157
+ "redact",
158
+ "batch",
159
+ )
160
+ return {"status": "ok", **{key: result[key] for key in keys if key in result}}
161
+
162
+
163
+ def chunk_files(request: dict, open_world: WorldOpener) -> dict:
164
+ """``chunk-files``: the rows files at ``sources``, typed by the world directory at
165
+ ``world``, as gzipped JSONL chunk files under ``out`` (an absolute directory on this
166
+ machine, created), ``chunk_bytes`` of JSONL per chunk before gzip (or ``chunk_rows``
167
+ rows). The answer is ``worlds data chunks``' report: ``rows`` and the chunks'
168
+ ``ordinal``, ``path``, ``rows``, ``bytes``, ``digest``, ``entity``."""
169
+ from .tree_import import TreeImport
170
+
171
+ sources, entity, delimiter = _sources(request, "chunk-files")
172
+ out = request.get("out")
173
+ if not isinstance(out, str) or not Path(out).is_absolute():
174
+ fail("input", "out must be an absolute path to a directory on this machine")
175
+ chunk_bytes = _count(request, "chunk_bytes")
176
+ chunk_rows = _count(request, "chunk_rows")
177
+ with tempfile.TemporaryDirectory(prefix="gateway-chunk-files-") as directory:
178
+ root = open_world(request, Path(directory))
179
+ tree = TreeImport(root, sources, entity=entity, delimiter=delimiter)
180
+ Path(out).mkdir(parents=True, exist_ok=True)
181
+ chunks = tree.chunks(Path(out), chunk_bytes=chunk_bytes, chunk_rows=chunk_rows)
182
+ return {"status": "ok", **TreeImport.chunk_report(chunks)}
@@ -0,0 +1,95 @@
1
+ """The bridge's read commands over a world's rows: ``counts`` and ``query``.
2
+
3
+ Both open the world through the ``open_world`` collaborator the dispatcher hands
4
+ them (:func:`platform._world_for`): inline ``files`` (small trees), a
5
+ ``workdir`` the platform prepared with the tree and any checked-out snapshot
6
+ already on disk (large trees; nothing travels through the request), or a local
7
+ ``world`` directory where this runtime may run authored code — and answer from
8
+ its compiled snapshot when it carries one, from its data files otherwise. The
9
+ prepared workdir is the caller's: opened in place, never copied, never removed
10
+ here.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import tempfile
16
+ from pathlib import Path
17
+ from typing import Callable
18
+
19
+ from .data import entity_counts, entity_query, entity_query_across, entity_rows, world_kind
20
+ from .validation import ContractError, fail
21
+
22
+ # (request, staging directory) -> the world root to read; the staging directory
23
+ # is where inline ``files`` are written and is gone when the command returns.
24
+ WorldOpener = Callable[[dict, Path], Path]
25
+
26
+
27
+ def counts(request: dict, open_world: WorldOpener) -> dict:
28
+ """``counts``: what the world seeds with. A kind whose seed lives elsewhere (a
29
+ harbor tree, an unknown layout) answers with the reason instead of a rejection,
30
+ so the caller can show it."""
31
+ entity = request.get("entity")
32
+ if entity is not None and not isinstance(entity, str):
33
+ fail("input", "entity must be a string")
34
+ with tempfile.TemporaryDirectory(prefix="gateway-counts-") as directory:
35
+ root = open_world(request, Path(directory))
36
+ kind = world_kind(root)
37
+ try:
38
+ found = entity_counts(root)
39
+ except ContractError as error:
40
+ if error.detail.get("code") != "kind":
41
+ raise
42
+ return {"status": "ok", "kind": kind, "entity_counts": None, "reason": error.detail["message"]}
43
+ report = {"status": "ok", "kind": kind, "entity_counts": found}
44
+ if entity is not None:
45
+ report["rows"] = entity_rows(root, entity)
46
+ return report
47
+
48
+
49
+ def query(request: dict, open_world: WorldOpener) -> dict:
50
+ """``query``: the rows of one entity that match ``where`` (a field to a value or
51
+ a list of values), a page at a time (``limit``, ``offset``). With ``resolve``,
52
+ each value is plaintext and is looked up in the forms the world's ``[redact]``
53
+ policy stores (:func:`data.entity_query`). A tree that carries its compiled
54
+ ``db/state.sqlite`` (a checked-out snapshot) answers from the snapshot, as
55
+ ``counts`` does; otherwise from its data files. With ``across`` (local runtime
56
+ only: ``world`` is a directory here, so its ``[dependencies]`` paths resolve) the
57
+ answer is :func:`data.entity_query_across`'s groups, one per linked world a
58
+ mapping carries a ``where`` field into."""
59
+ entity = request.get("entity")
60
+ if not isinstance(entity, str) or not entity:
61
+ fail("input", "entity must be a non-empty string")
62
+ where = request.get("where", {})
63
+ if not isinstance(where, dict):
64
+ fail("input", "where must be an object mapping a field to a value or a list of values")
65
+ resolve = request.get("resolve", False)
66
+ if not isinstance(resolve, bool):
67
+ fail("input", "resolve must be a boolean")
68
+ # The platform's cross-world query sends the mapping's transform chain per field
69
+ # under this key (worldDataQueryService.ts BRIDGE_WHERE_TRANSFORM_KEY).
70
+ where_transform = request.get("where_transform")
71
+ if where_transform is not None and not isinstance(where_transform, dict):
72
+ fail("input", "where_transform must be an object mapping a field to a list of transform names")
73
+ across = request.get("across", False)
74
+ compare = request.get("compare", False)
75
+ if not isinstance(across, bool) or not isinstance(compare, bool):
76
+ fail("input", "across and compare must be booleans")
77
+ if compare and not across:
78
+ fail("input", "compare needs across")
79
+ if across and request.get("world") is None:
80
+ fail("input", "across reads the linked worlds at their paths, so it takes world (a directory), not files")
81
+ scenario = request.get("scenario")
82
+ if scenario is not None and (not isinstance(scenario, str) or not scenario):
83
+ fail("input", "scenario must be a non-empty string", "/scenario")
84
+ page = {"limit": request.get("limit", 100), "offset": request.get("offset", 0)}
85
+ with tempfile.TemporaryDirectory(prefix="gateway-query-") as directory:
86
+ root = open_world(request, Path(directory))
87
+ if across:
88
+ report = entity_query_across(
89
+ root, entity, where, **page, resolve=resolve, compare=compare, scenario=scenario
90
+ )
91
+ return {"status": "ok", "kind": world_kind(root), **report}
92
+ report = entity_query(
93
+ root, entity, where, **page, resolve=resolve, where_transform=where_transform, scenario=scenario
94
+ )
95
+ return {"status": "ok", "kind": world_kind(root), **report}
@@ -0,0 +1,176 @@
1
+ """What a connector route's path arguments and query parameters bind to
2
+ (zero-context round 2, W2 and W5).
3
+
4
+ A ``{segment}`` of a route path is an argument the served route receives. It
5
+ binds when something names it: a top-level field of the route's entity
6
+ (``GET /records/{id}`` reads the row keyed so, ``/records/by-email/{email}``
7
+ the rows carrying that email), a ``filter`` mapping, an ``ingest.carry_args``
8
+ source, an ``api.sample`` value, or a ``params`` declaration (a scope segment
9
+ such as ``/accounts/{account}/records`` that selects nothing but must be
10
+ sent). A handler route reads its own arguments.
11
+ Anything else is a typo or a forgotten declaration, and
12
+ ``/items/{id}/{undeclared_param}`` used to compile, check and serve as if the
13
+ segment did not exist.
14
+
15
+ A query parameter that names a top-level field of the entity filters a read
16
+ route without a ``filter`` of its own, the way every vendor's list endpoint
17
+ reads (``GET /records?kind=invoice``); the served route (``api.py``) applies
18
+ that to every name the caller sends, declared or not, except the pager's own
19
+ (``[api].limit_param`` and friends). :func:`implied_filters` is the
20
+ declaration-time statement of the same rule over the declared parameters, so an
21
+ import plan and ``route add`` can say which of them filter and which pass
22
+ through to the pager or the handler.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ from dataclasses import dataclass
28
+ from pathlib import Path
29
+
30
+ from .api import FILTER_KEY, OperationSettings, operation_api_settings
31
+ from .compiler import Contract
32
+ from .connector import SPEC, Operation, Spec, spec_from
33
+ from .validation import fail, parse_toml
34
+
35
+
36
+ def operation_settings(raw: dict, spec: Spec) -> dict[str, OperationSettings]:
37
+ """Every operation's ``[operations.api]`` table (``api.operation_api_settings``), by name."""
38
+ entries = enumerate(raw.get("operations", []))
39
+ return {
40
+ e["name"]: operation_api_settings(e, spec.operations[e["name"]], f"/operations/{i}/api") for i, e in entries
41
+ }
42
+
43
+
44
+ PAGERS = ("limit", "offset", "cursor")
45
+
46
+
47
+ def paging_names(raw: dict) -> frozenset[str]:
48
+ """The query names the world's pager owns (``[api].limit_param`` and friends,
49
+ at their defaults when unset); the served route never filters on them."""
50
+ api = raw.get(FILTER_KEY)
51
+ table = api if isinstance(api, dict) else {}
52
+ return frozenset(str(table.get(f"{name}_param", name)) for name in PAGERS)
53
+
54
+
55
+ def entity_fields(contract: Contract, entity: str | None) -> set[str]:
56
+ declared = contract.entities.get(entity or "")
57
+ return set((declared or {}).get("schema", {}).get("properties", {}))
58
+
59
+
60
+ def key_fields(contract: Contract, entity: str | None) -> set[str]:
61
+ declared = contract.entities.get(entity or "")
62
+ return set((declared or {}).get("primary_key", ()))
63
+
64
+
65
+ def implied_filters(
66
+ operation: Operation, op: OperationSettings, contract: Contract, paging: frozenset[str] = frozenset(PAGERS)
67
+ ) -> dict[str, str]:
68
+ """Argument -> row field the served route filters on without an explicit
69
+ ``filter``: each path segment, and on a read route each declared query
70
+ parameter, naming a top-level field of the entity (``api._segment_filter``
71
+ and ``api._query_field_filter``). The pager's names (``paging``) and names
72
+ the entity does not declare imply nothing."""
73
+ if op.filter or not operation.entity:
74
+ return {}
75
+ fields = entity_fields(contract, operation.entity)
76
+ queries = [p for p in operation.params if p not in paging] if op.action == "read" else []
77
+ return {name: name for name in (*operation.placeholders, *queries) if name in fields}
78
+
79
+
80
+ @dataclass(frozen=True)
81
+ class RouteBinding:
82
+ """One route against the contract it serves."""
83
+
84
+ index: int
85
+ operation: Operation
86
+ op: OperationSettings
87
+ contract: Contract
88
+
89
+ @property
90
+ def location(self) -> str:
91
+ return f"/operations/{self.index}/path"
92
+
93
+ @property
94
+ def bound(self) -> set[str]:
95
+ return (
96
+ set(self.operation.params)
97
+ | set(self.op.filter)
98
+ | set(self.operation.carry_args.values())
99
+ | set(self.op.sample)
100
+ | entity_fields(self.contract, self.operation.entity)
101
+ )
102
+
103
+ @property
104
+ def unbound(self) -> list[str]:
105
+ if self.op.action == "handler":
106
+ return []
107
+ return [name for name in self.operation.placeholders if name not in self.bound]
108
+
109
+ def check(self) -> None:
110
+ unbound = self.unbound
111
+ if not unbound:
112
+ return
113
+ name = unbound[0]
114
+ entity = self.operation.entity
115
+ reason = (
116
+ "the route has no entity, so nothing reads it"
117
+ if entity is None
118
+ else f"it is not a field of {entity} and no filter maps it"
119
+ )
120
+ remedy = f"declare it with `--param {name}` (a scope segment the caller must send)"
121
+ if entity is not None:
122
+ remedy += f", or map it with `--filter {name}=<field of {entity}>`"
123
+ fail(
124
+ "spec",
125
+ f"{{{name}}} in {SPEC} path {self.operation.path} binds nothing: {reason}; {remedy}",
126
+ self.location,
127
+ argument=name,
128
+ )
129
+
130
+
131
+ class RouteBindings:
132
+ """Every route of a world's connector.toml against its compiled contract."""
133
+
134
+ def __init__(
135
+ self,
136
+ spec: Spec,
137
+ settings: dict[str, OperationSettings],
138
+ contract: Contract,
139
+ paging: frozenset[str] = frozenset(PAGERS),
140
+ ):
141
+ self.spec = spec
142
+ self.settings = settings
143
+ self.contract = contract
144
+ self.paging = paging
145
+
146
+ @classmethod
147
+ def load(cls, bundle: Path, contract: Contract) -> RouteBindings | None:
148
+ path = bundle / SPEC
149
+ if not path.is_file():
150
+ return None
151
+ raw = parse_toml(path.read_text(encoding="utf-8"))
152
+ spec = spec_from(raw)
153
+ return cls(spec, operation_settings(raw, spec), contract, paging_names(raw))
154
+
155
+ def __iter__(self):
156
+ for index, operation in enumerate(self.spec.operations.values()):
157
+ op = self.settings.get(operation.name, OperationSettings())
158
+ yield RouteBinding(index, operation, op, self.contract)
159
+
160
+ def check(self) -> None:
161
+ for binding in self:
162
+ binding.check()
163
+
164
+ def filters(self) -> dict[str, dict[str, str]]:
165
+ """Operation -> the query filters it implies (:func:`implied_filters`), for the
166
+ operations that imply any."""
167
+ found = {b.operation.name: implied_filters(b.operation, b.op, self.contract, self.paging) for b in self}
168
+ return {name: filters for name, filters in found.items() if filters}
169
+
170
+
171
+ def check_route_bindings(bundle: Path, contract: Contract) -> None:
172
+ """Refuse a connector.toml whose route has an unbound path argument; a world
173
+ without a connector.toml has no routes to check."""
174
+ bindings = RouteBindings.load(bundle, contract)
175
+ if bindings is not None:
176
+ bindings.check()
@@ -38,7 +38,7 @@ from .api import WorldApp, WorldState, operation_request, vendor_credential, wit
38
38
  from .dependencies import Dependency
39
39
  from .grading import Grade, GraderError, TaskGrader
40
40
  from .snapshot import SCENARIOS
41
- from .tasks import TASK_DIR, TaskSpec, unknown_task_entities, write_task_dir
41
+ from .tasks import TASK_DIR, TaskSpec, unknown_task_entities, verifier_source, write_task_dir
42
42
  from .tools_world import DependencyWorld, ToolsWorld, ToolsWorldState, inline_task, served_with_dependencies
43
43
  from .validation import fail
44
44
  from .workers import ConfinedVerifierSandbox
@@ -248,33 +248,61 @@ class WorldRuntime(ABC):
248
248
  state["report"] = report
249
249
  return state
250
250
 
251
- def grade(self, report: Optional[str] = None) -> dict:
251
+ def grade(self, report: Optional[str] = None, context: Optional[dict] = None) -> dict:
252
252
  """One grader path. The session's own task grades by its grader —
253
253
  assertions in process, verify.py confined like a worker, a rubric
254
254
  pending on the platform (the host has no model, no key and no business
255
255
  calling one from a tenant's session) — over the same state dump
256
256
  whatever the world's shape. A bundled task grades by the version's own
257
- graders."""
257
+ graders.
258
+
259
+ The task's cross-world verifiers anchored here grade next, each over
260
+ :meth:`TaskGrader.evidence` of this state and ``context`` (the other
261
+ scoped worlds' states, ``{alias: state}``, gathered by the platform),
262
+ and answer under ``verifiers`` by name — apart from the world's own
263
+ ``reward``, so a task aggregate counts each once. A verifier that
264
+ cannot grade (evidence missing, verify.py failed) answers null with
265
+ its ``error``; the world's own grade still stands."""
266
+ own = self._own_grade(report)
267
+ verifiers = self._verifiers()
268
+ if not verifiers:
269
+ return own
270
+ state = self.grader_state(report)
271
+ graded = {grader.name: self._verifier_grade(grader, state, context or {}) for grader in verifiers}
272
+ return {**own, "verifiers": graded}
273
+
274
+ def _own_grade(self, report: Optional[str]) -> dict:
275
+ """The session task's grade by its own grader, or null with the reason
276
+ when it has none; a bundled task's by the version's own graders."""
258
277
  spec = self.task_spec
259
- if spec is None or spec.grader is None:
278
+ if spec is None:
260
279
  bundled = self.bundled_grade()
261
280
  if bundled is not None:
262
281
  return bundled
263
282
  grader = self._task_grader(spec)
264
283
  if grader is None:
265
- return Grade(None).as_dict()
284
+ return Grade.ungraded().as_dict()
266
285
  try:
267
286
  return grader.grade(self.grader_state(report)).as_dict()
268
287
  except GraderError as error:
269
288
  fail("host", str(error))
270
289
  raise AssertionError # fail() never returns
271
290
 
291
+ @staticmethod
292
+ def _verifier_grade(grader: TaskGrader, state: dict, context: dict) -> dict:
293
+ try:
294
+ return grader.grade(grader.evidence(state, context)).as_dict()
295
+ except GraderError as error:
296
+ return {**Grade(None).as_dict(), "error": str(error)}
297
+
298
+ def _sandbox(self) -> tuple[ConfinedVerifierSandbox, Path]:
299
+ return ConfinedVerifierSandbox(), self.session_dir / "verify"
300
+
272
301
  def _task_grader(self, spec: Optional[TaskSpec]) -> Optional[TaskGrader]:
273
302
  """The session's grader: the spec's, with its verify.py where
274
303
  :func:`write_task_dir` put it; else the bundled task's verify.py; else
275
304
  none (an ungraded task grades null)."""
276
- sandbox = ConfinedVerifierSandbox()
277
- home = self.session_dir / "verify"
305
+ sandbox, home = self._sandbox()
278
306
  if spec is not None:
279
307
  if spec.grader is None:
280
308
  return None
@@ -285,6 +313,27 @@ class WorldRuntime(ABC):
285
313
  return None
286
314
  return TaskGrader.for_verifier(verify, sandbox=sandbox, home=home)
287
315
 
316
+ def _verifiers(self) -> list[TaskGrader]:
317
+ """The task's cross-world verifiers anchored on this session, each a
318
+ scoped :class:`TaskGrader` with its verify.py where
319
+ :func:`write_task_dir` put it."""
320
+ spec = self.task_spec
321
+ if spec is None:
322
+ return []
323
+ sandbox, home = self._sandbox()
324
+ task_dir = self.session_dir / TASK_DIR
325
+ return [
326
+ TaskGrader(
327
+ {k: v for k, v in row.items() if k not in ("name", "scope")},
328
+ verify=verifier_source(task_dir, row["name"]),
329
+ sandbox=sandbox,
330
+ home=home / row["name"],
331
+ scope=row["scope"],
332
+ name=row["name"],
333
+ )
334
+ for row in spec.verifiers
335
+ ]
336
+
288
337
  def call(self, tool: str, args: dict) -> dict:
289
338
  """One name of what the session serves: a tool by name (a dependency's
290
339
  as ``alias.tool``); on a tree with connector.toml, an operation by name
@@ -8,11 +8,14 @@ no records and is filled by ingestion or by hand-authored fixture batches.
8
8
 
9
9
  from __future__ import annotations
10
10
 
11
+ import base64
12
+ import binascii
11
13
  import json
12
14
  import shutil
13
15
  from pathlib import Path
14
16
 
15
17
  from .compiler import Contract, compile_bundle
18
+ from .store_contract import describe_store
16
19
  from .validation import ContractError, encoded, fail, read_json
17
20
 
18
21
  TEMPLATES = Path(__file__).resolve().parent / "connectors"
@@ -37,9 +40,10 @@ VERIFIER = """-- Scores 1.0 once the world holds any {entity} row; edit for real
37
40
  -- refuses this file until the FROM is edited or the file is deleted with it.
38
41
  SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "{entity}";
39
42
  """
40
- #: The custom scaffold's handler module without the example tools: an author
41
- #: declares tools in schema/world.json and gateway-env.toml, then writes them here.
42
- CUSTOM_HANDLERS = '''"""Custom connector world tools; keep writes on the store.
43
+ #: The docstring of every scaffolded custom ``tools/handlers.py``: how to bind a
44
+ #: tool, and the store contract in full (``{store}`` is filled from the real
45
+ #: store class by :func:`custom_handlers_doc`, so it cannot drift).
46
+ CUSTOM_HANDLERS_DOC = '''"""Custom connector world tools; keep writes on the store.
43
47
 
44
48
  Declare each tool under x-gateway.tools in schema/world.json and in
45
49
  [tools].serve of gateway-env.toml, then implement it here:
@@ -50,11 +54,45 @@ Declare each tool under x-gateway.tools in schema/world.json and in
50
54
  def list_records(kind):
51
55
  return [r for r in store.list("records") if r["kind"] == kind]
52
56
 
53
- `schema init --connector custom --with-example-tool` writes that example in full.
57
+ `store` (from gateway_env) is the world's rows. It offers exactly these methods;
58
+ `gateway worlds schema check .` refuses any other `store.<name>` at file:line, and a
59
+ hosted call into such a handler answers 400 {error: "handler", detail, handler}:
60
+
61
+ {store}
62
+
63
+ A handler that raises AttributeError, TypeError or NameError is answered 400 with
64
+ that structured body; any other exception is answered 500 {error: "engine", ...}.
65
+ `schema init --connector custom --with-example-tool` writes the example in full.
54
66
  """
55
67
  '''
56
68
 
57
69
 
70
+ #: Where the template module's docstring ends and its example tools begin.
71
+ _DOCSTRING_END = '\n"""\n'
72
+
73
+
74
+ def custom_handlers_doc() -> str:
75
+ """The scaffolded handler module's docstring with the store contract filled in."""
76
+ return CUSTOM_HANDLERS_DOC.replace("{store}", describe_store(" "))
77
+
78
+
79
+ def custom_handlers_template_source(template_handlers: bytes) -> bytes:
80
+ """The template ``custom/handlers.py`` as it must read: the generated docstring
81
+ above its example tools. A test pins the checked-in template to this, so
82
+ regenerate it from here when the store contract changes."""
83
+ _, _, body = template_handlers.decode("utf-8").partition(_DOCSTRING_END)
84
+ return (custom_handlers_doc() + body).encode("utf-8")
85
+
86
+
87
+ def custom_handlers_source(template_handlers: bytes, with_example_tool: bool) -> bytes:
88
+ """The ``tools/handlers.py`` a custom world starts with: the template in full,
89
+ or its contract docstring alone."""
90
+ if with_example_tool:
91
+ return template_handlers
92
+ doc, end, _ = template_handlers.decode("utf-8").partition(_DOCSTRING_END)
93
+ return (doc + end).encode("utf-8")
94
+
95
+
58
96
  def list_templates() -> list[str]:
59
97
  """Connector slugs that ``init_bundle`` accepts, custom last."""
60
98
  slugs = sorted(p.name for p in TEMPLATES.iterdir() if (p / "world.json").is_file())
@@ -257,7 +295,7 @@ def init_bundle(
257
295
  world["$id"] = f"urn:gateway:connector:{name}"
258
296
  if not with_example_tool:
259
297
  world["x-gateway"]["tools"] = {}
260
- handlers = CUSTOM_HANDLERS.encode("utf-8")
298
+ handlers = custom_handlers_source(handlers, with_example_tool)
261
299
  tools = sorted(world["x-gateway"]["tools"])
262
300
  try:
263
301
  (destination / "schema").mkdir(parents=True)
@@ -316,3 +354,24 @@ def _pretty(value) -> bytes:
316
354
 
317
355
 
318
356
  __all__ = ["CUSTOM", "TEMPLATES", "ContractError", "init_bundle", "list_templates"]
357
+
358
+
359
+ def request_files(request: dict) -> dict[str, bytes]:
360
+ """The ``files: [{path, content}]`` of a bridge request as ``{path: bytes}``:
361
+ what ``init_bundle_from_files`` and the template readers consume."""
362
+ listed = request.get("files")
363
+ if not isinstance(listed, list) or not listed:
364
+ fail("input", "Expected the template's files as [{path, content}]")
365
+ files: dict[str, bytes] = {}
366
+ for entry in listed:
367
+ if (
368
+ not isinstance(entry, dict)
369
+ or not isinstance(entry.get("path"), str)
370
+ or not isinstance(entry.get("content"), str)
371
+ ):
372
+ fail("input", "Each template file is {path, content} with base64 content")
373
+ try:
374
+ files[entry["path"]] = base64.b64decode(entry["content"], validate=True)
375
+ except (ValueError, binascii.Error):
376
+ fail("input", "Template file content must be base64")
377
+ return files