@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,18 +1,7 @@
1
- """Worlds — deterministic instances of a mock-tools environment's seeded state.
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
5
- against it: ``execute``, ``as_registry`` (the exact replay ``ToolStubRegistry``
6
- mapping contract), ``wrap_tools``, and grading (``verify`` / ``state``).
7
- """
8
-
9
1
  from __future__ import annotations
10
2
 
11
- import shutil
12
- import sqlite3
13
3
  import time
14
4
  import uuid
15
- from contextlib import nullcontext
16
5
  from dataclasses import dataclass, field
17
6
  from pathlib import Path
18
7
  from typing import TYPE_CHECKING, Any, Callable, Dict, List, Mapping, Optional, Union
@@ -20,126 +9,63 @@ from typing import TYPE_CHECKING, Any, Callable, Dict, List, Mapping, Optional,
20
9
  try:
21
10
  from ..replay import StubRegistryMapping
22
11
  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.
12
+ # The benchmark runner vendors only environment/ (no replay, no requests) and never calls as_registry.
30
13
  StubRegistryMapping = dict # type: ignore[assignment,misc]
31
14
  from . import runtime
15
+ from .backing import WorldBacking
32
16
  from .errors import ToolRouteError, VerifierError
17
+ from .score import Score
33
18
 
34
19
  if TYPE_CHECKING: # pragma: no cover
35
20
  from .core import Environment
21
+ from .schema.journal import JournalUse, WorldJournal
22
+ from .schema.session_files import ProvenTemplate, SessionExport
36
23
 
37
24
 
38
25
  @dataclass
39
26
  class VerifierResult:
40
- """One verifier outcome. ``score=None`` stays ``None`` (house rule: null
41
- scores are their own category, never coerced to 0) and yields
42
- ``passed=None``; otherwise ``passed = score >= 1.0``."""
27
+ """``passed`` is ``score >= 1.0``; a ``None`` score is ungraded, never 0, and has ``passed=None``."""
43
28
 
44
29
  name: str
45
30
  passed: Optional[bool]
46
31
  score: Optional[float]
47
32
  detail: str = ""
48
33
  rewards: Dict[str, float] = field(default_factory=dict)
49
-
50
-
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)
34
+ closed: Optional[str] = None
103
35
 
104
36
 
105
37
  class SqlVerifier:
106
- """One ``verifiers/<name>.sql``: the statements it runs and the one score
107
- rule every reader applies — ``schema check``, a local session's grade, the
108
- World Host's grade. Statements run in order; the score is the first column
109
- of the first row of the LAST statement that returns rows (or could). No
110
- rows / NULL → ``None``, never coerced to 0."""
38
+ """Every reader's score rule, pinned by ``sql-verifier-vectors.json``: NULL or no rows is ``None``, never 0."""
111
39
 
112
- def __init__(self, name: str, script: str) -> None:
40
+ def __init__(self, name: str, script: str, split: Callable[[str], List[str]]) -> None:
113
41
  self.name = name[:-4] if name.endswith(".sql") else name
114
- self.statements = split_sql_statements(script)
42
+ self.statements = split(script)
115
43
 
116
44
  @classmethod
117
- def read(cls, path: Path) -> "SqlVerifier":
118
- return cls(path.stem, path.read_text(encoding="utf-8"))
119
-
120
- def score(
121
- self, execute: Callable[[str], Optional[List[Any]]]
122
- ) -> "tuple[Optional[float], Optional[str]]":
123
- """Run every statement through ``execute`` (rows, or ``None`` for a
124
- statement that returns none, e.g. a temp-table DDL) and answer
125
- ``(score, sql)`` — the score and the statement it came from, both
126
- ``None`` when nothing returned rows."""
127
- score: Optional[float] = None
45
+ def read(cls, path: Path, split: Callable[[str], List[str]]) -> "SqlVerifier":
46
+ return cls(path.stem, path.read_text(encoding="utf-8"), split)
47
+
48
+ def score(self, execute: Callable[[str], Optional[List[Any]]]) -> "tuple[Optional[float], Optional[str]]":
49
+ value: Any = None
128
50
  last_sql: Optional[str] = None
