@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
@@ -1,46 +1,11 @@
1
- """A schema world's tools on the World Host.
2
-
3
- A schema-backed mock-tools bundle (``gateway-env.toml`` with ``[schema]`` at its
4
- root, ``tools/*.py`` handlers, ``verifiers/*.sql``) is reached through the
5
- ``tools`` surface, the platform's ``call``/``grade``/``reset``/``seed``
6
- rendezvous. On the pod engine that rendezvous is a runner sidecar and
7
- ``deploy/benchmark-runner/engines/schema_session.py``; on the host it is this
8
- module, driven by :class:`~gatewaysdk.environment.schema.host.WorldHost`.
9
-
10
- ONE SESSION, BOTH SURFACES. When the tree also carries ``connector.toml`` — the
11
- routes the served vendor API answers — the same session serves its HTTP surface
12
- too: :class:`ToolsWorldState` presents the :class:`ToolsWorld`'s store to the
13
- api runtime's :class:`~gatewaysdk.environment.schema.api.WorldApp`, so a row a
14
- tool writes is the row a route lists, and a route's create is what the SQL
15
- verifiers grade. This is the schema world stored as itself (the supported
16
- shape), not packaged as an api bundle; nothing has to be packaged to get HTTP.
17
-
18
- The session contract is the runner's: ``call`` executes a handler through the
19
- schema contract, ``grade`` runs the task's verifiers, ``reset`` copies the
20
- template back and re-arms the task context, ``seed`` lands rows through the
21
- contract. The handlers are world-authored code, so a tools version always
22
- lives in a version worker; the supervisor only detects the kind.
23
-
24
- DEPENDENCY WORLDS. A world whose manifest declares ``[dependencies]``
25
- (:mod:`dependencies`) opens beside them: one :class:`ToolsWorld` holds the
26
- root world and one isolated store per dependency, each under its alias. A
27
- dependency's tools are served as ``<alias>.<tool>`` (Relay calls
28
- ``slack.post_message`` and ``list_messages`` from one session), its verifiers
29
- grade as ``<alias>/<verifier>``, its rows are reported under
30
- ``worlds.<alias>`` and seeded as ``<alias>.<entity>``. The root's verifiers
31
- read every dependency's store as ``<alias>.<table>`` (attached read-only), so
32
- a cross-world check — the WhatsApp escalation that must land a Slack message —
33
- is one SQL file in the root world. A dependency's ``task`` names the scenario
34
- it starts in (``scenarios/<task>/`` of its tree): the overlay is laid on the
35
- dependency's template at open and again at reset, as ``--scenario`` lays the
36
- root's.
37
- """
1
+ """Twin of deploy/benchmark-runner/engines/schema_session.py: the runner's session contract on the World Host."""
38
2
 
39
3
  from __future__ import annotations
40
4
 
41
5
  import json
42
6
  import shutil
43
7
  import threading
8
+ import time
44
9
  import uuid
45
10
  from collections.abc import Callable
46
11
  from dataclasses import dataclass, field
@@ -48,60 +13,48 @@ from pathlib import Path
48
13
  from typing import Any
49
14
 
50
15
  from .. import _bundle
51
- from .._materialize import materialize_template
52
16
  from .._toml import tomllib
53
- from .._world import World
54
- from ..errors import WorldStartError
17
+ from .._world import VerifierResult, World
18
+ from ..errors import VerifierError, WorldStartError
55
19
  from ..world import World as WorldDetector
56
20
  from . import snapshot as snapshots
57
21
  from .api import ApiSettings, WorldState, load_api_settings
58
22
  from .api import load_handlers as load_api_handlers
23
+ from .call_log import CallLog
59
24
  from .compiler import ContractError, bundle_mode, check_bundle, fail
60
25
  from .connector import SPEC, Spec, load_spec
61
26
  from .data import seed_batch
27
+ from .database import WorldDatabase
62
28
  from .dependencies import Dependency, parse_dependencies
63
29
  from .grading import Grade, world_state
64
- from .handler_errors import HANDLER_BUG_ERRORS, engine_failure_body, handler_bug_body
30
+ from .handler_errors import failure_answer
31
+ from .journal import LINKED_JOURNAL, WorldJournal
32
+ from .route_bindings import RouteBindings
33
+ from .served_names import ServedNames
34
+ from .session_files import ProvenTemplate, SessionExport, real_dir
65
35
  from .tasks import TaskSpec
66
36
 
67
37
  Handler = Callable[..., Any]
68
38
 
69
- #: The reward key the scalar goes under; a verifier may not claim it.
70
39
  REWARD = "reward"
71
- #: The opt-in table a bundle declares to read the active task from SQL.
72
- TASK_CONTEXT_TABLE = "benchmark_runtime_context"
40
+ SESSION_WORLD = "session"
73
41
 
