@withgateway/sdk 0.6.0 → 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 (150) hide show
  1. package/dist/agents/index.d.mts +581 -0
  2. package/dist/agents/index.d.ts +581 -0
  3. package/dist/agents/index.js +1473 -0
  4. package/dist/agents/index.js.map +1 -0
  5. package/dist/agents/index.mjs +1424 -0
  6. package/dist/agents/index.mjs.map +1 -0
  7. package/dist/apiError-DHpfbmdx.d.mts +17 -0
  8. package/dist/apiError-DHpfbmdx.d.ts +17 -0
  9. package/dist/cli.js +11611 -6845
  10. package/dist/cli.js.map +1 -1
  11. package/dist/cli.mjs +10090 -5325
  12. package/dist/cli.mjs.map +1 -1
  13. package/dist/files/index.d.mts +3 -1
  14. package/dist/files/index.d.ts +3 -1
  15. package/dist/files/index.js +371 -102
  16. package/dist/files/index.js.map +1 -1
  17. package/dist/files/index.mjs +371 -102
  18. package/dist/files/index.mjs.map +1 -1
  19. package/dist/hooks/index.js +346 -136
  20. package/dist/hooks/index.js.map +1 -1
  21. package/dist/hooks/index.mjs +346 -136
  22. package/dist/hooks/index.mjs.map +1 -1
  23. package/dist/{index-LA-PMRJT.d.ts → index-DIN14Lhg.d.ts} +1 -1
  24. package/dist/{index-Di9nNqOY.d.mts → index-DuB-eQ0Z.d.mts} +1 -1
  25. package/dist/index.d.mts +7 -4
  26. package/dist/index.d.ts +7 -4
  27. package/dist/index.js +3177 -748
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +2987 -590
  30. package/dist/index.mjs.map +1 -1
  31. package/dist/media-CQUC7TkS.d.mts +39 -0
  32. package/dist/media-DQnBloaX.d.ts +39 -0
  33. package/dist/traces/index.d.mts +3 -1
  34. package/dist/traces/index.d.ts +3 -1
  35. package/dist/traces/index.js +371 -102
  36. package/dist/traces/index.js.map +1 -1
  37. package/dist/traces/index.mjs +371 -102
  38. package/dist/traces/index.mjs.map +1 -1
  39. package/dist/tracing/index.d.mts +3 -2
  40. package/dist/tracing/index.d.ts +3 -2
  41. package/dist/tracing/index.js +257 -16
  42. package/dist/tracing/index.js.map +1 -1
  43. package/dist/tracing/index.mjs +257 -16
  44. package/dist/tracing/index.mjs.map +1 -1
  45. package/dist/transport-CpRe7zgd.d.mts +123 -0
  46. package/dist/transport-CpRe7zgd.d.ts +123 -0
  47. package/dist/worlds/index.d.mts +1986 -1746
  48. package/dist/worlds/index.d.ts +1986 -1746
  49. package/dist/worlds/index.js +1470 -290
  50. package/dist/worlds/index.js.map +1 -1
  51. package/dist/worlds/index.mjs +1465 -286
  52. package/dist/worlds/index.mjs.map +1 -1
  53. package/package.json +6 -1
  54. package/runtime/gatewaysdk/environment/bundle_manifest.py +531 -0
  55. package/runtime/gatewaysdk/environment/factory_documents.py +670 -0
  56. package/runtime/gatewaysdk/environment/factory_rules.py +973 -0
  57. package/runtime/gatewaysdk/environment/factory_shapes.py +253 -0
  58. package/runtime/gatewaysdk/environment/factory_spine.py +1155 -0
  59. package/runtime/gatewaysdk/environment/factory_spine_shapes.py +480 -0
  60. package/runtime/gatewaysdk/environment/schema/__main__.py +2 -2
  61. package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +8 -23
  62. package/runtime/gatewaysdk/environment/schema/admission.py +61 -59
  63. package/runtime/gatewaysdk/environment/schema/api.py +3 -4
  64. package/runtime/gatewaysdk/environment/schema/assertions.py +7 -1
  65. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +20 -0
  67. package/runtime/gatewaysdk/environment/schema/cast.py +133 -67
  68. package/runtime/gatewaysdk/environment/schema/compiler.py +16 -17
  69. package/runtime/gatewaysdk/environment/schema/database/base.py +2 -2
  70. package/runtime/gatewaysdk/environment/schema/handler_errors.py +58 -4
  71. package/runtime/gatewaysdk/environment/schema/host.py +94 -12
  72. package/runtime/gatewaysdk/environment/schema/host_browser.py +48 -0
  73. package/runtime/gatewaysdk/environment/schema/host_control.py +35 -2
  74. package/runtime/gatewaysdk/environment/schema/host_handoff.py +4 -1
  75. package/runtime/gatewaysdk/environment/schema/host_loops.py +27 -4
  76. package/runtime/gatewaysdk/environment/schema/host_metrics.py +69 -0
  77. package/runtime/gatewaysdk/environment/schema/host_requests.py +35 -0
  78. package/runtime/gatewaysdk/environment/schema/host_session.py +20 -2
  79. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +6 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +100 -19
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +172 -50
  82. package/runtime/gatewaysdk/environment/schema/ingest.py +12 -3
  83. package/runtime/gatewaysdk/environment/schema/journal.py +7 -2
  84. package/runtime/gatewaysdk/environment/schema/local.py +32 -7
  85. package/runtime/gatewaysdk/environment/schema/mapping.py +1 -1
  86. package/runtime/gatewaysdk/environment/schema/measured_tests.py +187 -0
  87. package/runtime/gatewaysdk/environment/schema/page_checks.py +123 -0
  88. package/runtime/gatewaysdk/environment/schema/platform.py +80 -270
  89. package/runtime/gatewaysdk/environment/schema/platform_query.py +4 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_templates.py +420 -0
  91. package/runtime/gatewaysdk/environment/schema/process_memory.py +76 -0
  92. package/runtime/gatewaysdk/environment/schema/redaction.py +13 -0
  93. package/runtime/gatewaysdk/environment/schema/request_ledger.py +4 -1
  94. package/runtime/gatewaysdk/environment/schema/run_parameters.py +25 -0
  95. package/runtime/gatewaysdk/environment/schema/runtime.py +57 -5
  96. package/runtime/gatewaysdk/environment/schema/scaffold.py +386 -219
  97. package/runtime/gatewaysdk/environment/schema/session_files.py +13 -2
  98. package/runtime/gatewaysdk/environment/schema/shape_catalog.py +493 -0
  99. package/runtime/gatewaysdk/environment/schema/shape_declarations.py +219 -0
  100. package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
  101. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +1 -1
  102. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +2 -2
  103. package/runtime/gatewaysdk/environment/schema/skills/factory-orchestrator/SKILL.md +147 -0
  104. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +5 -1
  105. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +8 -6
  106. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +9 -9
  107. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  108. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +6 -6
  109. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +17 -2
  110. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  111. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  112. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/ui-map.md +3 -2
  113. package/runtime/gatewaysdk/environment/schema/slack.py +55 -10
  114. package/runtime/gatewaysdk/environment/schema/snapshot.py +28 -2
  115. package/runtime/gatewaysdk/environment/schema/tasks.py +25 -2
  116. package/runtime/gatewaysdk/environment/schema/template_record.py +131 -0
  117. package/runtime/gatewaysdk/environment/schema/tools_world.py +7 -5
  118. package/runtime/gatewaysdk/environment/schema/ui.py +54 -33
  119. package/runtime/gatewaysdk/environment/schema/ui_interactions.py +419 -0
  120. package/runtime/gatewaysdk/environment/schema/ui_recorder.js +895 -0
  121. package/runtime/gatewaysdk/environment/schema/ui_replay.py +366 -0
  122. package/runtime/gatewaysdk/environment/schema/ui_replay_record.LICENSE +25 -0
  123. package/runtime/gatewaysdk/environment/schema/ui_replay_record.js +109 -0
  124. package/runtime/gatewaysdk/environment/schema/validation.py +24 -1
  125. package/runtime/gatewaysdk/environment/schema/worker.py +12 -5
  126. package/runtime/gatewaysdk/environment/schema/worker_key.py +38 -0
  127. package/runtime/gatewaysdk/environment/schema/worker_peaks.py +38 -0
  128. package/runtime/gatewaysdk/environment/schema/worker_watch.py +50 -0
  129. package/runtime/gatewaysdk/environment/schema/workers.py +245 -69
  130. package/runtime/gatewaysdk/environment/schema/world_host.py +96 -73
  131. package/runtime/gatewaysdk/environment/schema/world_tests.py +3 -1
  132. package/runtime/gatewaysdk/environment/secret_values.py +1 -1
  133. package/runtime/gatewaysdk/environment/world.py +34 -43
  134. package/runtime/gatewaysdk/environment/world_session_contract.py +7 -34
  135. package/skills/benchmarks-getting-started/SKILL.md +1 -1
  136. package/skills/connector-schema-authoring/SKILL.md +2 -2
  137. package/skills/connector-schema-authoring/connector-worlds.md +3 -2
  138. package/skills/connector-schema-authoring/world-schema.md +36 -23
  139. package/skills/factory-orchestrator/SKILL.md +147 -0
  140. package/skills/world-data-ingestion/ROWS.md +5 -1
  141. package/skills/world-data-ingestion/SKILL.md +8 -6
  142. package/skills/worlds-getting-started/SKILL.md +9 -9
  143. package/skills/worlds-getting-started/references/cli-mcp-map.md +33 -2
  144. package/skills/worlds-getting-started/references/gotchas.md +6 -6
  145. package/skills/worlds-getting-started/references/journal-checks.md +17 -2
  146. package/skills/worlds-getting-started/references/new-world-sandbox.md +1 -1
  147. package/skills/worlds-getting-started/references/shape-catalog.md +59 -0
  148. package/skills/worlds-getting-started/references/ui-map.md +3 -2
  149. package/dist/media-BIApiPzS.d.mts +0 -102
  150. package/dist/media-BIApiPzS.d.ts +0 -102