129
51
  for statement in self.statements:
130
52
  rows = execute(statement)
131
53
  if rows is None:
132
54
  continue
133
55
  last_sql = statement
134
- value = rows[0][0] if rows else None
135
- score = self._as_score(value)
136
- return score, last_sql
56
+ value = self._number(rows[0][0] if rows else None)
57
+ return self._score(value), last_sql
58
+
59
+ def _number(self, value: Any) -> Any:
60
+ if value is None or (isinstance(value, (int, float)) and not isinstance(value, bool)):
61
+ return value
62
+ raise VerifierError(f"verifier '{self.name}' returned {value!r}, not a number")
137
63
 
138
- def _as_score(self, value: Any) -> Optional[float]:
64
+ def _score(self, value: Any) -> Optional[float]:
139
65
  if value is None:
140
66
  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")
67
+ if not Score.admits(value):
68
+ raise VerifierError(f"verifier '{self.name}' returned {Score.shown(value)}; {Score.RULE}")
143
69
  return float(value)
144
70
 
145
71
 
@@ -147,18 +73,12 @@ _NO_INPUT = object()
147
73
 
148
74
 
149
75
  def _stub_input(tool_input: Any, kwargs: Dict[str, Any]) -> Any:
150
- """One rule for callable seams: an explicit positional input (even None)
151
- is the input; keyword arguments are the input; nothing means omitted."""
152
76
  if tool_input is not _NO_INPUT:
153
77
  return tool_input
154
78
  return kwargs if kwargs else _NO_INPUT
155
79
 
156
80
 
157
81
  class WorldRegistry(StubRegistryMapping):
158
- """``world.as_registry()`` — the replay registry contract (mapping with
159
- ``__missing__``, ``lookup``, ``call_log``/``called_names``) backed by the
160
- live env world instead of recordings."""
161
-
162
82
  def __init__(self, world: "World") -> None:
163
83
  self._world = world
164
84
 
@@ -170,9 +90,7 @@ class WorldRegistry(StubRegistryMapping):
170
90
  stub.__qualname__ = f"gateway_env.{name}"
171
91
  return stub
172
92
 
173
- super().__init__(
174
- {name: make(name) for name in world.env._handlers}, make
175
- )
93
+ super().__init__({name: make(name) for name in world.env._handlers}, make)
176
94
 
177
95
  @property
178
96
  def call_log(self) -> List[Dict[str, Any]]:
@@ -186,41 +104,51 @@ class WorldRegistry(StubRegistryMapping):
186
104
 
187
105
 
188
106
  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:
107
+ def __init__(
108
+ self,
109
+ env: "Environment",
110
+ *,
111
+ world_id: Optional[str] = None,
112
+ snapshot: Optional[Path] = None,
113
+ template: Optional["ProvenTemplate"] = None,
114
+ ) -> None:
192
115
  self.env = env
193
116
  self.id = world_id or uuid.uuid4().hex[:8]
194
- self.db_path: Path = env._worlds_dir / f"world-{self.id}.db"
117
+ self.db_path: Path = self.database_file(env._worlds_dir, self.id)
195
118
  self.call_log: List[Dict[str, Any]] = []
119
+ self._template = self._proven(template)
120
+ self.contract = template.contract if template is not None else self._bundle_contract()
121
+ source, audit = (Path(snapshot), True) if snapshot is not None else self._seed()
122
+ self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
123
+
124
+ @staticmethod
125
+ def database_file(directory: Path, world_id: str) -> Path:
126
+ return Path(directory) / f"world-{world_id}.db"
127
+
128
+ @staticmethod
129
+ def _proven(template: Any) -> Any:
130
+ if template is None:
131
+ return None
132
+ from .schema.session_files import ProvenTemplate
133
+
134
+ return ProvenTemplate.required(template)
135
+
136
+ def _bundle_contract(self) -> Any:
196
137
  from .schema import bundle_mode, check_bundle
