@withgateway/sdk 0.3.1 → 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 (129) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +2880 -2032
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2982 -2135
  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 +180 -41
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +172 -35
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/{index-CBqbB_0J.d.ts → index-DUHmS74p.d.ts} +1 -1
  13. package/dist/{index-D-AMnAMa.d.mts → index-mJhG3vZU.d.mts} +1 -1
  14. package/dist/index.d.mts +4 -4
  15. package/dist/index.d.ts +4 -4
  16. package/dist/index.js +1309 -540
  17. package/dist/index.js.map +1 -1
  18. package/dist/index.mjs +1287 -532
  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 +177 -38
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +169 -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 +69 -13
  31. package/dist/tracing/index.js.map +1 -1
  32. package/dist/tracing/index.mjs +69 -13
  33. package/dist/tracing/index.mjs.map +1 -1
  34. package/dist/worlds/index.d.mts +249 -120
  35. package/dist/worlds/index.d.ts +249 -120
  36. package/dist/worlds/index.js +1240 -484
  37. package/dist/worlds/index.js.map +1 -1
  38. package/dist/worlds/index.mjs +1231 -476
  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 -514
  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/compiler.py +334 -158
  57. package/runtime/gatewaysdk/environment/schema/conform.py +8 -12
  58. package/runtime/gatewaysdk/environment/schema/connector.py +27 -62
  59. package/runtime/gatewaysdk/environment/schema/data.py +50 -207
  60. package/runtime/gatewaysdk/environment/schema/database/__init__.py +24 -0
  61. package/runtime/gatewaysdk/environment/schema/database/audit.py +121 -0
  62. package/runtime/gatewaysdk/environment/schema/database/base.py +995 -0
  63. package/runtime/gatewaysdk/environment/schema/database/budget.py +33 -0
  64. package/runtime/gatewaysdk/environment/schema/database/connections.py +101 -0
  65. package/runtime/gatewaysdk/environment/schema/database/engines.py +8 -0
  66. package/runtime/gatewaysdk/environment/schema/database/guard.py +208 -0
  67. package/runtime/gatewaysdk/environment/schema/database/ingest.py +154 -0
  68. package/runtime/gatewaysdk/environment/schema/database/matching.py +58 -0
  69. package/runtime/gatewaysdk/environment/schema/database/provenance.py +30 -0
  70. package/runtime/gatewaysdk/environment/schema/database/rows.py +53 -0
  71. package/runtime/gatewaysdk/environment/schema/database/runtime_rows.py +39 -0
  72. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +367 -0
  73. package/runtime/gatewaysdk/environment/schema/domain_migration.py +236 -0
  74. package/runtime/gatewaysdk/environment/schema/envelope.py +169 -0
  75. package/runtime/gatewaysdk/environment/schema/extract.py +6 -13
  76. package/runtime/gatewaysdk/environment/schema/grading.py +45 -30
  77. package/runtime/gatewaysdk/environment/schema/handler_errors.py +142 -12
  78. package/runtime/gatewaysdk/environment/schema/host.py +158 -250
  79. package/runtime/gatewaysdk/environment/schema/lanes.py +53 -0
  80. package/runtime/gatewaysdk/environment/schema/local.py +44 -71
  81. package/runtime/gatewaysdk/environment/schema/mapping.py +5 -25
  82. package/runtime/gatewaysdk/environment/schema/openapi_import.py +112 -73
  83. package/runtime/gatewaysdk/environment/schema/openapi_paging.py +147 -0
  84. package/runtime/gatewaysdk/environment/schema/openapi_payloads.py +288 -0
  85. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +97 -102
  86. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +113 -30
  87. package/runtime/gatewaysdk/environment/schema/platform.py +123 -171
  88. package/runtime/gatewaysdk/environment/schema/platform_import.py +2 -3
  89. package/runtime/gatewaysdk/environment/schema/platform_query.py +61 -5
  90. package/runtime/gatewaysdk/environment/schema/primary_key.py +61 -0
  91. package/runtime/gatewaysdk/environment/schema/proof.py +19 -12
  92. package/runtime/gatewaysdk/environment/schema/runtime.py +77 -160
  93. package/runtime/gatewaysdk/environment/schema/served_names.py +58 -0
  94. package/runtime/gatewaysdk/environment/schema/session_files.py +166 -0
  95. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +2 -2
  96. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +19 -11
  97. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +29 -3
  98. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +14 -14
  99. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +12 -12
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +15 -0
  102. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +50 -21
  103. package/runtime/gatewaysdk/environment/schema/slack.py +4 -8
  104. package/runtime/gatewaysdk/environment/schema/snapshot.py +385 -129
  105. package/runtime/gatewaysdk/environment/schema/store_contract.py +8 -14
  106. package/runtime/gatewaysdk/environment/schema/tasks.py +140 -55
  107. package/runtime/gatewaysdk/environment/schema/tools_world.py +110 -87
  108. package/runtime/gatewaysdk/environment/schema/ui.py +24 -5
  109. package/runtime/gatewaysdk/environment/schema/ui_static/app.js +100 -130
  110. package/runtime/gatewaysdk/environment/schema/ui_static/index.html +1 -8
  111. package/runtime/gatewaysdk/environment/schema/validation.py +166 -40
  112. package/runtime/gatewaysdk/environment/schema/workers.py +142 -57
  113. package/runtime/gatewaysdk/environment/schema/world_sql.py +81 -0
  114. package/runtime/gatewaysdk/environment/schema/world_tests.py +71 -39
  115. package/runtime/gatewaysdk/environment/score.py +57 -0
  116. package/runtime/gatewaysdk/environment/secret_values.py +36 -0
  117. package/runtime/gatewaysdk/environment/world.py +42 -3
  118. package/runtime/gatewaysdk/environment/world_session_contract.py +32 -5
  119. package/skills/benchmarks-getting-started/SKILL.md +2 -2
  120. package/skills/connector-schema-authoring/SKILL.md +19 -11
  121. package/skills/connector-schema-authoring/connector-worlds.md +13 -4
  122. package/skills/connector-schema-authoring/world-schema.md +103 -51
  123. package/skills/world-data-ingestion/ROWS.md +29 -3
  124. package/skills/world-data-ingestion/SKILL.md +14 -14
  125. package/skills/worlds-getting-started/SKILL.md +12 -12
  126. package/skills/worlds-getting-started/references/cli-mcp-map.md +3 -2
  127. package/skills/worlds-getting-started/references/gotchas.md +15 -0
  128. package/skills/worlds-getting-started/references/openapi-import.md +50 -21
  129. package/runtime/gatewaysdk/environment/schema/store.py +0 -1013
