@withgateway/sdk 0.3.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. package/README.md +8 -6
  2. package/dist/cli.js +4372 -2265
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +4362 -2256
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +259 -58
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +249 -50
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +124 -11
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +124 -11
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  19. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  20. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  21. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  22. package/dist/index.d.mts +5 -5
  23. package/dist/index.d.ts +5 -5
  24. package/dist/index.js +2240 -789
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2150 -739
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  29. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  30. package/dist/traces/index.d.mts +1 -1
  31. package/dist/traces/index.d.ts +1 -1
  32. package/dist/traces/index.js +253 -52
  33. package/dist/traces/index.js.map +1 -1
  34. package/dist/traces/index.mjs +243 -44
  35. package/dist/traces/index.mjs.map +1 -1
  36. package/dist/tracing/index.d.mts +2 -2
  37. package/dist/tracing/index.d.ts +2 -2
  38. package/dist/tracing/index.js +75 -13
  39. package/dist/tracing/index.js.map +1 -1
  40. package/dist/tracing/index.mjs +75 -13
  41. package/dist/tracing/index.mjs.map +1 -1
  42. package/dist/worlds/index.d.mts +893 -482
  43. package/dist/worlds/index.d.ts +893 -482
  44. package/dist/worlds/index.js +1968 -669
  45. package/dist/worlds/index.js.map +1 -1
  46. package/dist/worlds/index.mjs +1960 -662
  47. package/dist/worlds/index.mjs.map +1 -1
  48. package/package.json +1 -1
  49. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  50. package/runtime/gatewaysdk/environment/_materialize.py +48 -88
  51. package/runtime/gatewaysdk/environment/_world.py +155 -237
  52. package/runtime/gatewaysdk/environment/backing.py +133 -0
  53. package/runtime/gatewaysdk/environment/core.py +2 -17
  54. package/runtime/gatewaysdk/environment/legacy_sqlite.py +288 -0
  55. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  56. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  57. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  58. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  59. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  60. package/runtime/gatewaysdk/environment/schema/api.py +347 -892
  61. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  62. package/runtime/gatewaysdk/environment/schema/batch.py +44 -39
  63. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  64. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  65. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  66. package/runtime/gatewaysdk/environment/schema/call_log.py +503 -0
  67. package/runtime/gatewaysdk/environment/schema/call_redaction.py +526 -0
  68. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  69. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  70. package/runtime/gatewaysdk/environment/schema/conform.py +14 -39
  71. package/runtime/gatewaysdk/environment/schema/connector.py +113 -211
  72. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  75. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  76. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  77. package/runtime/gatewaysdk/environment/schema/data.py +60 -216
  78. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  79. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  80. package/runtime/gatewaysdk/environment/schema/database/base.py +936 -0
  81. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  82. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  83. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  84. package/runtime/gatewaysdk/environment/schema/database/guard.py +215 -0
  85. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  86. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  87. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  88. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  89. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  90. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  91. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +393 -0
  92. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  93. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  94. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  95. package/runtime/gatewaysdk/environment/schema/envelope.py +227 -0
  96. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  97. package/runtime/gatewaysdk/environment/schema/grading.py +90 -103
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +163 -12
  99. package/runtime/gatewaysdk/environment/schema/host.py +237 -1795
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  112. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  113. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  114. package/runtime/gatewaysdk/environment/schema/local.py +58 -170
  115. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  116. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  117. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  118. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  119. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  120. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  121. package/runtime/gatewaysdk/environment/schema/platform.py +137 -187
  122. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  123. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  124. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  125. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  126. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  127. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  128. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  129. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  130. package/runtime/gatewaysdk/environment/schema/runtime.py +178 -308
  131. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  132. package/runtime/gatewaysdk/environment/schema/session_files.py +275 -0
  133. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  134. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  135. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +10 -11
  136. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +49 -16
  137. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +39 -9
  138. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +27 -27
  139. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +33 -33
  140. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  141. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +49 -1
  142. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  143. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  144. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  145. package/runtime/gatewaysdk/environment/schema/snapshot.py +516 -140
  146. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  147. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  148. package/runtime/gatewaysdk/environment/schema/tasks.py +267 -276
  149. package/runtime/gatewaysdk/environment/schema/tools_world.py +146 -242
  150. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  151. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  152. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  153. package/runtime/gatewaysdk/environment/schema/validation.py +235 -41
  154. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  155. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  156. package/runtime/gatewaysdk/environment/schema/workers.py +345 -96
  157. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  158. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  159. package/runtime/gatewaysdk/environment/schema/world_tests.py +80 -50
  160. package/runtime/gatewaysdk/environment/score.py +57 -0
  161. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  162. package/runtime/gatewaysdk/environment/world.py +43 -4
  163. package/runtime/gatewaysdk/environment/world_session_contract.py +46 -5
  164. package/skills/agents/connector-template-author.md +5 -1
  165. package/skills/benchmarks-getting-started/SKILL.md +10 -11
  166. package/skills/connector-schema-authoring/SKILL.md +49 -16
  167. package/skills/connector-schema-authoring/connector-worlds.md +142 -11
  168. package/skills/connector-schema-authoring/world-schema.md +103 -51
  169. package/skills/world-data-ingestion/ROWS.md +39 -9
  170. package/skills/world-data-ingestion/SKILL.md +27 -27
  171. package/skills/worlds-getting-started/SKILL.md +33 -33
  172. package/skills/worlds-getting-started/references/cli-mcp-map.md +13 -7
  173. package/skills/worlds-getting-started/references/gotchas.md +49 -1
  174. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
  175. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  176. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -7,13 +7,14 @@ use; unsupported assertions fail rather than becoming unenforced promises.