@@ -0,0 +1,219 @@
1
+ """An entity's ``custom_fields``, ``ids`` and ``sequences`` (``schema/world.json``) and a route's
2
+ ``[operations.answer]`` (``connector.toml``), checked at compile and check. None of them is part
3
+ of the domain hash."""
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass, field
8
+ from typing import Any
9
+
10
+ from .cast import schema_types
11
+ from .validation import fail, json_pointer_parts, members, pointer
12
+
13
+ DECLARATION_MEMBERS = frozenset({"custom_fields", "ids", "sequences"})
14
+ ANSWER_POINTERS = ("records", "count", "total", "cursor")
15
+ ANSWER_KEYS = frozenset({*ANSWER_POINTERS, "id", "fields", "cursor_param"})
16
+ SCALAR = (str, int, bool)
17
+ CODE = "catalog"
18
+
19
+
20
+ def json_pointer(parts: list[str] | tuple[str, ...]) -> str:
21
+ return "".join(f"/{pointer(part)}" for part in parts)
22
+
23
+
24
+ def pointer_parts(value: Any, location: str, code: str = CODE) -> list[str]:
25
+ if not isinstance(value, str) or (value and not value.startswith("/")):
26
+ fail(code, "A pointer is a JSON Pointer: empty for the root, else starting with /", location)
27
+ return json_pointer_parts(value, location, code=code) if value else []
28
+
29
+
30
+ def dotted_pointer(path: str) -> str:
31
+ return json_pointer([part for part in path.split(".") if part])
32
+
33
+
34
+ def _list_of_tables(value: Any, location: str) -> list[dict]:
35
+ if not isinstance(value, list) or not all(isinstance(item, dict) for item in value):
36
+ fail(CODE, "Expected a list of objects", location)
37
+ return value
38
+
39
+
40
+ def _name(value: Any, location: str, code: str = CODE) -> str:
41
+ if not isinstance(value, str) or not value:
42
+ fail(code, "Expected a non-empty name", location)
43
+ return value
44
+
45
+
46
+ class EntityDeclarations:
47
+ def __init__(self, declared: dict[str, dict], payloads: dict[str, dict], prefix: str):
48
+ self.declared = declared
49
+ self.payloads = payloads
50
+ self.prefix = prefix
51
+
52
+ def check(self) -> None:
53
+ for entity, spec in sorted(self.declared.items()):
54
+ for member in sorted(DECLARATION_MEMBERS & set(spec)):
55
+ location = f"{self.prefix}/{entity}/{member}"
56
+ entries = _list_of_tables(spec[member], location)
57
+ CHECKS[member](self, entity, entries, location)
58
+
59
+ def _field(self, entity: str, name: Any, location: str) -> dict:
60
+ from .compiler import field_schema
61
+
62
+ if not isinstance(name, str) or name not in (self.payloads[entity].get("properties") or {}):
63
+ fail(CODE, f"{entity} has no field {name!r}", location)
64
+ return field_schema(self.payloads[entity], name, location, code=CODE)
65
+
66
+ def _entity(self, name: Any, location: str) -> str:
67
+ if name not in self.payloads:
68
+ fail(CODE, f"{name!r} is not an entity of this world", location)
69
+ return name
70
+
71
+ def _where(self, entity: str, where: Any, location: str) -> None:
72
+ if not isinstance(where, dict) or not all(isinstance(v, SCALAR) for v in where.values()):
73
+ fail(CODE, "where maps fields of the target entity to plain values", location)
74
+ for name in where:
75
+ self._field(entity, name, f"{location}/{pointer(name)}")
76
+
77
+ def _unique(self, values: list[Any], what: str, location: str) -> None:
78
+ if len(set(map(repr, values))) != len(values):
79
+ fail(CODE, f"{what} is declared twice", location)
80
+
81
+ def custom_fields(self, entity: str, entries: list[dict], location: str) -> None:
82
+ self._unique([entry.get("field") for entry in entries], "A custom-field set on one field", location)
83
+ for index, entry in enumerate(entries):
84
+ here = f"{location}/{index}"
85
+ members(entry, {"field", "definitions", "key", "where", "pairs"}, {"field", "definitions", "key"}, here)
86
+ wanted = "array" if "pairs" in entry else "object"
87
+ if wanted not in schema_types(self._field(entity, entry["field"], f"{here}/field")):
88
+ fail(CODE, f"custom_fields.field must be an {wanted} field (pairs = an array of id/value items)", here)
89
+ definitions = self._entity(entry["definitions"], f"{here}/definitions")
90
+ self._field(definitions, entry["key"], f"{here}/key")
91
+ self._where(definitions, entry.get("where", {}), f"{here}/where")
92
+ self._pairs(entry.get("pairs"), f"{here}/pairs")
93
+
94
+ def _pairs(self, pairs: Any, location: str) -> None:
95
+ if pairs is None:
96
+ return
97
+ members(pairs, {"id", "value"}, {"id", "value"}, location)
98
+ _name(pairs["id"], f"{location}/id")
99
+ _name(pairs["value"], f"{location}/value")
100
+
101
+ def ids(self, entity: str, entries: list[dict], location: str) -> None:
102
+ self._unique([entry.get("pointer") for entry in entries], "An id pointer", location)
103
+ for index, entry in enumerate(entries):
104
+ here = f"{location}/{index}"
105
+ members(entry, {"pointer", "entity", "key", "where", "values"}, {"pointer"}, here)
106
+ parts = pointer_parts(entry["pointer"], f"{here}/pointer")
107
+ if not parts:
108
+ fail(CODE, "An id pointer names a field of the row", f"{here}/pointer")
109
+ self._field(entity, parts[0], f"{here}/pointer")
110
+ if ("entity" in entry) == ("values" in entry):
111
+ fail(CODE, "An id names either an entity (with key) or its fixed values, not both", here)
112
+ if "values" in entry:
113
+ self._values(entry["values"], f"{here}/values")
114
+ continue
115
+ if "key" not in entry:
116
+ fail(CODE, "An id that names an entity names its key", here)
117
+ target = self._entity(entry["entity"], f"{here}/entity")
118
+ self._field(target, entry["key"], f"{here}/key")
119
+ self._where(target, entry.get("where", {}), f"{here}/where")
120
+
121
+ def _values(self, values: Any, location: str) -> None:
122
+ listed = _list_of_tables(values, location)
123
+ if not listed:
124
+ fail(CODE, "values lists at least one id", location)
125
+ for index, value in enumerate(listed):
126
+ members(value, {"id", "label"}, {"id", "label"}, f"{location}/{index}")
127
+ if isinstance(value["id"], bool) or not isinstance(value["id"], (str, int)):
128
+ fail(CODE, "An id is a string or an integer", f"{location}/{index}/id")
129
+ _name(value["label"], f"{location}/{index}/label")
130
+ self._unique([value["id"] for value in listed], "An id value", location)
131
+
132
+ def sequences(self, entity: str, entries: list[dict], location: str) -> None:
133
+ self._unique([entry.get("field") for entry in entries], "A sequence on one field", location)
134
+ for index, entry in enumerate(entries):
135
+ here = f"{location}/{index}"
136
+ members(entry, {"field", "scope", "start"}, {"field"}, here)
137
+ if "integer" not in schema_types(self._field(entity, entry["field"], f"{here}/field")):
138
+ fail(CODE, "A sequence numbers an integer field", f"{here}/field")
139
+ scope = entry.get("scope", [])
140
+ if not isinstance(scope, list) or entry["field"] in scope:
141
+ fail(CODE, "scope lists the other fields whose equal values share one counter", f"{here}/scope")
142
+ self._unique(scope, "A scope field", f"{here}/scope")
143
+ for position, name in enumerate(scope):
144
+ self._field(entity, name, f"{here}/scope/{position}")
145
+ start = entry.get("start", 1)
146
+ if isinstance(start, bool) or not isinstance(start, int) or start < 0:
147
+ fail(CODE, "start is a whole number", f"{here}/start")
148
+
149
+
150
+ CHECKS = {
151
+ "custom_fields": EntityDeclarations.custom_fields,
152
+ "ids": EntityDeclarations.ids,
153
+ "sequences": EntityDeclarations.sequences,
154
+ }
155
+
156
+
157
+ @dataclass(frozen=True)
158
+ class AnswerDeclaration:
159
+ values: dict[str, Any] = field(default_factory=dict)
160
+
161
+ @classmethod
162
+ def parse(cls, table: Any, location: str) -> "AnswerDeclaration":
163
+ if not isinstance(table, dict):
164
+ fail("spec", "answer must be a table", location)
165
+ unknown = sorted(set(table) - ANSWER_KEYS)
166
+ if unknown:
167
+ fail("spec", f"answer has no member {unknown[0]}; it takes {', '.join(sorted(ANSWER_KEYS))}", location)
168
+ for key in ANSWER_POINTERS:
169
+ if key in table:
170
+ pointer_parts(table[key], f"{location}/{key}", "spec")
171
+ for key in ("id", "cursor_param"):
172
+ if key in table:
173
+ _name(table[key], f"{location}/{key}", "spec")
174
+ fields = table.get("fields", [])
175
+ if not isinstance(fields, list) or not all(isinstance(name, str) and name for name in fields):
176
+ fail("spec", "answer.fields lists record field names", f"{location}/fields")
177
+ if len(set(fields)) != len(fields):
178
+ fail("spec", "answer.fields repeats a name", f"{location}/fields")
179
+ return cls(dict(table))
180
+
181
+ @property
182
+ def declared(self) -> list[str]:
183
+ return sorted(self.values)
184
+
185
+
186
+ def answer_declarations(raw: dict) -> dict[str, AnswerDeclaration]:
187
+ listed = raw.get("operations") if isinstance(raw.get("operations"), list) else []
188
+ declared: dict[str, AnswerDeclaration] = {}
189
+ for index, entry in enumerate(listed):
190
+ if isinstance(entry, dict) and "answer" in entry:
191
+ declared[str(entry.get("name"))] = AnswerDeclaration.parse(entry["answer"], f"/operations/{index}/answer")
192
+ return declared
193
+
194
+
195
+ def check_generated_sequences(raw: dict, world: Any) -> None:
196
+ """The runtime numbers an ``int`` it generates entity-wide from 1, so a declared sequence on that
197
+ field may not claim another scope or start."""
198
+ gateway = world.get("x-gateway") if isinstance(world, dict) else None
199
+ entities = gateway.get("entities") if isinstance(gateway, dict) else None
200
+ declared = {
201
+ (name, entry.get("field")): entry
202
+ for name, spec in (entities if isinstance(entities, dict) else {}).items()
203
+ for entry in (spec.get("sequences") if isinstance(spec, dict) else None) or []
204
+ if isinstance(entry, dict)
205
+ }
206
+ for index, operation in enumerate(raw.get("operations") if isinstance(raw.get("operations"), list) else []):
207
+ api = operation.get("api") if isinstance(operation, dict) else None
208
+ generate = api.get("generate") if isinstance(api, dict) else None
209
+ for field_name, generator in (generate if isinstance(generate, dict) else {}).items():
210
+ entry = declared.get((operation.get("entity"), field_name))
211
+ if generator != "int" or entry is None or (not entry.get("scope") and entry.get("start", 1) == 1):
212
+ continue
213
+ fail(
214
+ "spec",
215
+ f"operation {operation.get('name')} generates {field_name} as int, which the world numbers "
216
+ f"across the whole entity from 1, while sequences declares another scope or start; drop the "
217
+ "generate and number it in a handler, or drop the declared scope and start",
218
+ f"/operations/{index}/api/generate/{pointer(field_name)}",
219
+ )
@@ -32,6 +32,7 @@ NEXT_STEPS = {
32
32
  "world-data-ingestion": "gateway worlds data import <world> rows.json",
33
33
  "worlds-getting-started": "gateway worlds schema init ./my-world --connector custom",
34
34
  "benchmarks-getting-started": "gateway benchmarks init ./my-benchmark --connector custom",
35
+ "factory-orchestrator": "gateway factory agents <bundle>",
35
36
  "hooks-getting-started": "gateway hooks check gateway-hooks.toml",
36
37
  }