197
138
 
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 -------------------------------------------------
139
+ return check_bundle(self.env.bundle_path) if bundle_mode(self.env.bundle_path) is not None else None
140
+
141
+ def _seed(self) -> "tuple[Path, bool]":
142
+ if self._template is None:
143
+ return Path(self.env._template_db), True
144
+ return self._template.path, False
145
+
146
+ @property
147
+ def store(self):
148
+ """``None`` for a contract-less mock-tools world."""
149
+ return self._backing.store
220
150
 
221
151
  def execute(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
222
- """Execute atomically in schema mode, validating both input and output."""
223
- from .schema.store import ReadConnection
224
152
  from .schema.validation import validate
225
153
 
226
154
  handler = self.env._handlers.get(tool_name)
@@ -228,14 +156,14 @@ class World:
228
156
  raise ToolRouteError(f"tool '{tool_name}' has no declared env handler")
229
157
  supplied = ({} if self.contract else None) if tool_input is _NO_INPUT else tool_input
230
158
  started = time.perf_counter()
231
- with self.store.transaction() if self.store is not None else nullcontext():
159
+ with self._backing.transaction():
232
160
  if self.contract is not None:
233
161
  validate(
234
162
  self.contract.tools[tool_name]["input_schema"],
235
163
  supplied,
236
164
  location=f"world.json#/x-gateway/tools/{tool_name}/input",
237
165
  )
238
- token = runtime._active_connection.set(ReadConnection(self.store) if self.store is not None else self._conn)
166
+ token = runtime._active_connection.set(self._backing.handler_connection())
239
167
  store_token = runtime._active_store.set(self.store)
240
168
  try:
241
169
  if isinstance(supplied, Mapping):
@@ -258,9 +186,7 @@ class World:
258
186
  self.env._record_route(tool_name, "env", duration_ms, self.id)
259
187
  return result
260
188
 
261
- def _registry_call(
262
- self, tool_name: str, tool_input: Any = _NO_INPUT
263
- ) -> Any:
189
+ def _registry_call(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
264
190
  if tool_name in self.env._handlers and self.env.resolve_route(tool_name) == "env":
265
191
  return self.execute(tool_name, tool_input)
266
192
  route = self.env.resolve_route(tool_name)
@@ -275,21 +201,14 @@ class World:
275
201
  "through to the original function."
276
202
  )
277
203
  raise ToolRouteError(
278
- f"tool '{tool_name}' has no env handler "
279
- f"(served: {sorted(self.env._handlers)}) and no prod route."
204
+ f"tool '{tool_name}' has no env handler (served: {sorted(self.env._handlers)}) and no prod route."
280
205
  )
281
206
 
282
207
  def as_registry(self) -> WorldRegistry:
283
- """Tool-name → callable mapping, drop-in for agent tool layers —
284
- identical contract to ``ToolStubRegistry.as_registry()`` in replay."""
208
+ """Drop-in for agent tool layers, with the contract of replay's ``ToolStubRegistry.as_registry()``."""
285
209
  return WorldRegistry(self)
286
210
 
287
- def wrap_tools(
288
- self, tools: Union[Mapping[str, Any], List[Any]]
289
- ) -> Union[Dict[str, Any], List[Any]]:
290
- """Substitute env-served callables by name in a list/dict of tools;
291
- everything not served (or not env-routed) passes through unchanged."""
292
-
211
+ def wrap_tools(self, tools: Union[Mapping[str, Any], List[Any]]) -> Union[Dict[str, Any], List[Any]]:
293
212
  def routed_to_env(name: Optional[str]) -> bool:
294
213
  return bool(name) and name in self.env._handlers and self.env.resolve_route(name) == "env"
295
214
 
@@ -301,10 +220,7 @@ class World:
301
220
  return stub
302
221
 
303
222
  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
- }
223
+ return {name: (stub_for(name) if routed_to_env(name) else value) for name, value in tools.items()}
308
224
  wrapped: List[Any] = []
