@withgateway/sdk 0.3.3 → 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 (123) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +2221 -962
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2212 -953
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +81 -19
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +79 -17
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/hooks/index.d.mts +1 -1
  11. package/dist/hooks/index.d.ts +1 -1
  12. package/dist/hooks/index.js +124 -11
  13. package/dist/hooks/index.js.map +1 -1
  14. package/dist/hooks/index.mjs +124 -11
  15. package/dist/hooks/index.mjs.map +1 -1
  16. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  17. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  18. package/dist/index.d.mts +2 -2
  19. package/dist/index.d.ts +2 -2
  20. package/dist/index.js +903 -221
  21. package/dist/index.js.map +1 -1
  22. package/dist/index.mjs +868 -212
  23. package/dist/index.mjs.map +1 -1
  24. package/dist/traces/index.js +78 -16
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +76 -14
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.js +7 -1
  29. package/dist/tracing/index.js.map +1 -1
  30. package/dist/tracing/index.mjs +7 -1
  31. package/dist/tracing/index.mjs.map +1 -1
  32. package/dist/worlds/index.d.mts +692 -410
  33. package/dist/worlds/index.d.ts +692 -410
  34. package/dist/worlds/index.js +740 -197
  35. package/dist/worlds/index.js.map +1 -1
  36. package/dist/worlds/index.mjs +736 -193
  37. package/dist/worlds/index.mjs.map +1 -1
  38. package/package.json +1 -1
  39. package/runtime/gatewaysdk/environment/_materialize.py +5 -25
  40. package/runtime/gatewaysdk/environment/_world.py +58 -65
  41. package/runtime/gatewaysdk/environment/backing.py +20 -24
  42. package/runtime/gatewaysdk/environment/core.py +1 -16
  43. package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
  44. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  45. package/runtime/gatewaysdk/environment/schema/api.py +174 -471
  46. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  47. package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
  48. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  49. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  50. package/runtime/gatewaysdk/environment/schema/call_log.py +230 -18
  51. package/runtime/gatewaysdk/environment/schema/call_redaction.py +201 -19
  52. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  53. package/runtime/gatewaysdk/environment/schema/conform.py +6 -27
  54. package/runtime/gatewaysdk/environment/schema/connector.py +89 -152
  55. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  56. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  57. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  58. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  59. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  60. package/runtime/gatewaysdk/environment/schema/data.py +14 -13
  61. package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
  62. package/runtime/gatewaysdk/environment/schema/database/guard.py +43 -36
  63. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  64. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
  65. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  66. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  67. package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
  68. package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
  69. package/runtime/gatewaysdk/environment/schema/handler_errors.py +25 -4
  70. package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
  71. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  72. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  73. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  74. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  75. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  76. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  77. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  78. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  79. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  82. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  83. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  84. package/runtime/gatewaysdk/environment/schema/local.py +31 -116
  85. package/runtime/gatewaysdk/environment/schema/platform.py +15 -17
  86. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  87. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  88. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  89. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  90. package/runtime/gatewaysdk/environment/schema/runtime.py +129 -176
  91. package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
  92. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  93. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  94. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
  95. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +31 -6
  96. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
  97. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +13 -13
  98. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +23 -23
  99. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +35 -2
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  102. package/runtime/gatewaysdk/environment/schema/snapshot.py +149 -29
  103. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  104. package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
  105. package/runtime/gatewaysdk/environment/schema/tools_world.py +84 -203
  106. package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
  107. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  108. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  109. package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
  110. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  111. package/runtime/gatewaysdk/environment/schema/world_tests.py +9 -11
  112. package/runtime/gatewaysdk/environment/world.py +1 -1
  113. package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
  114. package/skills/agents/connector-template-author.md +5 -1
  115. package/skills/benchmarks-getting-started/SKILL.md +8 -9
  116. package/skills/connector-schema-authoring/SKILL.md +31 -6
  117. package/skills/connector-schema-authoring/connector-worlds.md +129 -7
  118. package/skills/world-data-ingestion/ROWS.md +12 -8
  119. package/skills/world-data-ingestion/SKILL.md +13 -13
  120. package/skills/worlds-getting-started/SKILL.md +23 -23
  121. package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  122. package/skills/worlds-getting-started/references/gotchas.md +35 -2
  123. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@withgateway/sdk",