7
7
  from __future__ import annotations
8
8
 
9
9
  import datetime as dt
10
+ import functools
10
11
  import hashlib
11
12
  import json
12
13
  import math
13
14
  import re
14
15
  import struct
15
16
  from pathlib import Path
16
- from typing import Any, NoReturn
17
+ from typing import Any, Mapping, NoReturn
17
18
 
18
19
  from .._toml import tomllib
19
20
 
@@ -93,6 +94,56 @@ def pointer(part: Any) -> str:
93
94
  return str(part).replace("~", "~0").replace("/", "~1")
94
95
 
95
96
 
97
+ LOCAL_DEFS = "#/$defs/"
98
+ COMPOSITIONS = ("allOf", "anyOf", "oneOf")
99
+
100
+
101
+ class InlineBudgetExceeded(Exception):
102
+ """Inlining every reference produced more schema nodes than a publishable contract holds."""
103
+
104
+
105
+ def local_reference(key: str, definition: dict) -> dict:
106
+ """A compiled reference to a shared definition, carrying the definition's type so a
107
+ reader that looks one level deep (columns, the generated ui) still sees it."""
108
+ typed = {"type": definition["type"]} if "type" in definition else {}
109
+ return {"$ref": LOCAL_DEFS + pointer(key), **typed}
110
+
111
+
112
+ def local_key(ref: Any) -> str | None:
113
+ if not isinstance(ref, str) or not ref.startswith(LOCAL_DEFS):
114
+ return None
115
+ return ref[len(LOCAL_DEFS) :].replace("~1", "/").replace("~0", "~")
116
+
117
+
118
+ def local_definition(defs: dict, ref: Any, location: str) -> dict:
119
+ key = local_key(ref)
120
+ if key not in defs:
121
+ fail("reference", f"Unresolved reference {ref}", location)
122
+ return defs[key]
123
+
124
+
125
+ def subschemas(schema: dict) -> list[dict]:
126
+ children = list(schema.get("properties", {}).values())
127
+ children += [schema[key] for key in ("items", "additionalProperties") if isinstance(schema.get(key), dict)]
128
+ return children + [branch for key in COMPOSITIONS for branch in schema.get(key, [])]
129
+
130
+
131
+ def structural(schema: dict) -> bool:
132
+ """Whether a compiled schema can hold an object or array: such a definition is worth
133
+ sharing; a scalar one (an enum, a formatted string) is inlined where it is used."""
134
+ types = schema.get("type", [])
135
+ types = {types} if isinstance(types, str) else set(types)
136
+ branches = [branch for key in COMPOSITIONS for branch in schema.get(key, [])]
137
+ return bool(types & {"object", "array"}) or "$ref" in schema or any(structural(b) for b in branches)
138
+
139
+
140
+ def local_references(schema: dict) -> set[str]:
141
+ found = {local_key(schema["$ref"])} if "$ref" in schema else set()
142
+ for child in subschemas(schema):
143
+ found |= local_references(child)
144
+ return found
145
+
146
+
96
147
  def json_value(value: Any, path: str = "") -> None:
97
148
  """Require JSON-native values and the explicitly supported numeric range."""
98
149
  if value is None or type(value) is bool:
@@ -221,15 +272,75 @@ def nonempty(value: Any, location: str) -> None:
221
272
 
222
273
  #: A connector operation name: snake_case, at most this long. The bound is shared with
223
274
  #: the TypeScript ``route add`` (``MAX_OPERATION_NAME`` in scaffoldRoutes.ts) and the
224
- #: OpenAPI importer, which truncates an ``operationId`` to fit; a 300-character name
225
- #: used to compile (zero-context round 2, W3).
275
+ #: OpenAPI importer, which truncates an ``operationId`` to fit.
226
276
  MAX_OPERATION_NAME = 64