37
38
 
@@ -326,7 +326,7 @@ fields and the reward signature against the verifiers version you install.
326
326
 
327
327
  ```bash
328
328
  gateway benchmarks init ./crm-bench # custom contract: example entity, three tools, one verifier, one task
329
- gateway benchmarks init ./slack-bench --connector slack # a shipped template: the vendor's entities, routes and tools
329
+ gateway benchmarks init ./slack-bench --connector slack # an official template (needs a login): the vendor's entities, routes and tools
330
330
  gateway benchmarks init ./x --task onboard --prompt "Create an account for Acme." --model openai/gpt-5-mini -k 3
331
331
  ```
332
332
 
@@ -106,6 +106,7 @@ deliverable can finish with synthetic fixtures and explicitly skipped live valid
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
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
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
+ - [ ] Declare the shapes a writer would otherwise guess (`worlds describe --json` reads them into its shape catalog): the keys of an open JSON field defined by another entity's rows (`custom_fields`, e.g. a properties map keyed by a property-definitions entity), ids inside a row that come from another entity or a fixed vendor table (`ids`), dense vendor-minted numbers (`sequences`), and, on a handler route, where its answer keeps the records, the id, the count and the total (`[operations.answer]`). Enums and nested shapes need nothing beyond the JSON Schema itself. See `world-schema.md` and `connector-worlds.md`.
109
110
  - [ ] `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
111
  - [ ] 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
112
 
@@ -174,7 +175,7 @@ No `upsert`: `get`, then `insert` or `update`. Read-only SQL: `gateway_env.db.on
174
175
 
175
176
  ### 7. Ship the template; register platform integration only when in scope
176
177
 