3
- "version": "0.3.3",
3
+ "version": "0.4.0",
4
4
  "description": "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
@@ -2,11 +2,8 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- import sys
6
5
  from pathlib import Path
7
- from tempfile import TemporaryDirectory
8
6
 
9
- from ._bundle import load_handlers, parse_manifest
10
7
  from .errors import WorldStartError
11
8
  from .legacy_sqlite import materialize
12
9
  from .schema import WorldDatabase, bundle_mode, check_bundle
@@ -29,16 +26,16 @@ def materialize_template(bundle: Path, destination: Path, *, require_sql: bool =
29
26
 
30
27
 
31
28
  def _materialize_schema(bundle: Path, destination: Path) -> dict | None:
32
- from .schema.snapshot import current_default, default_snapshot, refuse_unheld_pin
29
+ from .schema.snapshot import held_default, refuse_unheld_pin
33
30
 
34
31
  contract = check_bundle(bundle)
35
32
  if destination.exists():
36
33
  raise ContractError("state_exists", "Refusing to overwrite an existing template")
37
- copied = current_default(bundle, contract)
38
- if copied is not None:
34
+ held = held_default(bundle, contract)
35
+ if held is not None:
39
36
  # The compiled snapshot holds rows this contract may open; whether they are proven is the caller's (ProvenTemplate).
40
- WorldDatabase.clone_file(default_snapshot(bundle, contract), destination)
41
- return copied
37
+ WorldDatabase.clone_file(held[0], destination)
38
+ return held[1]
42
39
  refuse_unheld_pin(bundle, contract)
43
40
  initial = read_json(bundle / "data/initial.json")
44
41
  refuse_initial_rows(contract, initial)
@@ -102,20 +99,3 @@ def refuse_initial_rows(contract: Contract, initial: object) -> None:
102
99
  }
103
100
  row = initial["mutations"][first["index"]].get("value")
104
101
  raise_shape_refusal(contract, first, row, summary, context, first["pointer"])
105
-
106
-
107
- def validate_schema_materialization(bundle: Path) -> None:
108
- """Validate compiled artifacts and initial state without retaining a database."""
109
- bundle = Path(bundle)
110
- write_bytecode = sys.dont_write_bytecode
111
- sys.dont_write_bytecode = True
112
- try:
113
- load_handlers(bundle, parse_manifest(bundle))
114
- finally:
115
- sys.dont_write_bytecode = write_bytecode
116
- with TemporaryDirectory(prefix="gateway-schema-validation-") as directory:
117
- materialize_template(
118
- bundle,
119
- Path(directory) / "template.db",
120
- require_sql=True,
121
- )
@@ -1,11 +1,3 @@
1
- """Worlds — deterministic instances of a mock-tools environment's seeded state.
2
-
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
- 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
3
  import time
@@ -26,30 +18,24 @@ from .score import Score
26
18
 
27
19
  if TYPE_CHECKING: # pragma: no cover
28
20
  from .core import Environment
21
+ from .schema.journal import JournalUse, WorldJournal
29
22
  from .schema.session_files import ProvenTemplate, SessionExport
30
23
 
31
24
 
32
25
  @dataclass
33
26
  class VerifierResult:
34
- """One verifier outcome. ``score=None`` stays ``None`` (house rule: null
35
- scores are their own category, never coerced to 0) and yields
36
- ``passed=None``; otherwise ``passed = score >= 1.0``."""
27
+ """``passed`` is ``score >= 1.0``; a ``None`` score is ungraded, never 0, and has ``passed=None``."""
37
28
 
38
29
  name: str
39
30
  passed: Optional[bool]
40
31
  score: Optional[float]
41
32
  detail: str = ""
42
33
  rewards: Dict[str, float] = field(default_factory=dict)
34
+ closed: Optional[str] = None
43
35
 
44
36
 
45
37
  class SqlVerifier:
46
- """One ``verifiers/<name>.sql``: the statements it runs and the one score
47
- rule every reader applies — ``schema check``, a local session's grade, the
48
- World Host's grade. Statements run in order; the score is the first column
49
- of the first row of the LAST statement that returns rows (or could). No
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)."""
38
+ """Every reader's score rule, pinned by ``sql-verifier-vectors.json``: NULL or no rows is ``None``, never 0."""
53
39
 