@@ -1,18 +1,15 @@
1
1
  """Worlds — deterministic instances of a mock-tools environment's seeded state.
2
2
 
3
- A world is one sqlite file, branched (file-copied) from the environment's
4
- prepared template db, plus the seams that let an agent's tool calls execute
3
+ A world is one database file, branched (file-copied) from the environment's
4
+ prepared template, plus the seams that let an agent's tool calls execute
5
5
  against it: ``execute``, ``as_registry`` (the exact replay ``ToolStubRegistry``
6
6
  mapping contract), ``wrap_tools``, and grading (``verify`` / ``state``).
7
7
  """
8
8
 
9
9
  from __future__ import annotations
10
10
 
11
- import shutil
12
- import sqlite3
13
11
  import time
14
12
  import uuid
15
- from contextlib import nullcontext
16
13
  from dataclasses import dataclass, field
17
14
  from pathlib import Path
18
15
  from typing import TYPE_CHECKING, Any, Callable, Dict, List, Mapping, Optional, Union
@@ -20,19 +17,16 @@ from typing import TYPE_CHECKING, Any, Callable, Dict, List, Mapping, Optional,
20
17
  try:
21
18
  from ..replay import StubRegistryMapping
22
19
  except ImportError:
23
- # ``replay`` pulls in ``requests`` + the sessions stack. A lean consumer
24
- # that only needs worlds + verifiers (e.g. the benchmark runner's
25
- # mock_tools engine, which vendors just this ``environment`` subpackage —
26
- # no ``replay``) still imports ``World``/``verify``; only ``as_registry``
27
- # (the replay registry contract) is unavailable there, and it is never
28
- # called on that path. The full SDK always has ``replay``, so real
29
- # behaviour is unchanged.
20
+ # The benchmark runner vendors only environment/ (no replay, no requests) and never calls as_registry.
30
21
  StubRegistryMapping = dict # type: ignore[assignment,misc]
31
22
  from . import runtime