309
225
  for item in tools:
310
226
  name = getattr(item, "name", None)
@@ -313,76 +229,72 @@ class World:
313
229
  wrapped.append(stub_for(name) if routed_to_env(name) else item)
314
230
  return wrapped
315
231
 
316
- # -- state lifecycle -------------------------------------------------
317
-
318
232
  def reset(self) -> None:
319
- """Back to the seed, in place (same world instance)."""
320
- if self.contract is not None:
321
- from .schema import check_bundle
233
+ if self._template is None:
234
+ self._refuse_a_changed_contract()
235
+ source, audit = self._seed()
236
+ self._relay(source, audit=audit)
322
237
 
323
- if check_bundle(self.env.bundle_path).lock != self.contract.lock:
324
- from .schema import ContractError
238
+ def _refuse_a_changed_contract(self) -> None:
239
+ """An environment's bundle can change under a live world; a version's cannot."""
240
+ if self.contract is None:
241
+ return
242
+ from .schema import ContractError, check_bundle
325
243
 
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()
244
+ if check_bundle(self.env.bundle_path).lock != self.contract.lock:
245
+ raise ContractError("state_contract", "Bundle contract changed; create a new world explicitly")
333
246
 
334
247
  def restore(self, source: Union[str, Path]) -> None:
335
- """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()
248
+ """Audited row by row: the file is not one this store wrote."""
249
+ self._relay(Path(source), audit=True)
250
+
251
+ def resume(self, export: "SessionExport") -> None:
252
+ """No second row audit: a :class:`SessionExport` is digest-verified or this session's own recovered store."""
253
+ from .schema.session_files import SessionExport
254
+
255
+ self._relay(SessionExport.required(export).path, audit=False)
256
+
257
+ def _relay(self, source: Path, *, audit: bool) -> None:
258
+ self._backing.close()
259
+ self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
344
260
 
345
261
  def snapshot(self, destination: Union[str, Path]) -> Path:
346
- """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
262
+ return self._backing.snapshot(Path(destination))
353
263
 
354
264
  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 ---------------------------------------------------------
265
+ self._backing.close()
266
+
267
+ def set_task_context(self, scenario_id: str) -> bool:
268
+ """``False`` when a mock-tools world does not declare the table."""
269
+ return self._backing.set_task_context(scenario_id)
270
+
271
+ def set_run_parameters(self, parameters: Dict[str, str]) -> bool:
272
+ """``False`` when a mock-tools world does not declare the table."""
273
+ return self._backing.set_run_parameters(parameters)
274
+
275
+ def record_conversation_event(
276
+ self,
277
+ scenario_id: str,
278
+ user_turn_index: int,
279
+ event_type: str,
280
+ actor: str,
281
+ name: Optional[str],
282
+ payload_json: str,
283
+ ) -> bool:
284
+ """``False`` when a mock-tools world does not declare the table."""
285
+ return self._backing.record_conversation_event(
286
+ scenario_id, user_turn_index, event_type, actor, name, payload_json
287
+ )
364
288
 
365
289
  def state(self, sql: str, *params: Any) -> List[Dict[str, Any]]:
366
- """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]
377
-
378
- def verify(self, name: str) -> VerifierResult:
379
- """Run ``verifiers/<name>.sql`` against this world.
290
+ return self._backing.rows(sql, params)
380
291
 
381
- :class:`SqlVerifier` is the rule: the first column of the first row of
382
- the LAST row-returning statement. NULL / no rows → score None (passed
383
- None) — never coerced to 0.
384
- """
385
- from .schema import ContractError
292
+ def verify(self, name: str, journal: Optional["WorldJournal"] = None) -> VerifierResult:
293
+ """NULL or no rows scores ``None``, never 0. A verifier that read the journal fails closed when none was
294
+ recorded, and on an incomplete one unless ``gateway-env.toml`` declares
295
+ ``[verifiers.<name>] accepts_incomplete_journal = true``."""
296
+ from .schema.journal import JournalDatabase, WorldJournal
297
+ from .schema.validation import ContractError
386
298
 