54
40
  def __init__(self, name: str, script: str, split: Callable[[str], List[str]]) -> None:
55
41
  self.name = name[:-4] if name.endswith(".sql") else name
@@ -57,14 +43,9 @@ class SqlVerifier:
57
43
 
58
44
  @classmethod
59
45
  def read(cls, path: Path, split: Callable[[str], List[str]]) -> "SqlVerifier":
60
- """``split`` is the engine's statement splitter (``WorldDatabase.split_statements``)."""
61
46
  return cls(path.stem, path.read_text(encoding="utf-8"), split)
62
47
 
63
48
  def score(self, execute: Callable[[str], Optional[List[Any]]]) -> "tuple[Optional[float], Optional[str]]":
64
- """Run every statement through ``execute`` (rows, or ``None`` for a
65
- statement that returns none, e.g. a temp-table DDL) and answer
66
- ``(score, sql)`` — the score and the statement it came from, both
67
- ``None`` when nothing returned rows."""
68
49
  value: Any = None
69
50
  last_sql: Optional[str] = None
70
51
  for statement in self.statements:
@@ -92,18 +73,12 @@ _NO_INPUT = object()
92
73
 
93
74
 
94
75
  def _stub_input(tool_input: Any, kwargs: Dict[str, Any]) -> Any:
95
- """One rule for callable seams: an explicit positional input (even None)
96
- is the input; keyword arguments are the input; nothing means omitted."""
97
76
  if tool_input is not _NO_INPUT:
98
77
  return tool_input
99
78
  return kwargs if kwargs else _NO_INPUT
100
79
 
101
80
 
102
81
  class WorldRegistry(StubRegistryMapping):
103
- """``world.as_registry()`` — the replay registry contract (mapping with
104
- ``__missing__``, ``lookup``, ``call_log``/``called_names``) backed by the
105
- live env world instead of recordings."""
106
-
107
82
  def __init__(self, world: "World") -> None:
108
83
  self._world = world
109
84
 
@@ -129,14 +104,6 @@ class WorldRegistry(StubRegistryMapping):
129
104
 
130
105
 
131
106
  class World:
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
107
  def __init__(
141
108
  self,
142
109
  env: "Environment",
@@ -147,13 +114,17 @@ class World:
147
114
  ) -> None:
148
115
  self.env = env
149
116
  self.id = world_id or uuid.uuid4().hex[:8]
150
- 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)
151
118
  self.call_log: List[Dict[str, Any]] = []
152
119
  self._template = self._proven(template)
153
120
  self.contract = template.contract if template is not None else self._bundle_contract()
154
121
  source, audit = (Path(snapshot), True) if snapshot is not None else self._seed()
155
122
  self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
156
123
 
124
+ @staticmethod
125
+ def database_file(directory: Path, world_id: str) -> Path:
126
+ return Path(directory) / f"world-{world_id}.db"
127
+
157
128
  @staticmethod
158
129
  def _proven(template: Any) -> Any:
159
130
  if template is None:
@@ -168,18 +139,16 @@ class World:
168
139
  return check_bundle(self.env.bundle_path) if bundle_mode(self.env.bundle_path) is not None else None
169
140
 
170
141
  def _seed(self) -> "tuple[Path, bool]":
171
- """The file a fresh or reset world copies, and whether its rows are audited."""
172
142
  if self._template is None:
173
143
  return Path(self.env._template_db), True
174
144
  return self._template.path, False
175
145
 