177
- - [ ] SDK-shipped: commit authored files under `gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/<slug>/`; `list_templates()` and `test_schema_scaffold.py` cover the slug and preserve its authored dependencies/provenance during initialization. Schema-only templates declare an empty tools map and have no operation handlers.
178
+ - [ ] Official: an official editor pushes the template tree into the official organization (`gateway worlds create <slug> --from <dir>` with `GATEWAY_TOKEN` + `GATEWAY_PROJECT_ID`, then publish it), and every reader serves it from that world's head (`gateway worlds schema templates`, `schema init --connector <slug>`, `worlds create --from <slug>`). Authored trees still sit under `gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/<slug>/` until O4 moves them out; `tests/test_official_template_world.py` pins that a world built from the files is byte-identical to the old directory init. Schema-only templates declare an empty tools map and have no operation handlers.
178
179
  - [ ] Platform integration, if separately in scope: map an existing source kind in `schemaWorldTemplates.ts` so "Build from connector" offers it. Do not register a native provider or invent a source kind for an SDK-only schema milestone.
179
180
  - [ ] Treat `connectionMode` as the primary authentication path, not the only setup path. A managed connector may retain `remoteMcpPreset` as a fallback; render that action from the preset's presence. For native source connectors such as Slack, the source-backed Link action is the managed authentication path because native-provider dispatch intentionally precedes Merge.
180
181
  - [ ] User-added templates can use `--connector custom` and SDK publication. Generic schema upload and shared/project registry infrastructure remain unimplemented.
@@ -265,7 +266,6 @@ Python SDK as package data so an agent in any repository can install it.
265
266
  Revalidated 2026-09-07 while integrating `ba89fe16` with `015d6b25`:
266
267
  `schema/scaffold.py`, `schema/platform.py`, `tests/environment/test_schema_scaffold.py`,
267
268
  `worldSchemaPublication.ts`, `worldSchemaRuntime.ts`, `environmentBundleTester.ts`,
268
- `environmentBuildWorkbench.ts`, `environmentSchemaSandbox.ts`,
269
269
  `NativeSlackService.ts`, and `deploy/benchmark-runner/engines/{session_server,schema_session}.py`.
270
270
  Full source paths and runtime boundaries are listed in [world-schema.md](../../../documentation/features/world-schema.md).
271
271
  These source checks do not imply live-provider validation or executed fidelity scores.
