@withgateway/sdk 0.3.0 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/README.md +6 -1
  2. package/dist/cli.js +3971 -2338
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +3950 -2318
  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 +214 -41
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +206 -35
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-DAb-FCMg.d.ts → index-DUHmS74p.d.ts} +3 -13
  13. package/dist/{index-D6oi1TWE.d.mts → index-mJhG3vZU.d.mts} +3 -13
  14. package/dist/index.d.mts +4 -4
  15. package/dist/index.d.ts +4 -4
  16. package/dist/index.js +1456 -564
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1433 -557
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/{media-CbcAfQvd.d.mts → media-BIApiPzS.d.mts} +21 -2
  21. package/dist/{media-CbcAfQvd.d.ts → media-BIApiPzS.d.ts} +21 -2
  22. package/dist/traces/index.d.mts +1 -1
  23. package/dist/traces/index.d.ts +1 -1
  24. package/dist/traces/index.js +211 -38
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +203 -32
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.d.mts +2 -2
  29. package/dist/tracing/index.d.ts +2 -2
  30. package/dist/tracing/index.js +96 -21
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +96 -21
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +300 -123
  35. package/dist/worlds/index.d.ts +300 -123
  36. package/dist/worlds/index.js +1385 -508
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1377 -501
  39. package/dist/worlds/index.mjs.map +1 -1
  40. package/package.json +1 -1
  41. package/runtime/gatewaysdk/environment/_bundle.py +2 -27
  42. package/runtime/gatewaysdk/environment/_materialize.py +49 -69
  43. package/runtime/gatewaysdk/environment/_world.py +122 -197
  44. package/runtime/gatewaysdk/environment/backing.py +137 -0
  45. package/runtime/gatewaysdk/environment/core.py +1 -1
  46. package/runtime/gatewaysdk/environment/legacy_sqlite.py +301 -0
  47. package/runtime/gatewaysdk/environment/reward_keys.py +25 -0
  48. package/runtime/gatewaysdk/environment/runtime.py +8 -13
  49. package/runtime/gatewaysdk/environment/schema/__init__.py +4 -4
  50. package/runtime/gatewaysdk/environment/schema/admin_routes.py +86 -0
  51. package/runtime/gatewaysdk/environment/schema/api.py +266 -515
  52. package/runtime/gatewaysdk/environment/schema/batch.py +42 -37
  53. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +17 -5
  54. package/runtime/gatewaysdk/environment/schema/call_log.py +291 -0
  55. package/runtime/gatewaysdk/environment/schema/call_redaction.py +344 -0
  56. package/runtime/gatewaysdk/environment/schema/cast.py +31 -4
  57. package/runtime/gatewaysdk/environment/schema/compiler.py +334 -158
  58. package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
  59. package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
  60. package/runtime/gatewaysdk/environment/schema/data.py +50 -207
  61. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  62. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  63. package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
  64. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  65. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  66. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  67. package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
  68. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  69. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  70. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  71. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  72. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  73. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
  74. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  75. package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
  76. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  77. package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
  78. package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
  79. package/runtime/gatewaysdk/environment/schema/host.py +158 -250
  80. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  81. package/runtime/gatewaysdk/environment/schema/local.py +44 -71
  82. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  83. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  84. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  85. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  86. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  87. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  88. package/runtime/gatewaysdk/environment/schema/platform.py +124 -178
  89. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  90. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  91. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  92. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  93. package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
  94. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  95. package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
  96. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
  97. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +22 -14
  98. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
  99. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +16 -16
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +18 -18
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  102. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
  103. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  104. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  105. package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
  106. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  107. package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
  108. package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
  109. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  110. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  111. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  112. package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
  113. package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
  114. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  115. package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
  116. package/runtime/gatewaysdk/environment/score.py +57 -0
  117. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  118. package/runtime/gatewaysdk/environment/world.py +42 -3
  119. package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
  120. package/skills/benchmarks-getting-started/SKILL.md +2 -2
  121. package/skills/connector-schema-authoring/SKILL.md +22 -14
  122. package/skills/connector-schema-authoring/connector-worlds.md +26 -10
  123. package/skills/connector-schema-authoring/world-schema.md +111 -51
  124. package/skills/world-data-ingestion/ROWS.md +29 -3
  125. package/skills/world-data-ingestion/SKILL.md +16 -16
  126. package/skills/worlds-getting-started/SKILL.md +18 -18
  127. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  128. package/skills/worlds-getting-started/references/gotchas.md +15 -0
  129. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  130. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -0,0 +1,53 @@