176
146
  @property
177
147
  def store(self):
178
- """The world database of a schema world; ``None`` for a contract-less mock-tools world."""
148
+ """``None`` for a contract-less mock-tools world."""
179
149
  return self._backing.store
180
150
 
181
151
  def execute(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
182
- """Execute atomically in schema mode, validating both input and output."""
183
152
  from .schema.validation import validate
184
153
 
185
154
  handler = self.env._handlers.get(tool_name)
@@ -236,14 +205,10 @@ class World:
236
205
  )
237
206
 
238
207
  def as_registry(self) -> WorldRegistry:
239
- """Tool-name → callable mapping, drop-in for agent tool layers —
240
- identical contract to ``ToolStubRegistry.as_registry()`` in replay."""
208
+ """Drop-in for agent tool layers, with the contract of replay's ``ToolStubRegistry.as_registry()``."""
241
209
  return WorldRegistry(self)
242
210
 
243
211
  def wrap_tools(self, tools: Union[Mapping[str, Any], List[Any]]) -> Union[Dict[str, Any], List[Any]]:
244
- """Substitute env-served callables by name in a list/dict of tools;
245
- everything not served (or not env-routed) passes through unchanged."""
246
-
247
212
  def routed_to_env(name: Optional[str]) -> bool:
248
213
  return bool(name) and name in self.env._handlers and self.env.resolve_route(name) == "env"
249
214
 
@@ -265,7 +230,6 @@ class World:
265
230
  return wrapped
266
231
 
267
232
  def reset(self) -> None:
268
- """Back to the seed, in place (same world instance)."""
269
233
  if self._template is None:
270
234
  self._refuse_a_changed_contract()
271
235
  source, audit = self._seed()
@@ -281,14 +245,11 @@ class World:
281
245
  raise ContractError("state_contract", "Bundle contract changed; create a new world explicitly")
282
246
 
283
247
  def restore(self, source: Union[str, Path]) -> None:
284
- """Replace this world's state with a file :meth:`snapshot` wrote, in place.
285
- A schema-backed world audits it against its contract row by row, as it would
286
- any file it did not write."""
248
+ """Audited row by row: the file is not one this store wrote."""
287
249
  self._relay(Path(source), audit=True)
288
250
 
289
251
  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."""
252
+ """No second row audit: a :class:`SessionExport` is digest-verified or this session's own recovered store."""
292
253
  from .schema.session_files import SessionExport
293
254
 
294
255
  self._relay(SessionExport.required(export).path, audit=False)
@@ -298,39 +259,43 @@ class World:
298
259
  self._backing = WorldBacking.branch(source, self.db_path, self.contract, audit=audit)
299
260
 
300
261
  def snapshot(self, destination: Union[str, Path]) -> Path:
301
- """Pin this world's current state to a file (for debugging fixtures)."""
302
262
  return self._backing.snapshot(Path(destination))
303
263
 
304
264
  def close(self) -> None:
305
265
  self._backing.close()
306
266
 
307
267
  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."""
268
+ """``False`` when a mock-tools world does not declare the table."""
309
269
  return self._backing.set_task_context(scenario_id)
310
270
 
311
271
  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."""
272
+ """``False`` when a mock-tools world does not declare the table."""
313
273
  return self._backing.set_run_parameters(parameters)
314
274
 
315
275
  def record_conversation_event(
316
- self, scenario_id: str, user_turn_index: int, event_type: str, actor: str, name: Optional[str], payload_json: str
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,
317
283
  ) -> bool:
318
- """Log one turn event for verifiers; ``False`` when a mock-tools world does not declare the table."""
284
+ """``False`` when a mock-tools world does not declare the table."""
319
285
  return self._backing.record_conversation_event(
320
286
  scenario_id, user_turn_index, event_type, actor, name, payload_json
321
287
  )
322
288
 
323
289
  def state(self, sql: str, *params: Any) -> List[Dict[str, Any]]:
324
- """Read-only SQL against the world's db (SELECT/WITH only)."""
325
290
  return self._backing.rows(sql, params)