23
+ from .backing import WorldBacking
32
24
  from .errors import ToolRouteError, VerifierError
25
+ from .score import Score
33
26
 
34
27
  if TYPE_CHECKING: # pragma: no cover
35
28
  from .core import Environment
29
+ from .schema.session_files import ProvenTemplate, SessionExport
36
30
 
37
31
 
38
32
  @dataclass
@@ -48,98 +42,49 @@ class VerifierResult:
48
42
  rewards: Dict[str, float] = field(default_factory=dict)
49
43
 
50
44
 
51
- def split_sql_statements(script: str) -> List[str]:
52
- """Split a SQL script into complete statements (via
53
- ``sqlite3.complete_statement`` accumulation, so semicolons inside string
54
- literals don't split). Text that is only comments — a note after the last
55
- semicolon, a commented-out block — is not a statement and is dropped, so
56
- every reader of a verifier (check, grade, the host) sees the same list."""
57
- statements: List[str] = []
58
- buffer = ""
59
- for line in script.splitlines(keepends=True):
60
- buffer += line
61
- if sqlite3.complete_statement(buffer):
62
- _append_statement(statements, buffer)
63
- buffer = ""
64
- _append_statement(statements, buffer)
65
- return statements
66
-
67
-
68
- def _append_statement(statements: List[str], text: str) -> None:
69
- stripped = text.strip()
70
- if _without_comments(stripped).strip(" \t\r\n;"):
71
- statements.append(stripped)
72
-
73
-
74
- def _without_comments(sql: str) -> str:
75
- """``sql`` with ``--`` line comments and ``/* */`` blocks removed, string
76
- literals left alone (a ``--`` inside quotes is text, not a comment)."""
77
- out: List[str] = []
78
- i, n = 0, len(sql)
79
- quote: Optional[str] = None
80
- while i < n:
81
- ch = sql[i]
82
- if quote is not None:
83
- out.append(ch)
84
- quote = None if ch == quote else quote
85
- i += 1
86
- continue
87
- if ch in ("'", '"', "`"):
88
- quote = ch
89
- out.append(ch)
90
- i += 1
91
- continue
92
- if sql.startswith("--", i):
93
- end = sql.find("\n", i)
94
- i = n if end == -1 else end
95
- continue
96
- if sql.startswith("/*", i):
97
- end = sql.find("*/", i + 2)
98
- i = n if end == -1 else end + 2
99
- continue
100
- out.append(ch)
101
- i += 1
102
- return "".join(out)
103
-
104
-
105
45
  class SqlVerifier:
106
46
  """One ``verifiers/<name>.sql``: the statements it runs and the one score
107
47
  rule every reader applies — ``schema check``, a local session's grade, the
108
48
  World Host's grade. Statements run in order; the score is the first column
109
49
  of the first row of the LAST statement that returns rows (or could). No
110
- rows / NULL → ``None``, never coerced to 0."""
50
+ rows / NULL → ``None``, never coerced to 0; a value that is not a number
51
+ is a :class:`VerifierError` naming it, and so is a score that is not one
52
+ from 0 to 1 (:class:`Score`; earlier statements may count rows)."""
111
53
 
112
- def __init__(self, name: str, script: str) -> None:
54
+ def __init__(self, name: str, script: str, split: Callable[[str], List[str]]) -> None:
113
55
  self.name = name[:-4] if name.endswith(".sql") else name
114
- self.statements = split_sql_statements(script)
56
+ self.statements = split(script)
115
57
 
116
58
  @classmethod
117
- def read(cls, path: Path) -> "SqlVerifier":
118
- return cls(path.stem, path.read_text(encoding="utf-8"))
59
+ def read(cls, path: Path, split: Callable[[str], List[str]]) -> "SqlVerifier":
60
+ """``split`` is the engine's statement splitter (``WorldDatabase.split_statements``)."""
61
+ return cls(path.stem, path.read_text(encoding="utf-8"), split)
119
62
 
120
- def score(
121
- self, execute: Callable[[str], Optional[List[Any]]]
122
- ) -> "tuple[Optional[float], Optional[str]]":
63
+ def score(self, execute: Callable[[str], Optional[List[Any]]]) -> "tuple[Optional[float], Optional[str]]":
123
64
  """Run every statement through ``execute`` (rows, or ``None`` for a
124
65
  statement that returns none, e.g. a temp-table DDL) and answer
125
66
  ``(score, sql)`` — the score and the statement it came from, both
126
67
  ``None`` when nothing returned rows."""