@@ -0,0 +1,147 @@
1
+ ---
2
+ name: factory-orchestrator
3
+ description: Co-author a world bundle's Data Factory with a person — its ontology, entity graph, rules, tests and spine — and, when your switches allow it, edit the bundle's worlds and their relationships and write their rows. Use when you are a bundle's factory orchestrator, or an outside agent joined to a factory's roster.
4
+ ---
5
+
6
+ # Data Factory: the orchestrator
7
+
8
+ ## What you work on
9
+
10
+ A Data Factory belongs to one world bundle (a bundle of one world is allowed). It holds five documents. Each is a set of nodes, and each node has a stable `id`, a `name` and one `sentence`.
11
+
12
+ - **Ontology:** the things and events of this domain and how they relate. The kinds are whatever the person needs; there is no fixed vocabulary. A relation is `{type, to}`, with `type` a free word.
13
+ - **Entity graph:** notes on the bundle's entities: which world creates a record, cardinality, how fields merge. The links between worlds (identities and references) live in the bundle's `gateway-bundle.toml`, not here.
14
+ - **Rules:** what must hold. A rule is a sentence (guidance), code (`guard`, `derive`), or both.
15
+ - **Tests:** checks attached to nodes, marked `generate`, `verify` or both.
16
+ - **Spine:** the facts every writer must agree on: rosters, calendars, storylines, partitions and their quotas, reserved keys, sequence starts. Tables, facts and checks, checked at every commit.
17
+
18
+ Any node can point at another node, a spine row (`{kind: "row", node, key}`), a world, a schema field, a record or a drive file through `refs`.
19
+
20
+ The factory writes data. It never runs or simulates worlds, and there is no clock to advance: records carry their own dates.
21
+
22
+ ## Your tools
23
+
24
+ Your switches decide which write tools you have. Call only what you were given. Reads name the bundle as `slug`, writes as `bundle`. Every result carries `head`, the head revision's id, and may carry `hook_context`: lines the factory's rules add for you (read them before your next step).
25
+
26
+ | Tool | Does |
27
+ |---|---|
28
+ | `get_factory` | The head revision and the documents (pass `doc` for one). |
29
+ | `list_factory_revisions`, `get_factory_revision`, `diff_factory_revisions` | History, the documents as they were, and the nodes added, changed and removed between two revisions. |
30
+ | `update_ontology`, `update_entity_graph`, `update_rules`, `update_tests`, `update_spine` | Commit nodes (`upsert`, `remove`) to one document, on a `base` revision. `update_spine` also takes row edits (`rows`). |
31
+ | `get_spine`, `get_spine_rows` | The spine: tables (without their rows, with `rowCount`), facts with their `resolved` values, and warnings; then one table's rows a page at a time (`offset`, `limit`, `q` to search). |
32
+ | `generate_spine` | Run tables' generators and commit their rows (`dryRun: true` shows a sample and writes nothing). Present with `update_spine` when "Writes spine" is on. |
33
+ | `accept_factory_unit` | Check a unit's quotas against the rows the run holds: `{partition, key}` → each quota's expected and actual count. |
34
+ | `get_factory_data` | What this run wrote per member: row counts per entity in its draft and in Day 0. `origin: true` adds where each entity's rows came from (`real:<source>`, `generated`, `propagated`, `authored`, `seed`); `pending: true` lists the run's pending references. |
35
+ | `describe_member` | Each member's contract as a write must fit it: every entity's fields with type, required, allowed values (`enum`) and `format`, its keys and relationships, and the identities and references that touch the member. Pass `world` (and `entity`) to narrow it. |
36
+ | `write_records`, `query_factory_data` | Write rows into the active run's drafts, for one member or several at once (`unit` names the partition unit the write is for); read one entity's rows: the run's draft, else Day 0, else main (`source` says which). Present only when "Writes data" is on. |
37
+ | `release_factory_data` | Release the drafts as each member's Day 0 state, and end the run. Present only when "Releases Day 0" is on. |
38
+ | World sandbox tools | `open_world_sandbox` … `commit_world_sandbox`, here, over MCP and with the CLI: edit a member world or the bundle's relationships, confined to the bundle and its members and signed as you. You cannot add or remove members; a commit that would is refused, and a person makes that change. Present only when "Edits worlds" is on. |
39
+ | `request_factory_upload`, `confirm_factory_upload` | Upload an export's rows into the active run, tagged `real:<source>`. Over MCP and the CLI, when "Uploads real data" is on; an upload that starts a run also needs "Starts runs". |
40
+ | `set_factory_enrichment` | Open or close one member entity's real fields to agents. Over MCP and the CLI, when "Opens real rows to agents" is on. |
41
+ | `start_factory_run` | Start a run when none is active. It is recorded on the factory's orchestrator and has no chat, and it is refused (`factory_run_needs_orchestrator`) until a person has set the factory up. Over MCP and the CLI, when "Starts runs" is on. |
42
+
43
+ These last three switches start off for every agent, and only a person turns them on. Use them only for the upload, the entity or the run the person asked for.
44
+
45
+ ## Writing rules and tests
46
+
47
+ Rule code is Python, run by the factory's rule runner: no network, no files, no clock, the same answer every time.
48
+
49
+ ```python
50
+ def guard(view, change):
51
+ payment = view.one("acme-billing", "payments", id=change["row"]["payment_id"])
52
+ if payment is None:
53
+ return "unknown payment " + str(change["row"]["payment_id"])
54
+ return True if change["row"]["amount"] <= payment["amount"] else "a refund never exceeds its payment"
55
+
56
+ def derive(view, change):
57
+ return [{"world": "acme-billing", "entity": "ledger", "row": {"payment_id": change["row"]["payment_id"]}}]
58
+ ```
59
+
60
+ - **`view`:** `rows(world, entity, **where)`, `one(world, entity, **where)`, `spine(node_id)` (a spine fact as `{value}`, a table as `{columns, key, rows}`, resolved; any other id reads that ontology node's `properties`), `statements(about=None)`, and `rng(name)`, the only randomness.
61
+ - **`change`:** `{world, entity, op, row, before, at, by: {principal, unit}}`. A hook guard on a tool call sees `{tool, input, by}`.
62
+ - **A guard returns `True` or a reason string.** Anything else is an error.
63
+ - **Imports:** only `math`, `statistics`, `decimal`, `datetime`, `re`, `json`, `collections`, `itertools` and `zoneinfo`. `now()` and `today()` are refused; take dates from the change or the spine. `hash`, `id`, `samples`, setting or deleting an attribute, and a bare `except` are refused too: catch the exception you expect.
64
+ - **Conventions:** guard the transition (`before` → `row`), not every write. Take roles from the roster, refuse an unknown reference by name, and join on reserved keys, never on text.
65
+ - **`rule_unit` test spec:** `{"rule": "<rule id>", "cases": [{"name", "rows": {"<world>.<entity>": [...]}, "spine"?, "change", "expect": "ok"|"deny", "reason"?, "derived"?: [...]}]}`. Write a passing case, the failure the rule exists for, and an edge (month end, Day 0, a time-zone boundary).
66
+ - **`chronicle` test spec:** `{"each": {"about": ["<node>"]}, "require": [{"cause": {"about": ["<node>"]}} | {"at": true} | {"causeBefore": true} | {"link": {"world", "entity"}}], "cases"?: [...]}`.
67
+ - **A commit that changes a rule's code or its tests runs those tests first.** Its answer carries `ruleTests`: warnings, and mutants no test caught ("`<=` → `<` on line 3 and every case still passes"). Add the case that would catch it.
68
+
69
+ ## Writing the spine
70
+
71
+ Put every number and name two writers must agree on in the spine, once, and point at it.
72
+
73
+ - **Tables:** `{kind: "table", columns: [{name, type, ref?}], key: "<column>", rows: [...]}`. Types: `string`, `integer`, `number`, `boolean`, `date`, `instant`, `json`, `ref`. Key cells are written literally and are unique. Change rows with `rows: [{table, upsert, remove}]` in `update_spine`; an `upsert` of a table node sends all its rows.
74
+ - **Facts:** `{kind: "fact", value}`. **Checks only:** `{kind: "check", checks: [...]}`. Any spine node may carry `checks` and a `group` ("roster", "calendar", "storyline") for the Spine tab.
75
+ - **Derived values, not copies.** A value (a fact's value, a cell, a check's field) is a literal or: `{from: {kind: "node", id}, path: "/volume"}`, `{from: {kind: "row", node, key}, path: "/publishedOn"}`, `{from: {kind: "node", id: "<table>"}, column: "tickets"}` (a list), `{formula: "a * b", with: {a: …, b: …}}`, or `{literal: …}` for an object that only looks like one. Formulas are Python expressions, with `largest_remainder(total, weights)`, `lookup(rows, column, **where)`, `count(rows, **where)`, `total(rows, column, **where)` and `working_day(date, holidays, weekend)`. When you must keep a written number, write `{copy: 3200, from: …}`: a copy that drifts from its source is a warning.
76
+ - **Checks:** `flow` (`start + created − closed = end`), `sum` (`parts` add up to `total`), `quota` (`quotas` sum to `total`, split from `weights` by largest remainder), `fact` (a history fact's `claims` equal its recomputed `value`, within `tolerance`), `steps` (each storyline row's `names` cell is a row ref that resolves, and business steps fall on working days). Arithmetic failures refuse the commit (`factory_spine_checks_failed`); off-day steps and drifted copies come back as `spineChecks.warnings`.
77
+ - **Generators:** a table's `generate` is Python `def generate(ctx)` returning its rows. `ctx.rng("<concept>")` is the only randomness, one stream per concept, so changing one roster never reshuffles another; `ctx.spine(id)` and `ctx.rows(id)` read the spine. Run it with `generate_spine`; bulk rows come from code, not from you row by row.
78
+ - **Partitions:** a table whose rows are units: `partition: {owner: "def owner(view, change): …", entities: [{world, entity}], quotas: [{column, world, entity, tolerance?}]}`. `owner` returns the unit key that owns `change["row"]`.
79
+ - **Reserved keys:** `reserves: [{column, world, entity, field}]` reserves each row's value of `column` in that member field (both ends of a cross-world join, such as an escalation's ticket and issue).
80
+
81
+ ## Writing data
82
+
83
+ - **Rows land in this run's draft of a member world**, not in the world itself. No session or run sees them until a person releases them as Day 0. A run starts from the seed chosen when it was started: by default the Day 0 the last run released (else main), so it adds to it; or main, nothing at all, a named state or a snapshot.
84
+ - **Read the contract first.** `describe_member` names each field's type, whether it is required, the values it allows and its format, so a write fits the first time.
85
+ - **Write to the member version the bundle pins.** Every read and check of a member (`describe_member`, every write, the release) uses the version the bundle pinned, even after the member's main has moved on. A world sandbox opens main, which may differ; trust `describe_member`. When the person wants a newer contract, they move the pin by committing the bundle.
86
+ - **One write is a slice:** `rows: {"<world>": {"<entity>": [rows]}}`, for any members of the bundle. It lands in every member or in none.
87
+ - **Lay structure first, then write the text with `mode: "patch"`.** A patch row names a stored row by its primary key and sends only the fields to change; objects merge, anything else replaces, nothing is filled, and the merged row is checked against the contract and the references. A patch for a row no member holds is refused as `row_not_found`. A patched row still carries its identity, so a member that lacks the person gets a counterpart.
88
+ - **A reserved key needs no order.** A reference whose value the spine reserves for its target passes, and the release refuses while a reserved value has no row (`reservation_unfulfilled`).
89
+ - **Write a unit's rows as that unit.** Send `unit: {partition, key}`: a row of an entity a partition owns is refused (`partition_other_unit`) unless the partition's owner function names your unit, both for the row you send and for the stored row it would replace. When the unit is done, `accept_factory_unit` compares its quotas with what the run holds.
90
+ - **Write referenced records first, or in the same slice.** The bundle's `[[references]]` (in `gateway-bundle.toml`) say which field names a record in another member; `write_records` refuses a row whose reference neither the slice nor any member holds. When the record comes later in the run, send `deferReferences: true`: the row lands and its reference stays pending (`pending.deferred` in the answer) until a write lands the record. Every write re-checks the pending list, and the release refuses while any remain.
91
+ - **Rows from real data keep their fields.** An upload tags its rows `real:<source>`. Changing a field such a row holds is refused (`real_field_protected`), and so is replacing an entity that holds such rows (`real_rows_protected`), unless that entity is open to enrichment. You may fill a field the real row lacks (a patch that sends only that field), and write new rows that name real ones.
92
+ - **People are written once.** For each `[[identities]]`, a row you write carries its identity value to every other member the identity spans: the platform writes the counterpart there, unless that member holds the value already or your slice writes it. Values match by the identity's key, through each span's transforms (an email under `lower` matches in any case). The answer counts counterparts in `propagated`, and `unpropagated` names a span no value reaches through its transforms.
93
+ - **Names travel with the person.** A span's `carry` (in `gateway-bundle.toml`) names fields, such as a name or a title, that are the same in every member. A carried field you send reaches every counterpart: a new one gets it, one a member holds is patched, and a counterpart you write without it gets it. Only fields you send travel, never a filled or stored value. Two values for one person's carried field in one write is `identity_conflict`. A carry into a member's primary key refuses the write; ask a person to carry it into another field. A counterpart's other fields are filled from the contract; write them yourself when they matter.
94
+ - **`complete: true` fills what a row leaves out** from the member's contract: defaults, the first enum value, null where allowed, a value hashed from the row for every key and unique field, and a parent in the same world. Send every field you care about; a filled date is one fixed instant. It never goes with a patch.
95
+ - **Give every row its own dates.** Nothing runs to advance a clock.
96
+ - **Write a few hundred rows at a time**, at most 5,000 a call. A row replaces the row with the same key; `mode: "replace"` empties each entity the write sends rows for first; an entity named with no rows is refused.
97
+ - **Check what landed** with `get_factory_data` (row counts per entity) and `query_factory_data`.
98
+ - **Release only when the person says so.** `release_factory_data` makes each member's draft its Day 0 state and ends the run; a member the run never wrote is released at its main data. It refuses while any `[[references]]` row names a record no member holds, and lists each one.
99
+
100
+ ## From a terminal
101
+
102
+ An agent with a factory-agent key (`fk_…`) stored by `gateway auth login` can do all of this with the `gateway` CLI. Each verb is the tool above that does the same work, under the same switch and the factory's rules:
103
+
104
+ - **Documents:** `gateway factory show|revisions|diff <bundle>`, and `gateway factory edit <bundle> --file edits.json --base <rev> --doc <ontology|graph|rules|tests|spine>`. Your edit must name its document with `--doc`.
105
+ - **Spine:** `gateway factory spine show <bundle>`, `spine rows <bundle> <table>`, `spine generate <bundle> <table>… --base <rev>` and `spine accept <bundle> <partition> <key>`.
106
+ - **Data:** `gateway factory describe|records|data|release <bundle>`, `gateway factory upload <bundle> <file> --world <world>`, `gateway factory enrichment <bundle> --world <world> --entity <entity> --on|--off` and `gateway factory run start <bundle>`.
107
+ - **Worlds:** `gateway worlds sandbox open <member>`, then `status`, `read`, `write`, `exec`, `check`, `commit`, `import` and `close` on that sandbox.
108
+
109
+ The key never reaches `gateway factory agents` (or its switches), `run stop`, `chat` or `sandbox list`. Those are a person's.
110
+
111
+ ## How to work
112
+
113
+ 1. **Read first.** Call `get_factory` and note `head`. Every write passes the latest `head` you saw as `base`.
114
+ 2. **Agree before writing.** Restate what you understood in a sentence or two. When the request can be read two ways, ask.
115
+ 3. **Write small.** Commit a few nodes at a time, with a `message` that says what changed. Reuse ids; never change an id to change a name.
116
+ 4. **Write in sentences.** A node's `sentence` is what a person reads first. Make it true and specific.
117
+ 5. **Point, don't copy.** Link to a world, a schema field or another node with `refs` instead of repeating it.
118
+
119
+ ## When something pushes back
120
+
121
+ - **`factory_conflict`:** someone changed the same field. Re-read the head, re-apply your change to the new text and commit on the new base. If the two intents disagree, ask the person.
122
+ - **`factory_invalid`:** each issue names its node and field. Fix those and commit again; nothing was written.
123
+ - **`factory_tool_not_granted`:** that switch is off for you. Tell the person which switch the change needs. Never reach for another tool to make the same change.
124
+ - **A result that carries `changes`:** someone moved the head since your last call; the line says what. When it touches what you are doing, re-read before your next write.
125
+ - **`factory_spine_checks_failed`:** each issue names a spine node, the check and the numbers. Fix the values or the facts they read; nothing was written.
126
+ - **`factory_spine_generate_failed`:** a generator raised or returned rows that are not objects; the error names the table. Fix its code; nothing was written.
127
+ - **`factory_unit_unknown`:** the `unit` names no partition table or no row of it.
128
+ - **`factory_rule_tests_failed`:** a `block` test failed; each failure names its test and case. Fix the rule or the test; nothing was written.
129
+ - **`factory_hook_denied`:** a rule's guard refused the call; `rule` and `reason` say why. Do what the reason asks, or tell the person; never retry the same call unchanged.
130
+ - **`factory_records_refused`:** each refusal names a row (`world`, `entity`, `index`, and `propagated` when it is a counterpart the platform wrote) and why: `reference_broken` (write the referenced record first, fix the value, or send `deferReferences: true` when it comes later), `row_refused` (the world's contract), `row_not_found` (a patch for a row no member holds; write it without `patch` first), `identity_conflict` (two values for one person's carried field; send one), `real_field_protected` or `real_rows_protected` (real data; leave those fields as they are, or ask the person to enable enrichment), `partition_other_unit` (another unit owns that row; leave it to that unit) or `partition_owner_failed` (the partition's owner function raised; fix it or tell the person). Nothing was written; fix those rows and send the write again.
131
+ - **`factory_run_required`, `factory_run_released`, `factory_run_stopped`, `factory_budget_reached`:** no run is active, or it ended, so nothing can be written. Tell the person. Start a run yourself only when the person asked for one and "Starts runs" is on.
132
+ - **`factory_agent_key_mcp_only`, `factory_roster_people_only`:** that is a person's: the roster, switches, keys, stopping a run or the chat. Tell the person what you need.
133
+ - **`factory_run_busy`:** another write or the release held the run, or other writes kept moving the drafts while yours was built. Nothing of yours was kept in any member; send the same write again.
134
+ - **`factory_run_hold_ended`:** your write ran past the run's lock (three minutes). Nothing of yours was kept; send the same rows again as smaller slices.
135
+ - **`factory_draft_name_taken`:** a member already has a world state named like this run's draft. Tell the person; nothing was written.
136
+ - **`factory_records_failed`:** a member's import failed, and the message names it. Nothing of yours was kept; read the drafts with `get_factory_data` before writing again.
137
+ - **`factory_state_carrying`:** a person moved the bundle's pin, and a member's draft or Day 0 is being carried onto the new version. Nothing was written; wait a minute, then read or send the same call again. After three such answers for the same member, stop and tell the person.
138
+ - **`factory_state_not_carried`:** that carry failed or was refused. When the message says a write, a release or a run start queues it again, at most once every 10 minutes, send the same write again after that. When it says to start from main or empty, tell the person: this run's draft cannot follow the new pin.
139
+ - **`factory_state_off_pin`:** a member's state was built on a version past the one the bundle pins. Nothing was written; tell the person, who can commit the bundle to move the pin, or start a run from main or empty.
140
+ - **`factory_release_refused`:** each refusal names a member world, a row and the value no member holds (`pending` when the row was deferred, `reservation_unfulfilled` when the spine reserved it). Write the missing records or fix the rows, then release again; nothing was released.
141
+ - **`factory_release_conflict`:** a member's draft or Day 0 state changed outside this run. Check what the members hold, then release again; nothing was released.
142
+ - **`factory_rule_runner_unavailable`:** the rule runner could not start, so nothing that needs it ran. Tell the person; try again later.
143
+
144
+ ## What never happens
145
+
146
+ - No document leaves the platform: never paste a whole document into a file, a world or a message outside this factory.
147
+ - Never invent a kind, a rule or a relationship the person did not ask for. Propose it, and wait.
@@ -260,7 +260,10 @@ A `.csv`/`.tsv` (optionally `.gz`) is read as a stream — memory is bounded at
260
260
  split by `--delimiter` (one character, `\t` for a tab; default `,`, tab for a `.tsv`). The header
261
261
  row names the fields; `--entity` says which entity they fill. Every cell is cast by that field's
262
262
  schema type, the same rule in the TypeScript CLI (`worldData/cast.ts`) and the Python package
263
- (`schema/cast.py`), pinned by `gatewaysdk/sdk/tests/conformance/csv_cast.json`:
263
+ (`schema/cast.py`), pinned by `gatewaysdk/sdk/tests/conformance/csv_cast.json`. The type is the one
264
+ `worlds describe` reports: the JSON type words the field admits through `$ref`s (into sibling
265
+ `schema/*.json` files too) and unions, so a field that is a reference to an object casts as JSON and
266
+ `anyOf [Count, null]` as `integer | null`:
264
267
 
265
268
  | Field type | Cell | Value |
266
269
  | --- | --- | --- |
@@ -270,6 +273,7 @@ schema type, the same rule in the TypeScript CLI (`worldData/cast.ts`) and the P
270
273
  | `array` / `object` | JSON text of that shape (quote it in the CSV: `"[""a"",""b""]"`) | the parsed value |
271
274
  | `string` | anything | the text as given |
272
275
  | `integer \| string` (union) | each member tried in order, `string` last | the first that fits |
276
+ | `number \| boolean \| string \| null` (a union that admits string) | `00501`, `true` | the typed member that fits first (`501.0`, `true`): leading zeros and literal text do not survive; import JSON or JSONL to keep a value as text |
273
277
  | any, empty cell | (nothing) | null when the type admits null; `""` for a required string; left out otherwise (a required one is then refused by the contract) |
274
278
 
275
279
  A cell that fits none stays its text and the contract refuses the row as it refuses a JSON row
@@ -101,7 +101,7 @@ commit, with a warning); bulk rows reach the platform world through `worlds sand
101
101
 
102
102
  ```bash