1
+ """``Lanes``: one holder at a time per key, served in the order they arrived.
2
+
3
+ The World Host keys them by version: a version is built once while its other
4
+ opens wait, and its sessions open one after another, so a burst of opens queues
5
+ instead of running together in the version's one worker.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import threading
11
+ from collections.abc import Iterator
12
+ from contextlib import contextmanager
13
+ from dataclasses import dataclass
14
+
15
+
16
+ @dataclass
17
+ class _Lane:
18
+ changed: threading.Condition
19
+ issued: int = 0
20
+ serving: int = 0
21
+
22
+
23
+ class Lanes:
24
+ """One holder at a time per key, first come first served; another key never
25
+ waits. A key is forgotten once nobody holds it or waits on it."""
26
+
27
+ def __init__(self) -> None:
28
+ self._lock = threading.Lock()
29
+ self._lanes: dict[str, _Lane] = {}
30
+
31
+ @contextmanager
32
+ def turn(self, key: str) -> Iterator[None]:
33
+ with self._lock:
34
+ lane = self._lanes.get(key)
35
+ if lane is None:
36
+ lane = self._lanes[key] = _Lane(threading.Condition(self._lock))
37
+ ticket = lane.issued
38
+ lane.issued += 1
39
+ lane.changed.wait_for(lambda: lane.serving == ticket)
40
+ try:
41
+ yield
42
+ finally:
43
+ with self._lock:
44
+ lane.serving += 1
45
+ if lane.serving == lane.issued:
46
+ del self._lanes[key]
47
+ else:
48
+ lane.changed.notify_all()
49
+
50
+ def held(self) -> list[str]:
51
+ """The keys someone holds or waits on now."""
52
+ with self._lock:
53
+ return sorted(self._lanes)
@@ -8,7 +8,9 @@ session verbs under ``/__session/`` for every schema world (``POST call``,
8
8
  ``GET state``, ``POST grade``, ``POST reset``, ``POST seed``, ``GET tools``,
9
9
  ``GET task``, ``POST close``, the host's own shapes) and, when the tree carries
10
10
  ``connector.toml``, the vendor routes beside them with the api pin as the key.
11
- Tool calls and HTTP requests hit the SAME store, as they do on the host.
11
+ Tool calls and HTTP requests hit the SAME store, as they do on the host. The
12
+ runner's ``/__world/*`` routes answer only the session's own :attr:`LocalSession.admin`
13
+ token, which ``worlds test`` hands its pytest files; the host serves none of them.
12
14
 
13
15
  The session is what an outside agent works against: ``GET task`` hands it the
14
16
  prompt it is to carry out and the verifiers that will grade it (a
@@ -37,13 +39,15 @@ from pathlib import Path
37
39
  from typing import Any, Callable
38
40
 
39
41
  from . import snapshot as snapshots
42
+ from .admin_routes import AdminToken
40
43
  from .api import Router, Via, WorldApp, load_api_settings, send_response, vendor_credential, with_query
44
+ from .call_log import CallLog
41
45
  from .compiler import bundle_mode, fail
42
46
  from .conform import PIN
43
47
  from .connector import SPEC, load_spec
44
48
  from .dependencies import local_dependency_trees
45
49
  from .host_surfaces import UiSurface, api_target, cross_site, load_ui_surface, static_file
46
- from .runtime import call_operation, client_grant, task_card
50
+ from .runtime import client_grant, task_card
47
51
  from .tools_world import (
48
52
  DependencyWorld,
49
53
  ToolsTask,
@@ -65,14 +69,14 @@ def has_http(root: str | Path) -> bool:
65
69
  return (Path(root) / SPEC).is_file()
66
70
 
67
71
 
68
- def load_local_version(root: Path, scratch: Path, *, require_tasks: bool) -> ToolsVersion:
72
+ def load_local_version(root: Path, scratch: Path) -> ToolsVersion:
69
73
  if bundle_mode(root) is None:
70
74
  fail(
71
75
  "world",
72
76
  f"{root} is not a schema world (no gateway-env.toml with a [schema] table); "
73
77
  "`gateway worlds schema init` starts one",
74
78
  )
75
- return load_tools_version(root, scratch / "template.sqlite", None, run_handlers=True, require_tasks=require_tasks)
79
+ return load_tools_version(root, scratch / "template.db", None, run_handlers=True)
76
80
 
77
81
 
78
82
  def load_local_dependencies(root: Path, version: ToolsVersion, scratch: Path) -> dict[str, DependencyWorld]:
@@ -81,7 +85,7 @@ def load_local_dependencies(root: Path, version: ToolsVersion, scratch: Path) ->
81
85
  pins, this machine cannot."""