127
- score: Optional[float] = None
68
+ value: Any = None
128
69
  last_sql: Optional[str] = None
129
70
  for statement in self.statements:
130
71
  rows = execute(statement)
131
72
  if rows is None:
132
73
  continue
133
74
  last_sql = statement
134
- value = rows[0][0] if rows else None
135
- score = self._as_score(value)
136
- return score, last_sql
75
+ value = self._number(rows[0][0] if rows else None)
76
+ return self._score(value), last_sql
77
+
78
+ def _number(self, value: Any) -> Any:
79
+ if value is None or (isinstance(value, (int, float)) and not isinstance(value, bool)):
80
+ return value
81
+ raise VerifierError(f"verifier '{self.name}' returned {value!r}, not a number")
137
82
 
138
- def _as_score(self, value: Any) -> Optional[float]:
83
+ def _score(self, value: Any) -> Optional[float]:
139
84
  if value is None:
140
85
  return None
141
- if isinstance(value, bool) or not isinstance(value, (int, float)):
142
- raise VerifierError(f"verifier '{self.name}' returned {value!r}, not a number")
86
+ if not Score.admits(value):
87
+ raise VerifierError(f"verifier '{self.name}' returned {Score.shown(value)}; {Score.RULE}")
143
88
  return float(value)
144
89
 
145
90
 
@@ -170,9 +115,7 @@ class WorldRegistry(StubRegistryMapping):
170
115
  stub.__qualname__ = f"gateway_env.{name}"
171
116
  return stub
172
117
 
173
- super().__init__(
174
- {name: make(name) for name in world.env._handlers}, make
175
- )
118
+ super().__init__({name: make(name) for name in world.env._handlers}, make)
176
119
 
177
120
  @property
178
121
  def call_log(self) -> List[Dict[str, Any]]:
@@ -186,41 +129,57 @@ class WorldRegistry(StubRegistryMapping):
186
129
 
187
130
 
188
131
  class World:
189
- """One live, isolated instance of the environment's seeded state."""
190
-
191
- def __init__(self, env: "Environment", *, world_id: Optional[str] = None, snapshot: Optional[Path] = None) -> None:
132
+ """One live, isolated instance of the environment's seeded state.
133
+
134
+ ``template`` is a version's :class:`~.schema.session_files.ProvenTemplate`:
135
+ the world starts from it, and resets to it, with the contract and DDL check
136
+ and no row audit. Without one the world copies its environment's own
137
+ template and audits every row on each open and reset; a ``snapshot`` file
138
+ to start from is always audited."""
139
+
140
+ def __init__(
141
+ self,
142
+ env: "Environment",
143
+ *,
144
+ world_id: Optional[str] = None,
145
+ snapshot: Optional[Path] = None,
146
+ template: Optional["ProvenTemplate"] = None,
147
+ ) -> None:
192
148
  self.env = env
193
149
  self.id = world_id or uuid.uuid4().hex[:8]
194
150
  self.db_path: Path = env._worlds_dir / f"world-{self.id}.db"
195
151
  self.call_log: List[Dict[str, Any]] = []
152
+ self._template = self._proven(template)
153
+ self.contract = template.contract if template is not None else self._bundle_contract()
154
+ source, audit = (Path(snapshot), True) if snapshot is not None else self._seed()
155
+ self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
156
+
157
+ @staticmethod
158
+ def _proven(template: Any) -> Any:
159
+ if template is None:
160
+ return None
161
+ from .schema.session_files import ProvenTemplate
162
+
163
+ return ProvenTemplate.required(template)
164
+
165
+ def _bundle_contract(self) -> Any:
196
166
  from .schema import bundle_mode, check_bundle
197
167
 
