@withgateway/sdk 0.3.0 → 0.3.3

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 (130) hide show
  1. package/README.md +6 -1
  2. package/dist/cli.js +3971 -2338
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +3950 -2318
  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 +214 -41
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +206 -35
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-DAb-FCMg.d.ts → index-DUHmS74p.d.ts} +3 -13
  13. package/dist/{index-D6oi1TWE.d.mts → index-mJhG3vZU.d.mts} +3 -13
  14. package/dist/index.d.mts +4 -4
  15. package/dist/index.d.ts +4 -4
  16. package/dist/index.js +1456 -564
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1433 -557
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  21. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  22. package/dist/traces/index.d.mts +1 -1
  23. package/dist/traces/index.d.ts +1 -1
  24. package/dist/traces/index.js +211 -38
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +203 -32
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.d.mts +2 -2
  29. package/dist/tracing/index.d.ts +2 -2
  30. package/dist/tracing/index.js +96 -21
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +96 -21
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +300 -123
  35. package/dist/worlds/index.d.ts +300 -123
  36. package/dist/worlds/index.js +1385 -508
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1377 -501
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  42. package/runtime/gatewaysdk/environment/_materialize.py +49 -69
  43. package/runtime/gatewaysdk/environment/_world.py +122 -197
  44. package/runtime/gatewaysdk/environment/backing.py +137 -0
  45. package/runtime/gatewaysdk/environment/core.py +1 -1
  46. package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
  47. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  48. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  49. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  50. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  51. package/runtime/gatewaysdk/environment/schema/api.py +266 -515
  52. package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
  53. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  54. package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
  55. package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
  56. package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
  57. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  58. package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
  59. package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
  60. package/runtime/gatewaysdk/environment/schema/data.py +50 -207
  61. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  62. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  63. package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
  64. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  65. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  66. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  67. package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
  68. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  69. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  70. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  71. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  72. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  73. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
  74. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  75. package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
  76. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  77. package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
  78. package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
  79. package/runtime/gatewaysdk/environment/schema/host.py +158 -250
  80. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  81. package/runtime/gatewaysdk/environment/schema/local.py +44 -71
  82. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  83. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  84. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  85. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  86. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  87. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  88. package/runtime/gatewaysdk/environment/schema/platform.py +124 -178
  89. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  91. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  92. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  93. package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
  94. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  95. package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
  96. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
  97. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +22 -14
  98. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
  99. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +16 -16
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +18 -18
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  102. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
  103. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  104. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  105. package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
  106. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  107. package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
  108. package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
  109. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  110. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  111. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  112. package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
  113. package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
  114. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  115. package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
  116. package/runtime/gatewaysdk/environment/score.py +57 -0
  117. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  118. package/runtime/gatewaysdk/environment/world.py +42 -3
  119. package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
  120. package/skills/benchmarks-getting-started/SKILL.md +2 -2
  121. package/skills/connector-schema-authoring/SKILL.md +22 -14
  122. package/skills/connector-schema-authoring/connector-worlds.md +26 -10
  123. package/skills/connector-schema-authoring/world-schema.md +111 -51
  124. package/skills/world-data-ingestion/ROWS.md +29 -3
  125. package/skills/world-data-ingestion/SKILL.md +16 -16
  126. package/skills/worlds-getting-started/SKILL.md +18 -18
  127. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  128. package/skills/worlds-getting-started/references/gotchas.md +15 -0
  129. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  130. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -0,0 +1,166 @@