227
277
  #: An entity name: at most this long, so ``data-import:<entity>:<identity>`` source
228
- #: records and SQLite table names stay inside the 256-character record limit. Shared
278
+ #: records and table names stay inside the 256-character record limit. Shared
229
279
  #: with the TypeScript ``schema entity add`` (``MAX_ENTITY_NAME`` in scaffold.ts) and
230
280
  #: the OpenAPI importer, which truncates a schema name to fit.
231
281
  MAX_ENTITY_NAME = 64
232
282
  OPERATION_NAME = re.compile(r"^[a-z][a-z0-9_]*$")
283
+ #: A vendor-named field (an entity property, a redacted field) as the vendor spells it:
284
+ #: hyphens kept (``reference-count``), never a dot or slash, which address nested fields.
285
+ #: The TypeScript ``schema entity add`` pins the same rule (``PROPERTY_NAME`` in scaffoldJson.ts).
286
+ FIELD_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]*$")
287
+ METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE")
288
+
289
+
290
+ def table_of(value: Any, location: str) -> dict:
291
+ """A connector.toml table, or the refusal naming where one was expected."""
292
+ if not isinstance(value, dict):
293
+ fail("spec", "Expected a table", location)
294
+ return value
295
+
296
+
297
+ def string_of(table: dict, key: str, location: str, *, default: str | None = None, required: bool = True) -> str | None:
298
+ """``table[key]`` as a non-empty string, stripped; ``default`` when an optional key is absent."""
299
+ if key not in table and required:
300
+ fail("spec", f"Missing {key}", location)
301
+ if key not in table:
302
+ return default
303
+ value = table[key]
304
+ if not isinstance(value, str) or not value.strip():
305
+ fail("spec", f"{key} must be a non-empty string", f"{location}/{key}")
306
+ return value.strip()
307
+
308
+
309
+ PLACEHOLDER = re.compile(r"\{([A-Za-z_][A-Za-z0-9_]*)\}")
310
+
311
+
312
+ def route_path(path: str, location: str) -> str:
313
+ """``path`` as a route declares it: from ``/``, with no query or fragment, each
314
+ ``{argument}`` a segment of its own at most once."""
315
+ if not path.startswith("/") or "?" in path or "#" in path:
316
+ fail("spec", "path must start with / and carry no query", location)
317
+ placeholders = PLACEHOLDER.findall(path)
318
+ repeated = [p for p in placeholders if placeholders.count(p) > 1]
319
+ if repeated:
320
+ fail(
321
+ "spec",
322
+ f"{{{repeated[0]}}} appears twice in path {path}; each path argument may appear once",
323
+ location,
324
+ argument=repeated[0],
325
+ )
326
+ return path
327
+
328
+
329
+ @functools.lru_cache(maxsize=4096)
330
+ def path_pattern(path: str) -> re.Pattern:
331
+ """A declared path as a pattern over a request's path, each ``{name}`` one segment."""
332
+ escaped = re.escape(path)
333
+ return re.compile("^" + re.sub(r"\\\{([A-Za-z_][A-Za-z0-9_]*)\\\}", r"(?P<\1>[^/]+)", escaped) + "$")
334
+
335
+
336
+ def names_of(table: dict, key: str, location: str, pattern: re.Pattern = FIELD_NAME) -> tuple[str, ...]:
337
+ """``table[key]`` as a list of distinct names ``pattern`` accepts, empty when absent."""
338
+ value = table.get(key, [])
339
+ if not isinstance(value, list) or not all(isinstance(v, str) and pattern.match(v) for v in value):
340
+ fail("spec", f"{key} must be a list of field names", f"{location}/{key}")
341
+ if len(set(value)) != len(value):
342
+ fail("spec", f"{key} repeats a name", f"{location}/{key}")
343
+ return tuple(value)
233
344
 
234
345
 
235
346
  def parse_toml(text: str) -> dict:
@@ -265,8 +376,9 @@ def equal(left: Any, right: Any) -> bool:
265
376
  return left == right
266
377
 
267
378
 
268
- def validate(schema: dict, value: Any, *, location: str = "", path: str = "") -> None:
379
+ def validate(schema: dict, value: Any, *, location: str = "", path: str = "", defs: dict | None = None) -> None:
269
380
  json_value(value, path)
381
+ defs = schema.get("$defs", {}) if defs is None else defs
270
382
 
271
383
  def error(code: str, message: str, keyword: str = "", **context: Any) -> NoReturn:
272
384
  fail(code, message, f"{location}/{keyword}" if keyword else location, path=path, **context)
@@ -289,17 +401,20 @@ def validate(schema: dict, value: Any, *, location: str = "", path: str = "") ->
289
401
  )
290
402
  if types and not matches:
