@withgateway/sdk 0.3.1 → 0.4.0

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 (176) hide show
  1. package/README.md +8 -6
  2. package/dist/cli.js +4372 -2265
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +4362 -2256
  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 +259 -58
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +249 -50
  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 +124 -11
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +124 -11
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  19. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  20. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  21. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  22. package/dist/index.d.mts +5 -5
  23. package/dist/index.d.ts +5 -5
  24. package/dist/index.js +2240 -789
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2150 -739
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  29. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  30. package/dist/traces/index.d.mts +1 -1
  31. package/dist/traces/index.d.ts +1 -1
  32. package/dist/traces/index.js +253 -52
  33. package/dist/traces/index.js.map +1 -1
  34. package/dist/traces/index.mjs +243 -44
  35. package/dist/traces/index.mjs.map +1 -1
  36. package/dist/tracing/index.d.mts +2 -2
  37. package/dist/tracing/index.d.ts +2 -2
  38. package/dist/tracing/index.js +75 -13
  39. package/dist/tracing/index.js.map +1 -1
  40. package/dist/tracing/index.mjs +75 -13
  41. package/dist/tracing/index.mjs.map +1 -1
  42. package/dist/worlds/index.d.mts +893 -482
  43. package/dist/worlds/index.d.ts +893 -482
  44. package/dist/worlds/index.js +1968 -669
  45. package/dist/worlds/index.js.map +1 -1
  46. package/dist/worlds/index.mjs +1960 -662
  47. package/dist/worlds/index.mjs.map +1 -1
  48. package/package.json +1 -1
  49. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  50. package/runtime/gatewaysdk/environment/_materialize.py +48 -88
  51. package/runtime/gatewaysdk/environment/_world.py +155 -237
  52. package/runtime/gatewaysdk/environment/backing.py +133 -0
  53. package/runtime/gatewaysdk/environment/core.py +2 -17
  54. package/runtime/gatewaysdk/environment/legacy_sqlite.py +288 -0
  55. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  56. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  57. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  58. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  59. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  60. package/runtime/gatewaysdk/environment/schema/api.py +347 -892
  61. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  62. package/runtime/gatewaysdk/environment/schema/batch.py +44 -39
  63. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  64. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  65. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +503 -0
  67. package/runtime/gatewaysdk/environment/schema/call_redaction.py +526 -0
  68. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  69. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  70. package/runtime/gatewaysdk/environment/schema/conform.py +14 -39
  71. package/runtime/gatewaysdk/environment/schema/connector.py +113 -211
  72. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  75. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  76. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  77. package/runtime/gatewaysdk/environment/schema/data.py +60 -216
  78. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  79. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  80. package/runtime/gatewaysdk/environment/schema/database/base.py +936 -0
  81. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  82. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  83. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  84. package/runtime/gatewaysdk/environment/schema/database/guard.py +215 -0
  85. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  86. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  87. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  88. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  89. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  90. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  91. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +393 -0
  92. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  93. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  94. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  95. package/runtime/gatewaysdk/environment/schema/envelope.py +227 -0
  96. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  97. package/runtime/gatewaysdk/environment/schema/grading.py +90 -103
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +163 -12
  99. package/runtime/gatewaysdk/environment/schema/host.py +237 -1795
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  112. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  113. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  114. package/runtime/gatewaysdk/environment/schema/local.py +58 -170
  115. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  116. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  117. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  118. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  119. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  120. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  121. package/runtime/gatewaysdk/environment/schema/platform.py +137 -187
  122. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  123. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  124. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  125. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  126. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  127. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  128. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  129. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  130. package/runtime/gatewaysdk/environment/schema/runtime.py +178 -308
  131. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  132. package/runtime/gatewaysdk/environment/schema/session_files.py +275 -0
  133. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  134. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  135. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +10 -11
  136. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +49 -16
  137. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +39 -9
  138. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +27 -27
  139. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +33 -33
  140. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  141. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +49 -1
  142. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  143. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  144. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  145. package/runtime/gatewaysdk/environment/schema/snapshot.py +516 -140
  146. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  147. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  148. package/runtime/gatewaysdk/environment/schema/tasks.py +267 -276
  149. package/runtime/gatewaysdk/environment/schema/tools_world.py +146 -242
  150. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  151. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  152. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  153. package/runtime/gatewaysdk/environment/schema/validation.py +235 -41
  154. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  155. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  156. package/runtime/gatewaysdk/environment/schema/workers.py +345 -96
  157. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  158. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  159. package/runtime/gatewaysdk/environment/schema/world_tests.py +80 -50
  160. package/runtime/gatewaysdk/environment/score.py +57 -0
  161. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  162. package/runtime/gatewaysdk/environment/world.py +43 -4
  163. package/runtime/gatewaysdk/environment/world_session_contract.py +46 -5
  164. package/skills/agents/connector-template-author.md +5 -1
  165. package/skills/benchmarks-getting-started/SKILL.md +10 -11
  166. package/skills/connector-schema-authoring/SKILL.md +49 -16
  167. package/skills/connector-schema-authoring/connector-worlds.md +142 -11
  168. package/skills/connector-schema-authoring/world-schema.md +103 -51
  169. package/skills/world-data-ingestion/ROWS.md +39 -9
  170. package/skills/world-data-ingestion/SKILL.md +27 -27
  171. package/skills/worlds-getting-started/SKILL.md +33 -33
  172. package/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  173. package/skills/worlds-getting-started/references/gotchas.md +49 -1
  174. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
  175. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  176. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -93,7 +93,11 @@ ship `connector.toml` in the template directory. `init` copies it to the world r
93
93
  The format is documented in `SKILL.md` under "Custom connections" and "Serving the vendor's API":
94
94
 
95
95
  - `[connector]` slug and `base_url`; `[auth]` scheme (`header|bearer|basic|query|oauth2|none`),