1
+ """The files a session's store opens without auditing every row again.
2
+
3
+ A version's :class:`ProvenTemplate` is the file every session of the version
4
+ starts from. Its rows are proven once, when the host caches the version; an
5
+ open or a reset clones it and the store runs only its contract and DDL check.
6
+ A :class:`SessionExport` is a checkpoint a session continues from: its bytes
7
+ must hash to the sha256 the platform recorded when the host exported it, and
8
+ it carries the session's call log beside the rows.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ import os
15
+ import uuid
16
+ from pathlib import Path
17
+ from typing import NamedTuple
18
+
19
+ from .._materialize import materialize_template
20
+ from .compiler import Contract
21
+ from .database import WorldDatabase
22
+ from .snapshot import contract_hash, file_sha256, runtime_version
23
+ from .validation import fail
24
+
25
+ _PROVEN = object()
26
+
27
+
28
+ def refuse_digest_mismatch(path: Path, sha256: str) -> None:
29
+ """Refuse a session export whose bytes do not hash to the sha256 recorded for them."""
30
+ actual = file_sha256(path)
31
+ if actual != sha256.lower():
32
+ fail("host", f"session export checksum mismatch: expected {sha256}, got {actual}")
33
+
34
+
35
+ class ProvenTemplate:
36
+ """The file every session of a version starts from, its rows proven once.
37
+
38
+ When the host caches a version the template is built through the store (every
39
+ row audited as it was written), copied from the snapshot the host fetched and
40
+ verified against the sha256 the platform recorded, or copied from the tree's own
41
+ ``db/state.sqlite`` and audited in full there and then: a sidecar the tree wrote
42
+ is its author's claim, not a proof. The proof beside the file names its sha256,
43
+ the contract and the runtime, so a later build (a restart, the version's worker)
44
+ trusts the same bytes without a second audit, and builds any other bytes afresh.
45
+ What it names is fixed once :meth:`prove` returns."""
46
+
47
+ __slots__ = ("_path", "_contract")
48
+
49
+ def __init__(self, path: Path, contract: Contract, proof: object) -> None:
50
+ if proof is not _PROVEN:
51
+ raise TypeError("a ProvenTemplate comes from ProvenTemplate.prove")
52
+ self._path = Path(path)
53
+ self._contract = contract
54
+
55
+ @property
56
+ def path(self) -> Path:
57
+ return self._path
58
+
59
+ @property
60
+ def contract(self) -> Contract:
61
+ return self._contract
62
+
63
+ @staticmethod
64
+ def required(template: object) -> ProvenTemplate:
65
+ """``template`` itself, refused unless :meth:`prove` made it."""
66
+ if not isinstance(template, ProvenTemplate):
67
+ raise TypeError("a world opens unaudited only on a ProvenTemplate (ProvenTemplate.prove)")
68
+ return template
69
+
70
+ @classmethod
71
+ def prove(cls, bundle: Path, path: Path, contract: Contract, *, fetched: bool) -> ProvenTemplate:
72
+ """The version's template at ``path``. ``fetched`` says the tree's snapshot is
73
+ the platform's, downloaded and verified against its recorded sha256 just now."""
74
+ template = cls(path, contract, _PROVEN)
75
+ if not template._recorded():
76
+ template._build(bundle, fetched=fetched)
77
+ return template
78
+
79
+ @property
80
+ def proof_path(self) -> Path:
81
+ return self.path.with_name(f"{self.path.name}.proof.json")
82
+
83
+ def _proof(self) -> dict[str, str]:
84
+ return {
85
+ "sha256": file_sha256(self.path),
86
+ "contractHash": contract_hash(self.contract),
87
+ "runtime": runtime_version(),
88
+ }
89
+
90
+ def _recorded(self) -> bool:
91
+ try:
92
+ recorded = json.loads(self.proof_path.read_text(encoding="utf-8"))
93
+ except (OSError, ValueError):
94
+ return False
95
+ return self.path.is_file() and recorded == self._proof()
96
+
97
+ def _build(self, bundle: Path, *, fetched: bool) -> None:
98
+ staging = self.path.with_name(f".{self.path.name}.{uuid.uuid4().hex}")
99
+ try:
100
+ copied = materialize_template(bundle, staging, require_sql=True) is not None
101
+ if copied and not fetched:
102
+ WorldDatabase.open(staging, self.contract).close()
103
+ os.replace(staging, self.path)
104
+ finally:
105
+ staging.unlink(missing_ok=True)
106
+ record = self.proof_path.with_name(f".{self.proof_path.name}.{uuid.uuid4().hex}")
107
+ record.write_text(json.dumps(self._proof(), sort_keys=True) + "\n", encoding="utf-8")
108
+ os.replace(record, self.proof_path)
109
+
110
+
111
+ class ExportFile(NamedTuple):
112
+ """A session export on this host's disk and the sha256 the platform recorded for it."""
113
+
114
+ path: Path
115
+ sha256: str
116
+
117
+ def for_worker(self) -> dict[str, str]:
118
+ return {"path": str(self.path), "sha256": self.sha256}
119
+
120
+
121
+ _VERIFIED = object()
122
+
123
+
124
+ class SessionExport:
125
+ """A checkpoint the host continues a session from, verified where it is opened.
126
+
127
+ The bytes hash to the sha256 the platform recorded when the host exported them,
128
+ so they are the store's own copy, every row audited as it committed, and the
129
+ session opens on them without a second row audit. :meth:`verified` is the only
130
+ way to get one. The call log rides in the file as ``_gateway_calls``, a table the
131
+ store never opens: :meth:`carry_calls` writes it into a fresh export, and
132
+ :meth:`verified` reads it back and drops it before the store sees the file. What
133
+ it names is fixed once :meth:`verified` returns."""
134
+
135
+ __slots__ = ("_path", "_calls")
136
+
137
+ def __init__(self, path: Path, calls: list[dict], proof: object) -> None:
138
+ if proof is not _VERIFIED:
139
+ raise TypeError("a SessionExport comes from SessionExport.verified")
140
+ self._path = Path(path)
141
+ self._calls = tuple(calls)
142
+
143
+ @property
144
+ def path(self) -> Path:
145
+ return self._path
146
+
147
+ @property
148
+ def calls(self) -> list[dict]:
149
+ return list(self._calls)
150
+
151
+ @staticmethod
152
+ def required(export: object) -> SessionExport:
153
+ """``export`` itself, refused unless :meth:`verified` made it."""
154
+ if not isinstance(export, SessionExport):
155
+ raise TypeError("a session resumes only from a SessionExport (SessionExport.verified)")
156
+ return export
157
+
158
+ @classmethod
159
+ def verified(cls, export: ExportFile, engine: type[WorldDatabase]) -> SessionExport:
160
+ refuse_digest_mismatch(export.path, export.sha256)
161
+ calls = [json.loads(entry) for entry in engine.take_entries(export.path)]
162
+ return cls(export.path, calls, _VERIFIED)
163
+
164
+ @staticmethod
165
+ def carry_calls(path: Path, calls: list[dict], engine: type[WorldDatabase]) -> None:
166
+ engine.carry_entries(path, [json.dumps(call, sort_keys=True) for call in calls])
@@ -407,8 +407,8 @@ reward: 0 {"ticket_closed":0}
407
407
  reward is for the untouched world; an agent's rollout is what `benchmarks run` grades. Drive one by hand: …
408
408
  ```
409
409
 
410
- A verifier that cannot run — bad SQL, a missing entity — prints `FAIL verifier 'x': …` with SQLite's
411
- words and exits 1; that is what the dry run is for. A reward of 1.0 here means the verifier passes
410
+ A verifier that cannot run — bad SQL, a missing entity — prints `FAIL verifier 'x': …` with the database
411
+ engine's words and exits 1; that is what the dry run is for. A reward of 1.0 here means the verifier passes
412
412
  before any agent acts: rewrite it. Without the bundled runtime (no python3 >= 3.12) the four steps
413
413
  print and the run is marked not executed, exit 0.
414
414
 
@@ -41,7 +41,7 @@ registration, a platform builder, live ingestion, tools, or a registry framework
41
41
  ## The rules that never bend
42
42
 
43
43
  - **The schema is the deliverable.** A world with a faithful model and no tools is complete. Tools are added when wanted, by whoever wants them.
44
- - **Every write goes through the schema.** Handlers use `gateway_env.store`; ingestion uses `store.apply_batch` or `store.ingest`; nothing else writes. Out-of-contract writes are rejected with the reason.
44
+ - **Every write goes through the schema.** Handlers use `gateway_env.store`; ingestion uses `store.apply_batch` or `store.ingest`; nothing else writes. Out-of-contract writes are rejected with the reason (one known gap: never name an ingest session's `TEMP` staging table after a world table; see `world-schema.md`, Raw ingestion).
45
45
  - **Check the right boundary.** Compile/check validate compiled artifacts; materialization and store operations validate persisted data. Publication checks actual bundle bytes, handler declarations and initial state through the trusted runtime. Fidelity evidence and Environment Actions remain advisory.
46
46
  - **Fidelity shape is decided by the vendor, not by a house rule.** A **base** connector is prebaked once (Slack). A **tenant-shaped** connector's model is mostly customer-defined, so describe at bind time is required (Salesforce, NetSuite, Workday). A **mixed** connector is a base plus an optional overlay (Okta, Entra, Google, LDAP, Jamf).
47
47
  - **Surface parity is advisory.** If the world declares it mirrors an MCP surface, produce the parity report and show it. Never block on it, never shrink or bend the model to satisfy it.
@@ -55,7 +55,7 @@ registration, a platform builder, live ingestion, tools, or a registry framework
55
55
  | Command or path | Status |
56
56
  | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
57
57
  | `gateway worlds schema init PATH --connector <slug> [--name NAME] [--with-example-tool]` | exists (#219); `--connector custom` is the blank starting point for an arbitrary connector: its `$id` is derived from `--name` (`urn:gateway:connector:<name>`), it ships the `records` entity and a starter verifier but no tools unless `--with-example-tool` asks for the `list_records`/`get_record`/`create_record` example, and it writes no `data/records.json` (Brex retrospective, 2026-09-14) |
58
- | `gateway worlds schema init PATH --from-openapi SOURCE [--plan-only] [--include GLOB\|TAG]… [--exclude GLOB\|TAG]…` | exists (2026-09-22); imports a Swagger 2.0 / OpenAPI 3.x document (JSON or YAML; a local path, `drive:<path>` read platform-side, or an http(s) URL) into `schema/world.json` + `connector.toml` + `schema/provenance.json`: keyed schemas the selected operations return become entities, every path+method a route (passthrough when the response is not an entity), the plan is printed first and `--plan-only` writes nothing; refusals (no `paths`, unknown `$ref`, cyclic entity root, undeclared path parameter) carry a JSON pointer. Rules: `worlds-getting-started` → `references/openapi-import.md` |
58
+ | `gateway worlds schema init PATH --from-openapi SOURCE [--plan-only] [--include GLOB\|TAG]… [--exclude GLOB\|TAG]…` | exists (2026-09-22); imports a Swagger 2.0 / OpenAPI 3.x document (JSON or YAML; a local path, `drive:<path>` read platform-side, or an http(s) URL) into `schema/world.json` + `connector.toml` + `schema/provenance.json`: the item schemas the selected operations' responses carry, read through the vendor's envelope, become entities (never the wrappers; keyed by a declared id, else the field the read route looks a row up by, nested as a JSON Pointer when it sits inside the row), every path+method a route that answers in the vendor's envelope (`envelope = "message.items"` + `wrapper`) and pages as the document says (passthrough when the response is not an entity), the plan is printed first and `--plan-only` writes nothing; a YAML document needs PyYAML in the Python that runs the runtime and is refused naming the fix without it; refusals (no `paths`, unknown `$ref`, cyclic entity root, undeclared path parameter) carry a JSON pointer. Rules: `worlds-getting-started` → `references/openapi-import.md` |
59
59
  | `gateway worlds connector validate\|capture\|ingest PATH` | exists; a `connector.toml` in the world describes base URL, auth scheme, pacing, redaction and operations; `capture` records paced, redacted pages (errors included) under `captures/` with the secret never written; `ingest` seeds `data/initial.json` through the contract in a scratch copy first; `ingest --dry-run [--report refusals.jsonl]` lists every violation of every capture (the `data import --report` records plus `capture`), exit 2, nothing written |
60
60
  | `gateway worlds schema reconcile PATH --from captures [--write]` | exists (runtime, offline CLI and `gateway worlds schema reconcile`); the contract against the captured rows: relaxes `required` for fields absent in captures, adds undocumented keys as optional properties typed from the values, drops formats the captured values fail; a report of every change, `schema/world.json` rewritten and recompiled only with `--write` |
61
61
  | `gateway worlds connector conform PATH --openapi vendor.yaml` | exists; serves the world in-process, calls every declared operation with arguments from its own seed, and checks status + body against the vendor's OpenAPI response schemas; non-zero exit on any mismatch. Run it before calling a world 1:1; its FAIL list is the work list (unseeded entities → 404s, creates the contract rejects → 4xx, honest 501s). Reads OpenAPI 3.0 `nullable`, reference cycles and `discriminator` unions; `[operations.api] sample_headers` / `sample_body` shape a request the route demands (`Idempotency-Key`, a body) |
@@ -64,7 +64,8 @@ registration, a platform builder, live ingestion, tools, or a registry framework
64
64
  | `gateway worlds schema compile \| check \| describe PATH` | exists (#216); `compile` also writes `ui/static` (index.html, app.js, contract.json) when connector.toml declares `[ui]` (every shipped template does): the page over the routes an agent drives with `--surface ui,browser`; `[ui] generated = false` keeps a hand-written page |
65
65
  | `gateway worlds schema ui init PATH` | exists (TS CLI + `python -m … ui-init`); declares `[ui]` in connector.toml when missing (before the first `[[operations]]`) and compiles, which generates the page; refuses a world with no connector.toml (a page shows routes). `worlds serve` serves it on its own port at `/` (and at `/__ui/`) and answers its `api_path` for the pin; `generated = false` + any frontend built to static files into `ui/static` is served the same way |
66
66
  | `gateway worlds schema entity add PATH NAME --ref D \| --fields "a:string,b:integer?" \| --schema JSON --key F [--unique F,F] [--relationship F->entity]` | exists (TS CLI, local); declares one entity in `schema/world.json` without hand-editing the document: keeps `$defs`, package metadata and other entities byte-for-byte in meaning, refuses duplicate names, non-required or non-string/integer keys, unknown `$defs` and undeclared relationship targets, and writes nothing on refusal |
67
- | `gateway worlds connector route add PATH NAME --path /v1/x/{id} [-X POST] [--param q] [--entity E] [--results r] [--action create] [--filter id=id] [--body f=p] [--handler fn]` | exists (TS CLI, local); appends one `[[operations]]` (+ `[operations.api]`) to `connector.toml` leaving existing bytes untouched; validates name, method, path, entity against `schema/world.json`, filter keys against `{args}`/params, and the handler/action pairing |
67
+ | `gateway worlds schema entity remove PATH NAME` | exists (TS CLI, local); takes one entity out of `schema/world.json` with the `$defs` only it used; refused (exit 2, nothing written) while a `connector.toml` operation, a `verifiers/*.sql`, rows in `data/initial.json`, a `[dependencies.<alias>.entities]` map or another entity's relationship uses it, each named; keeps at least one entity and re-points the untouched `state_present.sql` placeholder |
68
+ | `gateway worlds connector route add PATH NAME --path /v1/x/{id} [-X POST] [--param q] [--entity E] [--results r] [--action create] [--filter id=id] [--body f=p] [--handler fn]` | exists (TS CLI, local); appends one `[[operations]]` (+ `[operations.api]`) to `connector.toml` leaving existing bytes untouched; validates name, method, path, entity against `schema/world.json`, filter keys against `{args}`/params, and the handler/action pairing; a new `connector.toml` starts with `[auth] scheme = "bearer"` (the hosted session token) and `--action handler --handler fn` writes a 501 stub into `api/handlers.py` unless `fn` is defined |
68
69
  | `gateway worlds connector publish DIR [--slug S] [-m MSG] [--tag T] [--workspace-visible] [--project-scope]` | exists; saves a template directory, or the world it was authored in, as a workspace connector (Context Hub `connector` repo, org-owned, versioned); the platform compiles the template before accepting it and answers 400 with the reason; a re-publish is a new commit and paths no longer present are removed; `data/`, `captures/`, `db/` and generated files stay behind |
69
70
  | `gateway worlds connector list [--hub] [--query Q]` / `pull SLUG [--out DIR] [--version V]` / `clone SLUG-OR-ID [--name N] [--slug S]` | exists; `list` shows this org's connectors (vendor, auth, entities, operations), `--hub` adds every connector another org published; `pull` writes the template files; `clone` copies a published connector into this org with provenance — a live reference is never made, so the publisher's later edits need a re-clone |
70
71
  | `gateway worlds schema init PATH --connector workspace:<slug>` | exists; initializes from the platform's copy through `init_bundle_from_files` (needs `GATEWAY_*` keys); the offline `python -m gatewaysdk.environment.schema init` refuses `workspace:` and names this command |
@@ -103,9 +104,9 @@ deliverable can finish with synthetic fixtures and explicitly skipped live valid
103
104
  - [ ] Author `schema/world.json` and reusable sibling definitions from pinned vendor sources, following the type-mapping notes in [CONNECTORS.md](CONNECTORS.md). `gateway worlds schema entity add` declares an entity with its key, uniques and relationships in one command so the declaration shape is never wrong; hand-author only the payload definitions (`--schema` or `$defs`). Record source URLs, versions/retrieval dates, and hashes of the actual retrieved bytes in `schema/provenance.json`.
104
105
  - [ ] Entities have the vendor's keys, relationships, enums, and nullability, and follow [CONVENTIONS.md](CONVENTIONS.md): one reserved prefix per template, plural snake_case names, vendor casing on fields, shared `base.json` primitives. Reserved prefixes and the `payload` name are avoided.
105
106
  - [ ] Enforce supported required fields, types, enums, key uniqueness, and reference integrity. Document vendor rules the dialect cannot express, normalization choices, and constraints the future mapper must enforce; structural validation is not vendor behavior.
106
- - [ ] Real vendor documents compile as they come (Brex retrospective, 2026-09-14): `format: int64`/`double` on numbers is ignored, not refused (string formats are still validated); a schema-valued `additionalProperties` types a map (`Record<string, string>`); a type nested in itself (`ExpandableExpense` holding an `ExpandableExpense`) compiles, with the nested occurrence validated as its bare type and stored as JSON, never projected to a column. A nested key or relationship field is a JSON Pointer, `/owner/user_id`, never `owner.user_id`; the compiler's refusal says so.
107
- - [ ] Every property verifier SQL will name has a column: scalars and compositions whose non-null branches are scalar (`anyOf [{$ref Status}, {type: null}]`, the nullable-enum shape) project; a composition that may hold an object or array stays JSON-only. A verifier that names a column the contract never projected fails the grade with SQLite's message and the statement; it never scores 0 quietly (double-quoted unknown names no longer fall back to string literals).
108
- - [ ] `gateway worlds schema compile PATH` then `check PATH` pass. Never edit generated files; SDK templates contain authored inputs and generate bundle artifacts at `init` time. Changing the root `$id` after `init` is fine: `compile` re-stamps an empty `data/initial.json` onto the new domain; a journal that holds rows is refused with the fix named (re-import its rows, or restore the schema it was written against).
107
+ - [ ] Real vendor documents compile as they come (Brex retrospective, 2026-09-14): `format: int64`/`double` on numbers is ignored, not refused (string formats are still validated); a schema-valued `additionalProperties` types a map (`Record<string, string>`); a type nested in itself (`ExpandableExpense` holding an `ExpandableExpense`) compiles, with the nested occurrence validated as its bare type and stored as JSON, never projected to a column. A contract whose inlined files would pass the 4 MB publication cap (Google Docs' recursive body) compiles each object/array definition once under `$defs` and references it instead; nothing to do in the template. A nested key or relationship field is a JSON Pointer, `/owner/user_id`, never `owner.user_id`; the compiler's refusal says so. A primary key may be nested too (`/protocolSection/identificationModule/nctId`) when every object on its path is required and non-null; lookups (`get`, `update`, `delete`) then pass it flat under the pointer itself. Field names keep the vendor's hyphens (`reference-count`); dots and slashes never belong to a name. A verifier's SQL double-quotes such a column (`"reference-count"`): unquoted, SQLite reads a subtraction.
108
+ - [ ] Every property verifier SQL will name has a column: scalars and compositions whose non-null branches are scalar (`anyOf [{$ref Status}, {type: null}]`, the nullable-enum shape) project; a composition that may hold an object or array stays JSON-only. A verifier that names a column the contract never projected fails the grade with the database engine's message and the statement; it never scores 0 quietly (double-quoted unknown names no longer fall back to string literals).
109
+ - [ ] `gateway worlds schema compile PATH` then `check PATH` pass. Never edit generated files; SDK templates contain authored inputs and generate bundle artifacts at `init` time. Changing the root `$id` after `init` is fine: `compile` re-stamps an empty `data/initial.json` onto the new domain; a journal that holds rows follows a change that only adds to its domain (a new entity, a new field that is not required) and is refused otherwise, with the fix named (re-import its rows, or restore the schema it was written against).
109
110
  - [ ] Shared templates and committed fixtures hold synthetic data only. Tenant captures stay in their owning project; initial batches and refresh journals retain explicit capture/synthetic provenance.
110
111
 
111
112
  ### 2. Tenant overlay (required for tenant-shaped, optional for mixed, absent for base)
@@ -132,7 +133,8 @@ deliverable can finish with synthetic fixtures and explicitly skipped live valid
132
133
  ### 5. Tools (only if the world ships tools)
133
134
 
134
135
  - [ ] Every tool in `x-gateway.tools` has exactly one handler in `tools/*.py` (the loader refuses a mismatch); generated defaults are fine.
135
- - [ ] Handler reads use `gateway_env.store.get` / `list`; writes use `insert` / `update` / `delete`. Read-only SQL uses `gateway_env.db.one/all`; raw SQL writes are denied. The host's `SQLiteStore.query` is not exposed by the handler store proxy.
136
+ - [ ] Routes are never tools. A call by a route's name is refused (`not_a_tool`, naming the session's api URL), and a task's `tools` lists declared tools only. A tool may share an operation's name: a call by that name runs the tool, and the route answers only over HTTP at its path.
137
+ - [ ] Handler reads use `gateway_env.store.get` / `list`; writes use `insert` / `update` / `delete`. Read-only SQL uses `gateway_env.db.one/all`; raw SQL writes are denied. The host's `WorldDatabase.query` is not exposed by the handler store proxy.
136
138
  - [ ] Handlers never read `benchmark_runtime_context` or `benchmark_conversation_events`.
137
139
  - [ ] A user attaching custom tools to this world needs nothing from this checklist beyond the store API; document any conventions the model expects (key formats, enum values).
138
140
 
@@ -142,7 +144,9 @@ Tool handlers (`tools/*.py`) reach the world's rows through `from gateway_env im
142
144
  exactly these methods; `gateway worlds schema check .` refuses any other `store.<name>` at file:line
143
145
  with this list, and a hosted call into such a handler answers 400 `{error: "handler", detail, handler}`
144
146
  (an `AttributeError`/`TypeError`/`NameError` is the author's bug; anything else a handler raises is a
145
- 500 `{error: "engine", detail, handler}`; never a bare exception string).
147
+ 500 `{error: "engine", detail, handler}`; never a bare exception string). A route's handler answers the
148
+ same way on every door, and an answer JSON cannot carry (a `datetime`, a set, NaN) is its 400; a route
149
+ answering bytes names its `Content-Type` (a vendor's `404 text/plain`), and the bytes go out as sent.
146
150
 
147
151
  - `get(entity: str, key: dict) -> dict | None` — one row by primary key, or `None`.
148
152
  - `list(entity: str) -> list[dict]` — every row, ordered by key.
@@ -234,7 +238,7 @@ Full procedure: `.llm_artifacts/plans/connector-implementation-orchestration.md`
234
238
  - Treating descriptive resources as schema authority. `init` preserves flat supporting `.json`, `.md` and `.toml` files; only referenced schemas become compiler inputs. Slack capability defaults expand into self-contained entries; see [world-schema.md](../../../documentation/features/world-schema.md#connector-templates-and-init).
235
239
  - Converting Slack message timestamps to floats or RFC3339. Preserve exact `(workspace_id, channel_id, ts)` keys; see the [Slack model guide](../../../gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/slack/MODEL.md) for normalization and limits.
236
240
  - Writing a nested field as `owner.user_id` in `unique` or `relationships`. Nested paths are JSON Pointers: `/owner/user_id`.
237
- - Reading a verifier's 0 as "the agent failed". If the SQL names a column that does not exist the grade is now an error carrying SQLite's message; an older world that still scores 0 on every task has verifier SQL naming an unprojected property — recompile, the nullable-enum shape projects now.
241
+ - Reading a verifier's 0 as "the agent failed". If the SQL names a column that does not exist the grade is now an error carrying the database engine's message; an older world that still scores 0 on every task has verifier SQL naming an unprojected property — recompile, the nullable-enum shape projects now.
238
242
 
239
243
  ## Where this skill is discoverable
240
244
 
@@ -388,7 +392,10 @@ them:
388
392
  - `[api] envelope = "results"` wraps rows as `{"results": [...], "hits": N, "cursor": ""}`
389
393
  (empty means a bare array); `hits_key = ""` leaves the count out and
390
394
  `cursor_absent_when_done = true` (world-wide, or per route under `[operations.api]`)
391
- leaves the cursor key out of the last page — Brex's `{items, next_cursor?}`.
395
+ leaves the cursor key out of the last page — Brex's `{items, next_cursor?}`. A dotted
396
+ `envelope = "message.items"` nests the page (`{message: {items, total-results, next-cursor}}`),
397
+ and `[operations.api] wrapper = '{"status": "ok", "message-type": "work-list"}'` lays it onto
398
+ the rest of the vendor's envelope; a single row is wrapped only by its route's own `envelope`.
392
399
  - `unauthorized` / `not_found` / `invalid` are JSON strings replayed on 401 / 404 / 400, so
393
400
  the vendor's own error bodies come back; `""` (or `'null'`) means no body at all. A route
394
401
  whose missing row the vendor answers its own way sets `not_found` and `not_found_status`
@@ -404,10 +411,11 @@ them:
404
411
  credential for it, the way it does for a bearer of the session token.
405
412
 
406
413
  `gateway worlds serve PATH --port 8080 [--api-key K]` runs it locally; the runner's admin
407
- endpoints (`/healthz`, `/__world/seed`, `/__world/reset`, `/__world/state`) sit beside the
408
- vendor routes. `gateway bench push PATH` publishes the world: for a world carrying
414
+ endpoints (`/__world/seed`, `/__world/reset`, `/__world/state`) sit beside the vendor routes
415
+ and answer only the run's `X-World-Admin-Token` (`gateway worlds test` hands a world's pytest
416
+ files theirs as `WORLD_ADMIN_TOKEN`; by hand, use `/__session/*`); `/healthz` answers everyone,
417
+ and a World Host session's doors answer none of the others. `gateway bench push PATH` publishes the world: for a world carrying
409
418
  `connector.toml` it packages the api-kind bundle the platform hosts on the way (root
410
419
  legacy-shaped on purpose, since the api runner refuses a schema bundle there; `server/`
411
420
  needs nothing installed). Open a session with `--surface api` and hand the client that
412
- URL; the vendor's auth scheme applies (`WORLD_API_KEY` on the host pins the credential,
413
- otherwise any non-empty one).
421
+ URL; the vendor's auth scheme applies, with the session's own api token as the credential.
@@ -292,9 +292,10 @@ A schema world's validated database is kept, not rebuilt. `gateway worlds schema
292
292
  builds `db/state.sqlite` (the default snapshot: `data/initial.json` applied through the
293
293
  contract) and `scenarios/<name>/state.sqlite` (the default with the scenario's overlays),
294
294
  each with a `state.json` sidecar `{contractHash, batchDigest, entityCounts, builtAt,
295
- runtime, fileSha256}`; the same key is never rebuilt, `schema check` verifies the sidecars,
296
- and a data batch the contract refuses leaves no snapshot behind. `gateway worlds serve` and
297
- the api bundle open the snapshot (copy + `SQLiteStore.open`, no row replay) and reset by
295
+ runtime, fileSha256}`; a snapshot that already holds the same data is never rebuilt,
296
+ `schema check` verifies the sidecars, and a data batch the contract refuses leaves no
297
+ snapshot behind. `gateway worlds serve` and
298
+ the api bundle open the snapshot (copy + `WorldDatabase.open`, no row replay) and reset by
298
299
  copying it again; without one the JSON is replayed as before. A hosted pod gets
299
300
  `WORLD_SNAPSHOT_URL` (presigned GET, `.gz` or `Content-Encoding: gzip` is gunzipped),
300
301
  `WORLD_SNAPSHOT_SHA256` and `WORLD_SNAPSHOT_DIGEST`; the server downloads, verifies, writes
@@ -303,3 +304,28 @@ reports `"snapshot": {batchDigest, contractHash}` (or null) and `/__world/seed`
303
304
  overlay form `{"base": digest, "rows": {...}, "mode": append|replace}` beside the legacy
304
305
  whole-state body. Snapshot files are build outputs: gitignore `db/state.sqlite`,
305
306
  `db/state.json`, `scenarios/*/state.*`.
307
+
308
+ **Which edits keep a snapshot.** Rows are bound to the domain they were stored under, not to
309
+ the whole contract: adding a tool, editing a handler, a route, a test, a documentation file or
310
+ the package version keeps every snapshot (local, hosted, pinned), with no re-import. A change
311
+ that only adds to the domain (a new entity, a new field that is not required, another
312
+ `domain_version`) carries the rows: compile migrates the snapshots the tree holds and keeps the
313
+ pin with the stored domain's `lock` and `entities`, `sandbox check` says the commit migrates the
314
+ hosted snapshot, and `sandbox commit` migrates it and re-pins the tree (a CLI push of such a
315
+ change is refused, naming the sandbox). Any other change to an entity, a field (its description
316
+ or title too), a key or a relationship refuses it, naming each change:
317
+
318
+ ```text
319
+ snapshot_pinned at /db/snapshot.json: The rows here were stored under the previous domain, and
320
+ this change requires field users.age. Stored rows carry over only when a change adds to their
321
+ domain (a new entity, a new field that is not required, or another domain_version): ...
322
+ ```
323
+
324
+ Then keep those as they were, or remove `db/snapshot.json` and import every row again. A tree
325
+ pinned to a hosted snapshot (`db/snapshot.json`, what a data import publishes) compiles and checks
326
+ without the snapshot itself, as in a sandbox: compile keeps the pin, never rebuilds state from
327
+ the data files, and records in the pin (`lock`) the contract the snapshot was built under, which
328
+ is how the platform proves the next edit still fits it. If `schema/lock.json` was replaced by
329
+ artifacts compiled elsewhere before that, compile says the domain cannot be proven: restore
330
+ `schema/lock.json` from the version you started from and compile again. A `[redact]` change is
331
+ not part of it: the store never applies the policy; capture and `--redact apply` do.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: world-data-ingestion
3
- description: Put rows into a world from any agent. Use when uploading data to a world, seeding a world, importing rows (a few or millions), adding records to a schema world or mock-tools world, pulling a connector's data through an active connection (`gateway worlds data pull --connection`), seeding a live session, exporting a session's calls, turning a vendor export or a real run into world data, turning an agent's real tool calls, a trace's TOOL observations or a saved ClickHouse result into rows (`gateway worlds data calls pull`, then `data ingest --transform` with your own code or `--map ingest.toml`, `captureToolCalls`), or asking why a served world starts from a snapshot. Covers the rows file contract (JSON object, JSONL, --entity), the tool-call record contract, the transform contract, the `ingest.toml` grammar and `map init`, append vs replace, primary-key upsert, `gateway worlds describe`, `gateway worlds data show|import|pull|check|extract|calls pull|ingest|status|batches|publish`, chunked resumable uploads, refusal reports, data snapshots (`db/state.sqlite`, `WORLD_SNAPSHOT_*`), `gateway worlds session seed|export`, the MCP twins import_world_data / pull_world_data / seed_world_session / export_world_session, the refusals, and the definition of done.
3
+ description: Put rows into a world from any agent. Use when uploading data to a world, seeding a world, importing rows (a few or millions), adding records to a schema world or mock-tools world, pulling a connector's data through an active connection (`gateway worlds data pull --connection`), seeding a live session, exporting a session's calls, turning a vendor export or a real run into world data, turning an agent's real tool calls, a trace's TOOL observations or a saved ClickHouse result into rows (`gateway worlds data calls pull`, then `data ingest --transform` with your own code or `--map ingest.toml`, `captureToolCalls`), or asking why a served world starts from a snapshot. Covers the rows file contract (JSON object, JSONL, --entity), the tool-call record contract, the transform contract, the `ingest.toml` grammar and `map init`, append vs replace, primary-key upsert, `gateway worlds describe`, `gateway worlds data show|import|sql|pull|check|extract|calls pull|ingest|status|batches|publish`, chunked resumable uploads, refusal reports, data snapshots (`db/state.sqlite`, `WORLD_SNAPSHOT_*`), `gateway worlds session seed|export`, the MCP twins import_world_data / pull_world_data / sql_world_data / seed_world_session / export_world_session, the refusals, and the definition of done.
4
4
  ---
5
5
 
6
6
  # World data ingestion
@@ -71,8 +71,7 @@ Rules:
71
71
  (`--atomic`, the default); `--per-chunk` keeps the good chunks of a large upload and lists
72
72
  the refused ones.
73
73
  - Inside one batch, two rows with the same key merge by `--merge`: `upsert` (default, the
74
- later row replaces the earlier) or `fill` (the first row wins, later rows only add fields
75
- it lacks).
74
+ later row replaces the earlier) or `fill` (the first row wins, later rows only add fields it lacks).
76
75
 
77
76
  ## Decision table by world kind
78
77
 
@@ -95,7 +94,7 @@ Every CLI step has its MCP twin on the next line. `<WORLD>` is a local world dir
95
94
  platform world slug (the CLI pulls it to a temp dir, imports, and pushes a new version unless
96
95
  `--no-push`). Auth and host: `GATEWAY_HOST`, `GATEWAY_PUBLIC_KEY`, `GATEWAY_SECRET_KEY`, or
97
96
  `gateway auth login`. Third place: a CLI sandbox (`worlds sandbox open <slug>@main`) has `gateway` + `sqlite3` on PATH, so
98
- `sandbox exec <id> 'gateway worlds data import . rows.json'` (`show`, `query`) runs on the uncommitted copy with nothing local; `check` then `commit` lands it. Same refusals as a directory (exit 2).
97
+ `sandbox exec <id> 'gateway worlds data import . rows.json'` (`show`, `query`, `sql`) runs on the uncommitted copy with nothing local; `check` then `commit` lands it. Same refusals as a directory (exit 2).
99
98
  The sandbox holds **no platform credentials, by design**: never write keys into its tree (`.gateway-env`, `*.env` are held out of every
100
99
  commit, with a warning); bulk rows reach the platform world through `worlds sandbox import <id> <path>` from where the keys are (2d).
101
100
 
@@ -108,8 +107,13 @@ gateway worlds data show <WORLD> # {world, kind, entity_count
108
107
  gateway worlds data show <WORLD> --entity users # the rows of one entity
109
108
  gateway worlds data query <WORLD> users --where plan=pro --limit 50 # the rows you mean; a repeated --where key is IN
110
109
  gateway worlds data query <WORLD> users --where email=jo@acme.test --resolve # plaintext into a hashed field
110
+ gateway worlds data sql <WORLD> 'SELECT id, name FROM users LIMIT 5' # read-only SQL, any engine
111
111
  ```
112
112
 
113
+ `data sql` runs ONE read-only statement (joins, `GROUP BY`, counts) over a schema world's entity tables,
114
+ whatever its database engine: a write, `ATTACH`, `PRAGMA` or a second statement is refused; at most 1000 rows
115
+ (`--limit`). MCP twin: `sql_world_data({ slug, sql, limit? })`. A db/schema.sql world is a SQLite file: `sqlite3`.
116
+
113
117
  `data query --resolve` turns each `--where` value into the form the store holds under the
114
118
  `[redact]` policy before matching, and prints `resolved <field> -> <form>`; a dropped field
115
119
  resolves to nothing, so zero rows there is the policy, not a missing import. MCP twin:
@@ -269,9 +273,8 @@ level}]}`; text before the JSON is skipped; `input`/`output` decoded as JSON or
269
273
  ```