291
403
  error("type", f"Expected {' or '.join(types)}", "type")
404
+ if "$ref" in schema:
405
+ target = local_definition(defs, schema["$ref"], f"{location}/$ref")
406
+ validate(target, value, location=f"{location}/$ref", path=path, defs=defs)
292
407
  if "enum" in schema and not any(equal(value, option) for option in schema["enum"]):
293
408
  error("enum", "Value is outside the declared enum", "enum")
294
409
  if "const" in schema and not equal(value, schema["const"]):
295
410
  error("const", "Value differs from the declared constant", "const")
296
- for keyword in ("allOf", "anyOf", "oneOf"):
411
+ for keyword in COMPOSITIONS:
297
412
  if keyword not in schema:
298
413
  continue
299
414
  matches_count = 0
300
415
  for index, branch in enumerate(schema[keyword]):
301
416
  try:
302
- validate(branch, value, location=f"{location}/{keyword}/{index}", path=path)
417
+ validate(branch, value, location=f"{location}/{keyword}/{index}", path=path, defs=defs)
303
418
  matches_count += 1
304
419
  except ContractError:
305
420
  pass
@@ -318,6 +433,7 @@ def validate(schema: dict, value: Any, *, location: str = "", path: str = "") ->
318
433
  item,
319
434
  location=f"{location}/properties/{pointer(name)}",
320
435
  path=f"{path}/{pointer(name)}",
436
+ defs=defs,
321
437
  )
322
438
  elif schema.get("additionalProperties") is False:
323
439
  error(
@@ -327,13 +443,12 @@ def validate(schema: dict, value: Any, *, location: str = "", path: str = "") ->
327
443
  property=name,
328
444
  )
329
445
  elif isinstance(schema.get("additionalProperties"), dict):
330
- # A schema-valued additionalProperties types a map: every
331
- # undeclared member holds a value of that schema.
332
446
  validate(
333
447
  schema["additionalProperties"],
334
448
  item,
335
449
  location=f"{location}/additionalProperties",
336
450
  path=f"{path}/{pointer(name)}",
451
+ defs=defs,
337
452
  )
338
453
  if type(value) is list:
339
454
  for keyword, invalid in (
@@ -353,6 +468,7 @@ def validate(schema: dict, value: Any, *, location: str = "", path: str = "") ->
353
468
  item,
354
469
  location=f"{location}/items",
355
470
  path=f"{path}/{index}",
471
+ defs=defs,
356
472
  )
357
473
  if type(value) is str:
358
474
  if len(value) < schema.get("minLength", 0) or len(value) > schema.get("maxLength", math.inf):
@@ -394,14 +510,25 @@ def validate(schema: dict, value: Any, *, location: str = "", path: str = "") ->
394
510
 
395
511
 
396
512
  class Resolver:
397
- """Resolve only relative files under schema/ and JSON pointers into $defs."""
513
+ """Resolve only relative files under schema/ and JSON pointers into $defs.
514
+
515
+ Inlined (the default) every reference is replaced by its target, and a nested
516
+ occurrence of a type inside itself keeps only its bare type. Shared, a reference
517
+ below a root to a structural definition becomes a local ``$ref`` and the definition
518
+ is resolved once, so the output grows with the input rather than with the number of
519
+ paths through it. ``budget`` caps how many schema nodes inlining may produce."""
398
520
 
399
- def __init__(self, bundle: Path):
521
+ def __init__(self, bundle: Path, *, shared: bool = False, budget: int | None = None):
400
522
  self.root = (bundle / "schema").resolve()
401
523
  self.documents: dict[str, dict] = {}
402
524
  self.identities: dict[str, str] = {}
403
525
  self.checked: set[str] = set()
404
- self.checking: set[str] = set()
526
+ self.shared = shared
527
+ self.budget = budget
528
+ self.definitions: dict[str, dict] = {}
529
+ self.defining: set[str] = set()
530
+ self.projections: dict[str, dict] = {}
531
+ self.locations: dict[str, str] = {}
405
532
 
406
533
  def load(self, name: str) -> dict:
407
534
  path = self.root / name
@@ -460,7 +587,9 @@ class Resolver:
460
587
  stack: tuple[str, ...] = (),
461
588
  *,
462
589
  root: bool = False,
590
+ nested: bool = False,
463
591
  ) -> dict:
592
+ self.spend()
464
593
  if len(stack) > 80:
465
594
  fail("reference", "Reference nesting exceeds 80", location)
466
595
  if type(schema) is not dict:
@@ -493,46 +622,32 @@ class Resolver:
493
622
  fail("schema", "examples must be an array", location)
494
623
  result = {k: v for k, v in schema.items() if k not in {"$ref", "$defs", "$schema", "$id", "x-gateway"}}