103
103
  gateway worlds describe <WORLD> # entities, keys, relationships, row counts, and how each field is stored
104
- gateway worlds describe <WORLD> --json # the same as a document (fields[].redaction, redact)
104
+ gateway worlds describe <WORLD> --json [--entity e] # the document: fields[].redaction, .enum, .format, redact, catalog (enums, JSON shapes, custom fields, ids, sequences)
105
105
  gateway worlds data show <WORLD> # {world, kind, entity_counts}
106
106
  gateway worlds data show <WORLD> --entity users # the rows of one entity
107
107
  gateway worlds data query <WORLD> users --where plan=pro --limit 50 # the rows you mean; a repeated --where key is IN
@@ -140,6 +140,7 @@ gateway worlds data import <WORLD> rows.json --redact apply # run the w
140
140
  gateway worlds data import <slug> export.jsonl -m "Q3 tenants" # platform: chunked upload, new version
141
141
  gateway worlds data import <slug> export.jsonl --per-chunk --publish later --report refusals.jsonl
142
142
  gateway worlds data import <slug> export.jsonl --resume # pick a dead upload back up
143
+ gateway worlds data import <slug> rows.jsonl --state q4-messy # into a world state only: no version, main untouched
143
144
  gateway worlds data check <WORLD> rows.json --report refusals.jsonl # the dry run on its own; exit 2 on refusals