270
274
 
271
275
  A `gateway worlds session export` line (`{seq, kind, tool, args, result, error, completedAt}`)
272
- is accepted as it is: `kind != "call"` and a failed call are skipped and counted, never
273
- silently dropped. `captureToolCalls` (TS) / `capture_tool_calls` (Python) write the same
274
- record at the source.
276
+ is accepted as it is: `kind != "call"` (a grade, or a `--requests` line of kind `request`) and a failed call are skipped and counted, never
277
+ silently dropped. `captureToolCalls` (TS) / `capture_tool_calls` (Python) write the same record at the source.
275
278
 
276
279
  **2. Transform.** `--transform <script>`: a `.py` file, or `.ts`/`.mjs`/`.js` for node, that
277
280
  exports `transform(records) -> {entity: [rows]}` (node: `transform` or the default export),
@@ -380,26 +383,23 @@ state}` to poll with `data status`. A new-world sandbox commits once first. MCP:
380
383
 
381
384
  ### 3. Verify on a live session
382
385
 
383
- Open a session, seed it, hit it. Live seeding does not change the world's version; it
384
- changes this session only.
386
+ Open a session, seed it, hit it. Live seeding does not change the world's version; it changes this session only.
385
387
 
386
388
  ```bash
387
389
  gateway worlds session open <slug> -t <scenario> --surface api # prints sessionId and api.url