74
42
 
75
43
  @dataclass(frozen=True)
76
44
  class ToolsTask:
77
- """One task of a mock-tools bundle: the prompt and the checks that grade it.
78
- Mirrors the runner's ``MockTask`` minus the user-simulation fields, which
79
- a session does not run."""
45
+ """Mirrors the runner's ``MockTask`` minus the user-simulation fields, which a session does not run."""
80
46
 
81
47
  id: str
82
48
  prompt: str
83
49
  verifier: str | None = None
84
50
  verifiers: tuple[str, ...] = ()
85
51
  metadata: dict[str, Any] = field(default_factory=dict)
86
- #: Dependency verifiers the task grades with, by alias (``"worlds": {"slack":
87
- #: ["message_posted"]}``). An alias absent here grades with none of its
88
- #: verifiers; ``None`` (a task that names no worlds) grades with all of every
89
- #: dependency's, the way it grades with all of the root's.
90
52
  worlds: dict[str, tuple[str, ...]] | None = None
91
- #: An authored ``scenarios/<id>/`` task: its seed overlay replaces whole
92
- #: entities of the template at open and reset (None: the template alone).
93
53
  scenario: dict[str, list] | None = None
94
- #: The scenario's ``checks/verify.py``, when it grades by one instead of
95
- #: the world's SQL verifiers (the runtime's :class:`TaskGrader` runs it).
96
54
  verify: Path | None = None
97
- #: Whether the world's verifiers grade this task at all. A bundled task's
98
- #: do (all of them when it names none); a session task's never do — it
99
- #: grades by its own grader or is ungraded (the platform's ``no grader``).
100
55
  graded_by_world: bool = True
101
56
 
102
57
  def selected(self, all_verifiers: list[str]) -> list[str]:
103
- """The verifiers this task grades with: its own list, else the
104
- primary one, else every verifier the bundle ships."""
105
58
  if not self.graded_by_world:
106
59
  return []
107
60
  if self.verifiers:
@@ -111,7 +64,6 @@ class ToolsTask:
111
64
  return list(all_verifiers)
112
65
 
113
66
  def selected_of(self, alias: str, all_verifiers: list[str]) -> list[str]:
114
- """The verifiers of dependency ``alias`` this task grades with."""
115
67
  if not self.graded_by_world:
116
68
  return []
117
69
  if self.worlds is None:
@@ -119,17 +71,11 @@ class ToolsTask:
119
71
  return list(self.worlds.get(alias, ()))
120
72
 
121
73
 
122
- #: The id a session task takes when its spec names none.
123
74
  INLINE_TASK_ID = "session"
124
75
 
125
76
 
126
77
  def inline_task(spec: TaskSpec) -> ToolsTask:
127
- """A session task (:mod:`tasks`) as a schema-world task: the spec's
128
- instruction as the prompt. It grades by its own grader (assertions,
129
- python, rubric) the way an api world's session task does, over
130
- :meth:`ToolsWorld.grader_state`; without one it is ungraded — the
131
- bundle's verifiers were written for the bundle's tasks, not this one.
132
- The seed is applied by :class:`ToolsWorld` once the template copy exists."""
78
+ """Never graded by the bundle's verifiers: they were written for the bundle's tasks, not this one."""
133
79
  return ToolsTask(
134
80
  id=spec.name or INLINE_TASK_ID, prompt=spec.instruction, metadata=dict(spec.metadata), graded_by_world=False
135
81
  )
@@ -137,43 +83,28 @@ def inline_task(spec: TaskSpec) -> ToolsTask:
137
83
 
138
84
  @dataclass
139
85
  class ToolsVersion:
140
- """A mock-tools version as the host caches it: the bundle, its tasks and
141
- verifiers, the materialized template every session copies, and (in a
142
- worker) the loaded handlers."""
143
-
144
86
  bundle: Path
145
87
  manifest: _bundle.EnvManifest
146
88
  verifiers: list[str]
147
89
  tasks: dict[str, ToolsTask]
148
- template: Path
149
- #: The tools the version serves, by name: the loaded handlers' in a
150
- #: worker, the contract's in the supervisor (which imports no handler but
151
- #: still checks a session task's allow-list against what is served).
90
+ template: ProvenTemplate
91
+ engine: type[WorldDatabase]
92
+ #: The handlers' names in a worker, the contract's in the supervisor, which imports no world-authored code.
152
93
  tool_names: list[str] = field(default_factory=list)
153
94
  handlers: dict[str, Handler] | None = None
154
- #: The HTTP surface, when the tree carries ``connector.toml``: the routes
155
- #: and their served-API settings, and (in a worker) the ``api/handlers.py``
156
- #: module they name. None for a tree with tools only.
157
95
  spec: Spec | None = None
158
96
  settings: ApiSettings | None = None