387
299
  verifier_name = name[:-4] if name.endswith(".sql") else name
388
300
  path = self.env.bundle_path / "verifiers" / f"{verifier_name}.sql"
@@ -391,31 +303,22 @@ class World:
391
303
  raise VerifierError(f"unknown verifier '{name}' (available: {available})")
392
304
 
393
305
  def execute(statement: str) -> Optional[List[Any]]:
306
+ return self._backing.verifier_rows(verifier_name, statement)
307
+
308
+ database = JournalDatabase(journal or WorldJournal.unrecorded(), self.db_path.parent / "journal")
309
+ verifier = SqlVerifier.read(path, self._backing.split_statements)
310
+ with self._backing.journal(database) as used:
394
311
  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)
312
+ score, last_sql = verifier.score(execute)
313
+ except (ContractError, VerifierError):
314
+ closed = self._closed_on(verifier_name, database.journal, used(verifier.statements))
315
+ if closed is None:
316
+ raise
317
+ return VerifierResult(name=verifier_name, passed=False, score=0.0, detail=closed, closed=closed)
318
+ use = used(verifier.statements)
319
+ closed = self._closed_on(verifier_name, database.journal, use)
320
+ if closed is not None:
321
+ return VerifierResult(name=verifier_name, passed=False, score=0.0, detail=closed, closed=closed)
419
322
  if last_sql is None:
420
323
  detail = "no row-returning statement — score is null"
421
324
  elif score is None:
@@ -424,3 +327,18 @@ class World:
424
327
  detail = f"score {score} from: {last_sql}"
425
328
  passed = None if score is None else score >= 1.0
426
329
  return VerifierResult(name=verifier_name, passed=passed, score=score, detail=detail)