388
390
  gateway worlds session seed <SESSION_ID> rows.json # kind:"seed" call, waits for the result
389
391
  gateway worlds session seed <SESSION_ID> rows.json --redact refuse # same, refusing plaintext in a redacted field (apply hashes it first)
390
392
  gateway worlds session seed <SESSION_ID> rows.json --mode replace # swap the named entities
391
- curl -H 'x-api-key: any' "$API_URL/<route>" # read it back through the vendor's route
393
+ curl -H "Authorization: Bearer $API_TOKEN" "$API_URL/<route>" # read it back (api.token from session open)
392
394
  ```
393
395
 
394
396
  Prints `{sessionId, mode, result}`. MCP: `seed_world_session({ sessionId, rows, mode? })` waits
395
397
  up to 60 seconds for the engine and otherwise returns a `callId` to poll. Same caps as the
396
- import. Public API: `POST /api/public/world-sessions/{sessionId}/calls` with
397
- `{ kind: "seed", rows, mode }`.
398
+ import. Public API: `POST /api/public/world-sessions/{sessionId}/calls` with `{ kind: "seed", rows, mode }`.
398
399
 
399
400
  The tools surface is open by default; `--surface api` adds the vendor's HTTP routes. A fresh
400
401
  version's first session takes about fifteen minutes to come up (`PROVISIONING`, 503 on the
401
- URL); that is a cold pod, not a fault. Pass `--no-wait` and poll
402
- `gateway worlds session status <SESSION_ID>`.
402
+ URL); that is a cold pod, not a fault. Pass `--no-wait` and poll `gateway worlds session status <SESSION_ID>`.
403
403
 
404
404
  Which kinds can seed live: schema worlds (the store applies the batch through the contract),
405
405
  api worlds (the runner merges the rows into the whole state and posts it to the world's seed
@@ -478,8 +478,8 @@ Sanitize before importing: hash or drop personal fields the world's `[redact]` p
478
478
 
479
479
  ## Data snapshots
480
480
 
481
- Why a served world starts in under a second (`db/state.sqlite`, `WORLD_SNAPSHOT_*`, the
482
- `/__world/seed` overlay form): [ROWS.md — Data snapshots](ROWS.md#data-snapshots).
481
+ Why a served world starts in under a second (`db/state.sqlite`, `WORLD_SNAPSHOT_*`, `/__world/seed`), and why a tool,
482
+ handler or route edit keeps the imported data while an entity, field or key edit does not: [ROWS.md — Data snapshots](ROWS.md#data-snapshots).
483
483
 
484
484
  ## Definition of done
485
485
 
@@ -134,7 +134,7 @@ gateway worlds connector route add ./x create_account -X POST --path /v1/account
134
134
 
135
135
  Each refuses (and writes nothing) on a duplicate name, an undeclared entity or `$defs` reference, a key that is not a
136
136
  required string/integer field, or a filter on an unknown argument. A create route mints its single-field primary key (`uuid` for strings, `int` for integers) unless `--body` maps it;
137
- `--generate field=uuid|int|now` and `--default field=value` fill the rest. A custom world's first `route add` creates `connector.toml`; `schema init` prints `kind: "schema"`, `api` and the `next` commands in order (custom: entity add → route add → task add → compile → check → import → serve → `worlds create`).
137
+ `--generate field=uuid|int|now` and `--default field=value` fill the rest. A custom world's first `route add` creates `connector.toml` with `[auth] scheme = "bearer"` (a hosted session's api token; `worlds serve` answers 401 without one); `--action handler --handler fn` writes a 501 stub `fn(ctx, args, query, body)` into `api/handlers.py` unless it is defined. The custom scaffold's example entity is `records`: `gateway worlds schema entity remove ./x records` once yours are declared (refused, naming each reference, while a route, verifier, row, dependency map or relationship uses it). `schema init` prints `kind: "schema"`, `api` and the `next` commands in order (custom: entity add → entity remove records → route add → task add → compile → check → import → serve → `worlds create`).
138
138
  Manifest `kind` is `schema` (older trees: `mock-tools`). Handlers: `def name(ctx, args, query, body)`; `ctx` reads and writes the store and keeps the clock.
139
139
 
140
140
  ### From an OpenAPI spec (Swagger 2.0, OpenAPI 3.x)
@@ -168,7 +168,7 @@ with this list, and a hosted call into such a handler answers 400 `{error: "hand
168
168
  - `lineage(entity: str, key: dict) -> list[dict]` — the batches that wrote the row at `key`, oldest first.
169
169
  - `counts() -> dict[str, int]` — rows per entity, `{entity: count}`.
170
170
 
171
- No `upsert`: `get`, then `insert` or `update`. Read-only SQL: `gateway_env.db.one/all`; raw SQL writes are refused. The scaffolded `tools/handlers.py` docstring carries the same table.
171
+ No `upsert`: `get`, then `insert` or `update`. Read-only SQL: `gateway_env.db.one/all`; raw SQL writes are refused. The scaffolded `tools/handlers.py` docstring carries the same table. Every tool call and every route call (handler routes too) is one transaction: one that raises, breaks the contract or answers 4xx/5xx keeps no writes or `ctx.emit` events and is still logged with its status. A route's handler answers like a tool's on every door, an answer JSON cannot carry (a `datetime`, a set, NaN) is its 400, and a route answering bytes (a `404 text/plain`) comes back through `call` as `{status, body}` with the body as text.
172
172
 
173
173
  ## 3. Check
174
174
 
@@ -181,14 +181,14 @@ gateway worlds serve ./x --port 8080 # answers the vendor
181
181
  ```
182
182
 
183
183
  `check` validates the compiled bundle; `conform` drives every declared route against the
184
- vendor's document and exits non-zero on a mismatch. Its FAIL list is the work list.
184
+ vendor's document and exits non-zero on a mismatch. Its FAIL list is the work list. Routes are never tools: an agent reaches a world's routes over HTTP (the api url and token `session open --surface api` prints, or `worlds serve` and a request to `http://127.0.0.1:<port>/<path>`), and gets a tool only where `x-gateway.tools` declares one with a handler. A call by a route's name is refused (`not_a_tool`, naming the api URL). A task's `tools` lists declared tools only, and a task that lists any closes the session's routes (403 `route_not_allowed`). An api bundle serves no tools, so the benchmark runner refuses to run one: `gateway worlds migrate <slug> --apply` turns it into a schema world.
185
185
 
186
186
  MCP: `validate_connector_template({ files, slug? })` compiles without writing; answers `{ valid, reason? }`.
187
187
 
188
188
  ## 4. Data
189
189
 
190
190
  ```bash
191
- gateway worlds describe ./x # entities, keys, relationships, row counts, [redact] per field
191
+ gateway worlds describe ./x # entities, keys, relationships, row counts, enum values, [redact] per field
192
192
  gateway worlds data show ./x # kind + entity counts
193
193
  gateway worlds data query ./x users --where email=jo@acme.test --resolve # the rows you mean; plaintext into a hashed field
194
194
  gateway worlds data import ./x rows.json # rows file: {entity: [rows]} | JSONL | .csv/.tsv --entity (cells cast by the schema; --delimiter)
@@ -314,14 +314,14 @@ gateway worlds session open x -t default # prints {sessionId,
314
314
  gateway worlds session open x -t default --surface api # asks for api.url explicitly: the vendor's routes, hosted (400 on a tree with no connector.toml)
315
315
  gateway worlds session open x -t default --surface ui,browser # + ui.entry (the page, token once then cookie) and browser.wsUrl (a pool Chromium); 400 without [ui] or without a pool; --browser-tier standard (spot, may be reclaimed; the SDK repairs + reconnects, raises BrowserReconnected on a lost click/type) | premium (on-demand), default: the org's setting
316
316
  gateway worlds session browse <SESSION_ID> [--path /#/accounts] [--screenshot p.png] # open the page in the browser surface; prints url, title, text
317
- gateway worlds session open x [--no-wait] # EXPLORATORY: no task, no grader (task.source "none"); --no-wait returns at once on a cold version
317
+ gateway worlds session open x [--no-wait|--timeout S] # EXPLORATORY: no task, no grader (task.source "none"); waits up to S seconds (600) for ready, --no-wait not at all
318
318
  gateway worlds session open x --task-file task.json --surface api # the session's own task (below)
319
319
  gateway worlds session status <SESSION_ID> # poll until ready
320
320
  gateway worlds session seed <SESSION_ID> rows.json # rows into this session only
321
321
  gateway worlds session state <SESSION_ID> # every entity's rows, the dump a grader reads
322
322
  gateway worlds session reset <SESSION_ID> # back to the snapshot (+ the task's seed)
323
323
  gateway worlds session grade <SESSION_ID> [--timeout S] # {reward, rewards, raw}; exploratory → {reward: null, reason: "no grader"}
324
- gateway worlds session export <SESSION_ID> --out calls.jsonl
324
+ gateway worlds session export <SESSION_ID> --out calls.jsonl [--requests] # the platform's ledger; --requests (live session, one state call) adds the world's own request log, kind "request" with via
325
325
  gateway worlds data ingest x calls.jsonl --transform shape.py # the calls back in as rows, shaped by your code or --map ingest.toml (world-data-ingestion §2c)
326
326
  gateway worlds session close <SESSION_ID> # a closed session reopens by id, same URLs + token, from its last checkpoint: gateway worlds session reopen <SESSION_ID>
327
327
  ```
@@ -344,7 +344,7 @@ verifiers) is refused `world_kind_retired`; one on an api bundle opens and lists
344
344
  `instruction` is what the agent is told; `seed` (`{mode?, rows}`, the live-seed contract) is laid on the clone and re-applied by `reset`;