495
624
  if "$ref" in schema:
496
- if set(schema) - DOC_KEYS - {"$ref"}:
497
- fail(
498
- "unsupported",
499
- "$ref siblings may only be documentation annotations; use allOf for assertions",
500
- location,
501
- )
502
- target, target_name, target_location = self.reference(schema["$ref"], name, location)
503
- if target_location in stack:
504
- # Vendor models nest a type in itself (Brex's ExpandableExpense
505
- # holds an ExpandableExpense). Inlining would never end, so the
506
- # nested occurrence keeps only the target's bare type: it is
507
- # validated as that type and stored as JSON, never projected.
508
- return {**self.recursive(target, target_name, target_location, location), **result}
509
- result = {
510
- **self.resolve(target, target_name, target_location, (*stack, target_location)),
511
- **result,
512
- }
625
+ return self._reference(schema, result, name, location, stack, nested=nested)
513
626
  for key in ("$defs", "properties"):
514
627
  if key not in schema:
515
628
  continue
516
629
  if type(schema[key]) is not dict:
517
630
  fail("schema", f"{key} must be an object", f"{location}/{key}")
518
631
  children = {
519
- k: self.resolve(v, name, f"{location}/{key}/{pointer(k)}", stack)
632
+ k: self.resolve(v, name, f"{location}/{key}/{pointer(k)}", stack, nested=True)
520
633
  for k, v in sorted(schema[key].items())
521
634
  }
522
635
  if key == "properties":
523
636
  result[key] = children
524
637
  if "items" in schema:
525
- result["items"] = self.resolve(schema["items"], name, f"{location}/items", stack)
638
+ result["items"] = self.resolve(schema["items"], name, f"{location}/items", stack, nested=True)
526
639
  if isinstance(schema.get("additionalProperties"), dict):
527
- # A map of one value type (Brex's `Record<string, string>` shapes).
528
640
  result["additionalProperties"] = self.resolve(
529
- schema["additionalProperties"], name, f"{location}/additionalProperties", stack
641
+ schema["additionalProperties"], name, f"{location}/additionalProperties", stack, nested=True
530
642
  )
531
643
  for key in ("allOf", "anyOf", "oneOf"):
532
644
  if key in schema:
533
645
  if not isinstance(schema[key], list) or not schema[key]:
534
646
  fail("schema", f"{key} needs a nonempty schema array", location)
535
- result[key] = [self.resolve(s, name, f"{location}/{key}/{i}", stack) for i, s in enumerate(schema[key])]
647
+ result[key] = [
648
+ self.resolve(s, name, f"{location}/{key}/{i}", stack, nested=True)
649
+ for i, s in enumerate(schema[key])
650
+ ]
536
651
  types = result.get("type", [])
537
652
  types = [types] if isinstance(types, str) else types