82
86
  out: dict[str, DependencyWorld] = {}
83
87
  for alias, tree in local_dependency_trees(root, version.dependencies).items():
84
- dep_version = load_local_version(tree, scratch / "deps" / alias, require_tasks=False)
88
+ dep_version = load_local_version(tree, scratch / "deps" / alias)
85
89
  out[alias] = DependencyWorld.of(version.dependencies[alias], dep_version)
86
90
  return out
87
91
 
@@ -92,22 +96,16 @@ class LocalSession:
92
96
  world: ToolsWorld
93
97
  server: ThreadingHTTPServer | None
94
98
  _scratch: str
95
- #: The routes connector.toml declares, over the session's store, when the
96
- #: world has any: :meth:`call` answers an operation by name through them.
99
+ calls: CallLog
97
100
  app: WorldApp | None = None
98
- #: The credential the app takes: the pin a local serve is opened with.
99
101
  api_key: str | None = PIN
100
- #: The static ui connector.toml's ``[ui]`` declares, when the server serves one.
102
+ #: The key to this session's ``/__world/*`` routes, minted when it opened.
103
+ admin: AdminToken = field(default_factory=AdminToken)
101
104
  ui: UiSurface | None = None
102
- #: The ui's own origin: the page at ``/`` and its ``api_path`` beside it,
103
- #: the layout the World Host gives a session's ui, so a frontend built for
104
- #: the root (absolute ``/assets/…`` urls, a client-side router) runs here
105
- #: unchanged. ``/__ui/`` on :attr:`server` stays for the generated page.
105
+ #: The ui on its own origin, as the World Host lays it out, so a frontend built for the root runs unchanged.
106
106
  ui_server: ThreadingHTTPServer | None = None
107
- #: Set once ``POST /__session/close`` was answered: the opener's cue to :meth:`close`.
108
107
  closing: threading.Event = field(default_factory=threading.Event)
109
- #: Set by the opener's parent watch when the process that started the serve is
110
- #: gone; ``closing`` is set with it, so :meth:`wait` returns.
108
+ #: Set with ``closing`` when the opener's process is gone, so :meth:`wait` returns.
111
109
  orphaned: threading.Event = field(default_factory=threading.Event)
112
110
 
113
111
  @property
@@ -148,15 +146,15 @@ class LocalSession:
148
146
  return task_card(self.world)
149
147
 
150
148
  def call(self, tool: str, args: dict[str, Any]) -> dict:
151
- """The tool's ``{status, body}``, a route's when ``tool`` names an
152
- operation of connector.toml; a refusal is a 400 answer, not an error."""
149
+ """The tool's ``{status, body}``; a refusal (a route's name, an unknown
150
+ tool, one outside the task's list) is a 400 answer, not an error."""
153
151
  try:
154
- return call_served(self.world, self.app, tool, args, api_key=self.api_key)
152
+ return self.world.call(tool, args)
155
153
  except ContractError as error:
156
154
  return refusal(error)
157
155
 
158
156
  def state(self) -> dict:
159
- return self.world.state()
157
+ return self.calls.into_state(self.world.state())
160
158
 
161
159
  def grade(self) -> dict:
162
160
  return self.world.grade()
@@ -167,12 +165,6 @@ class LocalSession:
167
165
  def seed(self, args: dict) -> dict:
168
166
  return self.world.seed(args)
169
167
 