345
345
  `grader` is `assertions` (`entity`, `where`, `exists|absent|count|all|any`, `field op value`; each check's `id` becomes a `rewards` key;
346
346
  `entity: "calls"` reads the call log — `operation`, `args`, `selectors`, `status`, `rows`, `found`, and `via`: `ui` from the page's `api_path`,
347
- `api` from the api origin, `tool` by name), `{kind: "python", source}` (a `verify.py` body) or `{kind: "rubric", rubric, criteria?, model?}`
347
+ `api` from the api origin, `tool` for a declared tool's call; a credential-named or secret-shaped field reads `[redacted]`; `rows`/`found` are null where the answer declares no rows, a request too large to keep names what it lacks in `withheld`, and a check grades whenever the calls it can read decide it, ungraded only where those could change the result), `{kind: "python", source, timeoutSeconds?}` (a `verify.py` body; it reads the state as JSON on stdin — `{"<entity>": {"<primary key>": row}, "calls": [...], "report": "<the agent's report>"}`, a verifier's entities as `<alias>.<entity>` — and prints ONE flat JSON object as the last line of stdout, `reward` plus a number from 0 to 1 per check — `true`/`false` read as 1/0, `null` or a string as ungraded, no `reward` leaves the task ungraded, and a nested object or array (a `rewards` map included), a number outside 0..1 or NaN/Infinity fails the grade by key and value; it must exit 0 within `timeoutSeconds`, default and most 30, or the grade fails with the reason) or `{kind: "rubric", rubric, criteria?, model?}`
348
348
  (an LLM judge over end state + call log, graded on the platform: `grade` answers pending until
349
349
  the worker finalizes it); `tools: [names]` narrows the operations the session may call to