159
97
  api_handlers: dict[str, Handler] | None = None
160
- #: The manifest's ``[dependencies]``, by alias; ``{}`` for a world of its own.
161
98
  dependencies: dict[str, Dependency] = field(default_factory=dict)
99
+ read_fields: list[tuple[str, tuple[str, ...]]] = field(default_factory=list)
162
100
 
163
101
  @property
164
102
  def served_names(self) -> list[str]:
165
- """Everything a session task may allow: the tools and the operations."""
166
- operations = list(self.spec.operations) if self.spec is not None else []
167
- return sorted(set(self.tool_names) | set(operations))
103
+ return sorted(self.tool_names)
168
104
 
169
105
 
170
106
  @dataclass(frozen=True)
171
107
  class DependencyWorld:
172
- """A dependency as a session opens it: the alias the root's manifest gave
173
- it, its cached version, the tools of it this session serves (the
174
- manifest's ``tools`` allow-list, else every tool the version has), and the
175
- seed overlay of the scenario its ``task`` names (None: its template alone)."""
176
-
177
108
  alias: str
178
109
  version: ToolsVersion
179
110
  tools: tuple[str, ...]
@@ -210,9 +141,6 @@ class DependencyWorld:
210
141
 
211
142
 
212
143
  def served_with_dependencies(version: ToolsVersion, dependencies: dict[str, DependencyWorld]) -> list[str]:
213
- """Every name a session on ``version`` beside ``dependencies`` serves: the
214
- root's tools and operations, and ``<alias>.<tool>`` for each dependency.
215
- Refuses a root tool that reads as a dependency's (``slack.post_message``)."""
216
144
  declared = set(version.dependencies)
217
145
  missing = declared - set(dependencies)
218
146
  if missing:
