@withgateway/sdk 0.9.1 → 0.9.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/dist/agents/index.d.mts +12 -4
  2. package/dist/agents/index.d.ts +12 -4
  3. package/dist/agents/index.js +30 -0
  4. package/dist/agents/index.js.map +1 -1
  5. package/dist/agents/index.mjs +30 -0
  6. package/dist/agents/index.mjs.map +1 -1
  7. package/dist/cli.js +2291 -945
  8. package/dist/cli.js.map +1 -1
  9. package/dist/cli.mjs +2290 -944
  10. package/dist/cli.mjs.map +1 -1
  11. package/dist/files/index.js.map +1 -1
  12. package/dist/files/index.mjs.map +1 -1
  13. package/dist/index.js +325 -184
  14. package/dist/index.js.map +1 -1
  15. package/dist/index.mjs +324 -183
  16. package/dist/index.mjs.map +1 -1
  17. package/dist/traces/index.js.map +1 -1
  18. package/dist/traces/index.mjs.map +1 -1
  19. package/dist/tracing/index.js +1 -1
  20. package/dist/tracing/index.js.map +1 -1
  21. package/dist/tracing/index.mjs +1 -1
  22. package/dist/tracing/index.mjs.map +1 -1
  23. package/dist/worlds/index.d.mts +3 -1
  24. package/dist/worlds/index.d.ts +3 -1
  25. package/dist/worlds/index.js +178 -67
  26. package/dist/worlds/index.js.map +1 -1
  27. package/dist/worlds/index.mjs +177 -66
  28. package/dist/worlds/index.mjs.map +1 -1
  29. package/package.json +1 -1
  30. package/runtime/gatewaysdk/environment/bundle_manifest.py +297 -9
  31. package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
  32. package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
  33. package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
  34. package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
  35. package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
  36. package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
  37. package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
  38. package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
  39. package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
  40. package/runtime/gatewaysdk/environment/schema/host.py +21 -2
  41. package/runtime/gatewaysdk/environment/schema/host_control.py +3 -1
  42. package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
  43. package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
  44. package/runtime/gatewaysdk/environment/schema/host_requests.py +21 -0
  45. package/runtime/gatewaysdk/environment/schema/host_session.py +7 -0
  46. package/runtime/gatewaysdk/environment/schema/host_versions.py +4 -0
  47. package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
  48. package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
  49. package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
  50. package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
  51. package/runtime/gatewaysdk/environment/schema/platform.py +57 -3
  52. package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
  53. package/runtime/gatewaysdk/environment/schema/platform_templates.py +105 -17
  54. package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
  55. package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
  56. package/runtime/gatewaysdk/environment/schema/runtime.py +14 -0
  57. package/runtime/gatewaysdk/environment/schema/scaffold.py +21 -4
  58. package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
  59. package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
  60. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  61. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +1 -0
  62. package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
  63. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
  64. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +4 -4
  65. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +2 -2
  66. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +1 -0
  67. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  68. package/runtime/gatewaysdk/environment/schema/validation.py +14 -0
  69. package/runtime/gatewaysdk/environment/schema/worker.py +7 -4
  70. package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
  71. package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
  72. package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
  73. package/runtime/gatewaysdk/environment/schema/workers.py +237 -68
  74. package/runtime/gatewaysdk/environment/schema/world_host.py +56 -62
  75. package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
  76. package/skills/connector-schema-authoring/SKILL.md +1 -0
  77. package/skills/connector-schema-authoring/connector-worlds.md +1 -0
  78. package/skills/connector-schema-authoring/world-schema.md +7 -0
  79. package/skills/factory-orchestrator/SKILL.md +147 -0
  80. package/skills/world-data-ingestion/ROWS.md +5 -1
  81. package/skills/world-data-ingestion/SKILL.md +4 -4
  82. package/skills/worlds-getting-started/SKILL.md +2 -2
  83. package/skills/worlds-getting-started/references/cli-mcp-map.md +1 -0
  84. package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