350
350
  exactly those (a name the world does not serve is a 400); `metadata` rides the session. At most one of
@@ -352,7 +352,7 @@ exactly those (a name the world does not serve is a 400); `metadata` rides the s
352
352
  `task` block is `{source: "inline", name, hash, metadata}`. SDK: `openSession(slug, { task: spec })` / `openSession(slug)` (TS), `open_session(slug, spec)` / `open_session(slug)` (Python);
353
353
  `runSessions` / `run_sessions` take a mixed list of names and specs. Over several worlds, `worlds: {alias: {slug, …}}` opens one session per alias
354
354
  (`task up|grade|export|down`, `open_task`/`openTask`); a question spanning them is a `verifiers[]` entry (`name`, `scope`, assertions|python over
355
- `<alias>.<entity>` / `<alias>.calls`), graded on the platform only, rewards `x.<name>` (worlds/sessions.mdx).
355
+ `<alias>.<entity>` / `<alias>.calls`), graded on the platform only, rewards `x.<name>`, so no world is aliased `x` (worlds/sessions.mdx).
356
356
 
357
357
  **A stored task.** The same spec kept as a project resource, versioned by content, so many
358
358
  sessions open it by id and grades attribute to the task and its version:
@@ -391,15 +391,15 @@ gateway bench dispatch <RUN_CONFIG_ID> # each stored task
391
391
  The first session on a freshly pushed version takes about fifteen minutes: the pod is
