@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.
- package/README.md +6 -1
- package/dist/cli.js +3971 -2338
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +3950 -2318
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +1 -1
- package/dist/files/index.d.ts +1 -1
- package/dist/files/index.js +214 -41
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +206 -35
- package/dist/files/index.mjs.map +1 -1
- package/dist/{index-DAb-FCMg.d.ts → index-DUHmS74p.d.ts} +3 -13
- package/dist/{index-D6oi1TWE.d.mts → index-mJhG3vZU.d.mts} +3 -13
- package/dist/index.d.mts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1456 -564
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1433 -557
- package/dist/index.mjs.map +1 -1
- package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
- package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
- package/dist/traces/index.d.mts +1 -1
- package/dist/traces/index.d.ts +1 -1
- package/dist/traces/index.js +211 -38
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +203 -32
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +2 -2
- package/dist/tracing/index.d.ts +2 -2
- package/dist/tracing/index.js +96 -21
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +96 -21
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +300 -123
- package/dist/worlds/index.d.ts +300 -123
- package/dist/worlds/index.js +1385 -508
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1377 -501
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_bundle.py +2 -27
- package/runtime/gatewaysdk/environment/_materialize.py +49 -69
- package/runtime/gatewaysdk/environment/_world.py +122 -197
- package/runtime/gatewaysdk/environment/backing.py +137 -0
- package/runtime/gatewaysdk/environment/core.py +1 -1
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
- package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
- package/runtime/gatewaysdk/environment/runtime.py +8 -13
- package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
- package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
- package/runtime/gatewaysdk/environment/schema/api.py +266 -515
- package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
- package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
- package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
- package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
- package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
- package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
- package/runtime/gatewaysdk/environment/schema/data.py +50 -207
- package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
- package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
- package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
- package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
- package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
- package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
- package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
- package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
- package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
- package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
- package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
- package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
- package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
- package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
- package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
- package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
- package/runtime/gatewaysdk/environment/schema/host.py +158 -250
- package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
- package/runtime/gatewaysdk/environment/schema/local.py +44 -71
- package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
- package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
- package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
- package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
- package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
- package/runtime/gatewaysdk/environment/schema/platform.py +124 -178
- package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
- package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
- package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
- package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
- package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
- package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
- package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +22 -14
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +16 -16
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +18 -18
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
- package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
- package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
- package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
- package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
- package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
- package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
- package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
- package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
- package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
- package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
- package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
- package/runtime/gatewaysdk/environment/score.py +57 -0
- package/runtime/gatewaysdk/environment/secret_values.py +36 -0
- package/runtime/gatewaysdk/environment/world.py +42 -3
- package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
- package/skills/benchmarks-getting-started/SKILL.md +2 -2
- package/skills/connector-schema-authoring/SKILL.md +22 -14
- package/skills/connector-schema-authoring/connector-worlds.md +26 -10
- package/skills/connector-schema-authoring/world-schema.md +111 -51
- package/skills/world-data-ingestion/ROWS.md +29 -3
- package/skills/world-data-ingestion/SKILL.md +16 -16
- package/skills/worlds-getting-started/SKILL.md +18 -18
- package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
- package/skills/worlds-getting-started/references/gotchas.md +15 -0
- package/skills/worlds-getting-started/references/openapi-import.md +50 -21
- package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
|
@@ -17,6 +17,7 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
17
17
|
| `worlds migrate <slug> [--apply] [--force]` / `--all` | `migrate_world` |
|
|
18
18
|
| `bench push` | `env_write_file` + `env_commit`, or `create_environment_version` (one file) |
|
|
19
19
|
| `worlds data import` | `import_world_data` |
|
|
20
|
+
| `worlds data sql <world> '<sql>' [--limit] [--scenario] [--json]` | `sql_world_data` (`POST /api/public/worlds/{slug}/data/sql`; ONE read-only statement over a schema world's rows, whatever its engine; a write, `ATTACH`, `PRAGMA` or a second statement is refused; at most 1000 rows. A db/schema.sql world is a SQLite file: `sqlite3` in a sandbox) |
|
|
20
21
|
| `worlds session open [-t\|--task-id\|--task-file]` (none: exploratory) / `status` / `call` / `close` / `list` / `pin` | none on the public MCP server — CLI or REST only (`/api/public/world-sessions[/{id}[/calls]]`; the open answers `idleExpiresAt` + `pinned`) |
|
|
21
22
|
| `worlds session seed` | `seed_world_session` |
|
|
22
23
|
| `worlds session export` | `export_world_session` |
|
|
@@ -37,7 +38,7 @@ Reference for `worlds-getting-started`: every CLI step and its MCP twin, then ho
|
|
|
37
38
|
| `bench diff` / `propose` | `env_diff`, `env_propose` (proposals are the legacy PR-style door; edit sessions below are the version-control loop) |
|
|
38
39
|
| `worlds\|bench edit status\|list\|close\|discard\|rollback <slug>` | `list_world_edits({ slug, status?, limit? })`, `close_world_edit({ slug, sessionId?, force?, message? })`, `discard_world_edit`, `rollback_world_edit({ slug, sessionId, force?, message? })` (`GET /api/public/worlds/{slug}/edits`, `POST …/edits/close\|discard\|rollback`). After a world's first version every push, sandbox commit, data import, agent `env_commit` and UI save lands on the credential's open edit session — a private `edit/<id>` branch only that credential reads as `main` (`describe`, `pull`, `log`, `session open`, `sandbox open`); the write's JSON carries `editSessionId` + a hint. `close`, or 60 minutes without an edit, seals the session: the shared `main` moves to its tip (every version stays in `log`; the session is the rollback unit); a `main` that moved meanwhile is rebased when the paths differ, else the session parks as `conflict` (`close --force` takes its content). `rollback` restores source + data snapshot from before a sealed session as a new sealed session (`--force` when later sessions would be undone too). UI: world › History › Edit sessions |
|
|
39
40
|
| `worlds task edit status\|close\|rollback <task>` (task id, spec file with `worlds`, or `task up` manifest) | `get_task_edit({ task })`, `close_task_edit({ task, requireAll?, force?, message? })`, `rollback_task_edit({ task, groupId, force?, message? })` (`POST /api/public/world-task-edits/status\|close\|rollback`). The same edit sessions across every world a task names: `status` shows each world's unsealed edits (open and `parked` in conflict) and what closing would do (`fast-forward`, `rebase`, `conflict`) — your own `task up` opens them at your tip (`private: true`), everyone else still gets shared `main`; `close` seals every world in ONE transaction (a conflict, a missing world, a ref other than `main` or a parked session anywhere seals nothing, and the 409 names every world's problem; worlds with no edit are skipped unless `--require-all`), and the sessions share a `groupId`; `rollback --group` restores every world together to the `main` the group replaced, refused when anything reached a world's `main` after the group (a later session or a write outside sessions) unless `--force` |
|
|
40
|
-
| `worlds\|bench sandbox open\|status\|read\|write\|exec\|check\|commit\|close` | `open_world_sandbox`, `get_world_sandbox`, `read_world_sandbox_file`, `write_world_sandbox_file` (base64), `exec_in_world_sandbox`, `check_world_sandbox`, `commit_world_sandbox`, `close_world_sandbox({ sandboxId, force? })` (`/api/public/benchmark-containers/sandboxes[/{id}[/file\|exec\|check\|commit]]`; `close` with uncommitted work is a 409 `sandbox_uncommitted` naming the paths, nothing closed, unless `force: true` / `--force`; the source tree only — no data snapshot, nothing on the caller's disk; `commit` lands on the recorded base; `commit --rebase` sends `rebase: true` and replays onto a branch head that moved, a 409 naming each conflicting path). `open` reports `cli: {version, digest}` — the platform's own `gateway` CLI and a `sqlite3` are on PATH inside `exec`, so `gateway worlds schema entity add\|verifier add\|task add\|compile\|check .`, `gateway worlds data import\|show\|query .`, `gateway worlds test .`, `gateway worlds serve . --port 8080 & sleep 2; gateway worlds call http://localhost:8080 <tool> …` (one `exec`; a served world lives only as long as that command) and `sqlite3 db/state.sqlite "…"` run on the working copy; remote verbs (push, run, session open) stop in the sandbox by design — `check`/`commit` from your machine. `cli: null` + `warnings[]` means the image cannot host the runtime (python3 < 3.12 or node < 18); plain shell still runs |
|
|
41
|
+
| `worlds\|bench sandbox open\|status\|read\|write\|exec\|check\|commit\|close` | `open_world_sandbox`, `get_world_sandbox`, `read_world_sandbox_file`, `write_world_sandbox_file` (base64), `exec_in_world_sandbox`, `check_world_sandbox`, `commit_world_sandbox`, `close_world_sandbox({ sandboxId, force? })` (`/api/public/benchmark-containers/sandboxes[/{id}[/file\|exec\|check\|commit]]`; `close` with uncommitted work is a 409 `sandbox_uncommitted` naming the paths, nothing closed, unless `force: true` / `--force`; a sandbox whose machine was replaced gets its tree back (latest snapshot, or the base) and the next verb answers 409 `sandbox_recreated` once — look at the tree, redo lost edits, retry; 503 `sandbox_restore_failed` means retry; 409 `sandbox_tree_missing` means the world root was deleted, so close and reopen; the source tree only — no data snapshot, nothing on the caller's disk; `commit` lands on the recorded base; `commit --rebase` sends `rebase: true` and replays onto a branch head that moved, a 409 naming each conflicting path). `open` reports `cli: {version, digest}` — the platform's own `gateway` CLI and a `sqlite3` are on PATH inside `exec`, so `gateway worlds schema entity add\|verifier add\|task add\|compile\|check .`, `gateway worlds data import\|show\|query\|sql .`, `gateway worlds test .`, `gateway worlds serve . --port 8080 & sleep 2; gateway worlds call http://localhost:8080 <tool> …` (one `exec`; a served world lives only as long as that command) and `sqlite3 db/state.sqlite "…"` run on the working copy; remote verbs (push, run, session open) stop in the sandbox by design — `check`/`commit` from your machine. `cli: null` + `warnings[]` means the image cannot host the runtime (python3 < 3.12 or node < 18); plain shell still runs |
|
|
41
42
|
| `worlds\|bench sandbox open --new <slug> --from custom\|<template>` | `open_world_sandbox({ new, from })` (same route, body `{new, from}`; a world that does not exist yet — `baseVersionId`/`containerId`/`baseContentHash` null, `branch: main`, `pendingSlug`; `custom` = the `schema init` scaffold, else a shipped template (`GET /api/public/worlds/templates`; unknown → 400 naming the list); taken slug → 409 `world_exists`, never renamed; `check_world_sandbox` runs the first commit's gate; the first `commit_world_sandbox` creates the world on `main` through the `worlds create --from <dir>` door, later commits land on the new base; the same staged CLI runs on the scaffold) |
|
|
42
43
|
| `worlds skill <name>` / `worlds connector skill` | `get_connector_authoring_skill`, `guide` |
|
|
43
44
|
| `worlds connector capture --remote` / poll + download | `start_connector_capture`, `get_connector_capture` (platform agent only) |
|
|
@@ -53,7 +54,7 @@ before it makes a request.
|
|
|
53
54
|
| `sandbox exec --timeout`, `exec_in_world_sandbox timeoutMs` | default 60 s, at most 600 s | refused, not clamped |
|
|
54
55
|
| Sandbox tree at `check`/`commit`, `bench push` unpacked | 128 MB of source, 2000 files | refused, naming the limit, before a byte is read; move data to `worlds data import`, delete scratch files or list them in `.gatewayignore` |
|
|
55
56
|
| Sandbox tree at `check`/`commit`: credential-shaped files (`.env`, `*.pem`, `id_rsa`, `credentials.json`…; `.env.example` stays), symlinks, sockets/devices | held back, never in the version | listed under `ignored`, each named in `warnings` (path only); use `bench secrets set` for a key the world needs |
|
|
56
|
-
| `worlds data query` / `data show` on a stored version | none beyond the version's own caps | the platform opens the version's tree and snapshot in a prepared directory it owns; no size travels through the request |
|
|
57
|
+
| `worlds data query` / `data sql` / `data show` on a stored version | none beyond the version's own caps | the platform opens the version's tree and snapshot in a prepared directory it owns; no size travels through the request |
|
|
57
58
|
| `bench push` / `worlds create --from` compressed bundle | 64 MB (16 MB from the browser) | refused, naming the limit |
|
|
58
59
|
| A single manifest / metadata file in a bundle | 1 MB | refused |
|
|
59
60
|
| `sandbox write` HTTP body | 1 MB (framework cap; only reachable by a body no schema would accept) | 413 |
|
package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md
CHANGED
|
@@ -28,3 +28,18 @@ The things that bite once and never again, moved out of `SKILL.md` to keep it un
|
|
|
28
28
|
anything is provisioned — the same preflight a run dispatch applies; set the secret, then open.
|
|
29
29
|
- `gateway secret set NAME` is an upsert: the same name again rotates the value and answers
|
|
30
30
|
`updated: true`; `bench secrets set` does the same for a benchmark's environment.
|
|
31
|
+
- Imported data survives every edit that cannot touch a stored row. After `gateway worlds data import
|
|
32
|
+
<slug>` the world's tree carries `db/snapshot.json` (the hosted snapshot) and not the rows; in
|
|
33
|
+
`worlds sandbox open <slug>@main`, adding a tool, a handler, a route, a test or a documentation
|
|
34
|
+
file then `schema compile .` and `schema check .` pass and the commit keeps the snapshot, no
|
|
35
|
+
re-import, and `gateway bench fork <slug>` takes the data with it. Adding an entity or a field
|
|
36
|
+
that is not required (or another `domain_version`) carries the data too: `sandbox check` says
|
|
37
|
+
the commit migrates the snapshot, and `sandbox commit` migrates it and re-pins the tree.
|
|
38
|
+
Removing, retyping or requiring a field, or changing a key, a relationship or a description, is
|
|
39
|
+
refused, naming what changed: keep it as it was, or remove `db/snapshot.json` and import every
|
|
40
|
+
row again. `check` reports
|
|
41
|
+
the handlers `not_run` there, since a session needs the hosted rows; `gateway worlds session open
|
|
42
|
+
<slug>` runs them, so a handler that cannot be imported (a syntax error, a missing module) passes
|
|
43
|
+
`check` and is first refused at that open: open a session on the version after a handler edit.
|
|
44
|
+
Compile from a fresh `sandbox open` rather than copying in artifacts compiled
|
|
45
|
+
elsewhere: the pin proves its data's domain from the `schema/lock.json` it started with.
|
|
@@ -26,6 +26,12 @@ gateway worlds schema init ./x --from-openapi github.json --include '/repos/{own
|
|
|
26
26
|
Inside a world sandbox (`run_gateway_cli`, `sandbox exec`) only a workspace path is accepted:
|
|
27
27
|
write the document into the workspace first (`sandbox write --from spec.yaml`), then import.
|
|
28
28
|
|
|
29
|
+
The import itself runs in this machine's schema runtime whenever it has one; `GATEWAY_RUNTIME=local`
|
|
30
|
+
demands it and sends nothing to the platform. A YAML document is read by PyYAML in the Python that
|
|
31
|
+
runs the runtime: without it the command stops before anything is sent and names the fix
|
|
32
|
+
(`pip install pyyaml` there, point `GATEWAY_PYTHON` at a Python that has it, or convert the
|
|
33
|
+
document to JSON).
|
|
34
|
+
|
|
29
35
|
## What the plan says
|
|
30
36
|
|
|
31
37
|
`--from-openapi` always prints the plan first (JSON, one object):
|
|
@@ -50,28 +56,51 @@ With `--plan-only` the same object carries `"written": false` and no `domain`/`n
|
|
|
50
56
|
|
|
51
57
|
## Conversion rules (decided; the importer documents them in `schema/provenance.json`)
|
|
52
58
|
|
|
53
|
-
- **Entities
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
`
|
|
57
|
-
a
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
59
|
+
- **Entities are the rows the routes carry.** The importer reads each selected operation's
|
|
60
|
+
response and request body through the vendor's envelope to the item schema: an array of
|
|
61
|
+
objects, or an object that declares no key and holds exactly one array (Crossref's
|
|
62
|
+
`{status, message: {items: [Work], total-results}}`, ClinicalTrials.gov's
|
|
63
|
+
`{studies: [Study], nextPageToken}`); a single-row response is the item when some list carries
|
|
64
|
+
it, it declares a key, or it names the field the route's own `{segment}` reads it by, else the
|
|
65
|
+
one object its wrapper holds. Wrappers never become entities. An item no planned route reads or
|
|
66
|
+
writes is no entity either (it stays an inline `$def`). Each entity is a `$defs` entry plus
|
|
67
|
+
`x-gateway.entities.<snake_plural>` with `primary_key` (snake_case, at most 64 characters, the
|
|
68
|
+
original kept in provenance); `allOf` is merged; `oneOf`/`anyOf` become a union the world
|
|
69
|
+
validator accepts. Entity roots close (`additionalProperties: false`); the vendor's field names
|
|
70
|
+
are kept exactly as spelled, hyphens included (`reference-count`), so a rows file shaped like
|
|
71
|
+
the vendor's response imports as it is.
|
|
72
|
+
- **Keys.** A declared key first (`id`, `<name>Id`, `<name>_id`, a `readOnly` field the vendor
|
|
73
|
+
marks `x-unique`/`x-primary-key`), else the field the single-row route reads the row by:
|
|
74
|
+
top-level and spelled the vendor's way (`/works/{doi}` → `DOI`), or nested in the row's
|
|
75
|
+
objects (`/studies/{nctId}` → the JSON Pointer `/protocolSection/identificationModule/nctId`,
|
|
76
|
+
every object on the path made required; never through an array or a nullable object). An item
|
|
77
|
+
only list routes carry falls back to its first required string/integer field, with a warning
|
|
78
|
+
that rows sharing it collapse: mark the key with `x-primary-key` or include the read route.
|
|
63
79
|
- **Routes.** Every path+method in `get|post|put|patch|delete` becomes an `[[operations]]` entry:
|
|
64
80
|
`name` = `operationId` snake_cased, at most 64 characters, deduped with `_2`, `_3` and a
|
|
65
|
-
warning; `entity` = the
|
|
66
|
-
|
|
67
|
-
parameters become `params
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
81
|
+
warning; `entity` = the entity its response (or, for a write, its body or the path's `GET`)
|
|
82
|
+
carries, a list route or `read|create|update|delete` by method; path parameters and declared
|
|
83
|
+
query parameters become `params`, the vendor's names kept, dots included (`query.bibliographic`,
|
|
84
|
+
`filter.overallStatus`). The envelope's path becomes `results` and the route's dotted
|
|
85
|
+
`envelope` (`message.items`), and the rest of the envelope its `wrapper`, so the served world
|
|
86
|
+
answers the vendor's shape (`{status: "ok", message-type: "work-list", message: {items, …}}`).
|
|
87
|
+
On a list route a declared query parameter that names an entity field becomes a `filter`
|
|
88
|
+
(paging names never do). A single read whose path argument names no field of the row, and an
|
|
89
|
+
operation whose response is not an entity (login, upload, HTML), stay **passthrough** routes with
|
|
90
|
+
no entity, the reason in the plan — served, answering `501 {"error": "not_modelled"}` until you
|
|
91
|
+
give them a handler.
|
|
92
|
+
- **Paging.** A cursor parameter (`cursor`, `pageToken`) with a next-cursor field beside the rows
|
|
93
|
+
(`next-cursor`, `nextPageToken`) pages by cursor; an `offset` parameter by offset; the limit's
|
|
94
|
+
`default` becomes `page_size`; the count beside the rows (`total-results`, `totalCount`) is the
|
|
95
|
+
hits key. `[api]` pages the way most list routes do, a route paging otherwise names its own
|
|
96
|
+
`page`, and page-number paging (`page` + `per_page`) is named in a warning (that route answers
|
|
97
|
+
every row on one page).
|
|
98
|
+
- **Tools.** An import declares none: routes are never tools. An agent reaches the world's routes
|
|
99
|
+
over HTTP (the api url and token `session open --surface api` prints); declare a tool in
|
|
100
|
+
`x-gateway.tools`, with a handler, where an agent needs one.
|
|
73
101
|
- **Skipped, with a reason:** `HEAD`/`OPTIONS`/`TRACE`; a path argument that is not an
|
|
74
|
-
identifier; a
|
|
102
|
+
identifier; a path that repeats a placeholder (`/a/{id}/{id}`); a second operation on the same
|
|
103
|
+
method+path shape. **Refused, with a JSON pointer
|
|
75
104
|
into the document, nothing written:** no `paths`; an unknown or external `$ref`; an entity root
|
|
76
105
|
that is (transitively) cyclic — model the recursion as a relationship field (`parent_id`)
|
|
77
106
|
instead; a path parameter nothing declares (`--param <name>` on a hand-written route); a
|
|
@@ -85,6 +114,6 @@ With `--plan-only` the same object carries `"written": false` and no `domain`/`n
|
|
|
85
114
|
|
|
86
115
|
The printed `next` steps are the loop, in order: `schema compile`, `schema check`, `data import
|
|
87
116
|
<rows.json> --entity <first list entity>` (rows shaped like the vendor's response), `worlds serve`
|
|
88
|
-
then `
|
|
89
|
-
tree lives in a sandbox. `connector conform ./x --openapi <the same document>` then checks the
|
|
117
|
+
then `curl -s http://127.0.0.1:<port>/<list path>` (the route over HTTP), and `sandbox commit` when
|
|
118
|
+
the tree lives in a sandbox. `connector conform ./x --openapi <the same document>` then checks the
|
|
90
119
|
served world back against the spec.
|
|
@@ -8,14 +8,13 @@ from __future__ import annotations
|
|
|
8
8
|
|
|
9
9
|
from copy import deepcopy
|
|
10
10
|
import hashlib
|
|
11
|
-
import json
|
|
12
11
|
from pathlib import Path
|
|
13
12
|
import shutil
|
|
14
13
|
import tempfile
|
|
15
14
|
|
|
16
15
|
from .compiler import Contract, check_bundle
|
|
17
16
|
from .scaffold import init_bundle
|
|
18
|
-
from .
|
|
17
|
+
from .database import WorldDatabase
|
|
19
18
|
from .validation import encoded, fail, read_json
|
|
20
19
|
from ._slack_fidelity import fidelity_report, load_capabilities, slack_template_digest
|
|
21
20
|
from ._slack_scenario import write_scenario
|
|
@@ -260,15 +259,12 @@ def map_slack_evidence(
|
|
|
260
259
|
if item.get("file_access") == "check_file_info":
|
|
261
260
|
discriminator = {"file_access": "check_file_info"}
|
|
262
261
|
if not discriminator:
|
|
263
|
-
# No canonical full shape or explicit unavailable discriminator: refuse invention.
|
|
264
262
|
fail(
|
|
265
263
|
"slack_evidence", "Incomplete file projection lacks an access discriminator", "/evidence/files"
|
|
266
264
|
)
|
|
267
265
|
observe("slack_unavailable_message_files", {**base, "reference": discriminator}, source)
|
|
268
266
|
if "files" in value:
|
|
269
|
-
#
|
|
270
|
-
# unlike an API page of messages. Retain file metadata as historical
|
|
271
|
-
# observations but replace the occurrence's full/unavailable links.
|
|
267
|
+
# An explicit attachment collection is one value: keep file metadata as history, replace the links.
|
|
272
268
|
for entity in ("slack_file_shares", "slack_message_files", "slack_unavailable_message_files"):
|
|
273
269
|
retained = {
|
|
274
270
|
token
|
|
@@ -671,7 +667,7 @@ def build_slack_bundle(destination: str | Path, *, evidence: dict | None = None,
|
|
|
671
667
|
diagnostics = {}
|
|
672
668
|
batch = map_slack_evidence(evidence, contract, diagnostics=diagnostics)
|
|
673
669
|
with tempfile.TemporaryDirectory(prefix="gateway-slack-") as temporary:
|
|
674
|
-
with
|
|
670
|
+
with WorldDatabase.create(Path(temporary) / "world.db", contract) as store:
|
|
675
671
|
store.apply_batch(batch)
|
|
676
672
|
if store.get("slack_users", {"workspace_id": workspace["id"], "id": principal["user_id"]}) is None:
|
|
677
673
|
fail("slack_evidence", "The authenticated principal was not captured", "/evidence/principal")
|
|
@@ -724,7 +720,7 @@ def refresh_slack_bundle(destination: str | Path, evidence: dict | None = None,
|
|
|
724
720
|
return {"status": "already_applied", "batch": batch_id, "applied": 0}
|
|
725
721
|
batches = sorted((destination / "data/batches").glob("*.json"))
|
|
726
722
|
with tempfile.TemporaryDirectory(prefix="gateway-slack-refresh-") as temporary:
|
|
727
|
-
with
|
|
723
|
+
with WorldDatabase.create(Path(temporary) / "world.db", contract) as store:
|
|
728
724
|
store.apply_batch(read_json(destination / "data/initial.json"))
|
|
729
725
|
for path in batches:
|
|
730
726
|
store.apply_batch(read_json(path))
|