@@ -0,0 +1,59 @@
1
+ # The shape catalog
2
+
3
+ Reference for `worlds-getting-started`: what `gateway worlds describe <world> --json` carries under
4
+ `catalog`, where each part comes from, and how a world declares what nothing else says.
5
+
6
+ ```bash
7
+ gateway worlds describe x --json # the whole catalog (a platform world: GET /api/public/worlds/x)
8
+ gateway worlds describe x --entity tickets --json # one entity's fields and catalog entries; answers stay whole (?entity=tickets)
9
+ ```
10
+
11
+ MCP: `describe_world({ slug, ref?, entity? })` answers the same document. An entity the world does not
12
+ declare is refused naming the ones it does.
13
+
14
+ ## What it holds
15
+
16
+ | Key | What | Read from |
17
+ | --- | --- | --- |
18
+ | `enumerations` | `{entity, pointer, values, labels?}`: the values a field allows, at any depth (`/events/*/kind`); a union that also admits other values lists none | JSON Schema `enum`, `const`, `oneOf`/`anyOf` of `const` (a `title` is the label) |
19
+ | `columns`, `types` | `{entity, field, schema}` for every JSON field; the definitions they reach, keyed `<file>.<Name>` (`world.Event`, `types.Link`) | the entity's schema as the compiler resolves it, sibling `schema/*.json` files included, annotations left out |
20
+ | `customFields` | `{entity, field, definitions, key, where, pairs?, add}`: a JSON field's keys are rows of `definitions`; `add` is the row that defines one more | `custom_fields` on the entity |
21
+ | `ids` | `{entity, pointer, target: {entity, key, where}}` or `{entity, pointer, values: [{id, label}]}` | `ids` on the entity (top-level foreign keys stay `entities[].relationships`) |
22
+ | `sequences` | `{entity, field, scope, start, source, operations}`: dense numbers, one counter per `scope` value | `sequences` on the entity; `[operations.api] generate = { f = "int" }` |
23
+ | `redaction` | `legend` for `[hash]` `[preserve]` `[round]` `[drop]`, and `writes`: capture stores these forms, an import, seed or upload only with `--redact apply`, every other write (a factory write too) as written | `[redact]` |
24
+ | `answers` | per route: `records`, `id`, `fields`, `count`, `total`, `cursor`, `cursorParam`, `declared` (JSON pointers, `""` the root) | the route's `[api]` envelope, `hits_key`, `cursor_key`, paging and the entity's key; `[operations.answer]` |
25
+
26
+ A write that fills a JSON field writes the shape under `columns`; a key under `customFields` needs its
27
+ definitions row first (`add` names it); an id under `ids` must be one of the target's rows or values.
28
+
29
+ `catalog` is `null` when describe could not read it: the entities still list, and a local describe adds
30
+ `catalogRefused` with the refusal (for a built world, a `[ui] static` without its `index.html`, say).
31
+
32
+ ## Declaring what nothing else says
33
+
34
+ In `schema/world.json`, on the entity (all optional; none changes stored rows):
35
+
36
+ ```json
37
+ "custom_fields": [{"field": "properties", "definitions": "acme_fields", "key": "name", "where": {"object_type": "tickets"}}],
38
+ "ids": [{"pointer": "/links/*/type_id", "values": [{"id": 1, "label": "parent"}, {"id": 2, "label": "duplicate"}]}],
39
+ "sequences": [{"field": "number", "scope": ["queue_id"], "start": 100}]
40
+ ```
41
+
42
+ `pairs: {"id": "id", "value": "value"}` says the field is an array of id/value items instead of an
43
+ object. In `connector.toml`, under an `[[operations]]` entry whose answer the route settings cannot
44
+ describe (a handler's own shape):
45
+
46
+ ```toml
47
+ [operations.answer]
48
+ records = "/results"
49
+ id = "ticket_id"
50
+ fields = ["status"]
51
+ count = "/count"
52
+ total = "/meta/total"
53
+ ```
54
+
55
+ `gateway worlds schema compile` and `check` refuse a declaration naming a field or entity the world
56
+ does not have, a sequence on a non-integer field, an id with both `entity` and `values`, a pointer
57
+ that is not a JSON Pointer, or a scoped sequence (or one with its own `start`) on a field a route
58
+ generates as `int`, which the world numbers across the whole entity from 1 (`catalog` / `spec` codes,
59
+ with the location).