326
291
 
327
- def verify(self, name: str) -> VerifierResult:
328
- """Run ``verifiers/<name>.sql`` against this world.
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
329
298
 
330
- :class:`SqlVerifier` is the rule: the first column of the first row of
331
- the LAST row-returning statement. NULL / no rows → score None (passed
332
- None) — never coerced to 0.
333
- """
334
299
  verifier_name = name[:-4] if name.endswith(".sql") else name
335
300
  path = self.env.bundle_path / "verifiers" / f"{verifier_name}.sql"
336
301
  if not path.is_file():
@@ -340,7 +305,20 @@ class World:
340
305
  def execute(statement: str) -> Optional[List[Any]]:
341
306
  return self._backing.verifier_rows(verifier_name, statement)
342
307
 
343
- score, last_sql = SqlVerifier.read(path, self._backing.split_statements).score(execute)
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:
311
+ try:
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)
344
322
  if last_sql is None:
345
323
  detail = "no row-returning statement — score is null"
346
324
  elif score is None:
@@ -349,3 +327,18 @@ class World:
349
327
  detail = f"score {score} from: {last_sql}"
350
328
  passed = None if score is None else score >= 1.0
351
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
+ )
@@ -1,29 +1,25 @@
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
1
  from __future__ import annotations
6
2
 
7
3
  from abc import ABC, abstractmethod
4
+ from collections.abc import Callable
8
5
  from contextlib import AbstractContextManager
9
6
  from pathlib import Path
10
- from typing import Any, Dict, List, Optional
7
+ from typing import TYPE_CHECKING, Any, Dict, List, Optional
11
8
 
12
9
  from .schema.compiler import Contract
13
10
  from .schema.database import WorldDatabase
14
11
  from .schema.validation import ContractError
15
12
 
13
+ if TYPE_CHECKING:
14
+ from .schema.journal import JournalDatabase, JournalUse
16
15
 
17
- class WorldBacking(ABC):
18
- """One world's open state file."""
19
16
 
17
+ class WorldBacking(ABC):
20
18
  store: Optional[WorldDatabase] = None
21
19
 
22
20
  @staticmethod
23
21
  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)."""
22
+ """``audit=False`` only for a source whose rows are already proven: a version's template, a verified export."""
27
23
  from .legacy_sqlite import LegacySQLiteBacking
28
24
 
29
25
  WorldDatabase.clone_file(Path(source), Path(path))
@@ -36,34 +32,34 @@ class WorldBacking(ABC):
36
32
  raise
37
33
 
38
34
  @abstractmethod
39
- def transaction(self) -> AbstractContextManager[Any]:
40
- """The unit one tool call runs in."""
35
+ def transaction(self) -> AbstractContextManager[Any]: ...
41
36
 
42
37
  @abstractmethod
43
- def handler_connection(self) -> Any:
44
- """What a tool handler receives as ``conn``."""
38
+ def handler_connection(self) -> Any: ...
45
39
 
46
40
  @abstractmethod
47
41
  def split_statements(self, script: str) -> List[str]: ...
48
42
 
49
43
  @abstractmethod
50
44
  def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
51
- """Read-only SQL, each row as a dict (``world.state``)."""
45
+ """Read-only SQL: every backing refuses a write here (``world.state``)."""
52
46
 
53
47
  @abstractmethod
54
48
  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."""
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."""
56
54
 
57
55
  @abstractmethod
58
56
  def snapshot(self, destination: Path) -> Path: ...
59
57
 
60
58
  @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."""
59
+ def set_task_context(self, scenario_id: str) -> bool: ...
63
60
 
64
61
  @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."""
62
+ def set_run_parameters(self, parameters: Dict[str, str]) -> bool: ...
67
63
 
68
64
  @abstractmethod
69
65
  def record_conversation_event(
@@ -74,16 +70,13 @@ class WorldBacking(ABC):
74
70
  actor: str,
75
71
  name: Optional[str],
76
72
  payload_json: str,
77
- ) -> bool:
78
- """Log one turn event; ``False`` when the world does not declare the table."""
73
+ ) -> bool: ...
79
74
 