198
- self.contract = check_bundle(env.bundle_path) if bundle_mode(env.bundle_path) is not None else None
199
- self.store = None
200
- shutil.copyfile(snapshot if snapshot is not None else env._template_db, self.db_path)
201
- try:
202
- self._conn = self._connect()
203
- except BaseException:
204
- self.db_path.unlink(missing_ok=True)
205
- raise
206
-
207
- def _connect(self) -> sqlite3.Connection:
208
- # autocommit + cross-thread: agents call tools from worker threads, and
209
- # file copies (branch/snapshot/reset) must always see committed state.
210
- if self.contract is not None:
211
- from .schema import SQLiteStore
212
-
213
- self.store = SQLiteStore.open(self.db_path, self.contract)
214
- return self.store._conn # Trusted host only; handlers receive ReadConnection.
215
- conn = sqlite3.connect(self.db_path, isolation_level=None, check_same_thread=False)
216
- conn.row_factory = sqlite3.Row
217
- return conn
218
-
219
- # -- execution seams -------------------------------------------------
168
+ return check_bundle(self.env.bundle_path) if bundle_mode(self.env.bundle_path) is not None else None
169
+
170
+ def _seed(self) -> "tuple[Path, bool]":
171
+ """The file a fresh or reset world copies, and whether its rows are audited."""
172
+ if self._template is None:
173
+ return Path(self.env._template_db), True
174
+ return self._template.path, False
175
+
176
+ @property
177
+ def store(self):
178
+ """The world database of a schema world; ``None`` for a contract-less mock-tools world."""
179
+ return self._backing.store
220
180
 