144
145
  ```
145
146
 
@@ -162,13 +163,14 @@ state}` and `gateway worlds data status <batchId> [--report <file>]` reads it la
162
163
  published, 2 refused (the report is written when `--report` is given: JSONL of refusal
163
164
  records, at most 10,000 then `{"truncated": true, "total": N}`), 1 error.
164
165
 
166
+ `--state <name>` lands the batch in that world state (`worlds state create` first): `published`, no `versionId`, `worldState` in the view; `worlds state show|pull` reads it on any version (`--ref`); `--rebase` rebuilds a state its rows cannot follow on main's data; `--publish later` is refused.
165
167
  A manifest at `.gateway/imports/<batchId>.json` records every chunk's digest as it lands;
166
168
  `--resume` reopens the newest incomplete batch for that slug and files and uploads only the
167
169
  chunks the platform does not already hold. `--publish later` applies without a version;
168
170
  `gateway worlds data publish <slug>` folds every pending batch into one; `data batches <slug>` lists them.
169
171
  A refusal record, everywhere (dry run, report, status, MCP):
170
172
  `{"chunk", "index", "entity", "primaryKey", "field", "pointer", "detail"}`, `pointer` being
171
- `/<entity>/<index>/<field>` inside the chunk.
173
+ `/<entity>/<index>/<field>` inside the chunk (`chunk`, `index` null when it spans chunks).
172
174
 
173
175
  MCP: `import_world_data({ containerId | slug, rows, mode?, message? })`. `rows` is the JSON
174
176
  object shape (`{entity: [rows]}`), at most 5,000 rows and 4 MiB per call: the inline lane,
@@ -178,7 +180,7 @@ refused row is a tool error naming the field, and nothing is written.
178
180
  ### 2a. Pull a connector's data through an active connection
179
181
 
180
182
  For a schema world created from a connector template (`worlds create --from-connection`, or
181
- the Connectors page), the provider is the source — no rows file:
183
+ the WorldHub page), the provider is the source — no rows file:
182
184
 
183
185
  ```bash
184
186
  gateway worlds data pull <slug> --connection google_drive # connector slug when the project has one connection for it
@@ -194,7 +196,7 @@ contract like `data import`. `replace` (default) rebuilds the mapped entities fr
194
196
  `pulled|unchanged <slug> from <connector> connection <id> (<mode>, <n> calls[, k unmatched (tool…)])