80
75
  @abstractmethod
81
76
  def close(self) -> None: ...
82
77
 
83
78
 
84
79
  class ContractBacking(WorldBacking):
85
- """A schema world's state: the world database its contract compiled to."""
86
-
87
80
  def __init__(self, path: Path, contract: Contract, *, audit: bool = True) -> None:
88
81
  self.store = WorldDatabase.open(path, contract, audit=audit)
89
82
 
@@ -99,6 +92,9 @@ class ContractBacking(WorldBacking):
99
92
  def rows(self, sql: str, params: tuple) -> List[Dict[str, Any]]:
100
93
  return [dict(row) for row in self.store.query(sql, params)]
101
94
 
95
+ def journal(self, database: JournalDatabase) -> AbstractContextManager[Callable[[list[str]], JournalUse]]:
96
+ return database.attached(self.store)
97
+
102
98
  def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
103
99
  try:
104
100
  return self.store.query(statement, private=True)
@@ -153,7 +153,6 @@ class Environment:
153
153
 
154
154
  _install_ambient_interceptor()
155
155
 
156
- # -- kind guards -----------------------------------------------------
157
156
 
158
157
  def _require_mock(self, operation: str) -> None:
159
158
  if self.kind != KIND_MOCK_TOOLS:
@@ -172,7 +171,6 @@ class Environment:
172
171
  "the registry/execute seams instead."
173
172
  )
174
173
 
175
- # -- mock-tools: template + worlds ------------------------------------
176
174
 
177
175
  def _build_template_db(self) -> None:
178
176
  from ._materialize import materialize_template
@@ -235,7 +233,6 @@ class Environment:
235
233
  self._implicit_world = World(self)
236
234
  return self._implicit_world
237
235
 
238
- # -- delegates to the implicit world ----------------------------------
239
236
 