96
- `name`, and `secret_env` naming the environment variable, never a value.
96
+ `name`, and `secret_env` naming the environment variable, never a value; `prefixes` when the
97
+ vendor takes other `Authorization` words than `Bearer`, `credential = "password"` when its Basic
98
+ key is the password; `[auth.login]` when the vendor trades its key for a token,
99
+ `[auth.downloads]` when it hands out links to files; `[api] unauthorized_status` and
100
+ `unauthorized` as the vendor refuses a bad key.
97
101
  - `[capture]` pacing (`requests_per_minute` low; providers ask us to be sparing), cursor
98
102
  pagination when the vendor has it (`cursor_field` in the body or `cursor_header`);
99
103
  `[redact]` `hash`/`drop` for every PII field the vendor documents returning, `round` for
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: benchmarks-getting-started
3
- description: Build, validate, dry-run, push, run and read a benchmark on the platform, for an agent (Claude Code, Cursor, Codex). A benchmark is either a world with tasks (tools + data, a schema when the vendor has one; a prompt and the SQL verifiers that grade the world's end state) or a container benchmark (a harbor task tree graded by its own tests/test.sh in a container, or a verifiers package graded by Python reward functions), run k times per task per model. Use when building a benchmark, an eval suite, a coding benchmark, a task set or a leaderboard for an agent; when you have a harbor task tree, task.toml files, a verifiers package, a Taskset, or tests that grade an agent; when choosing between a world benchmark and a container (benchmark runner) benchmark; when you need a dry run before pushing (locally in Docker, or hosted on the benchmark runner with `--hosted` when the machine has no Docker); when running k rollouts per task per model or reading per-task results. Every CLI step names its MCP twin (create_world, env_write_file, env_commit, create_environment_version, run_evaluation, get_task_performance, list_rollouts, get_rollout_samples) and where the result shows in the UI.
3
+ description: Build, validate, dry-run, push, run and read a benchmark on the platform, for an agent (Claude Code, Cursor, Codex). A benchmark is either a world with tasks (tools + data, a schema when the vendor has one; a prompt and the SQL verifiers that grade the world's end state and the requests it received) or a container benchmark (a harbor task tree graded by its own tests/test.sh in a container, or a verifiers package graded by Python reward functions), run k times per task per model. Use when building a benchmark, an eval suite, a coding benchmark, a task set or a leaderboard for an agent; when you have a harbor task tree, task.toml files, a verifiers package, a Taskset, or tests that grade an agent; when choosing between a world benchmark and a container (benchmark runner) benchmark; when you need a dry run before pushing (locally in Docker, or hosted on the benchmark runner with `--hosted` when the machine has no Docker); when running k rollouts per task per model or reading per-task results. Every CLI step names its MCP twin (create_world, env_write_file, env_commit, create_environment_version, run_evaluation, get_task_performance, list_rollouts, get_rollout_samples) and where the result shows in the UI.
4
4
  ---
5
5
 
6
6
  # Benchmarks: getting started
@@ -355,13 +355,12 @@ gateway worlds schema task add ./crm-bench close_ticket --prompt "Close ticket T
355
355
  gateway worlds schema task add ./crm-bench escalate --prompt "..." --verifier state_present --world slack=state_present
356
356
  ```
357
357
 
358
- - `--prompt` is what the agent is told. `--verifier <name>` names `verifiers/<name>.sql`; it must
359
- exist — `schema verifier add <dir> <name> --entity <entity> [--where "<sql condition>"]` scaffolds
360
- it (without `--where`, the `state_present` placeholder). Each verifier becomes a key in `rewards`;
361
- `reward` is their mean.
362
- - A verifier is one SQL statement returning one number in 0..1 over the world's tables (entity
363
- names from `schema/world.json`): `SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM
364
- "crm_tickets" WHERE id = 'T-7' AND status = 'closed';`
358
+ - `--prompt` is what the agent is told. `--verifier <name>` names `verifiers/<name>.sql`; it must exist — `schema verifier add <dir> <name> --entity <entity> [--where "<sql condition>"]` scaffolds
359
+ it (without `--where`, the `state_present` placeholder). Each verifier becomes a key in `rewards`; `reward` is their mean.
360
+ - A verifier is one SQL statement returning one number in 0..1 over the world's tables (entity names from `schema/world.json`):
361
+ `SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "crm_tickets" WHERE id = 'T-7' AND status = 'closed';`
362
+ - A verifier can also read every request the session's world received, in `gateway_requests` (and its summary `gateway_journal`):
363
+ `SELECT CASE WHEN COUNT(*) = 0 THEN 1.0 ELSE 0.0 END FROM gateway_requests WHERE method = 'DELETE';`. Only a World Host session records them (`dry-run` and `validate` read them as not recorded, and such a verifier scores 0 there whatever it accepts); on a journal that may be missing requests it scores 0 with the reason unless `gateway-env.toml` has `[verifiers.<name>] accepts_incomplete_journal = true`, which suits a check a missing request can only fail (`COUNT(*) > 0`), never `= 0`. A linked world's verifier gets no journal, so one that reads it scores 0. Columns, fail-closed rules, declarative and `verify.py` checks over the same requests: `worlds-getting-started` `references/journal-checks.md`.
365
364
  - `--world <alias>=<verifier>` grades a linked world's state too (`schema link` first).
366
365
  - Stored task specs (`instruction`, `seed`, `grader` of kind `assertions` | `python` | `rubric`):
367
366
  `gateway worlds task create task.json --world <slug>`; `worlds-getting-started` §6.
@@ -407,8 +406,8 @@ reward: 0 {"ticket_closed":0}
407
406
  reward is for the untouched world; an agent's rollout is what `benchmarks run` grades. Drive one by hand: …
408
407
  ```
409
408
 
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
409
+ A verifier that cannot run — bad SQL, a missing entity — prints `FAIL verifier 'x': …` with the database
410
+ 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
411
  before any agent acts: rewrite it. Without the bundled runtime (no python3 >= 3.12) the four steps
413
412
  print and the run is marked not executed, exit 0.
414
413
 
@@ -496,5 +495,5 @@ Every run records the version it ran against; `results` shows the per-version tr
496
495
 
497
496
  - `worlds-getting-started`: the world itself — contract, data, sessions, stored tasks, links.
498
497
  - `world-data-ingestion`: rows in, calls out. `connector-schema-authoring`: contract, fidelity shapes.
499
- - Consumer pages: `gateway_documentation/pages/cli/benchmarks.mdx`, `pages/worlds/benchmarks.mdx`, `pages/evaluation/benchmarks-harbor.mdx`.
498
+ - Consumer pages (docs.surfacearea.ai): `cli/benchmarks`, `worlds/benchmarks`, `evaluation/benchmarks-harbor`.
500
499
  - `documentation/features/benchmark-containers.md`: the container substrate, kinds, the runner.
@@ -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) |
@@ -104,9 +104,9 @@ deliverable can finish with synthetic fixtures and explicitly skipped live valid
104
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`.
105
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.
106
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.
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 nested key or relationship field is a JSON Pointer, `/owner/user_id`, never `owner.user_id`; the compiler's refusal says so.
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 SQLite'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 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).
110
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.
111
111
 
112
112
  ### 2. Tenant overlay (required for tenant-shaped, optional for mixed, absent for base)
@@ -133,7 +133,8 @@ deliverable can finish with synthetic fixtures and explicitly skipped live valid
133
133
  ### 5. Tools (only if the world ships tools)
134
134
 
135
135
  - [ ] Every tool in `x-gateway.tools` has exactly one handler in `tools/*.py` (the loader refuses a mismatch); generated defaults are fine.
136
- - [ ] 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.
137
138
  - [ ] Handlers never read `benchmark_runtime_context` or `benchmark_conversation_events`.
138
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).
139
140
 
@@ -143,7 +144,9 @@ Tool handlers (`tools/*.py`) reach the world's rows through `from gateway_env im
143
144
  exactly these methods; `gateway worlds schema check .` refuses any other `store.<name>` at file:line
144
145
  with this list, and a hosted call into such a handler answers 400 `{error: "handler", detail, handler}`
145
146
  (an `AttributeError`/`TypeError`/`NameError` is the author's bug; anything else a handler raises is a
146
- 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.
147
150
 
148
151
  - `get(entity: str, key: dict) -> dict | None` — one row by primary key, or `None`.
149
152
  - `list(entity: str) -> list[dict]` — every row, ordered by key.
@@ -235,7 +238,7 @@ Full procedure: `.llm_artifacts/plans/connector-implementation-orchestration.md`
235
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).
236
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.
237
240
  - Writing a nested field as `owner.user_id` in `unique` or `relationships`. Nested paths are JSON Pointers: `/owner/user_id`.
238
- - 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.
239
242
 
240
243
  ## Where this skill is discoverable
241
244
 
@@ -270,8 +273,12 @@ These source checks do not imply live-provider validation or executed fidelity s
270
273
 
271
274
  A world can describe the vendor it mirrors in `connector.toml` at its root: base URL,
272
275
  auth scheme (`header`, `bearer`, `basic`, `query`, `oauth2`, `none`) with the secret named by an
273
- environment variable (for `basic`, the credential is the Basic *user* and the password is ignored:
274
- the host and `worlds serve` present `Basic b64("<key>:")`), capture pacing, a redaction policy (`hash` or `drop` fields at any
276
+ environment variable (a `bearer`'s `prefixes` lists the `Authorization` words the vendor takes,
277
+ `["Bearer", "token"]` for GitHub, the first carried; a `basic` key is the Basic user with an empty
278
+ password, or with `credential = "password"` the password under any user, as Atlassian and
279
+ ServiceNow take it), the vendor's own login route (`[auth.login]`; an oauth2 `token_url` path may
280
+ name a segment, `/ccx/oauth2/{tenant}/token`) and presigned download routes (`[auth.downloads]`),
281
+ capture pacing, a redaction policy (`hash` or `drop` fields at any
275
282
  depth), and the operations the agent actually calls (method, path with `{args}`, query
276
283
  params, and the entity plus results path their rows land in). The same file is meant to
277
284
  drive the platform's custom source later, so describe once.
@@ -313,6 +320,10 @@ Three refinements the first three vendors forced:
313
320
  as well as a path argument; a parameter the caller leaves out does not narrow, and one
314
321
  sent more than once (`status[]=a&status[]=b`) matches rows carrying any of its values.
315
322
  Handlers read every value from `ctx.query_all`; the `query` argument keeps the first.
323
+ - **Uploads.** A multipart form reaches a handler as its fields (a file part reads
324
+ `{"filename", "content_type", "size"}`) with the bytes in `ctx.files[name].content`; a raw
325
+ body (`application/octet-stream`, `text/csv`) reads `body` as `{}` with the bytes in
326
+ `ctx.raw`. A declared route refuses an upload as the vendor's 400.
316
327
 
317
328
  Four more the Brex retrospective forced (each cost a day of one-field-per-run fixing):
318
329
 
@@ -389,25 +400,47 @@ them:
389
400
  - `[api] envelope = "results"` wraps rows as `{"results": [...], "hits": N, "cursor": ""}`
390
401
  (empty means a bare array); `hits_key = ""` leaves the count out and
391
402
  `cursor_absent_when_done = true` (world-wide, or per route under `[operations.api]`)
392
- leaves the cursor key out of the last page — Brex's `{items, next_cursor?}`.
403
+ leaves the cursor key out of the last page — Brex's `{items, next_cursor?}`. A dotted
404
+ `envelope = "message.items"` nests the page (`{message: {items, total-results, next-cursor}}`),
405
+ and `[operations.api] wrapper = '{"status": "ok", "message-type": "work-list"}'` lays it onto
406
+ the rest of the vendor's envelope; a single row is wrapped only by its route's own `envelope`.
393
407
  - `unauthorized` / `not_found` / `invalid` are JSON strings replayed on 401 / 404 / 400, so
394
408
  the vendor's own error bodies come back; `""` (or `'null'`) means no body at all. A route
395
409
  whose missing row the vendor answers its own way sets `not_found` and `not_found_status`
396
- under `[operations.api]`, falling back to `[api]`.
410
+ under `[operations.api]`, falling back to `[api]`. A path the world does not serve answers
411
+ `not_found`; a path it serves, called with another method, answers `wrong_method` (405 with
412
+ `Allow`, no body unless declared; `wrong_method_status` for a vendor that says 404). A write
413
+ the contract refuses answers `invalid` exactly as declared; the refusal's rule goes to the
414
+ host's log, never the answer.
415
+ - `link_header = true` sends RFC 8288 `Link: <next>; rel="next"` (and `rel="prev"`) on list
416
+ answers, each URL the request's own (GitHub's paging); `cors = true` answers a browser's
417
+ preflight before any credential and names any origin (exposing `Link`) on every answer, for a vendor whose
418
+ API serves pages (`worlds serve` answers only this machine's pages). HEAD answers as GET
419
+ without a body on every world.
397
420
  - `[operations.api] action` makes a route a `create`, `update`, `delete` or `handler`; handlers live in the world's `api/handlers.py` and carry computed results and workflow state (`ctx.ladder` on the clock). A world is read _and_ write: an agent that creates a search and gets 501 is not testing anything. Full reference: `documentation/features/connector-worlds.md`.
398
421
  - `[operations.api] filter = { email = "attributes.email" }` maps a path argument to the
399
422
  row field it selects on, matched case-insensitively at any depth. An operation without
400
423
  an `entity` answers 501 `not_modelled` rather than inventing a response.
424
+ - `[auth.login]` mirrors a vendor that trades its key for a token (`path`, `credential = { json |
425
+ form | header = "<field>" }`, `required`, `reply = '{"data": {"token": "{token}"}}'`);
426
+ later calls carry the token the way `scheme` says, and only tokens minted for that session count.
427
+ `[auth.downloads] routes = ["download_x"]` lets those GET routes answer a link a handler signs with
428
+ `ctx.signed_url(path)` without the key. Tokens and links live as long as the session; set
429
+ `ttl_seconds` (login, downloads, oauth2) only when the eval needs expiry. `mode = "open"` under
430
+ `[auth]` opens sessions with no credential at all (a capability URL; `--auth` on the session's
431
+ open overrides; `scheme = "open"` is refused). Full grammar: connector-worlds.md, "The door".
401
432
  - `[ui] static = "ui/static"` (+ `entry`, `api_path`, `generated`) is the page over the
402
433
  routes: generated by `compile` from the contract unless `generated = false`, served by the
403
434
  host on the session's ui origin (`?token=` once, then a cookie; `api_path` rewritten onto
404
435
  the routes) and locally on its own port (and at `/__ui/`). A page holds no key; the host presents the world's
405
- credential for it, the way it does for a bearer of the session token.
436
+ credential for it, the way it does for a caller holding the session token in `X-World-Session`.
406
437
 
407
438
  `gateway worlds serve PATH --port 8080 [--api-key K]` runs it locally; the runner's admin
408
- endpoints (`/healthz`, `/__world/seed`, `/__world/reset`, `/__world/state`) sit beside the
409
- vendor routes. `gateway bench push PATH` publishes the world: for a world carrying
439
+ endpoints (`/__world/seed`, `/__world/reset`, `/__world/state`) sit beside the vendor routes
440
+ and answer only the run's `X-World-Admin-Token` (`gateway worlds test` hands a world's pytest
441
+ files theirs as `WORLD_ADMIN_TOKEN`; by hand, use `/__session/*`); `/healthz` answers everyone,
442
+ and a World Host session's api and tool doors answer none of them (there `/healthz` is the world's own path; its ui origin answers `/healthz` under `api_path` to the twin's own page). `gateway bench push PATH` publishes the world: for a world carrying
410
443
  `connector.toml` it packages the api-kind bundle the platform hosts on the way (root
411
444
  legacy-shaped on purpose, since the api runner refuses a schema bundle there; `server/`
412
445
  needs nothing installed). Open a session with `--surface api` and hand the client that
413
- URL; the vendor's auth scheme applies, with the session's own api token as the credential.
446
+ URL; the vendor's auth applies as `[auth]` declares it, with the session's own api token as the credential.
@@ -81,13 +81,143 @@ gateway worlds session open spycloud-world -t default --surface api # prints a
81
81
  A hosted api session runs on a fresh Fargate pod. The first open of a version takes about
82
82
  fifteen minutes (pod scheduling plus pulling the runner sidecar), during which the session
83
83
  reads `PROVISIONING` and the URL answers 503; that is a cold start, not a fault, until
84
- about twenty minutes have passed. `session open` waits ten minutes by default, so on a cold
85
- version pass `--no-wait` and poll `gateway worlds session status <sessionId>` until `ready`.
84
+ about twenty minutes have passed. `session open` waits `--timeout` seconds (default 600) and,
85
+ when that runs out, prints the session with `ready: false` and exits 1 while it keeps opening;
86
+ on a cold version pass `--no-wait` and poll `gateway worlds session status <sessionId>` until
87
+ `ready`.
88
+
89
+ The world's API mirrors the vendor's auth as `[auth]` declares it (`door.py`, "The door" below). A
90
+ hosted session's credential is its own api token, `worlds serve`'s the value `--api-key` pins
91
+ (default `conform`), and `WORLD_API_KEY` applies only to a legacy api bundle. A hosted session takes
92
+ that token the way the vendor takes its key: after an `Authorization` word the vendor takes, in the
93
+ declared header, as the Basic user (or password), in the declared query parameter, a token the
94
+ declared login minted for this session, or a signed download link. Platform tooling sends it in the
95
+ platform's own `X-World-Session` header, which every world takes and no vendor's client sends
96
+ (both SDKs' `apiHeaders`); the platform's `Authorization: Bearer` of the session token reaches
97
+ every world for good (the host counts it as `requests.platform_bearer` where the vendor takes its
98
+ key another way). An **open** session asks for nothing: a world sets `mode = "open"` under `[auth]`
99
+ as its sessions' default, and a session's open (`auth: "open"`, `--auth open`) chooses either way.
100
+ Its api and ui answer without a credential on a capability hostname,
101
+ `o-<sid>-<label>[-api].<worlds domain>`, the label a 130-bit secret derived from the session token
102
+ and kept for the session's life (a reopen, a reset, a restart keep the link); the session's own
103
+ `w-<sid>` hostname keeps asking for the credential. On the capability hostname the host is the
104
+ proof, so `ttl_seconds` bounds nothing there; a link the world signs still names the `w-` host. Anything
105
+ else answers the vendor's refusal configured under `[api].unauthorized_status` and
106
+ `[api].unauthorized` (`""` or `'null'` for a bare status with no body, the way some vendors
107
+ answer: `unauthorized_status = 403` with `'{"message": "Invalid API key"}'`); a world that declares
108
+ neither gets the host's own `401 {"error": "invalid session token"}`.
109
+
110
+ ### The door
111
+
112
+ `[auth]` says where the credential rides and, optionally, how the vendor trades it for a token and
113
+ which files it hands out as links (synthetic examples; every name is invented):
114
+
115
+ ```toml
116
+ [auth] # a key in the URL (?key=...)
117
+ scheme = "query"
118
+ name = "key"
119
+ secret_env = "VENDOR_API_KEY"
120
+ ```
121
+
122
+ ```toml
123
+ [auth] # Authorization: Bearer <key> or token <key>, as GitHub takes it
124
+ scheme = "bearer"
125
+ prefixes = ["Bearer", "token"] # the words the vendor takes, any case; calls carry the first
126
+ secret_env = "VENDOR_TOKEN"
127
+ ```
128
+
129
+ ```toml
130
+ [auth] # Basic email:api_token, the key the password under any user
131
+ scheme = "basic"
132
+ credential = "password" # default "user": the key the user, the password empty
133
+ secret_env = "VENDOR_API_TOKEN"
134
+ ```
135
+
136
+ ```toml
137
+ [auth] # a JSON login that answers a token; calls carry it as a bearer
138
+ scheme = "bearer"
139
+ secret_env = "VENDOR_PASSWORD"
140
+
141
+ [auth.login]
142
+ method = "POST" # the default
143
+ path = "/token" # under base_url's path, as routes are; never /__…
144
+ credential = { json = "password" } # or { form = "secret" }, { header = "X-Api-Key" }; a dotted json path reaches inside
145
+ required = ["username", "realm"] # what else the vendor demands, read from the same place
146
+ reply = '{"access_token": "{token}", "expires_in": "{expires_in}", "token_type": "Bearer"}'
147
+ ttl_seconds = 86400 # opt in to expiry; absent, a token lives as long as the session
148
+ ```
149
+
150
+ ```toml
151
+ [auth.login] # an api-key login whose reply nests the token: {"data": {"token": …}}
152
+ path = "/login"
153
+ credential = { json = "api_key" }
154
+ reply = '{"data": {"token": "{token}"}}'
155
+ ```
156
+
157
+ ```toml
158
+ [auth.downloads] # presigned links: these GET routes answer a signed URL without the key
159
+ routes = ["download_results"]
160
+ ttl_seconds = 900 # opt in to expiry; absent, a link lives as long as the session
161
+ ```
86
162
 
87
- The world's API honours the vendor's auth scheme: a hosted session accepts its own api token (as a
88
- bearer or in the vendor's header), `worlds serve` the credential `--api-key` pins (default `conform`),
89
- and `WORLD_API_KEY` applies only to a legacy api bundle. Anything else answers 401 with the body configured under
90
- `[api].unauthorized` (`""` or `'null'` for a bare status with no body, the way some vendors answer).
163
+ - **The session's credential is the key.** On the login route the session token (or the pin) goes
164
+ where `credential` says; a wrong or missing one is the vendor's 401 (`[api].unauthorized`), a
165
+ missing `required` field or an unreadable body its 400 (`[api].invalid`). The right one is
166
+ answered `reply` (default `{"access_token", "token_type", "expires_in"}`) with the token at
167
+ `"{token}"` and the lifetime at `"{expires_in}"`, a key whose value is `"{expires_in}"` left out
168
+ when the world declares no `ttl_seconds`; `status` (default 200) is the vendor's. On an open
169
+ session's capability hostname the login answers whatever credential the client sends, or none.
170
+ - **Later calls carry the token the way `scheme` says** (bearer, header, Basic, query parameter). A
171
+ login world takes only tokens it minted, never the raw key, as the vendor does; the platform's
172
+ `X-World-Session` header still reaches a hosted session (the SDKs send it), and the host then
173
+ presents the world a freshly minted token and drops the header. A refresh token an oauth2 world
174
+ minted answers every time it is presented, wherever the session runs, and lives as long as the
175
+ session even where `[auth]` declares `ttl_seconds`, which bounds the access token alone: the
176
+ short access token and long refresh real vendors hand out. An oauth2
177
+ `token_url` path may name a segment (`/ccx/oauth2/{tenant}/token`), which any value fills.
178
+ - **Tokens and links are bound to the session.** A token is an HS256 JWT, a link an HMAC-SHA256 over
179
+ its path and expiry, each under a key derived from the session's credential (no new secret): a
180
+ token or link from another session never verifies, a tampered one is refused, one past a declared
181
+ lifetime is refused, and a supervisor, its version worker and any host the session moves to check
182
+ them alike. Nothing expires unless the world declares `ttl_seconds`. Comparisons run in constant
183
+ time.
184
+ - **A download route is never open.** A handler hands out a link with
185
+ `ctx.signed_url("/exports/<id>/results.zip")` (the path as the client sends it under base_url's
186
+ path; an optional second argument gives it a lifetime in seconds); the route answers that link
187
+ without the key for the session's life, or until its declared lifetime ends, and the credential
188
+ as any other route does. The route names its object in the path and declares no `params`, and a
189
+ link carries `signature` (and `expires`, when it has a lifetime) alone, so it reaches the one
190
+ object it was signed for.
191
+ - **Nothing logs a key.** The call log and the request ledger drop a query key and a link's
192
+ `signature`; a token or a link's signature inside a longer string reads `[redacted]` in place;
193
+ the ledger keeps no login request body and scrubs every body it keeps (JSON or text, the answer
194
+ that hands out a link and a page link the world echoes included) of the session credential, a
195
+ carried parameter's value, a minted token and a signature; the host writes no request URL to its
196
+ log, and the chart's World Host Ingress keeps no nginx access log (an ALB access log you turn on,
197
+ or another controller's default access log, would record URLs).
198
+ - **A link reaches its own route.** A request a signed link admits is routed among the
199
+ `[auth.downloads]` routes alone, so a sibling route on the same path (one that takes `params`)
200
+ never answers a link.
201
+ - **Capture does not log in.** `connector capture` and the live hook lanes send `secret_env` in the
202
+ scheme's carrier as it is (oauth2 alone exchanges first): for a vendor that trades its key for a
203
+ token, set `secret_env` to a token its own login minted.
204
+ - `scheme = "oauth2"` is the RFC 6749 token route (below); it takes no `[auth.login]`, and neither
205
+ does `none`. A login path that is also a declared route of the same method is refused, as is a
206
+ download route that answers anything but GET or declares any `params`, and a setting of another
207
+ scheme (`prefixes` on `header`, `credential` on `bearer`).
208
+ - **Uploads reach handlers.** A write's body is read by its media type: JSON, a form, a multipart
209
+ form (each field's first part; a file part reads `{"filename", "content_type", "size"}` with its
210
+ bytes in `ctx.files[name].content`) or multipart/related (the first part as JSON, the rest in
211
+ `ctx.files["1"]`, …). Any other type (`application/octet-stream`, `text/csv`) is an upload: a
212
+ handler route reads `body` as `{}` and the bytes in `ctx.raw`; a declared route refuses it as the
213
+ vendor's 400, as it refuses JSON that does not parse.
214
+
215
+ The runner's own routes (`/__world/seed|reset|state|calls`) answer only `X-World-Admin-Token`. A session
216
+ pod and a Batch run mint that token themselves. A twin you host yourself (`hostedUrl`) gets it from
217
+ the world's secret `WORLD_ADMIN_TOKEN` (`gateway bench secrets set --env <slug> --key WORLD_ADMIN_TOKEN`,
218
+ the value on stdin), which a run or a session against the twin carries: start the twin's
219
+ `server/main.py` with the same `WORLD_ADMIN_TOKEN` in its environment, or every seed and grade is
220
+ refused with 403 `admin_token_required`.
91
221
 
92
222
  **Data.** Captures are one way in. Any agent can put rows into the world without knowing its
93
223
  layout: `gateway worlds data show ./spycloud-world` prints the kind and entity counts,
@@ -117,13 +247,13 @@ least one `[[operations]]` entry.
117
247
  | Table | Keys | Notes |
118
248
  | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
119
249
  | `[connector]` | `slug`, `base_url` | `base_url` is an http(s) origin plus optional path, no query. Requests carrying that path prefix are accepted too. |
120
- | `[auth]` | `scheme` (`header`, `bearer`, `basic`, `query`, `oauth2`, `none`), `name`, `secret_env`, `headers`, `token_url`, `client_id_env`, `scope` | The secret is only ever named by an env var. `headers = { "X-App-Token" = "VENDOR_APP_TOKEN" }` adds more credential headers. `oauth2` is the client-credentials grant: capture exchanges `client_id_env` + `secret_env` at `token_url` (a path under `base_url` or an absolute URL, default `/oauth/token`) for the bearer it then sends, and the served world mints bearers on the same path. |
250
+ | `[auth]` | `scheme` (`header`, `bearer`, `basic`, `query`, `oauth2`, `none`), `name`, `secret_env`, `headers`, `prefixes`, `credential`, `token_url`, `client_id_env`, `scope`, `[auth.login]`, `[auth.downloads]` | The secret is only ever named by an env var. `prefixes` (bearer, oauth2) lists the `Authorization` words the vendor takes; `credential = "password"` (basic) reads the key as the Basic password. A token path (`token_url`'s, `[api] token_path`) is a route path (each `{name}` once) that no declared POST operation answers too. `headers = { "X-App-Token" = "VENDOR_APP_TOKEN" }` adds more credential headers. `oauth2` is the client-credentials grant: capture exchanges `client_id_env` + `secret_env` at `token_url` (a path under `base_url` or an absolute URL, default `/oauth/token`) for the bearer it then sends, and the served world mints bearers on the same path. `[auth.login]` is the vendor's own login route and `[auth.downloads]` its presigned download routes ("The door" above). |
121
251
  | `[capture]` | `requests_per_minute`, `timeout_seconds`, `max_pages`, `cursor_param`, `cursor_field`, `cursor_header` | Pacing between pages; providers ask us to be sparing. The next cursor is read from a body field or a response header (Torchlight sends `Cursor:`), never both, and is sent back as `cursor_param`; a cursor that is an absolute URL on the connection's host (DRF's `next`) is followed by its query. |
122
252
  | `[redact]` | `hash`, `drop`, `round`, `preserve` | Applied before a body reaches disk. `preserve` hashes shape-preservingly (same length, digits stay digits, letters keep their case, separators stay; slug-salted, deterministic) so an account number still meets the field's format — `hash` made it a 71-char `sha256:` string the contract refused (Brex). `hash` writes `sha256:<hex>` salted with the slug so joins survive, element by element for arrays so the shape the contract expects survives too; `drop` removes; `round = { lat = 2, lon = 2 }` keeps numbers numeric but coarsens them. A bare name matches at any depth; a dotted path (`results.*.email`, `*` for list items) matches that place only, so a catalog's `assets` count map keeps its `email` key. Field names keep the vendor's casing. |
123
- | `[api]` | `envelope`, `hits_key`, `cursor_key`, `page`, `limit_param`, `offset_param`, `cursor_param`, `page_size`, `previous_key`, `page_links`, `page_headers`, `cursor_absent_when_done`, `unauthorized`, `not_found`, `invalid`, `*_status`, `error_content_type`, `token_path`, `handlers`, `before` | `envelope = "results"` wraps rows as `{results, hits, cursor}` under the vendor's key names; empty means a bare array. `hits_key = ""` leaves the count out and `cursor_absent_when_done = true` leaves the cursor key out of the last page (instead of `""`), together the `{items, next_cursor?}` shape Brex-style vendors answer and clients test with `"next_cursor" in body`. `page` is `none`, `offset` or `cursor`, with the vendor's parameter names; `previous_key` adds the previous page and `page_links = true` renders next/previous as absolute URLs of the served host, the way Django REST Framework answers; `page_headers = { cursor = "Cursor", total = "Total-Count" }` sends the same values as response headers for vendors that page that way (Torchlight). Error bodies are JSON strings replayed verbatim with the vendor's statuses and content type (`application/problem+json` for RFC 7807 vendors); `""` (or `'null'`) means no body at all, for vendors that answer a bare 401. An oauth2 world mints bearers on `token_path` (default the spec's `token_url`) and honours only those. `handlers` names the world's Python module (default `api/handlers.py` when present); `before` names a gate in it that runs before every operation, declarative ones included, and returns `None` to let the request through or an answer (quota, allow-list, key state) to stop it. |
124
- | `[[operations]]` | `name`, `method`, `path`, `params`, `entity`, `results` | `path` may carry `{args}`; a `params` name may end in `[]` (`expand[]`, `status[]`) for a key the vendor repeats, which capture then sends repeated and the served route filters on any value of; `results` is the dotted path to the row array (empty when the body is the row). An operation without `entity` never seeds and answers 501 `not_modelled`. An `entity` (or an `explode` target) that `schema/world.json` does not declare is refused by `connector validate`, `schema compile`, `schema check` and the platform's describe (`gateway worlds describe`, local or platform) alike — `operation X lands on entity Y, which schema/world.json does not declare (declared: …)` at `/operations/<i>/entity` — and nothing is written; hand-edited TOML meets the same gate `route add` applies. |
253
+ | `[api]` | `envelope`, `hits_key`, `cursor_key`, `page`, `limit_param`, `offset_param`, `cursor_param`, `page_size`, `previous_key`, `page_links`, `page_headers`, `link_header`, `cursor_absent_when_done`, `unauthorized`, `not_found`, `invalid`, `wrong_method`, `*_status`, `error_content_type`, `cors`, `token_path`, `handlers`, `before` | `envelope = "results"` wraps rows as `{results, hits, cursor}` under the vendor's key names; empty means a bare array. `hits_key = ""` leaves the count out and `cursor_absent_when_done = true` leaves the cursor key out of the last page (instead of `""`), together the `{items, next_cursor?}` shape Brex-style vendors answer and clients test with `"next_cursor" in body`. `page` is `none`, `offset` or `cursor`, with the vendor's parameter names; `previous_key` adds the previous page and `page_links = true` renders next/previous as absolute URLs of the served host, the way Django REST Framework answers; `page_headers = { cursor = "Cursor", total = "Total-Count" }` sends the same values as response headers for vendors that page that way (Torchlight). Error bodies are JSON strings replayed verbatim with the vendor's statuses and content type (`application/problem+json` for RFC 7807 vendors); `""` (or `'null'`) means no body at all, for vendors that answer a bare 401. A path the world does not serve answers `not_found`; a path it serves, called with a method none of its routes answer, answers `wrong_method` (405 by default with the `Allow` header RFC 9110 requires, no body unless declared; `wrong_method_status` for a vendor that answers another status, which carries no `Allow`). A write the contract refuses answers `invalid` exactly as declared, and the refusal's rule and schema path go to the host's log, never the answer (the request ledger keeps the request). `link_header = true` sends RFC 8288 `Link: <next>; rel="next"` (and `rel="prev"`) on list answers, each URL the request's own with the page's paging parameters, as GitHub pages. `cors = true` is a vendor whose API answers browsers: an `OPTIONS` preflight is answered 204 before any credential (`Access-Control-Allow-Origin: *`, the methods the world serves, the headers the page asked to send) and every answer names any origin and exposes its headers (`Link`); without it an `OPTIONS` is routed like any other method. `gateway worlds serve` (and `worlds test`, which opens it) answers only this machine's pages: a request from another site's `Origin` is refused 403, since its pin is public. A `HEAD` answers as `GET` without a body, and a `DELETE` that carries a body is read like a `POST`'s. An oauth2 world mints bearers on `token_path` (default the spec's `token_url`) and honours only those. `handlers` names the world's Python module (default `api/handlers.py` when present); `before` names a gate in it that runs before every operation, declarative ones included, and returns `None` to let the request through or an answer (quota, allow-list, key state) to stop it. |
254
+ | `[[operations]]` | `name`, `method`, `path`, `params`, `entity`, `results` | `path` may carry `{args}`; a `params` name keeps the vendor's spelling, dots included (`query.bibliographic`, `filter.overallStatus`), and may end in `[]` (`expand[]`, `status[]`) for a key the vendor repeats, which capture then sends repeated and the served route filters on any value of; `results` is the dotted path to the row array (empty when the body is the row). An operation without `entity` never seeds and answers 501 `not_modelled`. Routes are never tools: an agent calls them over HTTP (the api url and token `session open --surface api` prints), and a tool exists only where `x-gateway.tools` declares one with a handler. An `entity` (or an `explode` target) that `schema/world.json` does not declare is refused by `connector validate`, `schema compile`, `schema check` and the platform's describe (`gateway worlds describe`, local or platform) alike — `operation X lands on entity Y, which schema/world.json does not declare (declared: …)` at `/operations/<i>/entity` — and nothing is written; hand-edited TOML meets the same gate `route add` applies. |
125
255
  | `[operations.ingest]` | `drop`, `explode`, `carry_args` | `drop` removes vendor fields the entity does not carry; each `[[operations.ingest.explode]]` (`field`, `entity`, `carry`, `take`) turns a nested array into child rows; `carry_args = { account_id = "id" }` stamps the capture's path argument or query parameter onto every row before projection (a statement only knows its account from the URL it was fetched under). `connector ingest --dry-run [--report FILE]` lists every violation of every capture and writes nothing. |
126
- | `[operations.api]` | `filter`, `match`, `action`, `status`, `single`, `envelope`, `page`, `body`, `defaults`, `generate`, `handler`, `sample`, `sample_headers`, `sample_body`, `not_found`, `not_found_status`, `cursor_absent_when_done` | `filter` maps a path argument or declared query parameter to the row field it selects on (case-insensitive, any depth; an absent parameter does not narrow, one sent more than once matches rows carrying any of its values); `match = { name = "contains" }` switches an argument from equality to substring or `prefix`, and a list field matches when any element does. `action` is `read` (default), `create`, `update`, `delete` or `handler`: writes persist through the contract, `body` maps row fields (dotted for nested) to request-body paths, `defaults` fixes constants, `generate` fills `uuid`, `int` or `now`; `update` and `delete` find their row through `filter` and answer the vendor's 404 otherwise. `status` is the 2xx the vendor answers (201 for create, 204 for delete by default), `single` returns the row itself instead of an envelope, `envelope` and `page` override the world-wide setting per route. `handler` names a function `def name(ctx, args, query, body)` in the handlers module that returns a body, `(status, body)` or `(status, body, headers)`; `ctx` reads and writes the store (`rows`, `get`, `find`, `insert`, `update`, `delete`), keeps time (`now`, `elapsed`, `ladder` for status machines, frozen by `GATEWAY_WORLD_CLOCK`), mints ids (`uuid`) and shapes answers (`envelope`, `not_found`, `invalid`) and sees the request's `headers` and `query_all` (every value of every parameter, `{"expand[]": ["a", "b"]}`; the `query` argument keeps the first value only). `not_found` / `not_found_status` answer this route's missing row the vendor's own way (a 403 with its own message for one resource) and fall back to `[api]`; `cursor_absent_when_done` overrides `[api]` for this route. `sample = { ip = "203.0.113.5" }` gives the conformance run a value a validating route accepts when no seeded row can supply one; `sample_headers = { "Idempotency-Key" = "conform-1" }` and `sample_body = { reason = "conform" }` give it the headers and body a route demands (read by `connector conform` only; the served API never sends requests). |
256
+ | `[operations.api]` | `filter`, `match`, `action`, `status`, `single`, `envelope`, `wrapper`, `page`, `body`, `defaults`, `generate`, `handler`, `sample`, `sample_headers`, `sample_body`, `not_found`, `not_found_status`, `cursor_absent_when_done` | `filter` maps a path argument or declared query parameter to the row field it selects on (case-insensitive, any depth; an absent parameter does not narrow, one sent more than once matches rows carrying any of its values); `match = { name = "contains" }` switches an argument from equality to substring or `prefix`, and a list field matches when any element does. `action` is `read` (default), `create`, `update`, `delete` or `handler`: writes persist through the contract, `body` maps row fields (dotted for nested) to request-body paths, `defaults` fixes constants, `generate` fills `uuid`, `int` or `now`; `update` and `delete` find their row through `filter` and answer the vendor's 404 otherwise; they, and a `single` read with a path argument, refuse (`finds its row by nothing`, 400) when neither `filter` nor a path argument naming a field selects a row, rather than act on some row; a singleton served under a scoped path answers through `action = "handler"`. `status` is the 2xx the vendor answers (201 for create, 204 for delete by default), `single` returns the row itself instead of an envelope, `envelope` and `page` override the world-wide setting per route. A dotted `envelope` nests the answer the way the vendor does (`message.items` answers `{message: {items, total-results, next-cursor}}`), and a single row is wrapped only by its own route's `envelope` (`message` answers `{message: row}`). `wrapper` is the rest of the vendor's envelope as a JSON object string (`'{"status": "ok", "message-type": "work-list"}'`), the answer laid onto it key by key; `schema init --from-openapi` writes it from the document. `handler` names a function `def name(ctx, args, query, body)` in the handlers module that returns a body, `(status, body)` or `(status, body, headers)`; `ctx` reads and writes the store (`rows`, `get`, `find`, `insert`, `update`, `delete`), keeps time (`now`, `elapsed`, `ladder` for status machines, frozen by `GATEWAY_WORLD_CLOCK`), mints ids (`uuid`) and shapes answers (`envelope`, `not_found`, `invalid`) and sees the request's `headers` and `query_all` (every value of every parameter, `{"expand[]": ["a", "b"]}`; the `query` argument keeps the first value only). `not_found` / `not_found_status` answer this route's missing row the vendor's own way (a 403 with its own message for one resource) and fall back to `[api]`; `cursor_absent_when_done` overrides `[api]` for this route. `sample = { ip = "203.0.113.5" }` gives the conformance run a value a validating route accepts when no seeded row can supply one; `sample_headers = { "Idempotency-Key" = "conform-1" }` and `sample_body = { reason = "conform" }` give it the headers and body a route demands (read by `connector conform` only; the served API never sends requests). |
127
257
 
128
258
  ### Scaffolding a route
129
259
 
@@ -183,7 +313,8 @@ does all of that from the same `connector.toml`:
183
313
  handlers and the gate may answer with headers too (`SpyCloud-Error`, `Retry-After`).
184
314
  - An oauth2 world answers the vendor's token route before any authorization, so a client that
185
315
  performs the grant first works unchanged; a hosted session checks the client secret against its
186
- own api token, `worlds serve` against the `--api-key` pin.
316
+ own api token, `worlds serve` against the `--api-key` pin. A declared `[auth.login]` route is
317
+ answered the same way, ahead of every handler.
187
318
 
188
319
  The handlers ship inside the api bundle beside the world, so the hosted container runs them
189
320
  with nothing installed. The abstraction is the platform's; the handlers are the customer's.