@@ -231,8 +159,6 @@ def served_with_dependencies(version: ToolsVersion, dependencies: dict[str, Depe
231
159
 
232
160
 
233
161
  def is_tools_bundle(bundle: Path) -> bool:
234
- """The tree runs on the tools engine (a schema or legacy tools world stored
235
- as itself; an api bundle does not)."""
236
162
  return WorldDetector.from_dir(bundle).tools_engine
237
163
 
238
164
 
@@ -279,9 +205,6 @@ def _tasks_from_rows(rows: list) -> list[ToolsTask]:
279
205
 
280
206
 
281
207
  def _scenario_task(name: str, scenario: Path) -> ToolsTask:
282
- """A task from an authored scenario dir (what an api bundle carried and
283
- ``worlds migrate`` keeps): ``instruction.md`` or the toml's ``instruction``
284
- is the prompt, ``seed/*.json`` the overlay, ``checks/verify.py`` the grader."""
285
208
  table = tomllib.loads((scenario / "scenario.toml").read_text(encoding="utf-8"))
286
209
  instruction = scenario / "instruction.md"
287
210
  prompt = instruction.read_text(encoding="utf-8") if instruction.is_file() else str(table.get("instruction") or "")
@@ -296,19 +219,11 @@ def _scenario_task(name: str, scenario: Path) -> ToolsTask:
296
219
 
297
220
 
298
221
  def scenario_tasks(bundle: Path) -> list[ToolsTask]:
299
- """One task per ``scenarios/<name>/scenario.toml`` of the tree."""
300
222
  return [_scenario_task(name, path) for name, path in snapshots.scenario_dirs(bundle).items()]
301
223
 
302
224
 
303
- def load_tasks(
304
- bundle: Path, manifest: _bundle.EnvManifest, verifiers: list[str], *, required: bool = True
305
- ) -> dict[str, ToolsTask]:
306
- """The bundle's tasks, in the runner's precedence: ``[[tasks]]`` in the
307
- manifest, else ``tasks.jsonl`` / ``tasks.json``, else one task per
308
- verifier; plus one per authored ``scenarios/<name>/`` the declared tasks
309
- do not already name. A bundle with none has nothing to grade and is
310
- refused when ``required`` (the host opens it to grade); a local session
311
- that only calls tools opens it with none."""
225
+ def load_tasks(bundle: Path, manifest: _bundle.EnvManifest, verifiers: list[str]) -> dict[str, ToolsTask]:
226
+ """In the runner's precedence, so a bundle opens with the same tasks on the host as on the runner."""
312
227
  declared = manifest.raw.get("tasks")
313
228
  tasks = _tasks_from_rows(declared) if isinstance(declared, list) else []
314
229
  if not tasks:
@@ -341,11 +256,6 @@ def load_tasks(
341
256
  by_id[task.id] = task
342
257
  for task in scenario_tasks(bundle):
343
258
  by_id.setdefault(task.id, task)
344
- if not by_id and required:
345
- fail(
346
- "host",
347
- "mock-tools bundle declares no tasks and ships no verifiers/*.sql: nothing to grade",
348
- )
349
259
  return by_id
350
260
 
351
261
 
@@ -355,10 +265,7 @@ def load_tools_version(
355
265
  snapshot: dict[str, str] | None,
356
266
  *,
357
267
  run_handlers: bool,
358
- require_tasks: bool = True,
359
268
  ) -> ToolsVersion:
360
- """Cache a mock-tools version: verify and pin its snapshot, materialize the
361
- template once, read its tasks, and in a worker import its handlers."""
362
269
  if not is_tools_bundle(bundle):
363
270
  fail("host", f"{bundle} is not a mock-tools bundle (no gateway-env.toml)")
364
271
  manifest = _bundle.parse_manifest(bundle)
@@ -373,12 +280,17 @@ def load_tools_version(
373
280
  contract = check_bundle(bundle)
374
281
  if snapshot:
375
282
  snapshots.fetch(bundle, contract, snapshot["url"], snapshot["sha256"], snapshot["digest"])
376
- if not template.is_file():
377
- materialize_template(bundle, template, require_sql=True)
283
+ # connector.toml is read as the api runtime reads it, so an unservable route is refused at cache time.
284
+ spec = settings = None
285
+ if (bundle / SPEC).is_file():
286
+ spec = load_spec(bundle)
287
+ settings = load_api_settings(bundle, spec)
288
+ read_fields = RouteBindings.served(spec, settings, contract)
289
+ proven = ProvenTemplate.prove(bundle, template, contract, fetched=bool(snapshot), read_fields=read_fields)
378
290
  verifiers = verifier_names(bundle)
379
291
  if REWARD in verifiers:
380
292
  fail("host", f"verifier name '{REWARD}' is reserved for the scalar grade")
381
- tasks = load_tasks(bundle, manifest, verifiers, required=require_tasks)
293
+ tasks = load_tasks(bundle, manifest, verifiers)
382
294
  for task in tasks.values():
383
295
  unknown = set(task.selected(verifiers)) - set(verifiers)
384
296
  if unknown:
@@ -395,38 +307,30 @@ def load_tools_version(
395
307
  handlers = _bundle.load_handlers(bundle, manifest)
396
308
  except WorldStartError as error:
397
309
  fail("host", str(error))
398
- # The HTTP surface rides the same tree: connector.toml is read the way the
399
- # api runtime reads it for a bundle, so a route that would not serve there
400
- # is refused here, at cache time, not at the first request.
401
- spec = settings = api_handlers = None
402
- if (bundle / SPEC).is_file():
403
- spec = load_spec(bundle)
404
- settings = load_api_settings(bundle, spec)
405
- if run_handlers and settings.handlers is not None:
406
- api_handlers = load_api_handlers(settings)
310
+ api_handlers = None
311
+ if run_handlers and settings is not None and settings.handlers is not None:
312
+ api_handlers = load_api_handlers(settings)
407
313
  return ToolsVersion(
408
314
  bundle=bundle,
409
315
  manifest=manifest,
410
316
  verifiers=verifiers,
411
317
  tasks=tasks,
412
- template=template,
318
+ template=proven,
319
+ engine=WorldDatabase.for_contract(contract),
413
320
  tool_names=sorted(handlers) if handlers is not None else sorted(contract.tools),
414
321
  handlers=handlers,
415
322
  spec=spec,
416
323
  settings=settings,
417
324
  api_handlers=api_handlers,
418
325
  dependencies=dependencies,
326
+ read_fields=read_fields,
419
327
  )
420
328
 
421
329
 
422
330
  class _EnvHost:
423
- """What :class:`World` reads of an ``Environment``: the template, a scratch
424
- dir, the handlers, the bundle path, and always-``env`` routing."""
425
-
426
331
  def __init__(self, version: ToolsVersion, worlds_dir: Path) -> None:
427
332
  self.bundle_path = version.bundle
428
333
  self._worlds_dir = worlds_dir
429
- self._template_db = version.template
430
334
  self._handlers = version.handlers or {}
431
335
 
432
336
  def resolve_route(self, tool_name: str) -> str:
@@ -437,20 +341,6 @@ class _EnvHost:
437
341
 
438
342
 
439
343
  class ToolsWorld:
440
- """One session of a mock-tools version: a copy of the template in the
441
- session's own directory, executed through the bundle's handlers.
442
-
443
- ``task`` is the id of a task the bundle carries, or a :class:`ToolsTask`
444
- of the session's own (:func:`inline_task`). A session task may bring a
445
- ``seed`` (the spec's, ``{mode, rows}``), laid on the template copy at open
446
- and again on every reset — the way the host lays an api task's seed on
447
- its clone — and an ``allowed`` tool list, which ``call`` holds to.
448
-
449
- ``dependencies`` are the worlds the version's manifest declares, one
450
- :class:`DependencyWorld` per alias, every one of them required: each gets
451
- its own template copy under the session directory, and the root's store
452
- reads each as ``<alias>.<table>``."""
453
-
454
344
  def __init__(
455
345
  self,
456
346
  version: ToolsVersion,
@@ -460,22 +350,17 @@ class ToolsWorld:
460
350
  seed: dict | None = None,
461
351
  allowed: frozenset[str] | None = None,
462
352
  dependencies: dict[str, DependencyWorld] | None = None,
353
+ calls: CallLog | None = None,
463
354
  ) -> None:
464
355
  if version.handlers is None:
465
356
  fail("host", "a mock-tools session runs world-authored handlers; only a version worker opens one")
466
357
  for dep in (dependencies or {}).values():
467
358
  if dep.version.handlers is None:
468
359
  fail("host", f"dependency '{dep.alias}' has no handlers loaded; only a version worker opens one")
469
- if isinstance(task, ToolsTask):
470
- selected = task
471
- else:
472
- selected = version.tasks.get(task)
473
- if selected is None:
474
- fail("host", f"no task '{task}' in this world; it has {', '.join(sorted(version.tasks))}")
475
- raise AssertionError # fail() never returns
476
360
  self.version = version
477
- self.task = selected
361
+ self.task = self._task_of(version, task)
478
362
  self.allowed = allowed
363
+ self.calls = calls
479
364
  self.dependencies = dict(dependencies or {})
480
365
  self.served = served_with_dependencies(version, self.dependencies)
481
366
  self._task_seed = seed
@@ -483,59 +368,65 @@ class ToolsWorld:
483
368
  self._dir.mkdir(parents=True, exist_ok=True)
484
369
  self.worlds: dict[str, World] = {}
485
370
  try:
486
- self.world = World(_EnvHost(version, self._dir), world_id=uuid.uuid4().hex) # type: ignore[arg-type]
371
+ self.world = self._open_world(version, self._dir)
487
372
  for alias, dep in self.dependencies.items():
488
373
  dep_dir = self._dir / "worlds" / alias
489
374
  dep_dir.mkdir(parents=True, exist_ok=True)
490
- self.worlds[alias] = World(_EnvHost(dep.version, dep_dir), world_id=uuid.uuid4().hex) # type: ignore[arg-type]
375
+ self.worlds[alias] = self._open_world(dep.version, dep_dir)
491
376
  self._arm()
492
377
  self._apply_dependency_scenarios()
493
378
  self._apply_task_seed()
494
379
  except BaseException:
495
- # A seed the contract refuses is the open's failure, not a leaked
496
- # copy: the session directory goes with the world.
497
380
  self.close()
498
381
  raise
499
382
 
383
+ @staticmethod
384
+ def _task_of(version: ToolsVersion, task: str | ToolsTask) -> ToolsTask:
385
+ if isinstance(task, ToolsTask):
386
+ return task
387
+ selected = version.tasks.get(task)
388
+ if selected is None:
389
+ fail("host", f"no task '{task}' in this world; it has {', '.join(sorted(version.tasks)) or 'none'}")
390
+ return selected
391
+
392
+ @staticmethod
393
+ def _open_world(version: ToolsVersion, directory: Path) -> World:
394
+ host = _EnvHost(version, directory)
395
+ # _EnvHost is what a World reads of an Environment.
396
+ return World(host, world_id=SESSION_WORLD, template=version.template) # type: ignore[arg-type]
397
+
398
+ @staticmethod
399
+ def live_state(session_dir: Path) -> Path:
400
+ return World.database_file(session_dir, SESSION_WORLD)
401
+
402
+ @staticmethod
403
+ def dependency_states(session_dir: Path) -> dict[str, Path]:
404
+ """Each dependency's store, reached through no link (path confinement)."""
405
+ worlds = Path(session_dir) / "worlds"
406
+ homes = [alias for alias in sorted(worlds.glob("*")) if real_dir(alias)] if real_dir(worlds) else []
407
+ stores = {alias.name: World.database_file(alias, SESSION_WORLD) for alias in homes}
408
+ return {alias: store for alias, store in stores.items() if store.is_file() and not store.is_symlink()}
409
+
500
410
  def _apply_task_seed(self) -> None:
501
- """Start the session in its task's state: the template with the task's
502
- rows on top — a scenario task's overlay replacing whole entities, then
503
- the session task's seed. A task without either starts on the template."""
504
411
  if self.task.scenario is not None:
505
412
  self.seed({"rows": self.task.scenario, "mode": "replace"})
506
413
  if self._task_seed is not None:
507
414
  self.seed({"rows": self._task_seed["rows"], "mode": self._task_seed["mode"]})
508
415
 
509
416
  def _apply_dependency_scenarios(self) -> None:
510
- """Start each dependency in the scenario its ``task`` names: the overlay
511
- replaces whole entities on that dependency's template."""
512
417
  for alias, dep in self.dependencies.items():
513
418
  if dep.scenario:
514
419
  rows = {f"{alias}.{entity}": entity_rows for entity, entity_rows in dep.scenario.items()}
515
420
  self.seed({"rows": rows, "mode": "replace"})
516
421
 
517
422
  def _arm(self) -> None:
518
- """Write the active task into every world's opt-in context table, so
519
- SQL verifiers can key off the scenario without a tool that sets it, and
520
- attach each dependency's store to the root's for cross-world reads."""
521
423
  scenario_id = str(self.task.metadata.get("scenario_id") or self.task.id)
522
424
  for world in (self.world, *self.worlds.values()):
523
- conn = world._conn
524
- declared = conn.execute(
525
- "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", (TASK_CONTEXT_TABLE,)
526
- ).fetchall()
527
- if not declared:
528
- continue
529
- conn.execute(f"DELETE FROM {TASK_CONTEXT_TABLE}")
530
- conn.execute(
531
- f"INSERT INTO {TASK_CONTEXT_TABLE} (context_key, scenario_id) VALUES ('active_task', ?)",
532
- (scenario_id,),
533
- )
425
+ world.set_task_context(scenario_id)
534
426
  self._attach()
535
427
 
536
428
  def _attach(self) -> None:
537
- """Every dependency's file, readable from the root's connection as
538
- ``<alias>.<table>``. Redone after a reset or restore, which reconnect."""
429
+ """Redone after a reset or restore, which reconnect."""
539
430
  store = self.world.store
540
431
  if store is None:
541
432
  return
@@ -545,8 +436,6 @@ class ToolsWorld:
545
436
  store.attach(alias, world.db_path, world.contract.entities)
546
437
 
547
438
  def _route(self, tool: str) -> tuple[World, str]:
548
- """The world that serves ``tool`` and its name there: a dependency's by
549
- ``<alias>.<tool>``, else the root's."""
550
439
  alias, dot, local = tool.partition(".")
551
440
  if dot and alias in self.dependencies:
552
441
  dep = self.dependencies[alias]
@@ -554,52 +443,76 @@ class ToolsWorld:
554
443
  return self.worlds[alias], local
555
444
  elif tool in (self.version.handlers or {}):
556
445
  return self.world, tool
557
- known = ", ".join(self.served) or "(none)"
558
- fail("host", f"unknown tool '{tool}'; this world serves: {known}")
559
- raise AssertionError # fail() never returns
446
+ self.names.refuse(tool)
447
+
448
+ @property
449
+ def names(self) -> ServedNames:
450
+ return ServedNames.of(self.served, self.version.spec)
560
451
 
561
452
  def call(self, tool: str, args: dict) -> dict:
562
- """Run ``tool`` and answer as the handler's HTTP twin would: 200 with
563
- the result, 400 when the handler itself is wrong (a name, attribute or
564
- type error is the author's bug, never the engine's), 500 when anything
565
- else fails inside the handler. Both failure bodies are structured
566
- ``{error, detail, handler}`` — never a bare exception string."""
567
- world, local = self._route(tool)
453
+ """Answers as the handler's HTTP twin would; a contract refusal raised mid-call is logged as its 400."""
454
+ try:
455
+ world, local = self._admitted(tool)
456
+ except ContractError as refusal:
457
+ if self.calls is not None:
458
+ self.calls.refused_tool(tool, args, refusal.detail)
459
+ raise
460
+ started = time.monotonic()
461
+ status, body = 400, None
462
+ try:
463
+ status, body = self._run(world, local, args)
464
+ finally:
465
+ self._log(tool, args, status, body, time.monotonic() - started)
466
+ return {"status": status, "body": body}
467
+
468
+ def _admitted(self, tool: str) -> tuple[World, str]:
469
+ routed = self._route(tool)
568
470
  if self.allowed is not None and tool not in self.allowed:
569
471
  fail(
570
472
  "tool_not_allowed",
571
473
  f"tool '{tool}' is not allowed by this session's task; it allows: {', '.join(sorted(self.allowed))}",
572
474
  )
475
+ return routed
476
+
477
+ @staticmethod
478
+ def _run(world: World, local: str, args: dict) -> tuple[int, Any]:
573
479
  try:
574
- result = world.execute(local, args)
480
+ return 200, world.execute(local, args)
575
481
  except ContractError:
576
482
  raise
577
- except HANDLER_BUG_ERRORS as error:
578
- return {"status": 400, "body": handler_bug_body(local, error)}
579
483
  except Exception as error: # noqa: BLE001 - the handler's failure is the call's answer
580
- return {"status": 500, "body": engine_failure_body(local, error)}
581
- return {"status": 200, "body": result}
582
-
583
- def grade(self) -> dict:
584
- """The task's verifiers, the root's by name and each dependency's as
585
- ``<alias>/<name>``; ``reward`` is the primary verifier's score when the
586
- task names one, else the mean of the numeric scores — null when no
587
- verifier answered a number (never 0). A task no verifier grades is
588
- ungraded, with the reason."""
589
- rewards: dict[str, float | None] = {}
590
- for name in self.task.selected(self.version.verifiers):
591
- rewards[name] = self.world.verify(name).score
592
- for alias, dep in self.dependencies.items():
593
- for name in self.task.selected_of(alias, dep.version.verifiers):
594
- rewards[f"{alias}/{name}"] = self.worlds[alias].verify(name).score
595
- if not rewards:
484
+ return failure_answer(local, error)
485
+
486
+ def _log(self, tool: str, args: dict, status: int, body: Any, elapsed_s: float) -> None:
487
+ if self.calls is not None:
488
+ self.calls.record_tool(tool, args, status, body, elapsed_s)
489
+
490
+ def grade(self, journal: WorldJournal | None = None) -> dict:
491
+ """``reward`` is null when no verifier answered a number, never 0; a dependency's verifier that reads the
492
+ journal fails closed, as the journal is the root world's."""
493
+ try:
494
+ results = self._verifier_results(journal)
495
+ except VerifierError as error:
496
+ fail("verifier", str(error))
497
+ if not results:
596
498
  return Grade.ungraded().as_dict()
499
+ rewards = {name: result.score for name, result in results.items()}
597
500
  if self.task.verifier is not None and self.task.verifier in rewards:
598
501
  reward = rewards[self.task.verifier]
599
502
  else:
600
503
  numeric = [s for s in rewards.values() if isinstance(s, (int, float))]
601
504
  reward = sum(numeric) / len(numeric) if numeric else None
602
- return {REWARD: reward, "rewards": rewards}
505
+ reasons = {name: result.closed for name, result in results.items() if result.closed is not None}
506
+ return {REWARD: reward, "rewards": rewards, **({"reasons": reasons} if reasons else {})}
507
+
508
+ def _verifier_results(self, journal: WorldJournal | None) -> dict[str, VerifierResult]:
509
+ results: dict[str, VerifierResult] = {}
510
+ for name in self.task.selected(self.version.verifiers):
511
+ results[name] = self.world.verify(name, journal)
512
+ for alias, dep in self.dependencies.items():
513
+ for name in self.task.selected_of(alias, dep.version.verifiers):
514
+ results[f"{alias}/{name}"] = self.worlds[alias].verify(name, LINKED_JOURNAL)
515
+ return results
603
516
 
604
517
  def reset(self) -> dict:
605
518
  for world in self.worlds.values():
@@ -611,21 +524,25 @@ class ToolsWorld:
611
524
  return {"reset": True}
612
525
 
613
526
  def export(self, destination: Path) -> Path:
614
- """The session's state as one sqlite file, taken consistently. A
615
- session beside dependency worlds exports the root's state; theirs is
616
- not in the file, so a restore starts them from their templates."""
527
+ """Holds the root's state only, so a restore from it starts dependency worlds from their templates."""
617
528
  return self.world.snapshot(destination)
618
529
 
619
- def restore(self, source: Path) -> None:
620
- """Continue from a file :meth:`export` wrote."""
621
- for world in self.worlds.values():
622
- world.reset()
623
- self.world.restore(source)
530
+ def restore(self, export: SessionExport) -> None:
531
+ carried = export.worlds
532
+ for alias, world in self.worlds.items():
533
+ self._continue(world, carried.get(alias))
534
+ self.world.resume(export)
624
535
  self._arm()
536
+ if self.world.store is not None:
537
+ self.world.store.index_reads(self.version.read_fields)
538
+
539
+ @staticmethod
540
+ def _continue(world: World, export: SessionExport | None) -> None:
541
+ if export is None:
542
+ return world.reset()
543
+ world.resume(export)
625
544
 
626
545
  def _world_of(self, entity: str) -> tuple[World, str]:
627
- """The world an entity name of a seed addresses: ``<alias>.<entity>``
628
- is a dependency's, a bare name the root's."""
629
546
  alias, dot, local = entity.partition(".")
630
547
  if dot and alias in self.worlds:
631
548
  return self.worlds[alias], local
@@ -651,13 +568,13 @@ class ToolsWorld:
651
568
  store, contract = world.store, world.contract
652
569
  if store is None or contract is None:
653
570
  fail("host", "seed needs a schema-backed world (gateway-world/1); this bundle has none")
654
- raise AssertionError # fail() never returns
655
571
  batch = seed_batch(store, contract, local_rows, mode, batch_id=f"host-seed-{uuid.uuid4().hex}")
656
572
  applied = store.apply_batch(batch)
657
573
  seeded += applied.get("applied", sum(len(v) for v in local_rows.values()))
574
+ held = store.counts()
658
575
  for entity in local_rows:
659
576
  if entity in contract.entities:
660
- counts[f"{prefix}.{entity}" if prefix else entity] = len(store.list(entity))
577
+ counts[f"{prefix}.{entity}" if prefix else entity] = held[entity]
661
578
  return {"seeded": seeded, "mode": mode, "entity_counts": counts}
662
579
 
663
580
  @property
@@ -665,14 +582,12 @@ class ToolsWorld:
665
582
  return self._dir
666
583
 
667
584
  def state(self) -> dict:
668
- """The root's rows by entity, and under ``worlds`` each dependency's."""
669
585
  out: dict[str, Any] = {"entities": _entities_of(self.world)}
670
586
  if self.worlds:
671
587
  out["worlds"] = {alias: {"entities": _entities_of(world)} for alias, world in self.worlds.items()}
672
588
  return out
673
589
 
674
590
  def entity_names(self) -> list[str]:
675
- """Every entity name :meth:`grader_state` reports, rows or not."""
676
591
  names = list(self.world.contract.entities) if self.world.contract is not None else []
677
592
  for alias, world in self.worlds.items():
678
593
  if world.contract is not None:
@@ -680,7 +595,6 @@ class ToolsWorld:
680
595
  return names
681
596
 
682
597
  def grader_state(self) -> dict:
683
- """The rows as a session task's grader reads them (:func:`world_state`)."""
684
598
  return world_state(self.world, self.worlds)
685
599
 
686
600
  def close(self) -> None:
@@ -700,19 +614,11 @@ def _entities_of(world: World) -> dict[str, list]:
700
614
 
701
615
 
702
616
  class ToolsWorldState(WorldState):
703
- """The api runtime's view of a :class:`ToolsWorld`: the SAME store the tools
704
- write, presented through the :class:`~gatewaysdk.environment.schema.api.WorldState`
705
- interface :class:`~gatewaysdk.environment.schema.api.WorldApp` and its
706
- handlers read. Nothing is copied: ``store`` resolves to the world's live
707
- store on every access, so a reset or a restore that swaps the file
708
- underneath is seen at once. The state owns no store of its own — the
709
- :class:`ToolsWorld` opens and closes it — so ``close`` here is a no-op and
710
- ``reset`` is the world's (template plus the task's seed, the context table
711
- re-armed), never a snapshot clone."""
617
+ """The tools world's live store, resolved on every access so a reset or restore that swaps the file is seen at
618
+ once; the ToolsWorld opens and closes it, so ``close`` here is a no-op."""
712
619
 
713
620
  def __init__(self, tools: ToolsWorld, tree: Path) -> None:
714
- # Deliberately not ``super().__init__``: that opens a temporary store
715
- # from the tree's snapshot, and this state has the tools world's.
621
+ # Not super().__init__: that opens a store from the tree's snapshot, and this state reads the tools world's.
716
622
  self.world = tree
717
623
  self._tools = tools
718
624
  contract = tools.world.contract
@@ -720,13 +626,13 @@ class ToolsWorldState(WorldState):
720
626
  fail("host", "an http surface needs a schema-backed world (gateway-world/1); this bundle has none")
721
627
  self.contract = contract
722
628
  self._initial = None
723
- self._snapshot_path = snapshots.default_snapshot(tree)
629
+ self._snapshot_path = snapshots.default_snapshot(tree, contract)
724
630
  self.snapshot = None
725
- self._lock = threading.Lock()
631
+ self._lock = threading.RLock()
726
632
  self._clear_events()
727
633
 
728
634
  @property
729
- def store(self): # type: ignore[override]
635
+ def store(self): # type: ignore[override] # the tools world's live store, never one of its own
730
636
  return self._tools.world.store
731
637
 
732
638
  @store.setter
@@ -738,10 +644,8 @@ class ToolsWorldState(WorldState):
738
644
  self._clear_events()
739
645
 
740
646
  def seed(self, body: Any) -> dict:
741
- """The runner's legacy whole-state seed, over the template: the named
742
- entities hold exactly the rows given (a replace), the rest keep the
743
- template's. An overlay body is refused as it is on any world without a
744
- snapshot digest (``base_mismatch``)."""
647
+ """The runner's legacy whole-state seed; an overlay body is refused (``base_mismatch``), as on any world
648
+ without a snapshot digest."""
745
649
  if isinstance(body, dict) and isinstance(body.get("base"), str) and isinstance(body.get("rows"), dict):
746
650
  return self._seed_overlay(body)
747
651
  if not isinstance(body, dict):