221
181
  def execute(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
222
182
  """Execute atomically in schema mode, validating both input and output."""
223
- from .schema.store import ReadConnection
224
183
  from .schema.validation import validate
225
184
 
226
185
  handler = self.env._handlers.get(tool_name)
@@ -228,14 +187,14 @@ class World:
228
187
  raise ToolRouteError(f"tool '{tool_name}' has no declared env handler")
229
188
  supplied = ({} if self.contract else None) if tool_input is _NO_INPUT else tool_input
230
189
  started = time.perf_counter()
231
- with self.store.transaction() if self.store is not None else nullcontext():
190
+ with self._backing.transaction():
232
191
  if self.contract is not None:
233
192
  validate(
234
193
  self.contract.tools[tool_name]["input_schema"],
235
194
  supplied,
236
195
  location=f"world.json#/x-gateway/tools/{tool_name}/input",
237
196
  )
238
- token = runtime._active_connection.set(ReadConnection(self.store) if self.store is not None else self._conn)
197
+ token = runtime._active_connection.set(self._backing.handler_connection())
239
198
  store_token = runtime._active_store.set(self.store)
240
199
  try:
241
200
  if isinstance(supplied, Mapping):
@@ -258,9 +217,7 @@ class World:
258
217
  self.env._record_route(tool_name, "env", duration_ms, self.id)
259
218
  return result
260
219
 
261
- def _registry_call(
262
- self, tool_name: str, tool_input: Any = _NO_INPUT
263
- ) -> Any:
220
+ def _registry_call(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
264
221
  if tool_name in self.env._handlers and self.env.resolve_route(tool_name) == "env":
265
222
  return self.execute(tool_name, tool_input)
266
223
  route = self.env.resolve_route(tool_name)
@@ -275,8 +232,7 @@ class World:
275
232
  "through to the original function."
276
233
  )
277
234
  raise ToolRouteError(
278
- f"tool '{tool_name}' has no env handler "
279
- f"(served: {sorted(self.env._handlers)}) and no prod route."
235
+ f"tool '{tool_name}' has no env handler (served: {sorted(self.env._handlers)}) and no prod route."
280
236
  )
281
237
 
282
238
  def as_registry(self) -> WorldRegistry:
@@ -284,9 +240,7 @@ class World:
284
240
  identical contract to ``ToolStubRegistry.as_registry()`` in replay."""
285
241
  return WorldRegistry(self)
286
242
 
287
- def wrap_tools(
288
- self, tools: Union[Mapping[str, Any], List[Any]]
289
- ) -> Union[Dict[str, Any], List[Any]]:
243
+ def wrap_tools(self, tools: Union[Mapping[str, Any], List[Any]]) -> Union[Dict[str, Any], List[Any]]:
290
244
  """Substitute env-served callables by name in a list/dict of tools;
291
245
  everything not served (or not env-routed) passes through unchanged."""
292
246
 
@@ -301,10 +255,7 @@ class World:
301
255
  return stub
302
256
 
303
257
  if isinstance(tools, Mapping):
304
- return {
305
- name: (stub_for(name) if routed_to_env(name) else value)
306
- for name, value in tools.items()
307
- }
258
+ return {name: (stub_for(name) if routed_to_env(name) else value) for name, value in tools.items()}
308
259
  wrapped: List[Any] = []
309
260
  for item in tools:
310
261
  name = getattr(item, "name", None)
@@ -313,67 +264,65 @@ class World:
313
264
  wrapped.append(stub_for(name) if routed_to_env(name) else item)
314
265
  return wrapped
315
266
 
316
- # -- state lifecycle -------------------------------------------------
317
-
318
267
  def reset(self) -> None:
319
268
  """Back to the seed, in place (same world instance)."""
320
- if self.contract is not None:
321
- from .schema import check_bundle
269
+ if self._template is None:
270
+ self._refuse_a_changed_contract()
271
+ source, audit = self._seed()
272
+ self._relay(source, audit=audit)
322
273
 
323
- if check_bundle(self.env.bundle_path).lock != self.contract.lock:
324
- from .schema import ContractError
274
+ def _refuse_a_changed_contract(self) -> None:
275
+ """An environment's bundle can change under a live world; a version's cannot."""
276
+ if self.contract is None:
277
+ return
278
+ from .schema import ContractError, check_bundle
325
279
 
326
- raise ContractError("state_contract", "Bundle contract changed; create a new world explicitly")
327
- if self.store is not None:
328
- self.store.close()
329
- else:
330
- self._conn.close()
331
- shutil.copyfile(self.env._template_db, self.db_path)
332
- self._conn = self._connect()
280
+ if check_bundle(self.env.bundle_path).lock != self.contract.lock:
281
+ raise ContractError("state_contract", "Bundle contract changed; create a new world explicitly")
333
282
 
334
283
  def restore(self, source: Union[str, Path]) -> None:
335
284
  """Replace this world's state with a file :meth:`snapshot` wrote, in place.
336
- The file is opened the way a fresh copy of the seed is, so a schema-backed
337
- world audits it against its contract."""
338
- if self.store is not None:
339
- self.store.close()
340
- else:
341
- self._conn.close()
342
- shutil.copyfile(source, self.db_path)
343
- self._conn = self._connect()
285
+ A schema-backed world audits it against its contract row by row, as it would
286
+ any file it did not write."""
287
+ self._relay(Path(source), audit=True)
288
+
289
+ def resume(self, export: "SessionExport") -> None:
290
+ """Replace this world's state with an export whose bytes were verified against
291
+ the sha256 recorded when the store wrote them, without a second row audit."""
292
+ from .schema.session_files import SessionExport
293
+
294
+ self._relay(SessionExport.required(export).path, audit=False)
295
+
296
+ def _relay(self, source: Path, *, audit: bool) -> None:
297
+ self._backing.close()
298
+ self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
344
299
 
345
300
  def snapshot(self, destination: Union[str, Path]) -> Path:
346
301
  """Pin this world's current state to a file (for debugging fixtures)."""
347
- if self.store is not None:
348
- return self.store.snapshot(destination)
349
- dest = Path(destination)
350
- dest.parent.mkdir(parents=True, exist_ok=True)
351
- shutil.copyfile(self.db_path, dest)
352
- return dest
302
+ return self._backing.snapshot(Path(destination))
353
303
 
354
304
  def close(self) -> None:
355
- try:
356
- if self.store is not None:
357
- self.store.close()
358
- else:
359
- self._conn.close()
360
- except sqlite3.Error: # pragma: no cover — close is best-effort
361
- pass
362
-
363
- # -- grading ---------------------------------------------------------
305
+ self._backing.close()
306
+
307
+ def set_task_context(self, scenario_id: str) -> bool:
308
+ """Name the active task for verifiers; ``False`` when a mock-tools world does not declare the table."""
309
+ return self._backing.set_task_context(scenario_id)
310
+
311
+ def set_run_parameters(self, parameters: Dict[str, str]) -> bool:
312
+ """Bind the run's conditions; ``False`` when a mock-tools world does not declare the table."""
313
+ return self._backing.set_run_parameters(parameters)
314
+
315
+ def record_conversation_event(
316
+ self, scenario_id: str, user_turn_index: int, event_type: str, actor: str, name: Optional[str], payload_json: str
317
+ ) -> bool:
318
+ """Log one turn event for verifiers; ``False`` when a mock-tools world does not declare the table."""
319
+ return self._backing.record_conversation_event(
320
+ scenario_id, user_turn_index, event_type, actor, name, payload_json
321
+ )
364
322
 
365
323
  def state(self, sql: str, *params: Any) -> List[Dict[str, Any]]:
366
324
  """Read-only SQL against the world's db (SELECT/WITH only)."""
367
- if self.store is not None:
368
- return [dict(row) for row in self.store.query(sql, params)]
369
- head = sql.lstrip().split(None, 1)[0].upper() if sql.strip() else ""
370
- if head not in ("SELECT", "WITH"):
371
- raise ValueError(
372
- "world.state() is read-only — only SELECT/WITH queries are "
373
- "allowed (use tool handlers or verifiers for writes)."
374
- )
375
- rows = self._conn.execute(sql, params).fetchall()
376
- return [dict(row) for row in rows]
325
+ return self._backing.rows(sql, params)
377
326
 
378
327
  def verify(self, name: str) -> VerifierResult:
379
328
  """Run ``verifiers/<name>.sql`` against this world.
@@ -382,8 +331,6 @@ class World:
382
331
  the LAST row-returning statement. NULL / no rows → score None (passed
383
332
  None) — never coerced to 0.
384
333
  """
385
- from .schema import ContractError
386
-
387
334
  verifier_name = name[:-4] if name.endswith(".sql") else name
388
335
  path = self.env.bundle_path / "verifiers" / f"{verifier_name}.sql"
389
336
  if not path.is_file():
@@ -391,31 +338,9 @@ class World:
391
338
  raise VerifierError(f"unknown verifier '{name}' (available: {available})")
392
339
 
393
340
  def execute(statement: str) -> Optional[List[Any]]:
394
- try:
395
- if self.store is not None:
396
- try:
397
- return self.store.query(statement, private=True)
398
- except ContractError as error:
399
- # A verifier naming a column the contract never projected
400
- # must fail with SQLite's own words and the statement, not
401
- # read as a zero (Brex retrospective).
402
- reason = error.__cause__ if error.__cause__ is not None else error.detail["message"]
403
- raise ContractError(
404
- "verifier",
405
- f"verifier '{verifier_name}' failed: {reason}",
406
- sql=statement,
407
- ) from error
408
- cursor = self._conn.execute(statement)
409
- except sqlite3.Error as error:
410
- raise VerifierError(
411
- f"verifier '{verifier_name}' failed: {error}\n SQL: {statement}"
412
- ) from error
413
- if cursor.description is None:
414
- return None
415
- row = cursor.fetchone()
416
- return [] if row is None else [row]
417
-
418
- score, last_sql = SqlVerifier.read(path).score(execute)
341
+ return self._backing.verifier_rows(verifier_name, statement)
342
+
343
+ score, last_sql = SqlVerifier.read(path, self._backing.split_statements).score(execute)
419
344
  if last_sql is None:
420
345
  detail = "no row-returning statement — score is null"
421
346
  elif score is None:
@@ -0,0 +1,137 @@
1
+ """What a :class:`~gatewaysdk.environment._world.World`'s state lives in: a
2
+ contract-bound world database, or the raw SQLite file of a contract-less
3
+ mock-tools world. The world asks its backing and never branches on which."""
4
+
5
+ from __future__ import annotations
6
+
7
+ from abc import ABC, abstractmethod
8
+ from contextlib import AbstractContextManager
9
+ from pathlib import Path
10
+ from typing import Any, Dict, List, Optional
11
+
12
+ from .schema.compiler import Contract
13
+ from .schema.database import WorldDatabase
14
+ from .schema.validation import ContractError
15
+
16
+
17
+ class WorldBacking(ABC):
18
+ """One world's open state file."""
19
+
20
+ store: Optional[WorldDatabase] = None
21
+
22
+ @staticmethod
23
+ def branch(source: Path, path: Path, contract: Optional[Contract], *, audit: bool = True) -> "WorldBacking":
24
+ """A copy of ``source`` at ``path``, opened as the backing ``contract`` calls for;
25
+ ``path`` is removed again when the copy does not open. ``audit=False`` is for a
26
+ source whose rows are already proven (a version's template, a verified export)."""
27
+ from .legacy_sqlite import LegacySQLiteBacking
28
+
29
+ WorldDatabase.clone_file(Path(source), Path(path))
30
+ try:
31
+ if contract is None:
32
+ return LegacySQLiteBacking(Path(path))
33
+ return ContractBacking(Path(path), contract, audit=audit)
34
+ except BaseException:
35
+ Path(path).unlink(missing_ok=True)
36
+ raise
37
+
38
+ @abstractmethod
39
+ def transaction(self) -> AbstractContextManager[Any]:
40
+ """The unit one tool call runs in."""
41
+
42
+ @abstractmethod
43
+ def handler_connection(self) -> Any:
44
+ """What a tool handler receives as ``conn``."""
45
+
46
+ @abstractmethod
47
+ def split_statements(self, script: str) -> List[str]: ...
48
+
49
+ @abstractmethod
50
+ def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
51
+ """Read-only SQL, each row as a dict (``world.state``)."""
52
+
53
+ @abstractmethod
54
+ def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
55
+ """One verifier statement's rows (the first is the score), or ``None`` when it projects no columns."""
56
+
57
+ @abstractmethod
58
+ def snapshot(self, destination: Path) -> Path: ...
59
+
60
+ @abstractmethod
61
+ def set_task_context(self, scenario_id: str) -> bool:
62
+ """Name the active task; ``False`` when the world does not declare the table."""
63
+
64
+ @abstractmethod
65
+ def set_run_parameters(self, parameters: Dict[str, str]) -> bool:
66
+ """Bind the run's conditions; ``False`` when the world does not declare the table."""
67
+
68
+ @abstractmethod
69
+ def record_conversation_event(
70
+ self,
71
+ scenario_id: str,
72
+ user_turn_index: int,
73
+ event_type: str,
74
+ actor: str,
75
+ name: Optional[str],
76
+ payload_json: str,
77
+ ) -> bool:
78
+ """Log one turn event; ``False`` when the world does not declare the table."""
79
+
80
+ @abstractmethod
81
+ def close(self) -> None: ...
82
+
83
+
84
+ class ContractBacking(WorldBacking):
85
+ """A schema world's state: the world database its contract compiled to."""
86
+
87
+ def __init__(self, path: Path, contract: Contract, *, audit: bool = True) -> None:
88
+ self.store = WorldDatabase.open(path, contract, audit=audit)
89
+
90
+ def transaction(self) -> AbstractContextManager[Any]:
91
+ return self.store.transaction()
92
+
93
+ def handler_connection(self) -> Any:
94
+ return self.store.read_connection()
95
+
96
+ def split_statements(self, script: str) -> List[str]:
97
+ return self.store.split_statements(script)
98
+
99
+ def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
100
+ return [dict(row) for row in self.store.query(sql, params)]
101
+
102
+ def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
103
+ try:
104
+ return self.store.query(statement, private=True)
105
+ except ContractError as error:
106
+ # An unprojected column must fail with the engine's words, not read as a zero.
107
+ reason = error.__cause__ if error.__cause__ is not None else error.detail["message"]
108
+ raise ContractError("verifier", f"verifier '{verifier}' failed: {reason}", sql=statement) from error
109
+
110
+ def snapshot(self, destination: Path) -> Path:
111
+ return self.store.snapshot(destination)
112
+
113
+ def set_task_context(self, scenario_id: str) -> bool:
114
+ self.store.set_task_context(scenario_id)
115
+ return True
116
+
117
+ def set_run_parameters(self, parameters: Dict[str, str]) -> bool:
118
+ self.store.set_run_parameters(parameters)
119
+ return True
120
+
121
+ def record_conversation_event(
122
+ self,
123
+ scenario_id: str,
124
+ user_turn_index: int,
125
+ event_type: str,
126
+ actor: str,
127
+ name: Optional[str],
128
+ payload_json: str,
129
+ ) -> bool:
130
+ self.store.record_conversation_event(scenario_id, user_turn_index, event_type, actor, name, payload_json)
131
+ return True
132
+
133
+ def close(self) -> None:
134
+ try:
135
+ self.store.close()
136
+ except self.store.native_error:
137
+ pass
@@ -10,7 +10,7 @@
10
10
 
11
11
  Local mode only in P1: the version bundle is pulled via the existing
12
12
  environments/benchmark-hub clients, extracted to a cache dir, and executed
13
- in-process (sqlite worlds for ``mock-tools``; per-task docker sandboxes for
13
+ in-process (database-backed worlds for ``mock-tools``; per-task docker sandboxes for
14
14
  ``harbor``). ``mode="remote"`` and ``hosts=`` transport patching are P2/P3.
15
15
  """
16
16