392
392
  scheduled and the runner sidecar pulled; the session reads `PROVISIONING` and the api URL
393
393
  answers 503. That is a cold start, not a fault, until about twenty minutes have passed.
394
- `session open` prints `session <id> opening — gateway worlds session status <id>` on stderr at once, then waits ten minutes; on a cold version use `--no-wait` and poll. `open` and
394
+ `session open` prints `session <id> opening — gateway worlds session status <id>` on stderr at once while the World Host opens the session, then waits for ready up to `--timeout` seconds (600): a failed open exits 1 naming the reason and code (`browser_capacity` and `host_unavailable` are worth retrying), and a wait that runs out prints `ready: false`, exits 1 and leaves it opening; on a cold version use `--no-wait` and poll. A call on a session still opening waits up to 30 s, then 409 `session_starting`. `open` and
395
395
  `status` print `idleExpiresAt` (null once pinned) + `pinned`; `status` warns under 5 minutes. A call
396
396
  body over 4mb is refused client-side: `{status: "error", code: "payload_too_large"}`, exit 2.
397
397
 
398
- The world's API honours the vendor's auth scheme; `WORLD_API_KEY` on the host pins the
399
- credential, otherwise any non-empty one is accepted.
398
+ The world's API honours the vendor's auth scheme and accepts the session's own api token (bearer or
399
+ the vendor's header); `worlds serve` accepts the `--api-key` pin (default `conform`).
400
400
 