240
237
  def execute(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
241
238
  return self._ensure_world().execute(tool_name, tool_input)
@@ -255,7 +252,6 @@ class Environment:
255
252
  def reset(self) -> None:
256
253
  self._ensure_world().reset()
257
254
 
258
- # -- harbor ----------------------------------------------------------
259
255
 
260
256
  @property
261
257
  def tasks(self) -> List[HarborTask]:
@@ -284,7 +280,6 @@ class Environment:
284
280
  self._docker_runtime = CliDockerRuntime()
285
281
  return self._docker_runtime
286
282
 
287
- # -- routing ----------------------------------------------------------
288
283
 
289
284
  def resolve_route(self, tool_name: str) -> str:
290
285
  """Route map > effects default (read→default_route, write→env,
@@ -339,11 +334,6 @@ def _effects_of(tool_name: str) -> Optional[str]:
339
334
  return None
340
335
 
341
336
 
342
- # ---------------------------------------------------------------------------
343
- # Ambient interception — the define_tool wrapper's hook (spec §4.4, rung 1.5)
344
- # ---------------------------------------------------------------------------
345
-
346
-
347
337
  def _ambient_intercept(name: str, fn: Any, args: tuple, kwargs: dict) -> Any:
348
338
  """Called by the ``define_tool`` wrapper on every invocation. No active
349
339
  world → miss sentinel (the wrapper calls the original fn — the identity
@@ -410,11 +400,6 @@ def _install_ambient_interceptor() -> None:
410
400
  _interceptor_installed = True
411
401
 
412
402
 
413
- # ---------------------------------------------------------------------------
414
- # init
415
- # ---------------------------------------------------------------------------
416
-
417
-
418
403
  def init_from_path(
419
404
  path: Union[str, Path],
420
405
  *,
@@ -494,7 +479,7 @@ def init(
494
479
 
495
480
  bench = GatewayBenchmarkClient(resolved_host, resolved_public, resolved_secret)
496
481
  try:
497
- details = bench.resolve_version(slug, version or "latest")
482
+ details = bench.resolve_version(slug, version)
498
483
  except BenchmarkPushError as error:
499
484
  raise EnvironmentNotReady(f"no runnable version for '{slug}': {error}") from None
500
485
  content_hash = details.get("contentHash")
@@ -1,7 +1,4 @@
1
- """A contract-less mock-tools world's state: one raw SQLite file built from
2
- ``db/schema.sql`` + ``db/seed.sql``. Its handlers write SQL through ``conn`` and
3
- its seeds are SQL text, so it is SQLite by definition and stays outside the
4
- contract-bound :class:`~gatewaysdk.environment.schema.database.WorldDatabase`."""
1
+ """Handlers write SQL through ``conn`` and seeds are SQL text, so a mock-tools world is SQLite by definition."""
5
2
 
6
3
  from __future__ import annotations
7
4
 
@@ -10,7 +7,7 @@ import sqlite3
10
7
  import tempfile
11
8
  from contextlib import AbstractContextManager, nullcontext
12
9
  from pathlib import Path
13
- from typing import Any, Dict, List, Optional
10
+ from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional
14
11
 
15
12
  from .backing import WorldBacking
16
13
  from .errors import VerifierError, WorldStartError
@@ -19,6 +16,9 @@ from .schema.database import SQLiteWorldDatabase
19
16
  from .schema.database.runtime_rows import CONVERSATION_EVENTS, RUN_PARAMETERS, TASK_CONTEXT, RuntimeRows, Statement
20
17
  from .schema.validation import fail
21
18
 
19
+ if TYPE_CHECKING:
20
+ from .schema.journal import JournalDatabase, JournalUse
21
+
22
22
  MODES = ("append", "replace")
23
23
  #: Undoing a failed runtime write: the outermost savepoint is the transaction, and its RELEASE is the
24
24
  #: commit, so a busy RELEASE must be answered with ROLLBACK or the connection stays inside it.
@@ -67,12 +67,7 @@ def _check_row(columns: List[str], table: str, index: int, row: dict) -> None:
67
67
 
68
68
 
69
69
  def seed_statements(columns: Dict[str, List[str]], rows: Rows, mode: str = "append") -> List[str]:
70
- """SQL text that seeds ``rows`` into tables with these ``columns``.
71
-
72
- ``append`` writes ``INSERT OR REPLACE`` (an upsert by the table's own
73
- primary key); ``replace`` prefixes ``DELETE FROM`` for each named table and
74
- writes plain inserts.
75
- """
70
+ """``append`` upserts by each table's own primary key; ``replace`` first empties only the tables ``rows`` names."""
76
71
  if mode not in MODES:
77
72
  fail("mode", f"mode must be one of {', '.join(MODES)}", "/mode")
78
73
  _check_rows(columns, rows)
@@ -94,7 +89,6 @@ def _insert(verb: str, table: str, row: dict) -> str:
94
89
 
95
90
 
96
91
  def columns_of(conn: sqlite3.Connection) -> Dict[str, List[str]]:
97
- """Every user table's columns, in declaration order."""
98
92
  tables = [
99
93
  row[0]
100
94
  for row in conn.execute("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'")
@@ -103,11 +97,6 @@ def columns_of(conn: sqlite3.Connection) -> Dict[str, List[str]]:
103
97
 
104
98
 
105
99
  def seed_sqlite(conn: sqlite3.Connection, rows: Rows, mode: str = "append") -> Dict[str, int]:
106
- """Execute the seed for ``rows`` against a live sqlite, in one transaction.
107
-
108
- Columns come from the live database itself. A refused row rolls the whole
109
- seed back. Returns the row count of every touched table afterwards.
110
- """
111
100
  statements = seed_statements(columns_of(conn), rows, mode)
112
101
  try:
113
102
  conn.execute("BEGIN")
@@ -121,7 +110,6 @@ def seed_sqlite(conn: sqlite3.Connection, rows: Rows, mode: str = "append") -> D
121
110
 
122
111
 
123
112
  def schema_columns(schema: Path) -> Dict[str, List[str]]:
124
- """The tables and columns ``db/schema.sql`` declares, loaded in memory."""
125
113
  with sqlite3.connect(":memory:") as probe:
126
114
  try:
127
115
  probe.executescript(schema.read_text(encoding="utf-8"))
@@ -131,7 +119,6 @@ def schema_columns(schema: Path) -> Dict[str, List[str]]:
131
119
 
132
120
 
133
121
  def materialize(schema: Path, seed: Path, destination: Path) -> None:
134
- """``db/schema.sql`` then ``db/seed.sql`` (each when present) into a new file."""
135
122
  conn = sqlite3.connect(destination)
136
123
  try:
137
124
  if schema.is_file():
@@ -146,8 +133,7 @@ def materialize(schema: Path, seed: Path, destination: Path) -> None:
146
133
 
147
134
 
148
135
  class LegacySQLiteBacking(WorldBacking):
149
- """A mock-tools world's raw connection: handlers read and write through it,
150
- autocommit, across threads (agents call tools from worker threads)."""
136
+ """Autocommit, shared across threads: agents call tools from worker threads."""
151
137
 
152
138
  def __init__(self, path: Path, contract: Optional[Contract] = None) -> None:
153
139
  self.path = Path(path)
@@ -172,6 +158,12 @@ class LegacySQLiteBacking(WorldBacking):
172
158
  )
173
159
  return [dict(row) for row in self._conn.execute(sql, params).fetchall()]
174
160
 
161
+ def journal(self, database: JournalDatabase) -> AbstractContextManager[Callable[[list[str]], JournalUse]]:
162
+ """A legacy tools world keeps no journal: its verifiers read none."""
163
+ from .schema.journal import JournalUse
164
+
165
+ return nullcontext(lambda statements: JournalUse.none())
166
+
175
167
  def verifier_rows(self, verifier: str, statement: str) -> Optional[List[Any]]:
176
168
  try:
177
169
  cursor = self._conn.execute(statement)
@@ -197,11 +189,9 @@ class LegacySQLiteBacking(WorldBacking):
197
189
  }
198
190
 
199
191
  def seed(self, rows: Rows, mode: str = "append") -> Dict[str, int]:
200
- """:func:`seed_sqlite` into this world's live file."""
201
192
  return seed_sqlite(self._conn, rows, mode)
202
193
 
203
194
  def entities(self) -> Rows:
204
- """Every table's rows, tables by name."""
205
195
  return {
206
196
  table: [dict(row) for row in self._conn.execute(f"SELECT * FROM {quote(table)}")]
207
197
  for table in sorted(self.columns())
@@ -218,7 +208,6 @@ class LegacySQLiteBacking(WorldBacking):
218
208
  return found.fetchone() is not None
219
209
 
220
210
  def _write_runtime(self, table: str, statements: list[Statement]) -> bool:
221
- """The store's runtime statements, all or none, where the world declares ``table``."""
222
211
  if not self._declares(table):
223
212
  return False
224
213
  outer = not self._conn.in_transaction
@@ -261,15 +250,13 @@ class LegacySQLiteBacking(WorldBacking):
261
250
 
262
251
 
263
252
  class LegacyVerifiers:
264
- """A db/schema.sql world's ``verifiers/*.sql``, each scored by :class:`SqlVerifier`'s rule
265
- against its own copy of the seeded state, so no verifier sees another's writes."""
253
+ """Each verifier scores its own copy of the seeded state, so no verifier sees another's writes."""
266
254
 
267
255
  def __init__(self, root: Path) -> None:
268
256
  self.root = Path(root)
269
257
  self.paths = sorted((self.root / "verifiers").glob("*.sql"))
270
258
 
271
259
  def scores(self) -> List[Dict[str, Any]]:
272
- """``{path, ok, score[, error]}`` per verifier; a world that does not build fails every one."""
273
260
  schema = self.root / "db" / "schema.sql"
274
261
  if not schema.is_file():
275
262
  return [self._refused(path, "db/schema.sql is missing") for path in self.paths]