330
+
331
+ def _closed_on(self, verifier: str, journal: "WorldJournal", use: "JournalUse") -> Optional[str]:
332
+ from .schema.journal import accepting_incomplete
333
+
334
+ gap = journal.gap(use)
335
+ if gap is None:
336
+ return None
337
+ if not journal.recorded:
338
+ return f"{gap}: verifier '{verifier}' reads the journal"
339
+ if verifier in accepting_incomplete(self.env.bundle_path):
340
+ return None
341
+ return (
342
+ f"{gap}: verifier '{verifier}' reads the journal; declare "
343
+ f"[verifiers.{verifier}] accepts_incomplete_journal = true to grade an incomplete one"
344
+ )
@@ -0,0 +1,133 @@
1
+ from __future__ import annotations
2
+
3
+ from abc import ABC, abstractmethod
4
+ from collections.abc import Callable
5
+ from contextlib import AbstractContextManager
6
+ from pathlib import Path
7
+ from typing import TYPE_CHECKING, Any, Dict, List, Optional
8
+
9
+ from .schema.compiler import Contract
10
+ from .schema.database import WorldDatabase
11
+ from .schema.validation import ContractError
12
+
13
+ if TYPE_CHECKING:
14
+ from .schema.journal import JournalDatabase, JournalUse
15
+
16
+
17
+ class WorldBacking(ABC):
18
+ store: Optional[WorldDatabase] = None
19
+
20
+ @staticmethod
21
+ def branch(source: Path, path: Path, contract: Optional[Contract], *, audit: bool = True) -> "WorldBacking":
22
+ """``audit=False`` only for a source whose rows are already proven: a version's template, a verified export."""
23
+ from .legacy_sqlite import LegacySQLiteBacking
24
+
25
+ WorldDatabase.clone_file(Path(source), Path(path))
26
+ try:
27
+ if contract is None:
28
+ return LegacySQLiteBacking(Path(path))
29
+ return ContractBacking(Path(path), contract, audit=audit)
30
+ except BaseException:
31
+ Path(path).unlink(missing_ok=True)
32
+ raise
33
+
34
+ @abstractmethod
35
+ def transaction(self) -> AbstractContextManager[Any]: ...
36
+
37
+ @abstractmethod
38
+ def handler_connection(self) -> Any: ...
39
+
40
+ @abstractmethod
41
+ def split_statements(self, script: str) -> List[str]: ...
42
+
43
+ @abstractmethod
44
+ def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
45
+ """Read-only SQL: every backing refuses a write here (``world.state``)."""
46
+
47
+ @abstractmethod
48
+ def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
49
+ """``None`` when the statement projects no columns, which the score skips; ``[]`` (no rows) scores ``None``."""
50
+
51
+ @abstractmethod
52
+ def journal(self, database: JournalDatabase) -> AbstractContextManager[Callable[[list[str]], JournalUse]]:
53
+ """Yields what a verifier's statements read of ``database``, so one that read an incomplete journal fails closed."""
54
+
55
+ @abstractmethod
56
+ def snapshot(self, destination: Path) -> Path: ...
57
+
58
+ @abstractmethod
59
+ def set_task_context(self, scenario_id: str) -> bool: ...
60
+
61
+ @abstractmethod
62
+ def set_run_parameters(self, parameters: Dict[str, str]) -> bool: ...
63
+
64
+ @abstractmethod
65
+ def record_conversation_event(
66
+ self,
67
+ scenario_id: str,
68
+ user_turn_index: int,
69
+ event_type: str,
70
+ actor: str,
71
+ name: Optional[str],
72
+ payload_json: str,
73
+ ) -> bool: ...
74
+
75
+ @abstractmethod
76
+ def close(self) -> None: ...
77
+
78
+
79
+ class ContractBacking(WorldBacking):
80
+ def __init__(self, path: Path, contract: Contract, *, audit: bool = True) -> None:
81
+ self.store = WorldDatabase.open(path, contract, audit=audit)
82
+
83
+ def transaction(self) -> AbstractContextManager[Any]:
84
+ return self.store.transaction()
85
+
86
+ def handler_connection(self) -> Any:
87
+ return self.store.read_connection()
88
+
89
+ def split_statements(self, script: str) -> List[str]:
90
+ return self.store.split_statements(script)
91
+
92
+ def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
93
+ return [dict(row) for row in self.store.query(sql, params)]
94
+
95
+ def journal(self, database: JournalDatabase) -> AbstractContextManager[Callable[[list[str]], JournalUse]]:
96
+ return database.attached(self.store)
97
+
98
+ def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
99
+ try:
100
+ return self.store.query(statement, private=True)
101
+ except ContractError as error:
102
+ # An unprojected column must fail with the engine's words, not read as a zero.
103
+ reason = error.__cause__ if error.__cause__ is not None else error.detail["message"]
104
+ raise ContractError("verifier", f"verifier '{verifier}' failed: {reason}", sql=statement) from error
105
+
106
+ def snapshot(self, destination: Path) -> Path:
107
+ return self.store.snapshot(destination)
108
+
109
+ def set_task_context(self, scenario_id: str) -> bool:
110
+ self.store.set_task_context(scenario_id)
111
+ return True
112
+
113
+ def set_run_parameters(self, parameters: Dict[str, str]) -> bool:
114
+ self.store.set_run_parameters(parameters)
115
+ return True
116
+
117
+ def record_conversation_event(
118
+ self,
119
+ scenario_id: str,
120
+ user_turn_index: int,
121
+ event_type: str,
122
+ actor: str,
123
+ name: Optional[str],
124
+ payload_json: str,
125
+ ) -> bool:
126
+ self.store.record_conversation_event(scenario_id, user_turn_index, event_type, actor, name, payload_json)
127
+ return True
128
+
129
+ def close(self) -> None:
130
+ try:
131
+ self.store.close()
132
+ except self.store.native_error:
133
+ pass