401
401
  MCP: `seed_world_session`, `export_world_session`, `save_world_session_task`; open/call/close are CLI or REST only.
402
- Find what you opened: `gateway worlds session list` / `sandbox list`; `session pin <id>` stops the reaper.
402
+ Find what you opened: `gateway worlds session list` (every state; the live ones are `--state RUNNING` and `--state IDLE`) / `sandbox list`; `session pin <id>` stops the reaper.
403
403
 
404
404
  ## Test the world (not the agent)
405
405
 
@@ -412,10 +412,10 @@ gateway worlds test my-world # the same suite on the platform,
412
412
  gateway bench tests my-world # every run the platform kept (push, CLI, API)
413
413
  ```
414
414
 
415
- A case: `{"name": "...", "request": {"method": "GET", "path": "/v1/accounts", "auth": true},
416
- "expect": {"status": 200, "length": {"path": "$", "min": 1}}}`. Put `[actions]` `on_push = ["tests"]`
417
- in `gateway-env.toml` and the platform runs the suite on each push (world page → Tests tab). Public
418
- API: `POST/GET /api/public/worlds/{slug}/tests`. Details: `documentation/features/world-tests.md`.
415
+ A case: `{"name": "...", "request": {"method": "GET", "path": "/v1/accounts"}, "expect": {"status": 200}}`.
416
+ A `test_*.py` gets `WORLD_URL`, `WORLD_API_KEY` and, with `[ui]`, `WORLD_UI_URL` (the page on its own origin; the
417
+ platform's runner has no browser, so check the page over HTTP there). `[actions]` `on_push = ["tests"]` in
418
+ `gateway-env.toml` runs the suite on each push (Tests tab); `POST/GET /api/public/worlds/{slug}/tests`; `documentation/features/world-tests.md`.
419
419
 
420
420
  ## Act on a world as an outside agent (local)
421
421
 
@@ -438,7 +438,7 @@ its `api.url` takes the session's bearer): act on it by id, `gateway worlds call
438
438
  ## 7. Run and grade
439
439
 
440
440
  ```bash
441
- gateway worlds run x -a agent.mjs --all # TS CLI: agent module (default export async (session, task) => void), every task; -t <task> for one; x is a slug[@ref] or a pushed dir
441
+ gateway worlds run x -a agent.mjs --all # TS CLI: agent.mjs[#export] (the default export unless #name) async (session, task) => void, every task; -t <task> for one; x is a slug[@ref] or a pushed dir
442
442
  gateway worlds run x -a agent.py:agent # Python CLI: agent callable module:function; --path ./x runs a local dir, --no-file grades without filing
443
443
  gateway worlds ci ./x -a agent.mjs --min-score 0.8 # push the working tree, run, gate (CI); --run-config <file> instead of -a; Python: --path ./x -a agent.py:agent
444
444
  gateway environment run x -m <provider/model> -k 3 # hosted runner, one job per model; -k is 1–64
@@ -474,7 +474,7 @@ gateway worlds sandbox import <id> data/trips.csv --entity trip # rows a sandbo
474
474
  ```
475
475
 
476
476
  The sandbox carries the platform's `gateway` CLI and `sqlite3` on PATH: `exec` runs `worlds
477
- schema|data|test|serve|call …` on the working copy with nothing on your machine. `open` prints
477
+ schema|data|test|serve|call …` on the working copy with nothing on your machine; on a world whose data is a hosted snapshot, a tool, handler or route edit compiles and keeps that data, an entity or key edit is refused (`references/gotchas.md`). `open` prints
478
478
  `cli: {version, digest}`, or `cli: null` plus the reason under `warnings`. Remote verbs (`push`, `run`,
479
479
  `session open`) stop inside the sandbox by design: it holds no platform credential, and never write one
480
480
  into its tree — `check`/`commit` hold back scratch, credential-shaped files (`.env`, `.gateway-env`, `*.env`,