538
653
  if (
@@ -554,9 +669,7 @@ class Resolver:
554
669
  if isinstance(result.get("type"), list):
555
670
  result["type"] = sorted(types)
556
671
  if "format" in result and "string" not in types and set(types) & {"integer", "number"}:
557
- # OpenAPI documents annotate numbers with `int64`, `int32`, `double`
558
- # (Brex). Those are storage hints, not assertions: drop them rather
559
- # than refuse the document. String formats stay validated below.
672
+ # OpenAPI's int64 / int32 / double on a number are storage hints, not assertions.
560
673
  del result["format"]
561
674
  applicability = {
562
675
  "properties": {"object"},
@@ -619,10 +732,78 @@ class Resolver:
619
732
  or any(equal(v, p) for i, v in enumerate(values) for p in values[:i])
620
733
  ):
621
734
  fail("schema", "enum must contain distinct values", location)
622
- if "default" in result:
623
- validate(result, result["default"], location=f"{location}/default")
735
+ self._check_default(result, location)
624
736
  return result
625
737
 
738
+ def _reference(
739
+ self, schema: dict, annotations: dict, name: str, location: str, stack: tuple[str, ...], *, nested: bool
740
+ ) -> dict:
741
+ """A ``$ref`` beside documentation annotations alone. Shared, one below a root is a
742
+ local reference to its definition. A target already on this path (a vendor type
743
+ nested in itself, which would inline forever) keeps only its bare type: validated
744
+ as that type and stored as JSON, never projected. Otherwise the target is inlined."""
745
+ if set(schema) - DOC_KEYS - {"$ref"}:
746
+ fail(
747
+ "unsupported",
748
+ "$ref siblings may only be documentation annotations; use allOf for assertions",
749
+ location,
750
+ )
751
+ target, target_name, target_location = self.reference(schema["$ref"], name, location)
752
+ if self.shared and nested:
753
+ return {**self.definition(target, target_name, target_location, location), **annotations}
754
+ if target_location in stack:
755
+ return {**self.recursive(target, target_name, target_location, location), **annotations}
756
+ inlined = {**self.resolve(target, target_name, target_location, (*stack, target_location)), **annotations}
757
+ self._check_default(inlined, location)
758
+ return inlined
759
+
760
+ def _check_default(self, schema: dict, location: str) -> None:
761
+ """A ``default`` must be a value of its schema. A definition still being resolved
762
+ (a type nested in itself) is read as its bare type, as inlining reads it."""
763
+ if "default" not in schema:
764
+ return
765
+ defs = {**self.projections, **self.definitions}
766
+ validate(schema, schema["default"], location=f"{location}/default", defs=defs)
767
+
768
+ def spend(self) -> None:
769
+ if self.shared or self.budget is None:
770
+ return
771
+ self.budget -= 1
772
+ if self.budget < 0:
773
+ raise InlineBudgetExceeded
774
+
775
+ def standalone(self, schema: Any, name: str, location: str) -> dict:
776
+ """A root schema (an entity, a tool input or output) with the shared definitions it
777
+ reaches under its own ``$defs``, so it validates and serves on its own."""
778
+ body = self.resolve(schema, name, location)
779
+ defs: dict[str, dict] = {}
780
+ pending = local_references(body)
781
+ while pending:
782
+ key = pending.pop()
783
+ defs[key] = self.definitions[key]
784
+ pending |= local_references(defs[key]) - set(defs)
785
+ return {**body, "$defs": dict(sorted(defs.items()))} if defs else body
786
+
787
+ def definition(self, target: Any, name: str, target_location: str, location: str) -> dict:
788
+ key = self.key(target_location)
789
+ if key in self.defining:
790
+ projection = self.recursive(target, name, target_location, location)
791
+ self.projections[key] = projection
792
+ return local_reference(key, projection) if structural(projection) else projection
793
+ if key not in self.definitions:
794
+ self.defining.add(key)
795
+ self.definitions[key] = self.resolve(target, name, target_location, (target_location,))
796
+ self.defining.discard(key)
797
+ body = self.definitions[key]
798
+ return local_reference(key, body) if structural(body) else dict(body)
799
+
800
+ def key(self, target_location: str) -> str:
801
+ filename, fragment = target_location.split("#", 1)
802
+ key = Path(filename).stem + fragment.replace("/$defs/", ".")
803
+ if self.locations.setdefault(key, target_location) != target_location:
804
+ fail("reference", f"Definitions {self.locations[key]} and {target_location} share the name {key}", key)
805
+ return key
806
+
626
807
  def recursive(self, target: Any, name: str, target_location: str, location: str) -> dict:
627
808
  """The bare-type projection of a reference target already being resolved.
628
809
 
@@ -652,9 +833,22 @@ class Resolver:
652
833
  }
653
834
 
654
835
  def check_documents(self) -> None:
655
- # Resolving references can discover more files. Check all definitions,
656
- # including unused ones, so unsupported assertions never hide there.
836
+ """Check every document whole, unused definitions included, so an unsupported
837
+ assertion never hides in one; resolving may load more documents, checked in turn.
838
+ The check runs in this resolver's own form: an inlined build is checked inlined,
839
+ so a world that compiled inlined before compiles the same (the shared form names
840
+ definitions and reads defaults through them, which inlining never did)."""
657
841
  while set(self.documents) - self.checked:
658
842
  name = sorted(set(self.documents) - self.checked)[0]
659
843
  self.resolve(self.documents[name], name, f"{name}#", root=True)
660
844
  self.checked.add(name)
845
+
846
+
847
+ def ttl_seconds_of(table: Mapping[str, Any], location: str) -> int | None:
848
+ """``ttl_seconds`` when a world opts in to expiry, else None: it never expires."""
849
+ value = table.get("ttl_seconds")
850
+ if value is None:
851
+ return None
852
+ if isinstance(value, bool) or not isinstance(value, int) or value < 1:
853
+ fail("spec", "ttl_seconds is a positive whole number of seconds", f"{location}/ttl_seconds")
854
+ return value
@@ -1,16 +1,5 @@
1
- """The session protocol, once: every verb a world session answers, with the
2
- method it takes and how its body is read. Both HTTP transports dispatch
3
- through this table — the local session (``local.py``, ``/__session/<verb>``)
4
- and the World Host control plane (``host.py``, ``/__host/sessions/<sid>/
5
- <verb>``) — so the two cannot drift: a verb added here is served by both, a
6
- body shape accepted here is accepted by both. The transports stay distinct
7
- (loopback with no secret against a fleet with leases, workers and exports);
8
- only the verbs are shared.
9
-
10
- A verb marked ``hosted`` is the platform's rendezvous with a session it keeps
11
- alive across hosts (the lease, the state export, DELETE as the platform's
12
- close); the local session, which lives as long as the process serving it,
13
- refuses them by name."""
1
+ """The one verb table local.py and host.py both dispatch through, so the transports cannot drift; a ``hosted`` verb
2
+ is control plane only (lease, export, DELETE, the ledger's flush and outbox), refused by name locally."""
14
3
 
15
4
  from __future__ import annotations
16
5
 
@@ -18,17 +7,14 @@ from collections.abc import Callable
18
7
  from dataclasses import dataclass
19
8
  from typing import Any
20
9
 
10
+ from ..world_session_contract import REQUEST_LOG_PAGE_MAX
21
11
  from .redaction import parse_mode
12
+ from .request_ledger import OUTBOX_CURSOR
22
13
  from .validation import ContractError, fail
23
14
 
24
15
 
25
16
  @dataclass(frozen=True)
26
17
  class SessionVerb:
27
- """One row of the protocol: ``method`` and ``name`` are the route (``name``
28
- None addresses the session itself, as ``DELETE`` does); ``read`` turns the
29
- request body into the keyword arguments the session operation takes, or
30
- refuses the shape (a :class:`ContractError` the transport answers 400)."""
31
-
32
18
  method: str
33
19
  name: str | None
34
20
  read: Callable[[dict], dict[str, Any]]
@@ -47,9 +33,8 @@ def read_nothing(_body: dict) -> dict[str, Any]:
47
33
 
48
34
 
49
35
  def read_seed(body: dict) -> dict[str, Any]:
50
- """``{rows, mode, redact}``, the same under ``args`` (the platform wraps
51
- the seed it forwards), or bare ``{entity: [row, ...]}`` — the shape a rows
52
- file has — taken as the rows of an append."""
36
+ """``{rows, mode, redact}``, the same under ``args`` as the platform forwards it, or a bare rows file
37
+ ``{entity: [row, ...]}`` taken as an append."""
53
38
  args = body["args"] if isinstance(body.get("args"), dict) else body
54
39
  if "rows" not in args and "mode" not in args and args and all(isinstance(v, list) for v in args.values()):
55
40
  args = {"rows": args}
@@ -67,18 +52,20 @@ def read_seed(body: dict) -> dict[str, Any]:
67
52
 
68
53
 
69
54
  def read_grade(body: dict) -> dict[str, Any]:
70
- """``report`` is the agent's own account of the run, read by a rubric
71
- judge or put beside the state for a deterministic grader; absent is fine,
72
- anything but a string is not. ``context`` is the evidence of the task's
73
- other worlds (``{alias: state}``, each what that session's ``evidence``
74
- answers), read by the cross-world verifiers anchored on this session."""
55
+ """``report`` the agent's own account (a string), ``context`` the task's other worlds as ``{alias: state}``,
56
+ ``journal`` the session's journal as the platform stored it, ``grader`` a candidate graded instead."""
75
57
  report = body.get("report")
76
58
  if report is not None and not isinstance(report, str):
77
59
  fail("input", "report must be a string", "/report")
78
60
  context = body.get("context")
79
- if context is not None and (not isinstance(context, dict) or any(not isinstance(v, dict) for v in context.values())):
61
+ if context is not None and (
62
+ not isinstance(context, dict) or any(not isinstance(v, dict) for v in context.values())
63
+ ):
80
64
  fail("input", "context must be {alias: state} of the task's other worlds", "/context")
81
- return {"report": report, "context": context}
65
+ for key in ("journal", "grader"):
66
+ if body.get(key) is not None and not isinstance(body[key], dict):
67
+ fail("input", f"{key} must be an object", f"/{key}")
68
+ return {"report": report, "context": context, "journal": body.get("journal"), "grader": body.get("grader")}
82
69
 
83
70
 
84
71
  def read_call(body: dict) -> dict[str, Any]:
@@ -92,8 +79,22 @@ def read_call(body: dict) -> dict[str, Any]:
92
79
 
93
80
 
94
81
  def read_export(body: dict) -> dict[str, Any]:
82
+ """``knownSha256``: the platform's last export of the session; ``handoff``: this is the final
83
+ export of a session its host is handing off, which only that host takes."""
95
84
  known = body.get("knownSha256")
96
- return {"known_sha256": known if isinstance(known, str) else None}
85
+ return {"known_sha256": known if isinstance(known, str) else None, "handoff": body.get("handoff") is True}
86
+
87
+
88
+ def read_requests(body: dict) -> dict[str, Any]:
89
+ """``cursor`` names the last outbox page that was stored (absent before the first); ``limit`` is 1 to
90
+ REQUEST_LOG_PAGE_MAX, the max when absent."""
91
+ cursor = body.get("cursor")
92
+ limit = body.get("limit", REQUEST_LOG_PAGE_MAX)
93
+ if cursor is not None and not (isinstance(cursor, str) and OUTBOX_CURSOR.fullmatch(cursor)):
94
+ fail("input", "cursor must be the cursor a page of the request ledger outbox answered", "/cursor")
95
+ if type(limit) is not int or not 1 <= limit <= REQUEST_LOG_PAGE_MAX:
96
+ fail("input", f"limit must be an integer from 1 to {REQUEST_LOG_PAGE_MAX}", "/limit")
97
+ return {"cursor": cursor, "limit": limit}
97
98
 
98
99
 
99
100
  SESSION_VERBS: tuple[SessionVerb, ...] = (
@@ -101,6 +102,8 @@ SESSION_VERBS: tuple[SessionVerb, ...] = (
101
102
  SessionVerb("GET", "task", read_nothing),
102
103
  SessionVerb("GET", "state", read_nothing),
103
104
  SessionVerb("GET", "evidence", read_nothing),
105
+ SessionVerb("POST", "requests", read_requests, hosted=True),
106
+ SessionVerb("POST", "flush", read_nothing, hosted=True),
104
107
  SessionVerb("POST", "grade", read_grade),
105
108
  SessionVerb("POST", "reset", read_nothing),
106
109
  SessionVerb("POST", "seed", read_seed),
@@ -117,14 +120,10 @@ def session_verb(method: str, name: str | None) -> SessionVerb | None:
117
120
 
118
121
 
119
122
  def served_verbs(*, hosted: bool) -> tuple[SessionVerb, ...]:
120
- """The rows a transport answers: every one on the host, the session's own
121
- (not the lease's) locally."""
122
123
  return tuple(verb for verb in SESSION_VERBS if hosted or not verb.hosted)
123
124
 
124
125
 
125
126
  def unknown_verb(method: str, name: str | None, *, hosted: bool, prefix: str) -> dict:
126
- """The 404 body for a route off the table, naming what is on it. A hosted
127
- verb sent to the local session is refused by name, not as unknown."""
128
127
  verb = session_verb(method, name)
129
128
  if verb is not None and verb.hosted and not hosted:
130
129
  return {"error": f"{verb.route} is a hosted session's verb (the platform's lease); the local session has none"}
@@ -136,7 +135,4 @@ def unknown_verb(method: str, name: str | None, *, hosted: bool, prefix: str) ->
136
135
 
137
136
 
138
137
  def refusal(error: ContractError) -> dict:
139
- """A refused call as the answer a session gives it: an unknown tool,
140
- arguments off the schema, a tool outside the task's allow-list, a write the
141
- store will not take, all ``{status: 400, body: {error, detail}}``."""
142
138
  return {"status": 400, "body": {"error": error.detail.get("code", "host"), "detail": str(error)}}
@@ -15,7 +15,8 @@ import socket
15
15
  import sys
16
16
  from pathlib import Path
17
17
 
18
- from .host import WorldHost, make_host_handler
18
+ from .cache_layout import VERSIONS_DIR, WORKERS_DIR
19
+ from .host import make_host_handler
19
20
  from .workers import (
20
21
  DEFAULT_WORKER_MEMORY_MB,
21
22
  WORKER_LEASE_S,
@@ -23,6 +24,7 @@ from .workers import (
23
24
  apply_limits,
24
25
  seal_process,
25
26
  )
27
+ from .world_host import WorldHost
26
28
 
27
29
 
28
30
  def main(argv: list[str] | None = None) -> int:
@@ -39,7 +41,7 @@ def main(argv: list[str] | None = None) -> int:
39
41
  raise SystemExit("world worker: WORLDS_WORKER_SECRET is unset; a worker only answers its supervisor")
40
42
  supervisor_pid: int | None = None
41
43
  if args.socket_fd is not None:
42
- supervisor_pid = int(os.environ.get("WORLDS_SUPERVISOR_PID") or os.getppid())
44
+ supervisor_pid = os.getppid()
43
45
  listening: socket.socket | str = socket.socket(fileno=args.socket_fd)
44
46
  else:
45
47
  listening = args.socket
@@ -48,8 +50,8 @@ def main(argv: list[str] | None = None) -> int:
48
50
 
49
51
  cache_root = Path(args.cache_root)
50
52
  world_host = WorldHost(
51
- cache_root / "workers" / args.version,
52
- versions_root=cache_root / "versions",
53
+ cache_root / WORKERS_DIR / args.version,
54
+ versions_root=cache_root / VERSIONS_DIR,
53
55
  lease_s=WORKER_LEASE_S,
54
56
  run_handlers=True,
55
57
  pinned_version=args.version,