170
- def export(self, destination: Path) -> Path:
171
- return self.world.export(destination)
172
-
173
- def restore(self, source: Path) -> None:
174
- self.world.restore(source)
175
-
176
168
  def close(self) -> None:
177
169
  self.closing.set()
178
170
  for server in (self.server, self.ui_server):
@@ -222,16 +214,23 @@ def open_world(
222
214
  root = Path(root)
223
215
  scratch = tempfile.mkdtemp(prefix="gateway-local-")
224
216
  closing = threading.Event()
217
+ admin = AdminToken.mint()
225
218
  try:
226
- version = load_local_version(root, Path(scratch) / "version", require_tasks=False)
219
+ version = load_local_version(root, Path(scratch) / "version")
227
220
  dependencies = load_local_dependencies(root, version, Path(scratch) / "version")
228
221
  if task is not None and task not in version.tasks:
229
222
  fail(
230
223
  "task",
231
224
  f"no task '{task}' in {root.name}; it has {', '.join(sorted(version.tasks)) or 'none'}",
232
225
  )
226
+ spec = load_spec(root) if has_http(root) else None
227
+ calls = CallLog.for_spec(spec) if spec is not None else CallLog()
233
228
  world = ToolsWorld(
234
- version, Path(scratch) / "session", task if task is not None else LOCAL_TASK, dependencies=dependencies
229
+ version,
230
+ Path(scratch) / "session",
231
+ task if task is not None else LOCAL_TASK,
232
+ dependencies=dependencies,
233
+ calls=calls,
235
234
  )
236
235
  try:
237
236
  if scenario is not None:
@@ -240,20 +239,21 @@ def open_world(
240
239
  ui_server = None
241
240
  ui = None
242
241
  app = None
243
- if has_http(root):
244
- spec = load_spec(root)
242
+ if spec is not None:
245
243
  settings = load_api_settings(root, spec)
246
- app = WorldApp(ToolsWorldState(world, root), Router(spec, settings), api_key)
244
+ app = WorldApp(ToolsWorldState(world, root), Router(spec, settings), api_key, calls=calls, admin=admin)
247
245
  if http:
248
246
  if app is not None:
249
247
  ui = load_ui_surface(root)
250
- server = bind_server(host, port, make_session_handler(world, app, closing, ui=ui, api_key=api_key))
248
+ server = bind_server(
249
+ host, port, make_session_handler(world, app, calls, closing, ui=ui, api_key=api_key)
250
+ )
251
251
  threading.Thread(target=server.serve_forever, daemon=True).start()
252
252
  if ui is not None:
253
253
  ui_server = bind_server(
254
254
  host,
255
255
  ui_port if ui_port is not None else (port + 1 if port else 0),
256
- make_session_handler(world, app, closing, ui=ui, api_key=api_key, ui_origin=True),
256
+ make_session_handler(world, app, calls, closing, ui=ui, api_key=api_key, ui_origin=True),
257
257
  )
258
258
  threading.Thread(target=ui_server.serve_forever, daemon=True).start()
259
259
  except BaseException:
@@ -267,8 +267,10 @@ def open_world(
267
267
  world=world,
268
268
  server=server,
269
269
  _scratch=scratch,
270
+ calls=calls,
270
271
  app=app,
271
272
  api_key=api_key,
273
+ admin=admin,
272
274
  closing=closing,
273
275
  ui=ui,
274
276
  ui_server=ui_server,
@@ -301,9 +303,8 @@ def port_owner(port: int) -> str | None:
301
303
 
302
304
  def bind_server(host: str, port: int, handler: type[BaseHTTPRequestHandler]) -> ThreadingHTTPServer:
303
305
  """The session's server on ``host:port``, or a refusal that NAMES the port and,
304
- when it can, who holds it. A bare ``Address already in use`` from a backgrounded
305
- serve went unread, and every curl after it hit whatever else answered there
306
- (CRM dogfood, 2026-09-16); this serve never answers from another server."""
306
+ when it can, who holds it: a bare ``Address already in use`` from a backgrounded
307
+ serve goes unread while every curl after it reaches whatever else answers there."""
307
308
  try:
308
309
  return ThreadingHTTPServer((host, port), handler)
309
310
  except OSError as error:
@@ -318,17 +319,14 @@ def bind_server(host: str, port: int, handler: type[BaseHTTPRequestHandler]) ->
318
319
 
319
320
 
320
321
  SESSION_PREFIX = "/__session/"
321
- #: Where the session's port mounts the world's static ui beside the routes,
322
- #: for the generated page (relative asset urls, `./app.js`). The host serves
323
- #: a ui on its own origin, and so does the session's second listener
324
- #: (:func:`open_world` ``ui_port``): the page at ``/``, its ``api_path``
325
- #: beside it, so a frontend built for the root works in both places.
322
+ #: The generated page's mount on the session port; a built ui gets its own origin, as on the host.
326
323
  UI_PREFIX = "/__ui/"
327
324
 
328
325
 
329
326
  def make_session_handler(
330
327
  world: ToolsWorld,
331
328
  app: WorldApp | None,
329
+ calls: CallLog,
332
330
  closing: threading.Event | None = None,
333
331
  *,
334
332
  ui: UiSurface | None = None,
@@ -348,9 +346,7 @@ def make_session_handler(
348
346
  falls back to ``index.html``, for a client-side router) and its
349
347
  ``api_path`` prefix answered with the pin — nothing else, as on the host."""
350
348
  closing = closing if closing is not None else threading.Event()
351
- # The page's calls and a `/__session/call` of an operation are presented
352
- # as a granted client, as the host presents them; the world's own token
353
- # dance stays available beside.
349
+ # Page calls go in as a granted client, as on the host, or an oauth2 world refuses them.
354
350
  grant = client_grant(app, api_key)
355
351
 
356
352
  def close() -> dict:
@@ -363,22 +359,18 @@ def make_session_handler(
363
359
  return world.seed({"rows": rows, "mode": mode})
364
360
 
365
361
  def grade(report: str | None = None, context: dict | None = None) -> dict:
366
- # The local session grades by the world's own verifiers; an agent's
367
- # report and the other worlds' evidence are read by a session task's
368
- # graders, which only the host runs.
362
+ # Only the host runs a session task's graders, which read the report and the other worlds' evidence.
369
363
  return world.grade()
370
364
 
371
- # The session protocol (:data:`verbs.SESSION_VERBS`) bound to this
372
- # session's operations, by route; the host binds the same rows to its own.
373
365
  operations: dict[str, Callable[..., dict]] = {
374
366
  "GET tools": lambda: {"tools": list(world.served)},
375
367
  "GET task": lambda: task_card(world),
376
- "GET state": world.state,
377
- "GET evidence": world.grader_state,
368
+ "GET state": lambda: calls.into_state(world.state()),
369
+ "GET evidence": lambda: calls.into_state(world.grader_state()),
378
370
  "POST grade": grade,
379
371
  "POST reset": world.reset,
380
372
  "POST seed": seed,
381
- "POST call": lambda tool, args: call_served(world, app, tool, args, api_key=api_key, grant=grant),
373
+ "POST call": world.call,
382
374
  "POST close": close,
383
375
  }
384
376
 
@@ -503,25 +495,6 @@ def _local_origin(origin: str) -> bool:
503
495
  return host in ("127.0.0.1", "localhost", "::1")
504
496
 
505
497
 
506
- def call_served(
507
- world: ToolsWorld,
508
- app: WorldApp | None,
509
- tool: str,
510
- args: dict,
511
- *,
512
- api_key: str | None = PIN,
513
- grant: str | None = None,
514
- ) -> dict:
515
- """One name of what the session serves, answered as the World Host answers
516
- it: a tool by name (a dependency's as ``alias.tool``); on a tree with
517
- connector.toml, an operation by name too, answered by its route over the
518
- same store, ``{status, body}`` the route's own. A name that is both is the
519
- tool's."""
520
- if app is not None and tool not in world.version.tool_names and tool in app.router.spec.operations:
521
- return call_operation(app, tool, args, api_key or "", allowed=world.allowed, grant=grant)
522
- return world.call(tool, args)
523
-
524
-
525
498
  def _apply_scenario(world: ToolsWorld, root: Path, name: str) -> None:
526
499
  scenarios = snapshots.scenario_dirs(root)
527
500
  if name not in scenarios:
@@ -57,6 +57,7 @@ from pathlib import Path
57
57
  from typing import Any, Iterable
58
58
 
59
59
  from .._toml import tomllib
60
+ from .primary_key import PrimaryKey
60
61
  from .transforms import apply_transforms, parse_transform
61
62
  from .validation import ContractError, fail
62
63
 
@@ -82,9 +83,6 @@ _SOURCE_REF = re.compile(r"^trace:([^/]+)/(.+)$")
82
83
  MISSING: Any = object()
83
84
 
84
85
 
85
- # ---------------------------------------------------------------- paths
86
-
87
-
88
86
  def parse_path(text: str, location: str) -> tuple[Any, ...]:
89
87
  """A path as segments: a key, an integer index, or ``"*"`` for a fan-out.
90
88
 
@@ -165,9 +163,6 @@ def resolve(segments: tuple[Any, ...], scope: Scope) -> tuple[Any, bool]:
165
163
  return _walk(scope.item, segments)
166
164
 
167
165
 
168
- # ---------------------------------------------------------------- the grammar
169
-
170
-
171
166
  @dataclass(frozen=True)
172
167
  class Field:
173
168
  name: str
@@ -400,9 +395,6 @@ def parse_mapping(raw: str | dict, where: str = FILE) -> Mapping:
400
395
  return Mapping(sources=sources, on_conflict=on_conflict, unmatched=unmatched)
401
396
 
402
397
 
403
- # ---------------------------------------------------------------- the contract
404
-
405
-
406
398
  Entities = dict[str, dict]
407
399
 
408
400
 
@@ -465,9 +457,6 @@ def load_mapping(root: str | Path, path: str | Path | None = None) -> Mapping |
465
457
  return parse_mapping(file.read_text(encoding="utf-8"), file.name)
466
458
 
467
459
 
468
- # ---------------------------------------------------------------- values
469
-
470
-
471
460
  def _instant(value: Any) -> datetime | None:
472
461
  if not isinstance(value, str) or not value.strip():
473
462
  return None
@@ -560,9 +549,6 @@ def _holds(source: Source, scope: Scope) -> bool:
560
549
  return True
561
550
 
562
551
 
563
- # ---------------------------------------------------------------- the report
564
-
565
-
566
552
  class _SourceReport:
567
553
  def __init__(self, source: Source, entities: Entities) -> None:
568
554
  self.source = source
@@ -619,9 +605,6 @@ def sample(value: Any) -> str:
619
605
  return text if len(text) <= SAMPLE_WIDTH else text[: SAMPLE_WIDTH - 1] + "…"
620
606
 
621
607
 
622
- # ---------------------------------------------------------------- the rows
623
-
624
-
625
608
  def record_meta(record: dict, index: int) -> dict[str, Any]:
626
609
  source = record.get("source")
627
610
  ref = _SOURCE_REF.match(source) if isinstance(source, str) else None
@@ -649,12 +632,12 @@ class _Held:
649
632
  def put(self, entity: str, row: dict, at: datetime | None) -> None:
650
633
  self.sequence += 1
651
634
  order = (at or datetime.min.replace(tzinfo=timezone.utc), self.sequence)
652
- keys = self.entities[entity].get("primary_key", [])
635
+ identity = PrimaryKey.of(self.entities[entity]).identity(row)
653
636
  listed = self.rows.setdefault(entity, [])
654
- if not keys or any(k not in row for k in keys):
655
- listed.append((order, row)) # the import refuses it, naming the missing key field
637
+ if identity is None:
638
+ listed.append((order, row))
656
639
  return
657
- key = (entity, tuple(json.dumps(row[k], sort_keys=True) for k in keys))
640
+ key = (entity, identity)
658
641
  held = self.index.get(key)
659
642
  if held is None:
660
643
  self.index[key] = len(listed)
@@ -815,9 +798,6 @@ def apply_mapping(mapping: Mapping, records: Iterable[Any], entities: Entities)
815
798
  return rows, report
816
799
 
817
800
 
818
- # ---------------------------------------------------------------- map init
819
-
820
-
821
801
  def _shape(value: Any) -> str:
822
802
  if isinstance(value, dict):
823
803
  return "an object"