195
197
  <hash> [entity=count …]`; `changed: false` in `--json` when the pull reproduced the tip (no new
196
198
  version). The key reaches the connections shared with its project; a personal connection serves
197
- its owner alone (the Connectors page, or the MCP tool as that user) and is refused here. An
199
+ its owner alone (the WorldHub page, or the MCP tool as that user) and is refused here. An
198
200
  inactive connection, a world without a contract, or a template that does not read the connector
199
201
  is a refusal (exit 1) and nothing is written; a provider failure is reported as
200
202
  `provider tool failed (HTTP n)` with no provider body.
@@ -493,6 +495,6 @@ handler or route edit keeps the imported data while an entity, field or key edit
493
495
 
494
496
  - `worlds-getting-started`: the whole path, auth to runs, CLI with MCP twins.
495
497
  - `connector-schema-authoring`: the data model the rows are checked against.
496
- - `documentation/features/world-data-ingestion.md`: what exists, the contract, code pointers.
497
- - `documentation/features/connector-worlds.md`: captures, ingest, serving the vendor's API.
498
+ - `documentation/features/world-data-ingestion.md` (the contract, code pointers) and `connector-worlds.md` (captures, ingest, the vendor's API).
499
+ - `factory-orchestrator`: a bundle's factory run takes the same files at any point with `gateway factory upload <bundle> <file> --world <member>` (chunked, `--map ingest.toml`, `--per-chunk`, `--dry-run`, `--resume`, `--report`), checked across members and tagged `real:<source>`, so agents may not change those fields.
498
500
  - Consumer page: https://docs.surfacearea.ai/worlds/data.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: worlds-getting-started
3
- description: Starter guide for building worlds and environments on the platform, end to end, for an agent (Claude Code, Cursor, Codex). Use when starting a world from scratch, building a world or environment, mocking a vendor, importing a Swagger or OpenAPI spec into a world (schema init --from-openapi), choosing between a shipped template, a workspace connector, an OpenAPI document, a vendor API capture or a custom contract, provisioning worlds for tenants in one call (worlds create), publishing with bench push, opening a session, reading every request a world received (worlds requests), checks over those requests (journal checks on gateway_requests, calls, verify.py, SQL verifiers; task try before you save, task regrade of past runs), running and grading, or iterating with pull, fork, diff and edit sessions (worlds edit status/close/rollback: version control without PRs). Every CLI step names its MCP twin (list_connectors, publish_connector, create_world, init_world_from_connector, env_write_file, env_commit, import_world_data, run_evaluation and the rest) and where the result shows in the UI.
3
+ description: Starter guide for building worlds and environments on the platform, end to end, for an agent (Claude Code, Cursor, Codex). Use when starting a world from scratch, building a world or environment, mocking a vendor, importing a Swagger or OpenAPI spec into a world (schema init --from-openapi), choosing between an official template, a workspace connector, an OpenAPI document, a vendor API capture or a custom contract, provisioning worlds for tenants in one call (worlds create), publishing with bench push, opening a session, reading every request a world received (worlds requests), checks over those requests (journal checks on gateway_requests, calls, verify.py, SQL verifiers; task try before you save, task regrade of past runs), running and grading, or iterating with pull, fork, diff and edit sessions (worlds edit status/close/rollback: version control without PRs). Every CLI step names its MCP twin (list_connectors, publish_connector, create_world, init_world_from_connector, env_write_file, env_commit, import_world_data, run_evaluation and the rest) and where the result shows in the UI.
4
4
  ---
5
5
 
6
6
  # Worlds: getting started
@@ -55,7 +55,7 @@ first, then `guide({ topic: "connectors" })` for the connector loop and `guide({
55
55
  `schema init` writes: `schema/world.json` (the contract), `gateway-env.toml` with `[schema]`,
56
56
  and on top of it, optional, `tools/handlers.py` (tools, the `list_messages` style) and
57
57
  `connector.toml` + `api/handlers.py` (the vendor's HTTP routes) with a `[ui]` section for the
58
- page over those routes (every shipped template declares one; `schema compile` generates
58
+ page over those routes (every official template declares one; `schema compile` generates
59
59
  `ui/static` from the contract, `gateway worlds schema ui init ./x` declares it for a world of
60
60
  your own, `[ui] generated = false` keeps a hand-written page — the UI-twin templates such as
61
61
  notion, servicenow and zendesk ship a built twin under `ui/static` that way). It is stored as it is, and
@@ -75,7 +75,7 @@ browser; the tools are always there). Everything else is derived or retired (own
75
75
 
76
76
  | You have | Path | First command |
77
77
  | --- | --- | --- |
78
- | A vendor the SDK ships a template for (`gateway worlds schema templates`: github, slack, salesforce, jira, linear, workday, netsuite, microsoft-teams, google-drive, google-calendar, jamf, kandji, apple-business-manager, constella) | shipped template | `gateway worlds schema init ./x --connector github` |
78
+ | A vendor with an official template (`gateway worlds schema templates`: github, slack, salesforce, jira, linear, workday, netsuite, microsoft-teams, google-drive, google-calendar, jamf, kandji, apple-business-manager, …; fetched from the platform, so log in first) | official template | `gateway worlds schema init ./x --connector github` |
79
79
  | A connector someone in your org (or any org) already published | workspace connector | `gateway worlds connector list --hub` then `schema init ./x --connector workspace:<slug>` |
80
80
  | A Swagger 2.0 / OpenAPI 3.x document (JSON or YAML; a file, `drive:<path>` or a URL) | OpenAPI import | `gateway worlds schema init ./x --from-openapi petstore.yaml` — entities + routes from the spec, plan printed first; §2 "From an OpenAPI spec" |
81
81
  | A vendor API with a dev key and no template | vendor API capture | `schema init ./x --connector custom`, write `connector.toml`, capture, ingest (`documentation/features/connector-worlds.md`) |
@@ -188,7 +188,7 @@ MCP: `validate_connector_template({ files, slug? })` compiles without writing; a
188
188
  ## 4. Data
189
189
 
190
190
  ```bash
191
- gateway worlds describe ./x # entities, keys, relationships, row counts, enum values, [redact] per field
191
+ gateway worlds describe ./x [--entity e] [--json] # entities, keys, row counts, [redact] per field; --json: the shape catalog
192
192
  gateway worlds data show ./x # kind + entity counts
193
193
  gateway worlds data query ./x users --where email=jo@acme.test --resolve # the rows you mean; plaintext into a hashed field
194
194
  gateway worlds data import ./x rows.json # rows file: {entity: [rows]} | JSONL | .csv/.tsv --entity (cells cast by the schema; --delimiter)
@@ -204,7 +204,7 @@ gateway worlds data ingest ./x calls.jsonl --map ingest.toml # or a
204
204
  shape-preserved (`[preserve]`), rounded, or dropped (`[drop]`, never on disk). A hashed field is still looked up by
205
205
  its plaintext: the world's `[redact]` policy fixes the stored form (`sha256:` of `<slug>:<value>`), and the CLI, the
206
206
  SDK (`storedForms` in `@withgateway/sdk/worlds`) and the served handlers all compute it from that one rule. A dropped
207
- field is a documented miss, not an error.
207
+ field is a documented miss, not an error. Tags are capture's forms: other writes land as written (`--json` has the legend). `--json` also carries the **shape catalog** (enums at any depth, JSON shapes, custom fields, ids, sequences, each route's answer shape; MCP `describe_world`): `references/shape-catalog.md`.
208
208
 
209
209
  Rows file contract, modes, upsert and refusals: `world-data-ingestion`. Captures: pace with `[capture] requests_per_minute`;
210
210
  a vendor that allow-lists IPs is captured with `--remote` after `gateway bench secrets set --env x --key VENDOR_API_KEY`.
@@ -231,7 +231,7 @@ makes the world under a PAT session; under an API key it returns the initialized
231
231
  For a world you provision rather than iterate on (a tenant's Slack, one per customer):
232
232
 
233
233
  ```bash
234
- gateway worlds create acme-slack --from slack --rows rows.json --name "Acme Slack" # shipped template + their rows
234
+ gateway worlds create acme-slack --from slack --rows rows.json --name "Acme Slack" # official template + their rows
235
235
  gateway worlds create acme-crm --from workspace:acme-crm --overlay ./overlay --json # hub connector + your edits
236
236
  gateway worlds create acme-custom --from ./x # a directory, any kind
237
237
  gateway worlds create acme-drive --from-connection google_drive # the connector's template filled from an active connection (id or slug); `--from <template>` picks the template
@@ -246,7 +246,7 @@ version, attributed to the key (`apikey:<id>`), owned by nobody. 409 when the sl
246
246
  project. `--layout api-bundle` (body `layout`) packages the tree as its api bundle instead —
247
247
  deprecated, and the answer's `deprecations` says so. A legacy tools bundle, a Harbor tree or a
248
248
  verifiers package is a 400 `world_kind_retired`. `--from-connection` binds an active connection
249
- (Connectors page) shared with the key's project — a personal one serves its owner alone (MCP as
249
+ (WorldHub page) shared with the key's project — a personal one serves its owner alone (MCP as
250
250
  that user); an inactive connection or a template that does not read the connector is refused,
251
251
  nothing created. Refresh later with `gateway worlds data pull <slug> --connection …`.
252
252
 
@@ -256,7 +256,7 @@ is the same request and answer; a PAT session reaches its own personal connectio
256
256
 
257
257
  ### Migrate a stored world: `worlds migrate`
258
258
 
259
- The platform's connector worlds (the ones the Connectors page lists — containers created from
259
+ The platform's connector worlds (the ones the WorldHub page lists — containers created from
260
260
  a template) that were stored as api bundles become schema trees again:
261
261
 
262
262
  ```bash
@@ -321,7 +321,7 @@ gateway worlds session state <SESSION_ID> # every entity's row
321
321
  gateway worlds session reset <SESSION_ID> # back to the snapshot (+ the task's seed); `session restart <SESSION_ID> [--version <pin>]` does it on what its pin (x@ref; unpinned = newest you may read) points to NOW, same id, URLs + token, running or closed; a grade then reads only the requests after its session.restart ledger entry
322
322
  gateway worlds session grade <SESSION_ID> [--timeout S] # {reward, rewards, raw}; exploratory → {reward: null, reason: "no grader"}
323
323
  gateway worlds session export <SESSION_ID> --out calls.jsonl [--requests] # the platform's ledger; --requests adds the session's entries from the world's request ledger (kind "request": via, status, sizes; bodies by result.requestId), live or closed
324
- gateway worlds requests x [--session <SESSION_ID>] [--via api|ui|tool|webhook] [--status 4xx] [--since 2026-10-05] [--json] # every request the world received (every session, version and door), newest first, kept for its life; reading records nothing; `requests show x <REQUEST_ID> [--out f]` adds headers + bodies, `session requests <SESSION_ID>` lists one session's (exit 3: its engine records no requests, only World Host sessions do)
324
+ gateway worlds requests x [--session <SESSION_ID>] [--via api|ui|tool|webhook|page] [--status 4xx] [--since 2026-10-05] [--json] # every request the world received (every session, version and door), newest first, kept for its life; reading records nothing; `requests show x <REQUEST_ID> [--out f]` adds headers + bodies, `session requests <SESSION_ID>` lists one session's (exit 3: its engine records no requests, only World Host sessions do)
325
325
  gateway worlds data ingest x calls.jsonl --transform shape.py # the calls back in as rows, shaped by your code or --map ingest.toml (world-data-ingestion §2c)
326
326
  gateway worlds session close <SESSION_ID> # a closed session reopens by id, same URLs + token, from its last checkpoint: gateway worlds session reopen <SESSION_ID>
327
327
  ```